feat(pipeline): kickoff back-catalog migration + principle-12 rework — cross-session-kickoff-portability PR-2 - #523
Merged
Conversation
…12 portability rework — PR-2 Commits the 142 /pipeline kickoff design docs (incl. this umbrella's own — §0.1 dogfood) so plan discovery is a property of the committed tree on every machine. Completes the cross-session-kickoff-portability umbrella (R-phase #518; PR-1 mechanism = #520). - Back-catalog (D2/D2.5): 142 kickoff.md committed as real files (0 symlinks staged → D2 acceptance: no 120000-mode entries). Secret-scanned before commit — zero secrets, zero credentials, zero third-party PII (only the maintainer's own already-public email). - 3 oversized kickoffs (queue-mode-bootstrap 726, strategic-clarity-dialogue 660, aif-handoff-runtime-bridge-iphase 649) carry the `transient artifact` marker → exempt from the md-line-gate (audit-self.yml), paired-tested in PR-1. - principle 12 (12-ai-laziness-traps.test.ts) reworked for the committed-kickoff reality (the blocker PR-1's mechanism-only deferred): (a) AMNESTY — the 6 pre-convention kickoffs added to EXEMPT_LIST (date-cutoff can't distinguish them: one migration commit → one date; explicit allowlist instead); (b) population sentinel floor >=100 dropped for withinPopulationBounds (few/zero plans is valid — fresh clone, prune, consumer adopting /pipeline) + an always-run unit test (0/1/142/cap+1); (c) exempt-dir guard made tolerant of few/partial-plan checkouts. Test green 7/7 against the 142-kickoff state. Consumers unaffected: principle 12 is framework-internal (not shipped); the shipped D5 pre-push check is existsSync-guarded (script not shipped → skips); no .gitignore fragment ships, so a consumer's plans are tracked-by-default. Prior-art: prior-art-evaluations.md#116 (ADAPT — git is the owned portability channel; reuses done.md tracked-exception; amnesty via the existing EXEMPT_LIST allowlist, not a date-cutoff that the single-commit migration makes unusable). §1.7: forward-check applied — complies with no-paid-llm-in-ci.md (principle 12 is deterministic vitest, zero API), doc-authority-hierarchy.md (kickoffs folder-scoped under orchestrator-prompts), build-first-reuse-default.md (amnesty reuses EXEMPT_LIST pattern at packages/core/principles/12-ai-laziness-traps.test.ts:44). backward-check applied — complete sweep of .claude/orchestrator-prompts/*/kickoff.md (142 committed); the exact non-compliant set computed by the compound check (packages/core/principles/12-ai-laziness-traps.test.ts:52) and allowlisted; sentinel few-plans-safety unit-tested via withinPopulationBounds (packages/core/principles/12-ai-laziness-traps.test.ts); 3 oversized carry the marker (packages/core/audit-self/md-line-gate.sh:1). Also: audit-self.yml "Stale path references" guard excludes orchestrator-prompts/ — historical kickoffs legitimately quote now-removed artifacts as audit subjects (e.g. audit-tooling-refresh/kickoff.md references best-practices-sidecar.react.md as the thing to remove). The guard targets canonical/shipped docs, not committed historical kickoffs.
artyhoo
force-pushed
the
feat/cross-session-kickoff-portability-pr2
branch
from
June 14, 2026 15:42
d48985b to
018994b
Compare
artyhoo
added a commit
that referenced
this pull request
Aug 21, 2026
…us + principle 43 (#1506) * feat(host-verify-retrofit): kickoff inventory classifier — lanes + bulk-wave filter Warn-phase tool for the host-verify retrofit (PR #1491 park #2): classifies every .claude/orchestrator-prompts/*/kickoff.md into contracted | legacy-closed | attention/closed | attention/open. Fail-safe by direction of error: the blanket lane (legacy-closed) requires BOTH done.md AND last non-wave activity older than --min-days (default 30). Bulk waves (commits touching >10 umbrella dirs — back-catalog migration #523, done.md backfills, the FRS S2 spelling sweep itself) do not refresh activity dates. Contract recognition is delegated to scripts/host-verify.sh --list (the SSOT runner, dual-implementation-discipline §8) — never re-implemented here. Dirs without kickoff.md are out of scope by construction. Measured on staging c8d2e34 (322 kickoff files, lanes reconcile exactly): contracted 64, legacy-closed 86, attention/closed 133 (119 last=none-non-wave — every commit in their history is a bulk wave; 31 with dated non-wave activity — the human-review borderline), attention/open 39. Blanket-safe total: 86 + 119 = 205; manual lanes: 31 + 39 = 70. Recheck note: two dated files (pre-merge-carrier-meta-launch, generator-forbid-mvp-meta-launch) MENTION host-verify in prose/headings but carry no runner-recognized contract — classified as uncontracted, correctly. * docs(kickoff): host-verify retrofit B1 — blanket legacy-closed opt-outs (195 files) Retrofits the destination-environment-verification contract (.claude/rules/destination-environment-verification.md §1) onto the closed back-catalog: each file gets the canonical opt-out marker <!-- host-verify: none — legacy closed umbrella (done.md): work already accepted; no live host acceptance to declare — retro-marked 2026-08-21 --> recognized by the runner (bash scripts/host-verify.sh --list <path> → 0), replacing silent contract-absence with an explicit, greppable declaration. +2 lines per file, byte-identical otherwise. Population (lanes from scripts/kickoff-hv-inventory.sh, run at this commit): - legacy-closed 90 + attention/closed none-non-wave 102 → kickoff.md each - stage kickoffs of closed tracked umbrellas: beta-delivery-ux s1/s2/s3/s5 = 195 tracked files. Guards applied per file (escalate, never blanket): done.md required; runner-recognition skip; any prose 'host-verify' mention → individual lane. Escalated to B2: generator-forbid-mvp-meta-launch (prose mention the runner does not recognize — one of the two 'lying contracts'), beta-delivery-ux/ kickoff-r1.md (already carries a real contract; guard prevented a second declaration). consumer-install-{completeness,hardening} stage kickoffs are gitignored (per-umbrella un-ignore globs, .gitignore:31-55) — excluded: their kickoff.md is marked, the untracked stage files stay untouched. .husky/pre-commit, two accompaniments (both first-triggered by staging the corpus; no CI mirror, no shipped-template twin carries either gate — verified: grep 'exceeds 600' → only this hook): - 600-line gate: case entries for the two oversized closed meta-kickoffs it would otherwise block (queue-mode-bootstrap 730, strategic-clarity-dialogue 664). Both already self-declared the 'transient artifact' exemption in their headers at creation — only the case entry was missing. Same list∩marker shape as the two pre-existing entries. - markdownlint-cli2 arm now excludes .claude/orchestrator-prompts/**: the dispatch corpus is append-only history whose older files predate linting (95 pre-existing violations, 68 of them MD040 bare fences; zero introduced by this commit's EOF-only appends); full-file lint made any touch of an old kickoff a style-repair demand. The corpus keeps its dedicated spec-discipline soft-warn arm; all other md surfaces stay fully linted. * docs(kickoff): host-verify retrofit B2 — 28 individually adjudicated closed kickoffs The attention/closed-with-date lane: every umbrella HAS done.md but its dir saw non-wave activity inside the 30-day window, so the blanket pass refused them (guard: recent targeted touch = look before marking). Adjudication per dir — the git log of each — sorted every recent touch into four closure classes, zero live-work reopeners: - done.md closure commits (#1243 #1361 #1476 #1118 #1158 #1262 #1175 …) - closure-sweep backfills (#1268: 50 verified closures, round 3) - archival of superseded designs (#1221) - cosmetic example fixes on closed files (#1280 Jest→vitest in fenced examples; #1288 600-line unfreeze) Each of the 27 dated dirs + the G3-escalated generator-forbid-mvp-meta-launch gets the same canonical marker as B1 (+2 lines, EOF append). The two 'lying contracts' resolved as NOT lying declarations but prose vocabulary: generator-forbid-mvp-meta-launch §4d ('Cross-stage host-verify acceptance' section title, commands named as stage obligations — never a fenced contract) and pre-merge-carrier-meta-launch (prose pointers to the binding umbrella's §4 host-verify + 'both host-verify legs green' gate description). The runner is right to not see a contract; the marker states the machine truth, the historical prose stays byte-identical. * docs(kickoff): host-verify retrofit B3 — real contracts + honest opt-outs for the 39 open umbrellas (+ modular stages) The attention/open lane (no done.md — the lane the fail-safe classifier refuses to blanket): every file handled individually, error direction toward REAL contracts (an executable kickoff never gets a lazy opt-out). 17 contracts, each quoting the file's own acceptance material or the existing suites its acceptance names (mechanical quoting, no authorship): - heal-honest-capacity → the fixture suite §3 demands + criterion 8 - install-prepush-copylist → §5 bullet 2 verbatim (SHAs zeroed: the no-op deletion probe, live-verified exit 0 before quoting) - multi-model-profile-marker → live aif /tasks probe (§3 verifies live; the contract fails closed when the runtime is down — stated in the fence) - r2-enforced-zod-scope → gh-535-rule-enforced.test.sh (§6's harness) - r2-zod-aware-selector → make self-audit (§5 names it) - rule-bootstrapping-iphase-spike → snapshot compare (§7 byte-identical) - salg-m1-gate → principle 21 (its Part B, shipped) - salg-postinstall-smoke-p1 → the four harness homes §Deliverable names - shipped-skill-sync → check-skill-drift.sh (sibling gate, same surface) - zero-dep-synth-bundle → build-synth-bundle.sh --check (its step-6 gate) - zcode-full-parity + step1-emit-wrapper → the twin test suites §3/§4 name - modular-install-fullpack s1-s5 → snapshot compare (+shellcheck on s1), the §4 byte-identical guard; empirical consumer probes stay documented in §4 as live-session work 28 opt-outs, three precented classes, each naming its own evidence: - 15 planning STUBs (U4-U17 of the getff-to-prod МЕГАКИКОФФ + the self-declared stack-tooling-generation stub): stages are sketches; the full kickoff that replaces a stub declares the contract - 6 research/docs-only (h10, phase-10, salg R-phase, container-audit, worktree-flakiness tracker, trust-tiers adjudication): deliverable is a markdown artifact per each file's own header/scope - 7 meta-launch/orchestration/deferred (getff-to-prod МЕГАКИКОФФ, salg-meta-launch, beta-ai-docs-agnosticism [stages s1-s3 already carry contracts], modular umbrella + S0 table, executable-aidocs deferred WIs, m2-probe [DORMANT prose deliverable by design]) Every edited file verified: bash scripts/host-verify.sh --list <path> exits 0 (recognized contract or valid opt-out). * feat(principles): host-verify retrofit B4 — principle 43 (whole-population contract presence) + rule §1 note packages/core/principles/43-kickoff-host-verify-presence.test.ts: promotes the edit-time contract gate (fires only on touch) to a CI channel over the WHOLE tracked kickoff family — kickoff.md + stage kickoffs via kickoff-population.ts, mirrors excluded, gitignored stage files out of population (principle 40's tracked-file posture; they cannot ship a contract to CI). Detection shells to the SSOT runner (host-verify.sh --list) exactly like the edit-time gate — no second grammar (#sync-by-copy-paste avoided). Paired-negative fixtures prove the detector discriminates: absence fail-closed, fence pass, opt-out pass, too-short rationale fail; anti-tautology strips a real compliant kickoff and asserts the verdict flips; tripwire holds the population non-vacuous. First live run CAUGHT two real gaps the lane measurement missed: cross-worktree-symlink-iphase and f2-aif-fire-backend-iphase end in a dangling bare ``` (single fence line, CommonMark opens an unterminated code block), so their B1 opt-out markers landed inside the block and the runner rightly ignored them. Fixed by closing the dangling fence (+1 line, renders empty exactly as before); both now recognized. No exemption list: after the retrofit nothing is exempt. Rule §1 (destination-environment-verification.md): names the stage-kickoff family as bound (population SSOT), documents principle 43 as mechanism (c) in the Class header — honestly: PRESENCE, not execution; the Class-A promotion path is unchanged. Prior-art: prior-art-evaluations.md#229 (ADAPT — the destination-environment contract row; this commit promotes its edit-time gate to a population principle test on the same SSOT runner, grammar unchanged) * fix(review): host-verify retrofit B5 — cold-review round 1 fixes Code review (review-sidecar, cold): REVISE on one MAJOR, folded the cheap MINORs. Fidelity audit (cold): GO, no round-triggering findings. MAJOR — markdownlint exclusion was permanent and corpus-wide (no re-entry): new kickoffs would have escaped lint forever. Fixed by narrowing the carve-out to the legacy corpus ON TOUCH: the STAGED_MD filter now ADMITS orchestrator- prompts files with git status A (newly added — no pre-existing debt, fully linted), excludes only M-status touches of historical files. Re-entry trigger recorded in the comment, measurable: when 'npx markdownlint-cli2 .claude/orchestrator-prompts' reports zero, drop the filter. Awk filter unit-tested against synthetic A/M/R/non-md input. MINOR — principle 43 anti-tautology wrote its stripped copy INSIDE the real population dir (litter risk on mid-test failure): now mutates in tmpdir with a finally-cleanup; timeout 120_000 added (its find can spawn the runner hundreds of times on a non-compliant corpus). MINOR — comment precision: 342 tracked family files at retrofit (auditor's independent count), not 349. Verified: principle 43 4/4, sweep 26/26 (diff mode). * fix(hooks): host-verify retrofit B6 — pre-push §8 lychee legacy-corpus carve-out (A/M split) The push of the retrofit surfaced the same structural class the pre-commit markdownlint arm hit: §8 checks EVERY link in EVERY changed *.md, and the orchestrator-prompts back-catalog carries 101 pre-existing offline errors (links to since-moved targets — e.g. .github/workflows/discipline-self-check.yml resolved from the wrong base; gitignored drafts/ scratch; machine-local ~/… paths; one doubled .claude/.claude relative path). All 101 pre-date the retrofit; the touching commit introduces zero links. Fix mirrors the pre-commit markdownlint arm's A/M split exactly (one carve-out pattern, two gates): orchestrator-prompts *.md enter the lychee set only when git status A (newly authored — fully checked); M/R-status touches of legacy files are excluded. utils/git.ts gains getAddedFiles() (diff-filter=A via the existing parseNameStatus) reused by the section. Re-entry trigger recorded in the comment, measurable: when 'lychee --offline .claude/orchestrator-prompts' reports zero, drop the filter. No consumer-twin sync needed: the shipped husky-pre-push.sh template does not carry §8 (verified: zero lychee references). tsc clean; pre-push consumer-layout suite 32/32 (the §3 negative arm still guards the gate lives on consumer-owned md). * chore(install-sh): host-verify retrofit B7 — regenerate snapshot baselines for B6's shipped-file edits B6 edited two shipped files (packages/core/hooks/pre-push.ts §8 carve-out, packages/core/hooks/utils/git.ts getAddedFiles) without regenerating the fingerprints — the byte-identical battery (all 4 stacks × greenfield/brownfield) went RED on CI exactly as designed. SNAPSHOT_MODE=capture diff reviewed: only the two expected hash lines per baseline (fe4242205c0… pre-push.ts, 3a1b55973f… git.ts), matching the hashes CI computed — no other shipped byte moved. Sweep after B6 was skipped by me; this is the FRS S2 lesson repeated. * chore(install-sh): host-verify retrofit B8 — merge-forward staging + recapture refresh-baseline hashes staging moved under the PR (#1503 consumer-refresh-integrity R1 added the .ai-factory/refresh-baseline.json manifest + its baseline lines; #1504 R4; #1505 barrel fix). The PR merge-ref mixed my B6 hooks with staging's R1 manifest: the installed manifest hashes the shipped files, so B6's pre-push.ts/git.ts edits change its bytes — CI computed the new manifest hashes (7a39d960…/0b204c85…/34eb550e…/59008f53…), staging's baselines still carried the pre-B6 ones. merge origin/staging (clean, no conflicts) + SNAPSHOT_MODE=capture on the merged tree: diff is exactly the 4 refresh-baseline hash lines × 8 npm baselines, matching what CI's install computes — no other shipped byte moved. --------- Co-authored-by: Test <test@example.com>
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.
Cross-session kickoff portability — PR-2 (back-catalog migration + principle-12 rework)
Completes the umbrella (R-phase #518; PR-1 mechanism = #520). Commits the 142
/pipelinekickoff design docs — including this umbrella's own (the §0.1 dogfood) — so plan discovery is a property of the committed tree on every machine, and reworks principle 12 for the committed-kickoff reality (the blocker PR-1's mechanism-only deferred).What this ships
kickoff.mdcommitted as real files. 0 symlinks staged (D2 acceptance: no120000-mode entries). Secret-scanned before commit → zero secrets / credentials / third-party PII (only the maintainer's own already-public email).queue-mode-bootstrap726,strategic-clarity-dialogue660,aif-handoff-runtime-bridge-iphase649) carry thetransient artifactmarker → exempt from themd-line-gate(paired-tested in PR-1).12-ai-laziness-traps.test.ts):EXEMPT_LIST. (A commit-date cutoff can't distinguish them — the whole back-catalog lands in one migration commit → one date — so the grandfathered set is an explicit allowlist, the existing pattern.)≥100floor dropped forwithinPopulationBounds(few/zero plans is valid: fresh clone, prune, a consumer adopting/pipeline) + an always-run unit test (0/1/142/cap+1).Test green 7/7 against the 142-kickoff state.
Consumers unaffected
Principle 12 is framework-internal (not in
install.sh); the shipped D5 pre-push check isexistsSync-guarded (its script isn't shipped → skips); no.gitignorefragment ships → a consumer's plans are tracked-by-default.§1.7 Forward-check applied
Complies with active disciplines: no-paid-llm-in-ci — principle 12 is deterministic vitest, zero API (
packages/core/principles/12-ai-laziness-traps.test.ts:1); build-first-reuse-default — amnesty reuses the existingEXEMPT_LISTallowlist pattern rather than a new mechanism (packages/core/principles/12-ai-laziness-traps.test.ts:44); doc-authority-hierarchy — kickoffs are folder-scoped design docs under.claude/orchestrator-prompts/; the 600-line exemption marker ridespackages/core/audit-self/md-line-gate.sh:1.§1.7 Backward-check applied
Complete sweep of the new convention's scope
.claude/orchestrator-prompts/*/kickoff.md(142 committed): the exact non-compliant set was computed by the compound check (packages/core/principles/12-ai-laziness-traps.test.ts:52) and allowlisted (not hand-waved); sentinel few-plans-safety is unit-tested viawithinPopulationBounds(packages/core/principles/12-ai-laziness-traps.test.ts:1); the 3 oversized kickoffs carry the marker;state.md/_plan-cacheremain gitignored (PR-1 D4 check-ignore).🤖 Generated with Claude Code