Context
Follow-up to #12511 / PR #12512, which fixed the visible learn/agentos nav pollution + added the EXPLORATION_ARTIFACT publish-guard. This ticket finishes the job: the broader orphan-dump.
The Problem
After #12512, ~11 top-level learn/agentos/*.md files remain unpublished orphans (in the public dir, not in tree.json nav) — disorganized retained content the operator flagged as bloat: AGENTS_ATLAS, IdentitySchema, ModelStats, Tier2RevalidationSweep, v13-path, gemma4-rem-benchmark, sandman-handoff-format, sandman-silent-failure-forensics, contract-ledger, evidence-ladder, reference-hygiene.
The Fix
- Relocate the skill-methodology docs to a new non-published
agentos/process/ subfolder: contract-ledger, evidence-ladder, reference-hygiene. Couples to skill pointers + the #12497 reference-integrity lint — every live reference (V-B-A'd 2026-06-04: 5 / 8 / 4 referencing files respectively) must update in the same PR. AGENTS_ATLAS is RECLASSIFIED out of this set (V-B-A: referenced by the turn-loaded root AGENTS.md + ADRs 0007/0009/0011 → load-bearing substrate, not a sweepable orphan — see Contract Ledger row 2).
- Relocate
sandman-silent-failure-forensics → incidents/; gemma4-rem-benchmark → measurements/ (pending #B disposition); assess ModelStats/Tier2RevalidationSweep/v13-path/sandman-handoff-format/IdentitySchema (relocate vs delete-if-ticket-captured).
- Add the stricter
NO_TOP_LEVEL_ORPHAN invariant to lint-tree-json.mjs: every depth-1 learn/agentos/*.md MUST be registered in tree.json (forces non-guides into subfolders mechanically — closes the orphan-dump mode that EXPLORATION_ARTIFACT doesn't catch).
Contract Ledger
Classification: T3 (Explicit Matrix) per learn/agentos/contract-ledger.md. Backfilled in response to @neo-gpt's intake-block (comment IC_kwDODSospM8AAAABE7O7aQ), building on gpt's skeleton. Rows are Surface-Anchor V-B-A'd — live-reference counts from grep -rl on 2026-06-04.
| Target Surface |
Source of Authority |
Proposed Behavior |
Fallback / Edge Case |
Docs |
Evidence |
learn/agentos/process/*.md (NEW subfolder) ← relocate contract-ledger, evidence-ladder, reference-hygiene |
#12513 + #12511/#12512; operator public/non-public boundary |
Move the 3 skill-methodology docs out of public-learn top-level into non-published agentos/process/, keeping them repo-consumable by skills/ADRs |
All live inbound refs update in the SAME PR — V-B-A'd counts: contract-ledger 5, evidence-ladder 8, reference-hygiene 4, across .agents/skills/* (incl. skills.manifest.json) + ADRs 0007/0009/0011. Archived resources/content/{discussions,pulls}/* snapshots are frozen KB corpus → do NOT update. No broken live ref may remain. |
Update moved-doc links + @see |
ai:lint-skill-manifest + ai:lint-agents + #12497 reference-integrity green; grep -rl <oldpath> (excl. resources/content archive) = 0 |
learn/agentos/AGENTS_ATLAS.md disposition (HIGHEST-BLAST — split out) |
#12513 audit + the AGENTS.md atlas-pointer pattern |
Re-decide its home deliberately: it is the Atlas companion to the turn-loaded root AGENTS.md + cited by ADRs 0007/0009/0011 — load-bearing substrate, not a sweepable orphan |
RECOMMENDED: keep AGENTS_ATLAS.md at its AGENTS.md-expected path and either register it in tree.json (if deemed public) or mark it intentionally-internal via the NO_TOP_LEVEL_ORPHAN allowlist — do NOT lump it into the process/ relocation. If moved anyway, the root AGENTS.md (turn-loaded) + ADRs 0007/0009/0011 MUST update in the same PR. |
AGENTS.md + ADR pointer updates IF moved |
grep -rln AGENTS_ATLAS live-set consistent; AGENTS.md atlas-pointer resolves post-change |
ai/scripts/lint/lint-tree-json.mjs → new NO_TOP_LEVEL_ORPHAN invariant (invariant 7, after #12523's SEO_SYNC=6) |
#12513 (NEW surface) |
Fail when any depth-1 learn/agentos/*.md is absent from learn/tree.json (mechanically forces non-guides into subfolders) |
Explicit allowlist entry ONLY for a top-level doc intentionally published+registered OR intentionally-internal (e.g. AGENTS_ATLAS); pure-data list, never a threshold |
JSDoc + CLI --help + lint message enumerate invariant 7 |
New lintTreeJson.spec.mjs case + npm run ai:lint-tree-json green on cleaned tree |
Remaining top-level orphans disposition (ModelStats, Tier2RevalidationSweep, v13-path, sandman-handoff-format, IdentitySchema, sandman-silent-failure-forensics, gemma4-rem-benchmark) |
#12513 current-source audit |
Per-doc: relocate to correct non-published subfolder (incidents/, measurements/), register in tree.json if genuinely public, or delete IF ticket-captured — each with V-B-A evidence |
Leave top-level ONLY when intentionally published/allowlisted (else NO_TOP_LEVEL_ORPHAN fails it); deletion requires a V-B-A'd ticket/Epic capturing the content |
Link updates if moved |
git file-list before/after + ai:lint-tree-json + inbound-ref grep = 0 |
Implementation ordering (edge case): relocate/register/allowlist all orphans FIRST, THEN add NO_TOP_LEVEL_ORPHAN — adding the invariant while orphans still exist red-fails CI. Single PR, ordered commits. Sequencing dep: #12523 (SEO_SYNC = invariant 6) should land first so the new invariant numbers cleanly as 7.
Acceptance Criteria
Related
Parent concern: #12511 / PR #12512. Reference-integrity coupling: #12497. Invariant-numbering sequencing: #12523.
Origin Session ID: c2800781-b204-4883-a52f-2979a560718b
Context
Follow-up to #12511 / PR #12512, which fixed the visible learn/agentos nav pollution + added the
EXPLORATION_ARTIFACTpublish-guard. This ticket finishes the job: the broader orphan-dump.The Problem
After #12512, ~11 top-level
learn/agentos/*.mdfiles remain unpublished orphans (in the public dir, not intree.jsonnav) — disorganized retained content the operator flagged as bloat:AGENTS_ATLAS,IdentitySchema,ModelStats,Tier2RevalidationSweep,v13-path,gemma4-rem-benchmark,sandman-handoff-format,sandman-silent-failure-forensics,contract-ledger,evidence-ladder,reference-hygiene.The Fix
agentos/process/subfolder:contract-ledger,evidence-ladder,reference-hygiene. Couples to skill pointers + the #12497 reference-integrity lint — every live reference (V-B-A'd 2026-06-04: 5 / 8 / 4 referencing files respectively) must update in the same PR.AGENTS_ATLASis RECLASSIFIED out of this set (V-B-A: referenced by the turn-loaded rootAGENTS.md+ ADRs 0007/0009/0011 → load-bearing substrate, not a sweepable orphan — see Contract Ledger row 2).sandman-silent-failure-forensics→incidents/;gemma4-rem-benchmark→measurements/(pending #B disposition); assessModelStats/Tier2RevalidationSweep/v13-path/sandman-handoff-format/IdentitySchema(relocate vs delete-if-ticket-captured).NO_TOP_LEVEL_ORPHANinvariant tolint-tree-json.mjs: every depth-1learn/agentos/*.mdMUST be registered intree.json(forces non-guides into subfolders mechanically — closes the orphan-dump mode thatEXPLORATION_ARTIFACTdoesn't catch).Contract Ledger
Classification: T3 (Explicit Matrix) per
learn/agentos/contract-ledger.md. Backfilled in response to @neo-gpt's intake-block (commentIC_kwDODSospM8AAAABE7O7aQ), building on gpt's skeleton. Rows are Surface-Anchor V-B-A'd — live-reference counts fromgrep -rlon 2026-06-04.learn/agentos/process/*.md(NEW subfolder) ← relocatecontract-ledger,evidence-ladder,reference-hygieneagentos/process/, keeping them repo-consumable by skills/ADRscontract-ledger5,evidence-ladder8,reference-hygiene4, across.agents/skills/*(incl.skills.manifest.json) + ADRs 0007/0009/0011. Archivedresources/content/{discussions,pulls}/*snapshots are frozen KB corpus → do NOT update. No broken live ref may remain.@seeai:lint-skill-manifest+ai:lint-agents+ #12497 reference-integrity green;grep -rl <oldpath>(excl.resources/contentarchive) = 0learn/agentos/AGENTS_ATLAS.mddisposition (HIGHEST-BLAST — split out)AGENTS.md+ cited by ADRs 0007/0009/0011 — load-bearing substrate, not a sweepable orphanAGENTS_ATLAS.mdat itsAGENTS.md-expected path and either register it intree.json(if deemed public) or mark it intentionally-internal via theNO_TOP_LEVEL_ORPHANallowlist — do NOT lump it into theprocess/relocation. If moved anyway, the rootAGENTS.md(turn-loaded) + ADRs 0007/0009/0011 MUST update in the same PR.AGENTS.md+ ADR pointer updates IF movedgrep -rln AGENTS_ATLASlive-set consistent; AGENTS.md atlas-pointer resolves post-changeai/scripts/lint/lint-tree-json.mjs→ newNO_TOP_LEVEL_ORPHANinvariant (invariant 7, after #12523'sSEO_SYNC=6)learn/agentos/*.mdis absent fromlearn/tree.json(mechanically forces non-guides into subfolders)AGENTS_ATLAS); pure-data list, never a threshold--help+ lint message enumerate invariant 7lintTreeJson.spec.mjscase +npm run ai:lint-tree-jsongreen on cleaned treeModelStats,Tier2RevalidationSweep,v13-path,sandman-handoff-format,IdentitySchema,sandman-silent-failure-forensics,gemma4-rem-benchmark)incidents/,measurements/), register intree.jsonif genuinely public, or delete IF ticket-captured — each with V-B-A evidenceNO_TOP_LEVEL_ORPHANfails it); deletion requires a V-B-A'd ticket/Epic capturing the contentgitfile-list before/after +ai:lint-tree-json+ inbound-ref grep = 0Implementation ordering (edge case): relocate/register/allowlist all orphans FIRST, THEN add
NO_TOP_LEVEL_ORPHAN— adding the invariant while orphans still exist red-fails CI. Single PR, ordered commits. Sequencing dep: #12523 (SEO_SYNC= invariant 6) should land first so the new invariant numbers cleanly as 7.Acceptance Criteria
contract-ledger,evidence-ladder,reference-hygiene) relocated toagentos/process/; all live skill/doc/ADR references updated;ai:lint-skill-manifestreference-integrity green.AGENTS_ATLAS.mddisposition decided per Contract Ledger row 2 (registered/allowlisted in place, OR moved with coordinatedAGENTS.md+ADR update) — the turn-loaded atlas pointer must resolve.NO_TOP_LEVEL_ORPHANinvariant added + unit test; no depth-1 orphan remains (except intentional allowlist entries).ai:lint-tree-json+ai:lint-skill-manifest+ai:lint-agentsgreen.Related
Parent concern: #12511 / PR #12512. Reference-integrity coupling: #12497. Invariant-numbering sequencing: #12523.
Origin Session ID: c2800781-b204-4883-a52f-2979a560718b