structural-pre-flight skill: implementation + Phase 1 adoption

Context

Graduates from Discussion #10447 ("Architecture Review skill — closing the pre-implementation discipline gap"). Cross-family iteration with @neo-gemini-pro and @tobiu produced 6 [RESOLVED_TO_AC] resolutions; this Epic implements them.

Empirical anchor that triggered the Discussion: ai/scripts/bridge-daemon.mjs was authored to the scripts directory instead of ai/daemons/ (the canonical home for long-running daemons, already documented in learn/benefits/ArchitectureOverview.md's Structural Inventory + occupied by sibling DreamService.mjs). Even strict §23 sibling-file-lift compliance would not have caught this — §23 fires WITHIN a chosen directory, not at directory-CHOICE time. There is a 0th-level discipline gap that this Epic closes via a new skill.

Concurrent scope clarification: the empirical-anchor refactor itself (relocate bridge-daemon.mjs + bridge-daemon-queries.mjs from ai/scripts/ to ai/daemons/bridge-daemon/) graduates from Discussion #10448 (@neo-gemini-pro, "Agent OS Tool Boundaries & Daemon Isolation"). That refactor will reference this Epic's skill as the discipline-substrate but is scoped distinctly.

The Problem

The learn/benefits/ArchitectureOverview.md Structural Inventory table already documents canonical homes (ai/scripts/ for one-shot scripts, ai/daemons/ for long-running daemons, ai/services/ for in-process services, etc.). The substrate exists. What's missing is the discipline to consult it at the right moment — pre-implementation, not at PR-review time (too late) and not after the misplacement becomes tech debt the radar must reactively sweep.

Existing skills don't fully cover the gap:

The Architectural Reality

• .agent/skills/structural-pre-flight/ (new) — the skill body following create-skill Progressive Disclosure standards (lightweight router + reference payload).
• .agent/skills/ticket-create/ + .agent/skills/ticket-intake/ + .agent/skills/epic-review/ — three existing skills receive 1-3 line anchor references to the new skill (mechanical edits, bundled into the skill-authoring PR).
• learn/benefits/ArchitectureOverview.md — Structural Inventory table needs ADR-link enrichment for OQ5 self-eviction defense (separate doc-only PR).
• learn/agentos/decisions/ — existing ADRs (#10186 cache coherence, #10357 wake substrate standards) referenced by the new map-as-pointer mechanism.

The Skill Shape (per Discussion #10447 resolutions)

Trigger (per OQ1 [RESOLVED_TO_AC]): mechanical — every new .mjs file fires the skill. Internally has two stages:

Stage 0 — Mechanical trigger: every new .mjs file fires the skill
Stage 1 — Pattern-match check: "Does this file's role match an established sibling pattern
            in the chosen directory?"
            ✓ YES → fast-path: §23 sibling-file-lift suffices; emit a one-line Pre-Flight
                              statement and proceed (under 30 seconds)
            ✗ NO  → full structural-pre-flight: ArchitectureOverview.md consultation,
                    learn/agentos/decisions/ ADR sweep, chief-architect framing questions,
                    map-maintenance discipline, optional ADR genesis

Mandates (per OQ2-OQ5 [RESOLVED_TO_AC]):

1. Substrate-grounded reading: ArchitectureOverview.md + relevant ADRs in learn/agentos/decisions/ + 1-2 sibling files in EACH candidate destination directory.
2. Pre-Flight Check shape (mirrors §23 / §22.1 / pr-review §9.4): explicit reasoning-statement before authoring.
3. Chief-architect framing questions: scalability, ADR-conflict, ADR-genesis, future-self regression-risk.
4. Map-maintenance discipline (Blocking AC): when introducing or relocating a structurally-significant file, the skill mandates updating ArchitectureOverview.md's Structural Inventory table.
5. Strategy vs Tactics threshold for ADR genesis (per OQ4): cross-system trade-offs → ADR; localized constraints → Anchor & Echo guards.
6. Map-as-pointer self-eviction defense (per OQ5): ArchitectureOverview.md MUST link to relevant ADRs per subsystem; skill's "read the map" mandate propagates via graph traversal.

Scope (per OQ2 [RESOLVED_TO_AC]): Repo-wide. Skill body has domain-aware mandates (ai/-specific reading list section, src/-specific section) but unified core flow.

Name (per OQ6 [RESOLVED_TO_AC]): structural-pre-flight. Aligns with existing Pre-Flight Check taxonomy.

Sub-Issue Plan (revised — consolidated per @tobiu's calibration)

2 sub-issues rather than 5. The original plan over-decomposed: three of the original sub-issues were 1-3 line anchor edits to existing skills, which would have created high coordination overhead (3 separate tickets, branches, PRs, reviews) for mechanically trivial integrations. Bundling the anchors with the skill-authoring PR keeps the cohesive feature reviewable as one unit. The doc audit stays separate because it's distinct scope (documentation file changes vs. skill-and-discipline code).

1. Author structural-pre-flight skill + integrate anchors across ticket-create / ticket-intake / epic-review. One PR scope: creates .agent/skills/structural-pre-flight/SKILL.md (lightweight router) + references/structural-pre-flight-workflow.md (full payload with Stage 0 mechanical trigger, Stage 1 fast-path, full Pre-Flight, chief-architect framing questions, map-maintenance Blocking AC, Strategy-vs-Tactics ADR threshold), AND adds anchor references to the new skill in the three existing skill bodies (Stage 3 "Substrate" hook in ticket-create, architectural-relevance gate in ticket-intake, mandatory invocation in epic-review). One review covers the cohesive feature.

2. ArchitectureOverview.md ADR-link audit + Structural Inventory enrichment (closes OQ5 substrate gap). Doc-only PR: add explicit links from each subsystem section to relevant ADRs (e.g., Memory Core section → ADR 0001 cross-process cache coherence; Wake Substrate section → ADR 0002 standards alignment). The map-as-pointer mechanism becomes substrate-grounded rather than aspirational.

Out of Scope

• Empirical-anchor refactor (relocate bridge-daemon.mjs + bridge-daemon-queries.mjs from ai/scripts/ to ai/daemons/bridge-daemon/) — graduates from Discussion #10448. That refactor will reference this Epic's skill as the discipline-substrate but is scoped distinctly.
• Broader ai/daemons/services/ flat-structure refactor for DreamService.mjs's siblings — same scope clause; defer to Gemini's bridge-refactor Discussion or a follow-up Epic.
• Adding non-.mjs triggers (.sh, .json, .md, etc.) — Phase 2 enhancement; current scope is .mjs per OQ1 resolution. Empirical anchor swarm-heartbeat.sh is acknowledged but not a current AC.
• Migration of existing misplaced files beyond the bridge daemon (which is in #10448's scope) — separate cleanup work. The new skill prevents future debt; existing debt is tech-debt-radar's domain.

Acceptance Criteria

• Sub-issue 1 merged: .agent/skills/structural-pre-flight/SKILL.md + reference payload exist and pass create-skill standards (Progressive Disclosure router + reference). Anchor references to the new skill present in .agent/skills/ticket-create/, .agent/skills/ticket-intake/, .agent/skills/epic-review/ reference payloads. Tests if applicable.
• Sub-issue 2 merged: ArchitectureOverview.md Structural Inventory has explicit ADR-links per subsystem; ADR 0001 + 0002 reachable via graph traversal from the map.
• Empirical regression test: a representative new-.mjs-creation ticket goes through the full pipeline (ticket-create → structural-pre-flight Stage 0 → either fast-path or full Pre-Flight) and verifies the discipline fires correctly.
• Discussion #10447 marked GRADUATED with this Epic's number (already done at Epic-creation time).

Avoided Traps

• Trap: Bundle the skill + bridge daemon refactor + flat-structure refactor in one Epic. Avoided: the bridge refactor has its own Discussion (#10448); conflating substrate-discipline-establishment with empirical-instance-fixing dilutes both.
• Trap: Skip the OQ5 self-eviction defense (assume agents will read ADRs by discipline alone). Avoided: I empirically failed exactly this discipline THIS session — authored ADR 0001 in a prior session, didn't surface it. Map-as-pointer is the substrate fix; relying on agent memory is the failure mode.
• Trap: Make the trigger subjective ("when work is architecturally relevant"). Avoided: that's the very judgment the bridge-daemon authoring failed at. Mechanical trigger (every new .mjs) + fast-path for trivial cases is the calibration that closes the gap.
• Trap: Make pull-request an integration anchor. Avoided: by PR time the architectural choice is fait accompli; PR review remains focused on review-template + final-state validation.
• Trap: Bloat the top-level SKILL.md router with full skill content. Avoided: per create-skill Progressive Disclosure pattern, SKILL.md stays a lightweight trigger + payload-pointer; full mandates live in references/structural-pre-flight-workflow.md.
• Trap (resolved this iteration): Over-decompose the Epic into one sub-issue per anchor edit. Avoided: consolidated the three 1-3-line anchor edits into the skill-authoring PR (one cohesive review unit). Per @tobiu's "a sub ticket for EACH 3-liner anchor with an own review?" calibration. Coordination overhead per sub-issue (branch + PR + review cycle) was disproportionate to the work content.

Related

• Graduates from: Discussion #10447
• Cross-family iteration partners: @tobiu (mechanical trigger framing), @neo-gemini-pro (Chief Architect input on OQ2-OQ6 + structural-only framing for Stage 1 fast-path)
• Empirical anchor refactor (separate scope): Discussion #10448 (@gemini, "Agent OS Tool Boundaries & Daemon Isolation")
• ADR consultation substrate: learn/agentos/decisions/0001-cross-process-cache-coherence.md, 0002-phase3-wake-substrate-standards-alignment.md
• Architectural map substrate: learn/benefits/ArchitectureOverview.md
• Existing skill anchors to extend: .agent/skills/ticket-create/, .agent/skills/ticket-intake/, .agent/skills/epic-review/
• Skill-design substrate: .agent/skills/create-skill/
• Memory-anchored meta-pattern from this session-arc: "turn friction into gold" via inline Anchor & Echo guards (PR #10445); recurrent stale-branch race (PR #10446 / #10425); skill-content-loaded ≠ skill-mandate-applied (the Discussion-body-update gap I corrected in iteration 2); over-decomposition into per-3-liner sub-issues (this very revision).

Origin Session ID: c68a7d4b-909a-4965-9bf9-116906d271a3

Retrieval Hint: "structural-pre-flight skill epic implementation phase 1 adoption every new mjs file architectural review pre-implementation discipline gap closure cross-family iteration consolidated 2 sub-issues"