fix(beta-ai-docs-agnosticism): repair the refresh claim the Phase -1 re-review measured false - #1332
Merged
Merged
Conversation
…re-review measured false The re-review of #1329 returned REVISE: B2 CLOSED, zero regressions, but B1 only partially closed — the replacement sentence had itself gone false. #1329 wrote «`--refresh` never deepens an install, so `--refresh --profile env` on a `core` project is a no-op that still exits 0». That was true against its base (8d092f1) and false by the time it merged: #1327 landed ~20 minutes earlier and added a worktree-scripts refresh arm at install.sh:1001-1005 with NO profile check, while its delivery site documents `PROFILE=core → skip` (setup.d/85-worktree-scripts.sh:19-22). Re-measured against staging on a core consumer: `--refresh --profile env` → exit 0, tier-home NO, arch NO, but create-worktree.sh, worktree-node-modules.sh, link-coordination.sh and getff-work.sh all ARRIVE. Not a no-op. The claim is now stated so it holds whichever way the underlying defect is resolved: `--refresh` re-delivers fixes to what you already have and does NOT reliably deepen an install — no «never», no «no-op». The ungated arm is surfaced in INSTALL-FOR-AI.md as what a consumer actually observes, and attributed to beta-delivery-ux rather than fixed here (different umbrella; gating it is that umbrella's call). Also corrected, all measured rather than copied: - «core artefacts stay byte-identical» → every pre-existing core file IS byte-identical except .prettierignore, whose managed block gains the newly-shipped paths (verified by md5 manifest across a core→env deepening). - Stale line citations from the merge-forward: the F7 gate is install.sh:678, not 669-671 (that range is the core skills loop); the tier-home presence gate moved to install.sh:1090-1093. Verified: first-steps-parity 9/9 · principle 09 37/37 · SSOT parses · run-audit.sh «non-PORTABLE findings (none)» · baselines regenerated (11 added / 11 removed, all the one AI-USAGE-GUIDE.md path) · SNAPSHOT_MODE=compare 15/15. Prior-art: skipped — corrects a factual claim in shipped docs, no new capability.
This was referenced Aug 9, 2026
Merged
10 tasks
artyhoo
added a commit
that referenced
this pull request
Aug 17, 2026
…ll slugs (#1312, #1334) (#1412) ## Summary `do_refresh` had drifted from the install arm in **both** directions, and the two directions are the two issues this PR closes. #1312: three skill slugs shipped on install but reached no refresh loop — `arch` (in none at all), `claude-glm-executor-handoff` (factory install loop only), and `rule-tests`, which the refresh header **announced** and then skipped because its payload lives under `.claude/skills/`, not `skills/`. #1334: the worktree-scripts arm carried no profile check at all, so any `--refresh` on a `core` project delivered four `env+` artefacts — the inverse defect, and one that makes «what does `core` contain» unanswerable from `--profile` alone. Both are the same seam, so both get the same resolution: **every depth-gated refresh arm now uses the delivery site's own profile predicate OR presence-on-disk** (presence = prior opt-in, the brownfield upgrade path), and the per-tier slug lists collapse into one shared constant each so the two arms cannot drift again. ## Changes - **`setup.d/lib.sh:58-60`** — `GETFF_SKILLS_CORE` / `_ENV` / `_FACTORY`: the slug lists as an SSOT read by both arms. Issue #1312's own suggested direction #1; the three drifts it measured were three copies of one list, not three bugs. - **`setup.d/10-skills.sh:113/127/133`** — the install arm reads the constants; its `▶ Contour surface` / `▶ AIF operator suite` announcements render from them too. - **`install.sh:684-701`** — the refresh arm reads the same constants, in three loops with three gates: core unconditional, env+ (`env|factory|WITH_AIF_SUITE` OR presence), factory (`factory|WITH_AIF_SUITE` OR presence). `arch`, `pipeline` and `claude-glm-executor-handoff` are refreshed for the first time; `rule-tests` moves here from the plain-copy loop, where its source path could never resolve. - **`install.sh:643`** — the plain-copy header renders from `_PLAIN_SKILLS`, so it can no longer announce a slug the loop does not carry (#1312's honest-signals half). - **`install.sh:1030`** — the worktree-scripts arm gains the gate it never had (#1334). Presence probe is `scripts/create-worktree.sh`: the cluster's load-bearing entry point, present in every version of it, and the four ship together by construction — so a consumer who opted in before `getff-work.sh` joined the cluster still receives it. - **`install.sh:1128`** — tier-home moves from presence-ONLY to the same uniform gate. Without it, `--refresh --profile env` would deepen some arms and not others: the «each arm decides for itself» state `INSTALL-FOR-AI.md` previously had to describe in a paragraph. Named in #1334's own arm table as part of this decision. - **`tests/install-sh/consumer-upgrade-path.test.sh:447-612`** — TESTs 8-11, the behavioural gates: core refresh delivers no deeper artefact (#1334), a bare `--refresh` keeps an already-opted-in factory payload fresh (#1312), the `▶ Skills` header cannot announce what the run does not touch, and `--refresh --profile env` DOES deliver — which is the paired-negative for TEST 8's absence claim (same paths, same tree, present as soon as the profile says so). - **`tests/install-sh/refresh-covers-full-delivery.test.sh:296-345`** — extends the existing parity gate (added by #1327 for the same worktree cluster) rather than adding a parallel one: both arms must READ every tier constant, and neither may carry a literal-slug `for _skill in` loop (a fourth copy). Two paired-negative arms. - **`INSTALL-FOR-AI.md:152/160-166/444`** — re-measured. The old text documented both defects as consumer-observable behaviour; leaving it would have made the shipped doc lie in the opposite direction. ## Prior-art consult - [x] Not a capability commit per [CLAUDE.md «What is a capability commit?»](../CLAUDE.md) — no new dependency, no new file (all four touched files existed), nothing under `packages/`. Commit carries the escape-hatch trailer with rationale. - [x] No new capability area surfaced: the fix reuses the gate shape already in this function (`install.sh:621` agents arm, F7 skills arm) and the parity-test precedent from #1327. - [x] n/a — no SSOT entry matched or needed. - [x] n/a — no new capability area, so no context7 pass claimed. ## Test plan - [x] `bash tests/install-sh/consumer-upgrade-path.test.sh` — RED baseline before the fix: `PASS=37 FAIL=7` (the four worktree scripts leaking onto a core refresh ×2 arms; `arch`, `rule-tests`, `claude-glm-executor-handoff` stale after a bare refresh; the announced-then-skipped `rule-tests`; `arch`/`pipeline`/`tier-home` missing under `--refresh --profile env`). After: **`PASS=44 FAIL=0`**. - [x] `bash tests/install-sh/refresh-covers-full-delivery.test.sh` — before: `PASS=9 FAIL=2`; after: **`PASS=13 FAIL=0`** (both new checks plus their negatives). - [x] `SNAPSHOT_MODE=compare bash tests/install-sh/snapshot.sh` — exit 0, baselines unchanged (the install arm ships the same bytes; only its source of names moved). - [x] Full `tests/install-sh/*.test.sh` battery — see the run summary in the review findings section. - [x] `shellcheck --exclude=SC2034,SC2016,SC2317 setup.d/*.sh install.sh` — exit 0 (CI's exact invocation, `.github/workflows/audit-self.yml:804`). - [x] Manual smoke: `--profile core` install → bare `--refresh` → `--refresh --profile core` → `--refresh --profile env`, asserting the depth boundary at each step (this is TESTs 8/11 run end-to-end against real installs, not a mocked harness). ## Provenance n/a — issue-driven fix, not a stage PR. Base: `staging` @ `049b35e851`. In-session (no aif substrate). ## Review findings n/a — see Test plan for the RED→GREEN evidence. ## Fidelity verdict FIDELITY: skipped — issue-driven bug fix with no kickoff or spec stage behind it; the acceptance contract is the two issue bodies (#1312, #1334) plus the paired-negative gates listed in the Test plan. ## Parked questions n/a ### §1.7 Forward-check applied Checked against the disciplines this diff touches. [`dual-implementation-discipline.md §7`](../.claude/rules/dual-implementation-discipline.md) (single source of truth): the two hand-maintained slug lists collapse to `setup.d/lib.sh:58-60`, read by `setup.d/10-skills.sh:113` and `install.sh:684` — the duplication that drifted three times is gone rather than re-asserted. [`attention-is-not-a-mechanism.md §1`](../.claude/rules/attention-is-not-a-mechanism.md): every claim in this PR lands on a deterministic channel — the depth boundary on `tests/install-sh/consumer-upgrade-path.test.sh:447`, the announce↔deliver honesty on `:554`, the SSOT-consumption invariant on `tests/install-sh/refresh-covers-full-delivery.test.sh:296`; none of them is «a reviewer will read the diff». [`no-paid-llm-in-ci.md`](../.claude/rules/no-paid-llm-in-ci.md): the new gates are bash + real installs, zero API calls. [`effort-worthiness.md §1`](../.claude/rules/effort-worthiness.md): `build-and-verify` contour — a reversible installer change verified live against real consumer trees, no research-grade round. [`evidence-regeneration.md`](../.claude/rules/evidence-regeneration.md): `INSTALL-FOR-AI.md:160` was a dated measurement of the old behaviour, so it was re-measured (2026-08-17) instead of silently inherited. ### §1.7 Backward-check applied Swept every profile-gated install layer for its refresh counterpart, not just the two the issues named: `setup.d/20-agents.sh:39` (suite agents) → gated arm exists at `install.sh:621`; `setup.d/20-agents.sh:70` (skill-context) → gated arm exists at `install.sh:1146`; `setup.d/30-templates.sh:108` (tier-home) → was presence-only, unified here; `setup.d/85-worktree-scripts.sh:34` (worktree cluster) → the #1334 defect, fixed here; **`setup.d/55-runtime-bridge-vendor.sh:65` (factory vendor payload) → has NO refresh arm at all** — a pre-existing #1312-class gap, outside both issues' scope, so it is recorded in `INSTALL-FOR-AI.md:166` as install-only rather than silently fixed in this PR. Also swept for stale claims about the changed behaviour: `grep -rln "create-worktree\|getff-work.sh" tests/` → only the file updated here; `grep -rn 'for _skill in' setup.d install.sh` → no literal-slug loop survives (now asserted); `INSTALL-FOR-AI.md:152/160-166/444` were the only prose stating the old semantics, and #1329's weakened claim (repaired in #1332) still holds under the new behaviour. Closes #1312 Closes #1334
6 tasks
artyhoo
added a commit
that referenced
this pull request
Sep 2, 2026
…merge (#1569) (#1570) ## Summary Closes the `beta-ai-docs-agnosticism` umbrella. S4 merged as #1569 (squash `1d382d4783`) and was the last stage, so this adds the `done.md` closure marker — the load-bearing Layer-C3 signal `priority-score.sh` reads as `basis=done-md` (`docs/meta-factory/operational-conventions.md` §1, umbrella closure convention). One new file, no code, no behaviour change. ## Changes - **`.claude/orchestrator-prompts/beta-ai-docs-agnosticism/done.md`** (new, 79 lines) — the closure marker, plus two things worth carrying out of the umbrella: - **A stage table with the REAL head branch names.** S2 and S3 ran through the aif runtime, which mints `feature/<slug>-<id>` and exposes no branch override in `dispatch.ts` or `harvest.ts`. The meta-launch Stage-2→3 entry gate greps the kickoff's *predicted* names, so `gh pr list --search "is:merged head:beta-c-s2-skills-probe base:staging"` returns `[]` for both stages even though both landed. The marker says so explicitly, so the next reader does not re-run that grep and conclude the stages never merged. Landing was verified by substance: `git merge-base --is-ancestor 7534fd9 origin/staging` and the same for `ee0ccfe593`. - **The owner-parked residue**, copied out of the three stage PRs' `## Parked questions` sections rather than left to rot there: S3's `aif-version` fork and the `claims-conformance-auditor` skip-list follow-up, S2's drifted `tier-home.md` citation and census boundary, and S4's two maintainer-only Context7 legs, its Phase-2 flip proposal, and the three couplings that still need a gate in files those stages were not permitted to touch. Also synced to the coordination canon at `~/.claude-coordination/rules-as-tests-aif/beta-ai-docs-agnosticism/done.md` (`/dispatcher` §2.8). That path is machine-local and not part of this diff. ## Umbrella stages | Stage | PR | Squash | |---|---|---| | S1 — AGENTS.md layer + AI Usage Guide (C1) | #1311 | `744bb06e35` | | S1b — Phase -1 BLOCKER fixes | #1329 | `501af27ea5` | | S1c — refresh-claim repair | #1332 | `ebb974afde` | | S2 — skills agnosticism probe (C3) | #1552 | `ee0ccfe593` | | S3 — self-generating docs sweep (C5) | #1550 | `7534fd9a48` | | S4 — discoverability (C4) | #1569 | `1d382d4783` | ## Verification ``` $ git ls-files -s .claude/orchestrator-prompts/beta-ai-docs-agnosticism/done.md 100644 0435de2 0 .claude/orchestrator-prompts/beta-ai-docs-agnosticism/done.md ``` Mode `100644`, not `120000` — the coordination hook adopts new untracked files under that directory and replaces them with symlinks within about two minutes, so the file was written and staged in one step and the mode checked afterwards. ``` $ wc -l .claude/orchestrator-prompts/beta-ai-docs-agnosticism/done.md 79 ``` Under the 600-line markdown gate. `markdownlint-cli2` at pre-commit: `Summary: 0 error(s)`. Pre-push gates green on the push of this branch. ## Prior-art consult - [x] Not a capability commit — one markdown file, no dependency, nothing under `packages/`. The commit carries `Prior-art: skipped — closure marker for a completed umbrella, no capability and no code.` - [x] No new capability area surfaced; no SSOT entry needed. S4's own capability entry is row **264**, added in #1569. ## Test plan - [x] `git ls-files -s` confirms mode 100644 - [x] `markdownlint-cli2` green at pre-commit - [x] Pre-push gate battery green - [x] Every PR number and squash SHA in the table read from `gh pr view --json mergeCommit`, not from memory ## Provenance n/a — not a stage PR. This is the closure marker written by the session that merged the umbrella's final stage, per the umbrella closure convention. ## Review findings n/a — docs-only closure marker. Its factual content (six PR numbers, six squash SHAs, six head branch names) was read from `gh pr view --json number,title,mergedAt,mergeCommit,headRefName` for each PR, and the two ancestry claims from `git merge-base --is-ancestor`. ## Fidelity verdict FIDELITY: skipped — closure marker for an already-merged umbrella; no kickoff governs it, no deliverable to audit against, and the diff is one new markdown file with no code and no behaviour change. ## Parked questions n/a — this PR resolves nothing and decides nothing. The umbrella's open items are recorded IN the new file as owner-parked residue, deliberately carried forward rather than closed. ## §1.7 Self-discipline check ### §1.7 Skipped: mechanical closure marker for a merged umbrella — one new markdown file under .claude/orchestrator-prompts/, no discipline rule introduced or extended, no rules/principles/EXECUTION-PLAN/prior-art/CLAUDE.md path touched, and no behaviour change anywhere in the tree.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What + why
The Phase -1 re-review of #1329 (the fix that closed S1's two BLOCKERs) came back REVISE:
B2: CLOSED,Regressions introduced: 0, butB1: PARTIALLY CLOSED— the replacement sentence had itself gone false between authoring and merge. This PR repairs it. It closes the §7 REVISE loop; Stage 2 stays halted until this lands and the re-review returns GO.The defect
#1329 shipped: «
--refreshre-delivers fixes at your current depth — it never deepens an install, so--refresh --profile envon acoreproject is a no-op that still exits 0.»That was true against its base
8d092f1f64and false by the time it merged. #1327 (beta-delivery-ux S2) landed ~20 minutes earlier and added a worktree-scripts refresh arm with no profile check:— while the delivery site it mirrors documents the opposite (
setup.d/85-worktree-scripts.sh:19-22, «PROFILE=core→ skip (core lacks the workspace surface)»).Re-measured against
origin/stagingon a freshcoreconsumer:--refresh --profile env.ai-factory/tier-home.md.claude/skills/arch/scripts/create-worktree.shscripts/worktree-node-modules.shscripts/link-coordination.shscripts/getff-work.shNot a no-op.
The fix
The claim is restated so it holds whichever way the underlying defect is resolved — no «never», no «no-op»:
--refreshre-delivers fixes to what you already have and does not reliably deepen an install, with the concrete consequence named (tier-home.mdandarchstay absent while it exits 0). If the ungated arm is later gated, this text stays true; if it is not, it stays true.The ungated arm itself is surfaced, not fixed — it is a beta-delivery-ux artefact and gating it is that umbrella's call (the re-review raised exactly this as a cross-umbrella DECISION-NEEDED).
INSTALL-FOR-AI.mdrecords it as what a consumer actually observes, since a doc this umbrella owns cannot honestly describe the upgrade surface while omitting it.Also corrected — each measured, not copied forward
core → envdeepening: exactly one pre-existing file changes,.prettierignore, whose managed block gains the newly-shipped paths. Both docs now say so.install.sh:678(the cited669-671is the core skills loop), and the tier-home presence gate moved toinstall.sh:1090-1093.Verification
first-steps-parity9/9 · principle 09 37/37 · SSOT parses as JSON ·run-audit.sh→ «non-PORTABLE findings (none)» · markdownlint 0 errors · Prettier clean.Baselines regenerated with
SNAPSHOT_MODE=captureand audited for swept-in drift before committing: 11 added / 11 removed lines, every one the.ai-factory/AI-USAGE-GUIDE.mdpath;SNAPSHOT_MODE=compare→ 15 pass / 0 fail.§1.7 Forward-check applied
The rule this PR is an instance of is the umbrella's own thesis — a shipped doc must describe what is on disk today. The repair was therefore driven by measurement against
origin/staging(six install probes) rather than by editing prose to match the previous sentence's intent;packages/core/templates/shared/AI-USAGE-GUIDE.md:19-22states that a section describing something that does not exist is a lying doc, and a «no-op» claim about a command that writes four files is that. doc-authority-hierarchy §2-§3: no header changed, principle 09 green 37/37. no-paid-llm-in-ci / ci-tool-pinning: no workflow or install command touched at all in this diff. CLAUDE.md PR strategy: the root-cause defect (install.sh:1001-1005) belongs to beta-delivery-ux and is surfaced rather than fixed here;docs/meta-factory/research-patches/2026-07-25-beta-a-s1-inventory.md:353-355still carries the original false table but is owned by its discovering session per the Artifact Ownership Contract, so it is reported, not rewritten.§1.7 Backward-check applied
Class «claim about what
--refreshdelivers» — re-swept after the repair.packages/core/templates/shared/AI-USAGE-GUIDE.md:97-102andfirst-steps.source.json:83now carry the measured form;INSTALL-FOR-AI.md:152states the instruction and:160the per-arm breakdown;INSTALL-FOR-AI.md:162(«a deeper install survives a shallower refresh») was re-confirmed correct and left alone.GAP-FOUND, surfaced not fixed:install.sh:675-677's inline comment still recommends--refresh --profile factoryas «the upgrade-path mechanism», which now contradicts the docs — installer-owned prose, and correcting it belongs with the gating decision above.Class «pre-existing core artefact changed by a deepening» — the md5 manifest was diffed in full rather than spot-checked (
.prettierignorethe only hit), which is what turned the byte-identical sentence from an inherited assumption into a measured one.Fidelity verdict
FIDELITY: GO
Basis: Phase -1 re-review of #1329 —
B1: PARTIALLY CLOSED(MAJOR 1) plus its MINOR 1/2 citation findings; meta-launch kickoff §7 REVISE routingRound: 1
Audited-SHA: a500837
Evidence: packages/core/templates/shared/AI-USAGE-GUIDE.md:97 — the step no longer claims «never deepens» or «no-op» and instead names the observable outcome, which is the form that survives either resolution of install.sh:1001-1005; first-steps.source.json:83 carries the identical claim so the parity gate holds the two renders together (9/9). INSTALL-FOR-AI.md:160 — per-arm breakdown with the citations re-derived against staging (F7 gate install.sh:678; tier-home gate install.sh:1090-1093) rather than carried over from the pre-merge line numbers. The «not a no-op» finding was reproduced independently before the edit: a fresh core consumer, then
--refresh --profile env→ exit 0 with tier-home NO / arch NO but all four of create-worktree.sh, worktree-node-modules.sh, link-coordination.sh, getff-work.sh present. Baselines: 11 added / 11 removed lines, all.ai-factory/AI-USAGE-GUIDE.md,compare15/15.Provenance
Stage S1 second follow-up of umbrella
beta-ai-docs-agnosticism, closing the Phase -1 re-review of #1329. Meta-launch:.claude/orchestrator-prompts/beta-ai-docs-agnosticism-meta-launch/kickoff.md§7. Basestaging@501af27ea5.Prior-art: skipped — corrects a factual claim in shipped docs, no new capability introduced or changed.