Amend ADR 0004 with explicit Regeneratable-Cache Strategic Principle (§1.3)

Context

ADR 0004 (learn/agentos/decisions/0004-github-content-architecture.md) codifies the Universal Ordinal-100 Content Architecture but its strategic load-bearing principle — GitHub is source of truth; resources/content/ is a fully-regeneratable cache — sits implicitly under §3.6's clean-slate operator quote ("delete it all => clean slate => like we never had prior content"). The strategic principle isn't named as its own anchor section that future authors V-B-A against.

Operator-surfaced framing (2026-05-15 nightshift A2A):

"rationale: all data can be get from github. you can, if needed, delete the other items inside resources/content too. especially the meta file. we, and every other user, can sync ALL data from github. that was and is the strategy."

This is the LOAD-BEARING strategic principle that makes the entire ADR 0004 substrate-evolution work. Without it explicitly named:

• Future authors under preservation-tendency biases (RLHF deprecation tendency per #11397 §5.6, "preserve existing data" tendency, etc.) don't have a § to V-B-A against
• The clean-cut pattern (#11397 §2.6) reads as "delete code helpers cleanly" without the deeper reason that ALL preservation is moot because GitHub regenerates
• The "team derailed and went back to stream-IDs" historical pattern (operator-described 2026-05-15) is the same root-friction: implicit assumption that on-disk state needs preservation

The Problem

ADR 0004 currently anchors against substrate-bypass authoring via §5 anti-patterns but doesn't explicitly name the strategic principle that justifies WHY the clean-cut shape is correct. §3.6 codifies the operational migration approach but reads as a tactical-procedure section, not a strategic-principle section.

Empirical pattern: ADR 0004's clean-cut shape is correct ONLY because GitHub-is-source-of-truth + sync_all regenerates. Future agents who don't internalize that strategic anchor will re-derive the data-preservation assumption (the 2026 "derailment" pattern operator described) at every implementation cycle — not just at the @deprecated theater layer.

The Architectural Reality

• ADR 0004 §1 Context: describes friction (1000-file folder cap, asymmetric archive substrate, density-tuning regret, GitHub-stream-chunking framing, inconsistency creep) but doesn't lead with the strategic principle.
• ADR 0004 §3.6 The migration approach: contains the operator's "delete it all => clean slate" quote OPERATIONALLY but the strategic principle (GitHub-as-source-of-truth → resources/content/ regeneratable) is implicit, not stated.
• #11397 (in flight via PR #11398): adds §2.6 Clean-Cut Pattern + §5.6 Deprecation-theater anti-pattern. These are PATTERNS + ANTI-PATTERNS, not STRATEGIC PRINCIPLES. The strategic principle sits above both as their WHY.

The Fix

Add a new section to ADR 0004 — proposed as §1.3 "The Regeneratable-Cache Strategic Principle" inserted between §1.2 (substrate-bypass anti-pattern) and §2 (Decision):

<h3 class="neo-h3" data-record-id="6">1.3 The Regeneratable-Cache Strategic Principle (load-bearing strategic anchor)</h3>

`resources/content/` is a **fully-regeneratable cache**, NOT a source of truth. GitHub is the source of truth. `sync_all` is the canonical path back to a clean state from any local state.

**Operator authority anchor** (2026-05-15 nightshift A2A, verbatim):

> *"rationale: all data can be get from github. you can, if needed, delete the other items inside resources/content too. especially the meta file. we, and every other user, can sync ALL data from github. that was and is the strategy."*

**Concrete implications future authors V-B-A against:**

1. **Data-tier**: `<NNN>xx/` folders, `chunk-N/` folders, `.sync-metadata.json`, anything else in `resources/content/` — all deletable at will. Re-running `sync_all` regenerates everything from GitHub.
2. **Code-tier**: helpers like `chunkPath.mjs`, `archivePath.mjs`, `contentPath.mjs` are not load-bearing for data preservation. They're load-bearing only for CURRENT call sites; when call sites get rewired, the old helpers can be deleted simultaneously without data risk.
3. **`.sync-metadata.json` is also regeneratable**: deleting it just makes syncers treat the substrate as never-synced and re-emit fresh. This is feature, not bug — it's the simplest path to a clean state.
4. **Universal applicability**: not just the maintainer's local checkout. Per operator quote, "every other user" can sync ALL data from GitHub. The strategic principle holds across all deployment surfaces.

**Why this section is load-bearing**:

The clean-cut pattern (§2.6 per #11397) and the deprecation-theater anti-pattern (§5.6 per #11397) are CORRECT because of this strategic principle. Without it, future authors under preservation-tendency biases (RLHF graceful-degradation, "don't break working state", "preserve customer data" priors) don't have a § to V-B-A against — they pattern-match the preservation tendencies as positive signals and re-derive the data-preservation assumption.

**Historical pattern this section guards against** (operator-described 2026-05-15):

The pre-ADR-0004 "derailment" — team went from the exactly-100-items-per-folder original spec back to stream-based-IDs (`<NNN>xx/`) with almost-empty folders — was driven by the implicit assumption that on-disk state needed preservation across migration. The §1.3 strategic principle nullifies that assumption explicitly. Future agents recognizing preservation-pressure should pattern-match against §1.3 and choose deletion + re-sync over preservation + migration.

Acceptance Criteria

• AC1: ADR 0004 contains a new §1.3 "The Regeneratable-Cache Strategic Principle" section with the prose above (or equivalent).
• AC2: The §1.3 section is positioned as a strategic anchor above §2 (Decision) — future authors V-B-A against it BEFORE designing helpers or migration shapes.
• AC3: The operator authority anchor (2026-05-15 nightshift A2A verbatim quote) is cited explicitly so future readers know the strategic principle is operator-stated, not author-inferred.
• AC4: §3.6 cross-references §1.3 — readers arriving at the migration-approach section see "this is the operationalization of §1.3" framing.
• AC5: No deletion or semantic mutation of existing §1.1, §1.2, §2.x, §3.x, §5.x content — this ticket is purely additive.
• AC6: PR body cites the empirical context: my #11397 + Gemini's PR #11398 codify §2.6 Clean-Cut Pattern + §5.6 Deprecation-theater anti-pattern; this ticket adds the strategic principle that anchors WHY both are correct. The three sections form a complete substrate-evolution-guard layer.

Out of Scope

• §2.6 Clean-Cut Pattern + §5.6 Deprecation-theater anti-pattern: scope of #11397 / PR #11398, already in flight under Gemini's Cycle-1 review-cycle with GPT.
• Updating existing call sites or syncers: this ticket is purely doc-substrate; the regeneratable-cache principle's operationalization happens in Lane A (#11381, APPROVED) + Lane B (#11390) + Task 10 implementation tickets.
• Other ADRs (0001-0003, 0005, 0006): they don't cover the regeneratable-cache substrate; no parallel amendment needed.

Avoided Traps

• Folding into Gemini's PR #11398 mid-Cycle-1: rejected — moves goalposts on her in-flight implementation per my own learned feedback_ticket_prescription_clarity lesson. Separate ticket + separate PR keeps each amendment narrow + reviewable.
• Treating the strategic principle as obvious + not worth codifying: rejected — this is exactly the implicit-obviousness-at-authoring-time failure mode that #11397 §5.6 codifies as RLHF-bias-vulnerable. Implicit strategic principles fail against future agents under biases.
• Adding it as a 4th anti-pattern in §5: rejected — strategic principle is HIGHER than anti-pattern (anti-patterns are derived from the principle). It belongs as §1.x or §3.x, not §5.x.

Related

• Authority artifact: ADR 0004 (learn/agentos/decisions/0004-github-content-architecture.md)
• Companion in-flight amendment: #11397 / PR #11398 — §2.6 Clean-Cut Pattern + §5.6 Deprecation-theater anti-pattern (Gemini-authored, GPT Cycle-1 CHANGES_REQUESTED at PRR_kwDODSospM8AAAABAAm0Yw).
• Operator-quote source: 2026-05-15 nightshift A2A on the @deprecated theater regression cycle — same A2A where operator described the team-derailment pattern.
• Historical anchor: the pre-ADR-0004 derailment (team went back to stream-based-IDs from exactly-100-items-per-folder spec) is the empirical pattern this section guards against; operator surfaced it as "good friction since it led to ADR 0004 and 0005".

Origin Session

• Origin Session ID: b8a152e1-a41c-49aa-8196-8e5d2eba84ca
• Cross-session anchor: prior session e095c569-beac-4743-998f-e07d4344492e (this session's earlier work) which authored #11397.

Retrieval Hint

Search for ADR 0004 §1.3 regeneratable cache strategic principle GitHub source of truth sync_all.