feat(review): add read-only health checks for pushed branches

[Jay0130-a]

What

teamai review --branch <name> runs read-only health checks over a branch teamai push created (teamai/push/<user>/<timestamp>) and reports findings at three levels — fail (must fix), warn (needs a human decision), info (context). --json prints the same object for CI, and the command exits non-zero when any fail finding exists.

Fixes #776 (the "Add Skill health checks / validation" pair from the roadmap in #647, labelled help wanted).

Why

When the Git host cannot open a PR/MR (a plain ssh:// remote, for example), teamai push still lands new resources on a push branch, but nothing tells the human who merges by hand whether those resources are usable. This closes that gap.

How

Strictly read-only: the branch tree is read out of git's object store (git ls-tree / git show, via the existing listFilesAtRev / getFileContentAtRev) into a temp dir and is never checked out into the team repo; nothing is written back.

The checks reuse pull's own code paths instead of re-implementing them — scanTeamForPull (what counts as a resource), loadRolesManifestIfPresent / loadProjectsManifest, NAMESPACE_AXIS, parseAgentYaml, splitFrontmatter, isSafeNamespaceSegment and utils/redact — so a branch this command calls clean is one pull reads the same way.

Checks implemented:

• structure — SKILL.md at the skill root; the namespace is declared on the resource type's axis (NAMESPACE_AXIS)
• naming — path segments are usable; the frontmatter/YAML name matches the directory/file name
• duplicates — the same resource name in two namespaces that a single role or project can activate together (which makes pull fail)
• format — skill frontmatter present and description explains when to use the skill; agent specs parse via parseAgentYaml
• leaks — credential shapes via utils/redact, plus internal addresses (RFC 1918 / .internal / .corp / .lan)

Surface note

The issue proposed teamai review <branch>. teamai review [id] already exists for .teamai/pending-review.jsonl, so following the repo convention of extending an existing command this adds a --branch <name> option to it. The existing pending-review behaviour is unchanged — it only diverts when --branch is present. Happy to move it to a positional argument or a separate command if you prefer.

Testing

• vitest run src/__tests__/review-branch.test.ts → 11 passed: clean branch passes; missing SKILL.md fails; resource in a namespace no role/project declares fails; co-active duplicate fails and the never-co-active case does not; frontmatter/directory name mismatch fails; missing description warns; credential and internal address fail; agent name mismatch fails; --json shape.
• tsc --noEmit → clean. oxlint on the touched files → 0 warnings / 0 errors.
• Real CLI run against a temp team repo with a teamai/push/... branch: 4 fail / 1 warn reported, --json emitted the documented object, an unknown branch exits 1, and the team repo was left clean on main (git status --porcelain empty).

Deferred (a reviewer may want these)

• no conventions checks (the issue said they stay off by default)
• format/naming coverage for rules is thinner than for skills/agents
• "co-active" is judged conservatively (same role/project axis list); a member holding several roles via additionalRoles can still produce a false negative, never a false positive
• the branch tree is materialised file-by-file into a temp dir; git cat-file --batch would cut I/O on large repos
• no e2e test in src/__tests__/e2e/ yet (the real CLI record is above)

[github-actions]

• [P2 non-blocking] Multi-role collisions can pass review — src/review-branch.ts:154: coActive checks each role/project list independently. With vr in both frontend and backend, a member whose primary role enables one namespace and additionalRoles enables the other receives both, but review reports no duplicate and can return ok: true. The disclosed deferral leaves this false negative unresolved; account for supported role combinations.

• [P2 non-blocking] Skipped files silently receive a clean leak result — src/review-branch.ts:389: Files longer than 512 KiB are skipped without a finding. A valid skill containing a large reference file with an API credential therefore passes leak checks and can return ok: true. Scan large text files in chunks, or emit a warning that leak validation was incomplete.

Testing: The PR description includes a representative real-CLI verification record, satisfying the review requirement. No missing-e2e finding applies. I did not run, build, or install PR code.