v4: folio split (Phases 3 + 3.5 + 3.6) — craft 94→47 commands

[Data-Wise]

What this is

The v4 folio-split train — Phases 3, 3.5, and 3.6 — landing as the single gated
operation the plan always intended ("branch holds — 3.5 rides the same train").

craft's docs-authoring surface is extracted to the standalone folio plugin.
Surface: 94 → 47 commands, 40 skills, 2 agents.

Phase 3.6 — router consolidations: 1 of 5 shipped

Opened with five router workstreams; four were dropped after reading the command
bodies in full, which the original grill had only line-counted:

Workstream	Outcome
plan:feature	Excluded (pre-existing D2 lock)
arch	Dropped (D6) — no real duplication
orch	Dropped (D11) — already delegates to drive-engine/workflow-engine
code:audit	Shipped, shrunk 5 commands → 2 (D12) — the audit-router skill
ci	No router (D13) — a metadata fix only

Root cause of the drops: the grill locked load-bearing decisions from line counts and
flag names. Every family that looked cohesive from surface metrics collapsed on a full
read. Rule recorded in the GRILL ledger for future consolidation phases.

Real defects found and fixed

• 4 category: metadata mismatches — ci/{fix,local}.md declared category: code;
  orch/{drive,workflow}.md declared category: orchestrate against a nonexistent
  directory. All flagged by help_file_validator._check_category_mismatch (live-wired via
  docs_update_orchestrator → /craft:docs:update). A repo-wide sweep found the orch
  pair, which was pre-existing on dev. Repo-wide mismatches: 0.
• T3.4 — command floor 60 → 40. The floor is a mass-deletion guardrail and must sit
  below the real surface. It went stale twice (86 → 60) while the count fell 94 → 70 → 47,
  leaving the floor above the surface — CI hard-failed on every run. Rationale is now a
  comment in ci.yml.
• test_git_shim_correctness.sh — inverted, not deleted. It asserted each
  commands/git/*.md was a thin shim; T3.5.2 completed that migration by deleting all 11,
  making the assertions unsatisfiable (7 FAIL here, 21/21 on dev). It now guards the
  migration's end state: shims stay deleted, Operations 1–12 survive in the skill,
  issue-check stays live, no unsanctioned command reappears.

/craft:git:issue-check kept as a live command

dev shipped this (PR #283) into the surface this branch deleted. Git's directory-rename
detection auto-relocated it into skills/dev/git/references/ — which would have broken
tests/test_issue_check_unit.py: that test hardcodes commands/git/issue-check.md and
exec()s the classify_issue() block out of it, so the command file is the single source
of truth for the classifier. Same structural constraint recorded for commands/ci/triage.md
(D13). Restored to commands/git/; its 12 unit tests pass. SKILL.md's now-false claims
("commands/git/ is now empty", "no explicit /craft:git:* path anymore") are corrected
with the reason.

Test evidence

Run in the worktree the PR ships from (~/.git-worktrees/craft/feature-folio-split):

python3 -m pytest tests/          → 2601 passed, 1 failed, 43 skipped, 1 xfailed, 1 xpassed
                                    (was 4 failed pre-merge; the dev merge fixed the 3
                                    test_v115_adhd_enhancements stale-page assertions)

The 1 remaining failure is local-environment-only:
test_branch_guard_dogfood.py::TestHookInstallation::test_repo_copy_matches_installed
compares the repo's scripts/branch-guard.sh against ~/.claude/hooks/. This branch
legitimately changed the hook's message text (repointing /craft:git:guard → skill phrasing
after T3.5.2 removed that command), so the local machine's dev-era installed hook differs.
CI runs install-guards.sh at ci.yml:151 before the suites, syncing them. Proven, not
assumed — re-running that class with an isolated HOME containing the branch's hook:
6 passed, 1 skipped.

All 4 CI-required bash suites green (SKIP_PERF=1, as CI runs them):

test_branch_guard.sh          → ALL TESTS PASSED (0 failed)
test_branch_guard_e2e.sh      → ALL TESTS PASSED (0 failed)
test_no_switch_guard.sh       → ALL TESTS PASSED (0 failed)
test_git_shim_correctness.sh  → 25/25 passed

test_branch_guard.sh was red before the merge and needed no edit — it was stale-branch
drift. dev had renamed the test to ..._now_caught (expect 2) when PRs #287–#289 closed
that git -C gap; this branch carried the old ..._not_caught (expect 0). The suite exercises
the installed hook, so its result is machine-global state, not branch state — which is why
it passed on dev and failed here with identical code.

Rewritten test verified by planted defect, not just a green run:

resurrect commands/git/status.md      → caught (deleted:status.md + unsanctioned:status.md)
rename Operation 5 in SKILL.md        → caught (op:5 missing)
mark issue-check deprecated: true     → caught (live:issue-check.md)
clean baseline before and after       → 25/25 passed

Other gates:

./scripts/validate-counts.sh   → exit 0 (47 commands / 40 skills / 2 agents)
mkdocs build --strict          → exit 0, 0 errors/warnings
CI count floors simulated      → commands 47 ≥ 40 ✅ · skills 68 ≥ 26 ✅ · orchestrator ✅
leak scan (diff vs dev)        → clean (no secrets, no literal destructive git commands)

Merge notes (41 commits from dev, 34 conflicts)

~30 were count-cascade (dev 95/45/8 vs branch 46/40/2). Resolved to the post-split surface,
then every tracked count recomputed mechanically via bump-version.sh --counts-only
rather than trusting hand-resolution. The guard-script conflicts that were expected in
no-switch-guard.sh / install-guards.sh / version-check.sh did not materialise —
all auto-merged clean.

Judgment calls:

• commands/docs/quickstart.md (modify/delete) → kept deleted; folio owns it (verified on
  disk). dev's only change was a count bump inside an example template.
• mkdocs.yml nav → dropped dev's 7 deleted git entries, kept the issue-check entry
  (a blind --ours would have dropped it from the site).
• Long-tail doc counts (46 → 47) updated in 6 live user-facing files. Historical changelog
  entries, illustrative sample outputs, and spec/brainstorm records deliberately left at their
  original numbers.

Known, deliberately not fixed

docs/commands.md:15 ("46 commands now support dry-run mode") and :205 ("46 commands for
documentation generation…") are pre-existing errors, not off-by-one from this merge —
:205 was already wrong before it, since the docs surface moved to folio. They need a real
docs pass, not a sed.

Root blind spot this PR closes

The two CI gates that were red are bash suites (ci.yml:177–186) — pytest does not run
them. T3.5.2 cited "full pytest 2575 passed" as its verification evidence and shipped the
breakage behind a green check. Worth considering separately: a /craft:check tier that runs
both.

🤖 Generated with Claude Code