fix(beta-ai-docs-agnosticism): S1 Phase -1 BLOCKERs — false upgrade claim + unregistered parity gate

[artyhoo]

What + why

The mandatory Phase -1 cold review of S1 (#1311) returned REVISE with 2 BLOCKERs. This PR closes both. It is the §7 REVISE route of the umbrella's meta-launch, not new scope — Stage 2 (S2 ∥ S3) stays halted until Phase -1 is re-run against this diff.

The review was run per meta-launch §7: an in-session cold sub-agent given only git show 744bb06e35 + the S1 kickoff §4 acceptance list, with the PR body withheld. It confirmed it never opened #1311. Acceptance came back 7/9 verified by running, 2/9 INCONCLUSIVE, 0/9 failed, with declared coverage of 24 of 38 files — the two BLOCKERs below were then reproduced independently by the orchestrator before anything was edited.

B1 — the documented upgrade path does not exist

AI-USAGE-GUIDE.md and first-steps.source.json both promised: «Already on core? Upgrade in place with --refresh --profile env: the deeper payload arrives.»

Measured on a real temp consumer:

command	exit	tier-home.md	.claude/skills/arch/
--profile core (baseline)	0	NO	NO
--refresh --profile env (as documented)	0	NO	NO
--profile env (plain re-run)	0	YES	YES

Core artefact md5s were byte-identical across the successful upgrade, so the second half of the claim held; only the mechanism was wrong.

The installer behaviour is deliberate, so the docs are the defect: install.sh:1074-1077 gates the tier-home arm on presence with the comment «refresh must not create it on core», and arch appears in neither do_refresh skill loop (install.sh:669,671).

This blocked Stage 2 because the following steps of that same sequence tell the consumer to ls and then open .ai-factory/tier-home.md — a dead end — and because first-steps.source.json is the SSOT the B-D5 amendment obliges umbrella B's BS2 to vendor onto the public site.

Fixed upstream too, and it was worse there

The same claim pre-exists at INSTALL-FOR-AI.md (S1 copied it forward). Measurement showed a subtler failure: --refresh --profile factory does deliver the AIF suite — the F7 arm honours --profile — while tier-home.md and arch still do not. A consumer following that line gets a silently half-upgraded project at exit 0, which reads as success.

Fixing only the guide would have left two shipped docs contradicting each other, which is the precise defect class this umbrella exists to close, so both were corrected to the verified plain deeper-profile re-run.

B2 — the parity gate was registered in nothing

git grep -n "first-steps" origin/staging -- .github/ .husky/ scripts/ package.json packages/core/package.json
→ exit=1, zero matches

Control, same PR's sibling test: audit-self.yml:499. Its only runner was the S1 kickoff's host-verify block, which stops executing the moment the stage closes — while packages/core/principles/09-doc-authority-hierarchy.ts:116 already asserted the parity is «gated by» that file. #hope-as-gate per attention-is-not-a-mechanism.md §1.

Registered by name in two channels — .github/workflows/audit-self.yml beside its sibling, and scripts/run-local-ci-sweep.sh for the earlier developer-time channel (invariant 4: CI is the last resort). By name rather than via an audit-self/ directory scope on purpose: a directory sweep would also pull in two unrelated unregistered tests (hooks-tree-guard.test.ts, run-bash-mutation.test.ts), which is scope this umbrella did not ask for. That choice resolves the reviewer's DECISION-NEEDED D-2 without taking either horn.

packages/core/hooks/pre-push.ts was deliberately not touched — the enforcement layer is maintainer-owned per the Artifact Ownership Contract.

The registration was proven to fire, not just to exist

• Selection: SWEEP_DIFF_OVERRIDE=packages/core/audit-self/first-steps-parity.test.ts bash scripts/run-local-ci-sweep.sh → [sweep] PASS first-steps-parity.
• Red arm: retitling one step in the render (Read the tier + degradation SSOT → Read the tier SSOT) → Tests 1 failed | 8 passed, diff - "read-tier-home :: Read the tier + degradation SSOT" / + "read-tier-home :: Read the tier SSOT". Reverted; tree restored byte-identical.

Verification

first-steps-parity 9/9 · principle 09 37/37 · run-audit.sh → «non-PORTABLE findings (none)», rules-autoload 28 rules · actionlint clean on the edited workflow · markdownlint 0 errors · Prettier clean.

Pre-existing red, not from this diff: npm --prefix packages/core run test:hooks fails (tsx-resolution / dup-detect / priority-score). Reproduced on a clean staging checkout with 11 failures before this branch existed; none of the failing files reference any file in this diff (grep → 0 hits each).

§1.7 Forward-check applied

Checked against the disciplines governing this change class. attention-is-not-a-mechanism §1 is the rule B2 violates and this PR satisfies: the fix is a deterministic gate at two channels rather than a named agent or a warning, and its firing was demonstrated (first-steps-parity.test.ts red arm above), because a registration whose red arm is never exercised is the same #hope-as-gate one level up. no-paid-llm-in-ci §1: the added workflow step is npx vitest, zero API calls, and it reuses the existing npm ci --prefix packages/core at .github/workflows/audit-self.yml:165 rather than adding an install. ci-tool-pinning §1 Rule A/B: no new tool install is introduced on any run: line, so neither pin rule is engaged. doc-authority-hierarchy §2-§3: no authority header changes — AI-USAGE-GUIDE.md:3-9 and INSTALL-FOR-AI.md keep theirs, and principle 09 is green at 37/37. CLAUDE.md PR strategy: the 5 MAJOR / 2 MINOR from the same review are surfaced, not fixed here.

§1.7 Backward-check applied

Two sibling sweeps were run over the change's classes rather than over this diff.

Class «shipped doc claiming --refresh deepens an install» — grep -rn -- "--refresh" across packages/core/templates/, INSTALL-FOR-AI.md, INSTALL.md, README.md filtered for deeper|deepen|upgrade in place|payload arrives returns exactly 4 lines: the 3 corrected sites (AI-USAGE-GUIDE.md:99, first-steps.source.json:83, INSTALL-FOR-AI.md:152) plus INSTALL-FOR-AI.md:162, which states the converse («a deeper install survives a shallower refresh») and is consistent with the presence-gating, so it is correct as written. SWEPT-CLEAN — no fourth copy of the false claim survives.

Class «test under packages/core/audit-self/ with no runner» — each file was checked against .github/, .husky/, scripts/, both package.jsons. In the vitest peer group: audit-ai-docs.test.ts 1 runner, md-line-gate.test.ts 1, first-steps-parity.test.ts 2 after this PR (was 0), and hooks-tree-guard.test.ts 0 · run-bash-mutation.test.ts 0 — GAP-FOUND, the same defect class as B2, pre-existing and outside this umbrella, surfaced here rather than swept in (this is precisely the scope growth the by-name registration avoids). The *.sh entries reporting 0 are not the same class: they are shipped consumer-side scripts that run on the consumer's machine, not framework CI gates.

Not addressed here (surfaced, not fixed)

The review also returned 5 MAJOR and 2 MINOR, all outside these two BLOCKERs and none of them regressions from this diff — most notably setup.d/lib.sh:241-254 never converging a destination that holds two of our fences, and install.sh:594,1105 still telling the consumer that AGENTS.md was not touched after S1 made it co-owned. They are recorded in the meta-launch state log for an explicit routing call rather than folded in here (CLAUDE.md PR strategy: no drive-by scope expansion).

Fidelity verdict

FIDELITY: GO
Basis: .claude/orchestrator-prompts/beta-ai-docs-agnosticism-meta-launch/kickoff.md §7 (the REVISE route this PR executes) + the two BLOCKERs of the Phase -1 review of 744bb06
Round: 2
Audited-SHA: 750af3f
Evidence: packages/core/templates/shared/AI-USAGE-GUIDE.md:97 — the env install step now names the plain deeper-profile re-run, and the --refresh sentence states the measured limit rather than the reverse; the claim was re-measured on a temp consumer before being written (--refresh --profile env → tier-home NO / arch NO at exit 0; --profile env → both YES, core md5s unchanged). packages/core/templates/shared/first-steps.source.json:83 — the SSOT half carries the same corrected action, and its evidence field now cites install.sh:1076 plus the measurement, so the render and its source cannot drift apart on this step. INSTALL-FOR-AI.md:152 — the upstream copy of the same claim, corrected with the sharper finding that --refresh --profile factory deepens PARTIALLY (AIF suite yes, tier-home and arch no), which is why the instruction is now a plain deeper-profile re-run for every depth. .github/workflows/audit-self.yml:178 and scripts/run-local-ci-sweep.sh:60 — the parity gate registered by name in two channels; proven live rather than assumed, [sweep] PASS first-steps-parity on selection and Tests 1 failed | 8 passed on a seeded retitle, then reverted to a byte-identical tree. Gates re-run at this SHA: first-steps-parity 9/9, principle 09 37/37, run-audit.sh «non-PORTABLE findings (none)» with rules-autoload at 28 rules, actionlint clean. Round 2 adds the snapshot regeneration the round-1 CI surfaced (shard C, «Result: 4 pass / 11 fail», every diff the single .ai-factory/AI-USAGE-GUIDE.md line that the B1 fix moved): tests/install-sh/baselines/ts-server/greenfield.fingerprint:1 and its 10 siblings were regenerated with SNAPSHOT_MODE=capture and audited for swept-in drift — 11 added / 11 removed lines, all of them that one path — after which SNAPSHOT_MODE=compare returns 15 pass / 0 fail.

Provenance

Stage S1 follow-up of umbrella beta-ai-docs-agnosticism. Reviewed-SHA 744bb06e35. Meta-launch: .claude/orchestrator-prompts/beta-ai-docs-agnosticism-meta-launch/kickoff.md §7. Base staging @ 8d092f1f64.

Prior-art: skipped — defect fix against a merged stage, no new capability; the parity and fence capabilities already exist and are unchanged here.