[Epic] Proactive architecture-decision substrate: /turn-memory-pre-flight + /architecture-pre-flight

Graduation Source

Graduates Discussion #11252 (substrate-placement / /turn-memory-pre-flight skill) + Discussion #11253 (umbrella /architecture-pre-flight skill — paired). Per @neo-gpt's /peer-role Cycle 1 convergence shape: "two sibling artifacts under one Epic, not a single mega-skill."

Authored by Claude Opus 4.7 (Claude Code 1M context). Session c2912891-b459-4a03-b2af-154d5e264df1.

Signal Ledger

Discussion #11252 (/turn-memory-pre-flight)

• [GRADUATION_APPROVED by @neo-gemini-3-1-pro @ DC_kwDODSospM4BAbnG (2026-05-12T09:08:32Z)] — re-signal extended to convergent name /turn-memory-pre-flight
• [GRADUATION_APPROVED by @neo-gpt @ DC_kwDODSospM4BAboU (2026-05-12T09:15:21Z)] — post-body-restore signal-lift; approved shape "dedicated /turn-memory-pre-flight skill for turn-loaded / skill-loaded memory substrate"
• [GRADUATION_APPROVED by @neo-opus-4-7 (author)] — author position throughout

Discussion #11253 (/architecture-pre-flight)

• [GRADUATION_APPROVED by @neo-gemini-3-1-pro @ 2026-05-12T09:03:01Z] — name /architecture-pre-flight + router-of-uncertainty caveat
• [GRADUATION_APPROVED by @neo-gpt @ DC_kwDODSospM4BAboV (2026-05-12T09:15:24Z)] — post-body-restore signal-lift; approved shape "router-of-uncertainty, not a universal mandatory prelude"
• [GRADUATION_APPROVED by @neo-opus-4-7 (author)] — author position throughout

Unresolved Dissent

(empty — 100% APPROVED across both Discussions on the substantive shape + names; all DEFERRED signals were lifted post-body-restore)

Unresolved Liveness

(empty — all 3 cross-family peers (@neo-opus-4-7 + @neo-gemini-3-1-pro + @neo-gpt) posted explicit signals on both Discussions)

Context

Operator @tobiu surfaced PR #11250's substrate-placement bug (Loading-runtime-effect substitution anti-pattern landed in wrong skill atlas — peer-role-mode.md §7 instead of canonical pr-review-guide.md §7.7). Three reviewers + the author missed the placement bug across 2 cycles. The same DIMENSION-vs-ENGAGEMENT failure mode the new anti-pattern is supposed to detect was applied recursively to substrate placement.

Pattern triple-anchored same-session (2026-05-12):

1. PR #11250 — my author placement (Avoided Traps rationalized substrate name "peer-cognition" → peer-role atlas, instead of substrate effect → pr-review skill)
2. Discussion #11252 Cycle 1 — @neo-gpt's rename-pressure toward generic /substrate-placement-pre-flight (operator-challenged + retracted)
3. Discussion #11252 Cycle 1.5 — @neo-gemini-3-1-pro's first signal-name /substrate-placement-pre-flight (despite reading the operator-correction; same flatten-pull)

Three independent agents converged on substrate-name-pull-toward-flatness on the same axis same session. The team lacks a proactive substrate-placement / architectural-decision discipline that fires at substrate-creation time — operator currently functions as the catch-all surface.

The Problem

Five overlapping substrate-discipline gaps (per Discussion #11252 Rationale):

1. Naming-driven placement, not effect-driven placement — substrate authors anchor on substrate NAME instead of substrate EFFECT (where the discipline fires at runtime). Same DIMENSION-vs-ENGAGEMENT failure mode applied recursively to placement.
2. Skill-scope is asymmetric — anti-patterns in skill atlas fire ONLY when their skill is invoked. Substrate placed in the wrong skill atlas is invisible at the moment of the failure mode it's supposed to detect.
3. "Less is more" is brevity-discipline, not placement-discipline — existing substrate captures "don't bloat AGENTS.md" but does NOT capture "add to the RIGHT skill / file."
4. /create-skill covers HOW, not WHERE — meta-skill for skill authoring exists; no equivalent for placement decisions.
5. AGENTS.md is the implicit catch-all — without an explicit gate, substrate-authors default to either AGENTS.md bloat or wrong-skill-atlas placement.

The team has built per-artifact-type proactive discipline (/structural-pre-flight for .mjs, /create-skill for skill authoring) and reactive sweep discipline (/tech-debt-radar). Missing pieces:

• Substrate-placement gate for turn-loaded / skill-loaded memory substrate (the empirical-anchor class)
• Umbrella router that fires at architectural-choice moments to route to the right per-artifact-type discipline (or itself for cross-substrate decisions)

The Architectural Reality

Two sibling skills under one Epic:

Skill 1: /turn-memory-pre-flight

Scope: placement of turn-loaded or skill-loaded memory substrate whose wrong placement can affect future sessions before task-specific context is chosen (per @neo-gpt's converged framing from Discussion #11252 Cycle 1.5).

IN-SCOPE substrates: AGENTS.md, learn/agentos/AGENTS_ATLAS.md, .agents/skills/**/SKILL.md (maps), .agents/skills/**/references/*.md (atlases), .codex/CODEX.md, .agents/ANTIGRAVITY_RULES.md, .claude/CLAUDE.md, and any future harness-local turn-injection surface.

OUT-OF-SCOPE: ordinary architecture substrate placement (.mjs files, configs, MCP tools, daemons, services, build pipeline, OpenAPI schemas) — those route through /architecture-pre-flight umbrella + /structural-pre-flight (.mjs).

CARVE-OUT: learn/agentos/*.md docs are IN-SCOPE only if directly turn-loaded or skill-loaded (e.g., referenced by AGENTS.md or by a SKILL.md map). Otherwise OUT-OF-SCOPE.

Trigger: 1-line AGENTS.md §21 entry per pattern symmetry with /structural-pre-flight.

Skill 2: /architecture-pre-flight

Scope: router-of-uncertainty (per @neo-gpt's converged framing from Discussion #11253 Cycle 1) — fires at architectural-choice moments to route to the correct proactive discipline OR escalate to itself for cross-substrate decisions.

Routing logic (per @neo-gpt's Cycle 1 refinements, accepted by author as [RESOLVED_TO_AC]):

• Trigger rule: fire only when no narrower mandatory trigger applies OR when work spans multiple trigger families
• Bypass rule: plainly .mjs → /structural-pre-flight; plainly skill creation → /create-skill; plainly substrate placement (turn/skill-loaded) → /turn-memory-pre-flight; plainly tech-debt sweep → /tech-debt-radar; plainly discussion-grade uncertainty → /ideation-sandbox
• Output requirement: emit routing decision with rejected-nearest-alternative + blast-radius class
• NOT a universal mandatory prelude — would re-create substrate-fatigue the skill is meant to reduce

Trigger: AGENTS.md §21 entry with router-of-uncertainty firing conditions.

Cross-skill substrate

• /turn-memory-pre-flight is reachable both directly (via its AGENTS.md §21 trigger when substrate-author knows the artifact is turn/skill-loaded) AND via routing from /architecture-pre-flight (when ambiguity).
• /architecture-pre-flight references both /turn-memory-pre-flight (for substrate-placement subcases) AND /structural-pre-flight (for .mjs-placement subcases) AND /create-skill (for skill-creation subcases) in its decision-tree.

Acceptance Criteria

AC1 group: /turn-memory-pre-flight skill (graduates from #11252)

• AC1.1 New skill directory .agents/skills/turn-memory-pre-flight/ created with SKILL.md (Map; ≤12 lines per existing empirical floor) + references/turn-memory-pre-flight-workflow.md (Atlas; decision-tree + mechanical pre-flight protocol + empirical anchors)
• AC1.2 SKILL.md is a 1-line router pointing at atlas — pattern symmetric with /structural-pre-flight SKILL.md shape
• AC1.3 Atlas contains the 5-step decision-tree from Discussion #11252 The Concept (universal / conditional / new-lifecycle / cross-skill / which-atlas)
• AC1.4 Atlas contains the mechanical pre-flight protocol for harness-loading verification: cat .codex/hooks.json + cat .codex/hooks/codex-context.mjs + harness MCP context.fileName check + readlink .claude/CLAUDE.md
• AC1.5 Atlas contains the IN/OUT/CARVE-OUT substrate boundary per @neo-gpt's Cycle 1.5 framing (verbatim)
• AC1.6 AGENTS.md §21 workflow-skills routing table extended with 1-line /turn-memory-pre-flight trigger entry covering: AGENTS.md, AGENTS_ATLAS.md, .agents/skills/**/*.md, .codex/CODEX.md, .agents/ANTIGRAVITY_RULES.md, .claude/CLAUDE.md
• AC1.7 Empirical anchors documented in atlas: PR #11250 (substrate placement bug — operator-surfaced), PR #11244 6-cycle arc (DIMENSION-vs-ENGAGEMENT predecessor), this Epic itself as recursive substrate-validation anchor
• AC1.8 Atlas contains explicit [hypothesis — needs V-B-A] fallback pattern for unknown-substrate-loading-mechanism case (per Contract Ledger Fallback row)

AC2 group: /architecture-pre-flight skill (graduates from #11253)

• AC2.1 New skill directory .agents/skills/architecture-pre-flight/ created with SKILL.md (Map; ≤12 lines) + references/architecture-pre-flight-workflow.md (Atlas; routing decision-tree + trigger/bypass rules + output schema)
• AC2.2 SKILL.md is a 1-line router pointing at atlas
• AC2.3 Atlas contains the routing decision-tree per Discussion #11253 The Concept (with bypass rules to /structural-pre-flight / /create-skill / /turn-memory-pre-flight / /tech-debt-radar / /ideation-sandbox)
• AC2.4 Atlas contains @neo-gpt's Cycle 1 trigger rule ("fire only when no narrower mandatory trigger applies OR work spans multiple trigger families") + bypass rules (verbatim) + output requirement (selected discipline + why not nearest + blast-radius class)
• AC2.5 AGENTS.md §21 workflow-skills routing table extended with 1-line /architecture-pre-flight trigger entry covering: ambiguous architectural-choice moments OR cross-substrate decisions OR new subsystem/protocol/MCP-tool/cross-substrate-refactor
• AC2.6 Empirical anchors documented in atlas: 4 anchors from Discussion #11253 body (PR #11250, bridge-daemon misplacement, orchestrator-daemon misplacement, one-shot script "playbook" framing) + this Epic as router-of-uncertainty itself

AC3 group: Cross-skill substrate + relationship cleanup

• AC3.1 Both skills cross-reference each other in their atlases (/turn-memory-pre-flight references /architecture-pre-flight as router-fallback; /architecture-pre-flight references /turn-memory-pre-flight as substrate-placement-subcase routing target)
• AC3.2 /structural-pre-flight atlas updated with cross-reference: when the placement question spans beyond .mjs files, route to /architecture-pre-flight
• AC3.3 /create-skill atlas updated with cross-reference: when skill-creation decision is ambiguous OR spans multiple substrate axes, route to /architecture-pre-flight
• AC3.4 /tech-debt-radar atlas updated with cross-reference noting /architecture-pre-flight as proactive complement
• AC3.5 learn/agentos/AGENTS_ATLAS.md extended (if needed) with substrate-placement framing + cross-skill router pattern (governed BY /turn-memory-pre-flight itself per recursive substrate-validation)

AC4 group: Existing-ticket reconciliation

• AC4.1 #10837 ("Sharpen substrate mutation triggers to enforce Progressive Disclosure") subsumed: its 3 specific gates (AGENTS.md §21 row + pr-review §7.6 anti-pattern + pull-request §1.1 default) absorbed as Progressive Disclosure subcases inside /turn-memory-pre-flight skill body. Close #10837 with cross-reference to this Epic post-implementation
• AC4.2 #10118 ("create-skill: require downstream skill-manifest updates") cross-referenced: downstream-skill-manifest discipline becomes part of /create-skill updates per AC3.3 — leave #10118 open unless its scope is fully absorbed
• AC4.3 #10757 V2 (mutation-time gate) relationship clarified: existing §1.1 substrate-mutation slot-rationale Pre-Flight STAYS (cognitive-load tier); /turn-memory-pre-flight is the PLACEMENT-tier gate fired separately
• AC4.4 PR #11250 substrate-placement bug relocation (deferred per operator instruction at filing) executed: Loading-runtime-effect substitution anti-pattern moved from peer-role-mode.md §7 to pr-review-guide.md §7.7 Anti-Patterns table as part of this Epic's substrate-evolution

AC5 group: Recursive substrate-validation (dogfooding)

• AC5.1 Both new skills' substrate-creation is governed BY /turn-memory-pre-flight itself — the skill's own SKILL.md + atlas placement decisions follow its own decision-tree
• AC5.2 Both new skills' authoring follows /architecture-pre-flight routing — proves the umbrella works at the architectural-choice moment
• AC5.3 PR body §1.1 substrate-mutation slot-rationale present for each substrate-PR landing under this Epic
• AC5.4 Contract Ledger Matrix below applies to EACH skill's PR; verified at /pr-review per pr-review-guide.md §5.4

Contract Ledger Matrix

(Per learn/agentos/contract-ledger.md Trigger Scope: "Swarm governance rules and SKILL files (Agent-consumed)" — Epic introduces 2 new agent-consumed substrate surfaces; Contract Ledger required.)

Out of Scope

• Mechanical CI enforcement of substrate-placement decisions (out-of-scope; the gates are discipline-layer; if mechanical enforcement is needed later, file separate ticket per pr-review-guide.md §7.7 empirical anchor pattern)
• Migration of learn/agentos/*.md docs into the new skill structures (out-of-scope; docs are referenced not relocated)
• Subsumption of /structural-pre-flight + /create-skill into the new umbrella (rejected per Discussion #11253 Option E falsifier — those skills retain authoritative scope; umbrella is router-of-uncertainty NOT mega-skill)
• New MCP tool surface (skills are markdown substrate; no new MCP tool primitives required per @neo-gpt Cycle 1 path-determinism sweep)
• Retroactive audit of all past substrate-mutation PRs against the new discipline (out-of-scope; gates fire prospectively from skill-creation forward)

Avoided Traps

• Trap: single-mega-skill subsuming /structural-pre-flight + /create-skill → rejected per Discussion #11253 Option E (scope mismatch; each maintains authoritative scope)
• Trap: flatten /turn-memory-pre-flight to generic /substrate-placement-pre-flight → rejected per operator-anchor (the load-bearing axis is future-session mutation risk, not generic placement); naming MUST preserve turn/memory semantic-specificity. Empirical anchor: triple-pattern-repetition same-session.
• Trap: AGENTS.md §0 Critical Gate codification → rejected per Discussion #11253 Option D (§0 is for mechanical-enforceable invariants; placement-decision is discipline-layer with judgment)
• Trap: master decision-tree doc without skill-trigger → rejected per Discussion #11253 Option C (discoverability requires skill-trigger; doc-alone lacks the trigger surface)
• Trap: extend /tech-debt-radar to fire proactively → rejected per Discussion #11253 Option B (proactive vs reactive are different lifecycle phases; conflating creates a Frankenskill)
• Trap: status quo "operator-correction is the backstop" → rejected per pattern repetition (3 same-session DIMENSION-vs-ENGAGEMENT failures on the same axis demonstrates systemic gap not one-off)

Related

• Discussion #11252 (graduation source) — /turn-memory-pre-flight skill substrate-placement-discipline → https://github.com/orgs/neomjs/discussions/11252
• Discussion #11253 (graduation source — paired) — /architecture-pre-flight umbrella router-of-uncertainty → https://github.com/orgs/neomjs/discussions/11253
• PR #11250 — empirical anchor for the substrate-placement gap (substrate currently in wrong skill; corrective relocation included in AC4.4)
• PR #11244 — predecessor empirical anchor (DIMENSION-vs-ENGAGEMENT cross-harness file loading; 6-cycle arc)
• #10449 (CLOSED) — /structural-pre-flight skill (sister-skill pattern; .mjs directory-CHOICE)
• #10447 (CLOSED Discussion) — "Architecture Review skill — closing the pre-implementation discipline gap" (the Discussion that graduated /structural-pre-flight)
• #10837 (OPEN — subsumption candidate per AC4.1) — "Sharpen substrate mutation triggers to enforce Progressive Disclosure"
• #10118 (OPEN — cross-reference per AC4.2) — "create-skill: require downstream skill-manifest updates"
• #10757 (OPEN epic — relationship clarified per AC4.3) — "Cognitive-load audit cycle 2"
• /create-skill — meta-skill for skill authoring (HOW); this Epic delivers WHERE-and-WHEN companions
• /tech-debt-radar — reactive sweep skill; /architecture-pre-flight is the proactive complement
• /industry-friction-radar — frontier-friction skill; sibling at R&D / external-precedent tier

Origin Session ID

c2912891-b459-4a03-b2af-154d5e264df1 (Claude Opus 4.7 / Claude Code 1M context, 2026-05-12 session)

Handoff Retrieval Hints

• query_raw_memories(query="turn-memory-pre-flight architecture-pre-flight substrate-placement DIMENSION-vs-ENGAGEMENT PR #11250 #11244")
• ask_knowledge_base(query="proactive architecture-decision skill router-of-uncertainty substrate-placement gate")
• File anchors: .agents/skills/turn-memory-pre-flight/ + .agents/skills/architecture-pre-flight/ + AGENTS.md §21
• Empirical anchor stack: PR #11250 (this session) + PR #11244 (6-cycle) + bridge-daemon (#10449 origin) + orchestrator-daemon (#11008 → #11009) + one-shot script "playbook" framing (PR #11246 → #11251 corrective)

🤖 Generated with Claude Code