@tyroneross/build-loop 0.30.3

package/skills/build-loop/references/modular-systems-pack.md

@@ -0,0 +1,96 @@
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# Modular Systems Pack
+
+Use this pack on every non-trivial build. It makes modular, scalable structure the default while allowing a simpler or more integrated approach when that better serves the use case.
+
+## Default
+
+Build-loop should prefer systems that are:
+
+- **Modular**: each module hides one important design decision behind a stable interface.
+- **Scalable**: the design can grow in data volume, user volume, feature count, or team ownership without immediate redesign.
+- **MECE**: task groups, file ownership, and agent scopes are mutually exclusive and collectively exhaustive.
+- **Pyramid-structured**: plans, handoffs, reports, and repo organization lead with the governing thought, then supporting groups, then details.
+
+This is a default, not dogma. The goal is durable user value, not extra architecture.
+
+## Exception Rule
+
+Do not add modularity for its own sake. Choose a simpler or more integrated approach when:
+
+- The change is a one-off script, short-lived migration, or isolated fix.
+- A new boundary would add indirection without reducing real complexity.
+- A performance hot path needs a tightly integrated implementation.
+- The repo is small and the added module structure would obscure the core workflow.
+- The product need is intentionally limited and extra optionality would confuse users.
+
+When taking an exception, record:
+
+```text
+MODULARITY EXCEPTION: <why simpler/integrated is better for this use case>
+```
+
+## MECE File And Agent Partition
+
+Phase 2 Plan must partition work so every changed file has exactly one owner and every required responsibility has an owner.
+
+For each task group, use this packet:
+
+```md
+Group: <name>
+Dimension: <domain | layer | workflow | bounded context | adapter | test surface>
+Owns files: <paths>
+Does not own: <paths handled elsewhere>
+Interface contract: <exports/events/API/schema it may change>
+Integration checkpoint: <command or review step>
+Intent link: <north-star or user-value rule this group supports>
+```
+
+MECE checks:
+
+- No overlap: a file or interface is not owned by two agents unless the plan defines a handoff point.
+- No gaps: every required behavior, state, migration, test, and user-facing surface has an owner.
+- One dimension per level: avoid mixing domains, layers, and workflows in the same grouping level.
+- Stable interfaces: agents can change internals, but cross-group contracts are explicit.
+- Integration checkpoint: every boundary has a test, build, visual check, schema check, or reviewer step.
+
+## Modular Design Heuristics
+
+- Hide volatile decisions behind small interfaces: data shape, provider choice, algorithm, storage, rendering strategy, or external API.
+- Prefer high cohesion: code that changes for the same reason lives together.
+- Prefer loose coupling: callers depend on published interfaces, not internal data structures or side effects.
+- Design around business/domain capabilities when the system is large enough for domains to matter.
+- Keep boundaries small enough to understand and large enough to own a useful capability.
+- Separate deploy/runtime config from code when values vary by environment.
+- Preserve directness when extra layers make the core workflow harder to read, test, or operate.
+
+## Pyramid Structure
+
+Use pyramid structure for plans, reports, repo notes, and agent handoffs:
+
+1. Governing thought: the one decision, result, or recommendation.
+2. MECE key lines: 3-5 non-overlapping supporting claims or work groups.
+3. Evidence/details: commands, files, risks, interfaces, and validation.
+
+For repo structure, this means names should communicate purpose, folders should group by one clear dimension, and cross-cutting utilities should stay genuinely shared rather than becoming a junk drawer.
+
+## Review Gates
+
+Critic and final review should flag:
+
+- Avoidable tight coupling or weak cohesion.
+- Hidden cross-file ownership overlap between agents.
+- Missing owner for a required behavior, state, migration, test, or user-facing surface.
+- Abstraction added without user, scalability, testability, security, or maintainability benefit.
+- Simplification that collapses a boundary needed for accuracy, security, scale, testability, or future optionality.
+- Missing `MODULARITY EXCEPTION` when the plan intentionally chooses an integrated shortcut.
+
+## Source Basis
+
+- Parnas, "On the Criteria to Be Used in Decomposing Systems into Modules" (CACM, 1972): https://cacm.acm.org/research/on-the-criteria-to-be-used-in-decomposing-systems-into-modules/
+- AWS Well-Architected REL04-BP02, "Implement loosely coupled dependencies": https://docs.aws.amazon.com/wellarchitected/2024-06-27/framework/rel_prevent_interaction_failure_loosely_coupled_system.html
+- Microsoft Azure Architecture Center, domain analysis for microservices: https://learn.microsoft.com/en-us/azure/architecture/microservices/model/domain-analysis
+- Microsoft Azure Architecture Center, design principles for Azure applications: https://learn.microsoft.com/en-gb/azure/architecture/guide/design-principles/
+- Twelve-Factor App config guidance: https://12factor.net/config
+- MECE framework overview: https://www.casestar.io/guides/mece

package/skills/build-loop/references/output-style.md

@@ -0,0 +1,129 @@
+# Output Style Contract — User-Facing Terminal Output
+
+Final user-facing output (Phase 4 Review-G report, phase status lines printed to the operator's terminal) must be **clear, direct, concise, and free of internal jargon**. This contract is enforced — `scripts/report_lint.py` runs on the draft before the user sees it, and Review-G auto-revises on findings (warn-and-self-heal, never a hard halt).
+
+It extends — does not duplicate — the existing guidance:
+
+- `CLAUDE.md` § "Concise output" — say only what the user needs to decide or act
+- `~/.claude/CLAUDE.md` § "Intentional word choice" — every line must transmit information the reader does not already have
+- `~/.claude/CLAUDE.md` § "Reporting Work" — pyramid-principle headline + verification line + impact-by-size
+
+Scope: **user-facing output only.** Internal agent-to-agent envelopes (subagent return JSON, judge-decisions, run records, MECE briefs) are structured data and stay as-is — they exist for machines, not the human.
+
+## The five rules
+
+1. **Headline = one plain full sentence** stating what changed. First non-blank line. Not a noun phrase, not a telegraph fragment, not a heading.
+2. **Bulleted concrete artifacts.** Below the headline: commit hashes, file paths, issue paths. Concrete things the user can grep, open, or `git show`.
+3. **Substance bullets.** What the change captures or does, in plain language. Optional when the artifacts alone are self-explanatory.
+4. **Validation line, explicit.** Name the exact command, method, or observer that verified the work, with a status marker:
+   - `✅ Verified by <method>` — ran the script, passing test, curl response, IBR scan, demo
+   - `⚠️ Untested — <what couldn't be verified and why>`
+   - `❓ Uncertain — <what's assumed and what would close it>`
+5. **Plain language.** No jargon (see blocklist below). No contrastive pivot (`not X — it's Y`, `isn't X, it's Y`, `not just X but Y`) — state the point directly.
+
+## Jargon blocklist (user-facing only)
+
+These tokens are fine in internal envelopes; they must be translated to plain language in user-facing output:
+
+| Internal token | Plain-language translation |
+|---|---|
+| `GAP-1`, `GAP-N` | Name the actual gap (e.g. "missing auditor dispatch") |
+| `auditor_status: not-run:parent-must-dispatch` | "Auditor not run — parent owes it" |
+| `auditor_status: ran:dispatched-agent` | "Auditor ran" or omit if obvious |
+| `sub-step G`, `sub-step F` | "Final report step", "Auto-resolve step", or omit |
+| `MECE` | "ownership split", "one owner per file" |
+| `envelope` | "return data", "result" |
+| `scope=build` | "full build review" or omit |
+| `suggest_correction` / `yay` / `nay` / `look_again` | "approve", "reject", "needs change", "needs another look" |
+| `Phase 4G` / `Phase 5` | "final review", "iterate step" |
+| `state.json.runs[]` | "run record" |
+| Internal phase codenames (C-HEAL, C-RCA, C-FLOW…) | Describe the behavior, not the code |
+
+## Good — the exemplar (Codex output, captured 2026-06-04)
+
+```
+- ad1ac79a memory(build-loop): capture native ax ui follow-up
+- Issue: dev/git-folder/build-loop-memory/projects/build-loop/issues/bl-native-ax-light-ui-gap-check.md
+- Backlog row added to .../backlog.md
+
+It captures:
+- skills/native-ax-driver/ as the home.
+- IBR as the primary/full verifier, native AX as the lighter gap/fill layer.
+- Blockers: clean main/fresh worktree and recovered AX/screencapture.
+
+Validation passed: python3 scripts/validate_memory_store.py --strict.
+```
+
+Why this is good: plain-sentence headline implied by the commit subject, bulleted concrete artifacts with paths and a commit hash, an "It captures:" substance block, and an explicit validation line naming the exact command. Scannable, direct, no jargon.
+
+## Good — exemplar B (scoped-edit narration, captured 2026-06-06)
+
+```
+Claim is recorded. I'm keeping the edit scoped: selector scoring plus one regression
+test that reproduces "old handoff masks newer targeted inbox/review request."
+[visible actions: git switch -c …, Explored: read/search …]
+The edit is small: add a typed helper for requires_ack evidence, score direct targeted
+artifacts as inbox-doorbell work, and cover it with a regression where a stale handoff
+used to hide the newer message.
+```
+
+Why it's good: declarative state → scope stated plainly with the bug in plain words → the change in one informed sentence.
+
+## Good — exemplar C (closeout note, captured 2026-06-06)
+
+```
+Commit 4392166 is created on fix/actionable-inbox-next. I'm posting the closeout to
+Rally and releasing the two file claims now.
+[visible actions: rally say release …, rally say artifact …]
+```
+
+Why it's good: states the landed artifact (commit + branch) → then the action-in-progress in one plain line.
+
+## Bad — verbose + jargon (rewritten Good)
+
+**Bad (jargon + filler):**
+
+```
+Phase 4G Sub-step G completed for the auditor dispatch ladder. The auditor_status
+field was changed to ran:dispatched-agent based on the GAP-1 contract; the build
+scope=build review-completeness gate passed. We've now wired the MECE envelope
+through the build-orchestrator so it propagates to the runs[] entry. Suggested
+correction verdict from independent-auditor: yay. Want me to push?
+```
+
+**Good (rewrite):**
+
+```
+Auditor now runs on every build commit; the gap where nested orchestrators
+skipped it is closed.
+
+- Commit: 7e54621 fix(audit): close nested-orchestrator audit gap
+- Files: agents/build-orchestrator.md, scripts/audit_before_commit.py
+- Run record: .build-loop/state.json runs[] entry build-2026-06-07-...
+
+It captures:
+- Nested orchestrators now hand the audit back to the dispatching parent.
+- Auditor's approve verdict recorded in .build-loop/judge-decisions.json.
+
+✅ Verified by python3 scripts/test_audit_before_commit.py — 14 passed.
+```
+
+## What stays internal (do not lint)
+
+These are structured data for machines, not user-facing prose:
+
+- Subagent return envelopes (JSON return values, `status: blocked | partial`, etc.)
+- `state.json` writes
+- `.build-loop/judge-decisions.json` entries
+- MECE brief packets between orchestrator and implementers
+- Rally Point post bodies on internal channels (peer-to-peer coordination)
+- `auditor_status` and other machine fields embedded in run records
+
+The lint targets ONLY the final user-facing report markdown + phase status lines printed to the operator's terminal. Inline backtick spans are NOT exempted — if an internal token appears in prose (even quoted), translate it; use a full fenced block only for verbatim code/trace the user should see literally.
+
+## Enforcement summary
+
+- `scripts/report_lint.py <draft.md> --json` runs on every Phase 4G draft
+- Findings are WARN (advisory): the orchestrator self-heals by revising the draft once, then emits it
+- Never hard-blocks a run — worst case is one revision pass
+- The structural lint (`scripts/build_report_lint.py`) keeps running in parallel; it is orthogonal (parallel_batch / merge_plan / evidence triplet shape)

package/skills/build-loop/references/pay-it-forward-arch.md

@@ -0,0 +1,98 @@
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# Pay-it-Forward Architectural Posture (full protocol)
+
+> Loaded from `skills/build-loop/SKILL.md` summary. Encodes the user's preference that scalability and product-roadmap unlocks matter more than short-term build velocity when costs aren't prohibitive.
+
+## The rule (verbatim, user-stated 2026-05-11)
+
+> *"I'd rather do a slightly harder thing now to avoid a more painful change in the future if not prohibited by costs or other concerns."*
+
+When a chunk has two viable implementations:
+
+- **Path A** — minimum-viable, working v1, easy to ship now.
+- **Path B** — same user-visible behavior, but extends the typed / structural contract so future surfaces can reuse it.
+
+**Default to Path B** unless one of the explicit gates below blocks.
+
+## Gates (Path B blocked when ANY is true)
+
+| Gate | Condition | Recommendation |
+|---|---|---|
+| **Time-budget gate** | Path B blows the immediate time budget by more than 2× (e.g. requires a schema migration when none was needed for Path A). | Fall back to Path A. |
+| **Missing dep / infra** | Path B requires a dependency or infrastructure not yet in the project. | Fall back to Path A. Note the dep as a roadmap item. |
+| **Missing design decision** | Path B requires a product/architecture decision the user has not yet made (multi-tenant boundary, auth model, etc.). | Fall back to Path A. Surface the decision in the plan's Open Questions section. |
+| **Empty foreclosed-future-capability list** | Path B's "what does this unlock?" list is empty — no named future capability needs the typed contract. | Fall back to Path A. The "flexibility" is speculative. |
+
+## Anti-pattern explicitly excluded
+
+Path B that's flexibility-for-its-own-sake is **NOT** what this rule means. Excluded shapes:
+
+- Plugin/extension systems with no named future plugin.
+- Abstract factories / hook architectures for a single current consumer.
+- Generic event buses for a single producer / single consumer pair.
+- Parameterized configs whose only caller hardcodes one value.
+
+Path B must be tied to a **NAMED** future capability that's in the roadmap, PRD, intent.md, or stated user goal. "Future flexibility" is not a named capability.
+
+## When this fires
+
+Phase 2 Plan must trigger a Path A / Path B comparison for any chunk that touches:
+
+1. **A typed protocol or interface boundary** — engine types, API contracts, DB schemas, message schemas, envelope shapes, MCP tool input/output schemas, agent return contracts.
+2. **User-facing behavior servable by multiple surfaces** — a feature that could theoretically be exposed via chat + voice + native + email + CLI. Even if today only one surface uses it.
+3. **A consumer where the path of least resistance inlines the contract** — prompt templates that embed business logic, route handlers that JSON-shape ad-hoc, single components that own a state machine.
+4. **A schema change** — any addition/modification to a typed boundary (Prisma schema, Pydantic model, TypeScript interface, JSON Schema, Protobuf message).
+
+If the chunk fits NONE of these signals, skip the comparison and proceed.
+
+## How to apply (Phase 2 Plan output)
+
+For each chunk that fires the signal above, the plan must include:
+
+```markdown
+### Path A vs Path B — <chunk name>
+
+**Path A (minimum-viable):**
+- <one paragraph: what gets shipped, where the contract lives>
+- Time estimate: <derived from t-shirt size>
+- Limitation: <what future capability is foreclosed if we go this way>
+
+**Path B (typed-contract extension):**
+- <one paragraph: what gets shipped, where the contract lives>
+- Time delta vs A: <e.g. "+30 min — adds 1 type definition + 1 module boundary">
+- Unlocks (named future capabilities, NOT generic flexibility):
+  - <capability 1, with citation to roadmap/PRD/intent.md>
+  - <capability 2, with citation>
+
+**Gates check:**
+- Time-budget (>2× A)? <yes/no>
+- Missing dep / infra? <yes — name it / no>
+- Missing design decision? <yes — name it / no>
+- Foreclosed-future list empty? <yes — explain / no — list above>
+
+**Recommendation:** **Path B** (default) / **Path A** (because <named gate>).
+```
+
+The orchestrator's default recommendation is **Path B**. User may override to A on plan acceptance.
+
+## Examples (from user's prior decisions)
+
+- **Clarifier flow**: prompt-layer (A) vs engine-typed (B) — Decision Doctor C6b. Path B chosen because typed engine output unlocked voice + native surfaces named in the PRD.
+- **Auth checks**: per-route gate (A) vs middleware abstraction (B). Path B chosen when 3+ routes need the check; Path A when only one route.
+- **Theme**: hardcoded primary color (A) vs CSS-var token scaffold (B). Path B chosen when alt-theme is on the roadmap; A otherwise.
+- **Search results**: route-shape JSON (A) vs typed result schema in `lib/` (B). Path B chosen when a second consumer (chat tool, RSS export) is already planned.
+
+## Phase 4 Review-A Critic check
+
+When reviewing a commit that landed on Path A, the critic asks: did the plan's Path A/B section name a gate that justified A? If the plan lacked the section entirely AND the chunk fits the signals above, flag as a strong checkpoint: **"missing Path-A-vs-B analysis on a typed-boundary commit."**
+
+This is a process check, not a re-implementation request — the commit can still ship on A, but the synthesis decision should be on the record.
+
+## Relationship to existing packs
+
+- **Intent Capability Pack** (`references/intent-capability-pack.md`) — captures user value + non-goals. Provides the named-future-capability list this pack draws on.
+- **UI Input/Output Contract** (`references/ui-io-contract.md`) — names every user input/output. Surfaces the "could be served by multiple surfaces" signal.
+- **Modular Systems Pack** (`references/modular-systems-pack.md`) — MECE/cohesion/coupling defaults. Path B usually advances modularity; Path A often inlines responsibilities.
+
+The three packs together establish *what* the build is for and *how* it should be structured. The pay-it-forward pack establishes *which version* to ship when there's a choice.

package/skills/build-loop/references/phase-1-assess.md

@@ -0,0 +1,218 @@
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# Phase 1: Assess (full protocol)
+
+> Loaded from `skills/build-loop/SKILL.md` summary. Contains the full Assess phase: state understanding, goal definition, and scoring criteria.
+
+## Phase 1: Assess — State, Goal, and Criteria
+
+**Goal**: Know what exists AND what success looks like before writing any code. Combines situational awareness with goal definition so the plan phase has everything it needs.
+
+### Understand current state
+
+0. **Peer-detection (cheap fail-fast — runs BEFORE plugin detection so a peer collision is surfaced before any other Phase 1 cost is paid).** Bash, ≤4 commands; output goes into the assess report. **The check is automated end-to-end — never pauses to ask the user.** Any non-empty line is written to `state.json.assess.peerDetect[]` and surfaces in `## Notes from judges`. Phase 2 Plan auto-routes per default policy: if scope overlap is detected, the orchestrator fast-forwards (`git merge --ff-only`) when ancestry allows, otherwise splits the affected chunks out and continues, logging `WARN: peer_collision_<kind>` either way. Operator reviews the report post-hoc. Complements Rally Point session-presence (§"Multi-session concurrency" in `agents/build-orchestrator.md`) — Rally Point covers active *sessions*; this covers dormant *artifacts* (coordination notes, stale worktrees, unmerged branches) those sessions leave behind.
+
+   ```bash
+   ls .build-loop/coordination/*.md 2>/dev/null | grep -v /archived/   # live coordination notes
+   git worktree list --porcelain                                       # all worktrees
+   git worktree list --porcelain | awk '/^worktree /{print $2}' \
+     | while read -r wt; do [ -d "$wt" ] && echo "$wt dirty=$(git -C "$wt" status --porcelain 2>/dev/null | wc -l | tr -d ' ')"; done  # per-worktree dirty (Codex addition: dirty is stronger signal than branch merge status)
+   git branch -a --no-merged main | grep -vE 'archive|HEAD'            # unmerged branches
+   ```
+
+   Helper errors (`grep -v`/`awk` non-zero) are NOT a failure — empty output means clean. Any non-empty line surfaces in the assess report for Phase 2 to reason about.
+
+0a. **Credential preflight** (fail-soft, names only — no values ever surfaced): run
+
+   ```bash
+   python3 "${CLAUDE_PLUGIN_ROOT}/scripts/credential_preflight.py" \
+     --workdir "$PWD" --json
+   ```
+
+   Write the result to `.build-loop/state.json.assess.credentialPreflight`. If `missing[]` is non-empty, surface each name as `[CREDENTIAL REQUIRED] <name>` in the Assess summary and repeat verbatim in the end-of-run readback. A missing credential is a "genuine inability to proceed" under the autonomy policy: log it, continue all work that does not require the key, and surface it in the readback — do NOT stop-and-ask. Script failure (non-zero exit / bad JSON) → log one warning line; never blocks Assess.
+
+0b. **Stale-context triage** (fail-soft, proactive drift notice): run
+
+   ```bash
+   python3 "${CLAUDE_PLUGIN_ROOT}/scripts/stale_context_check.py" \
+     --workdir "$PWD" --json
+   ```
+
+   Write the result to `.build-loop/state.json.assess.staleContext`. For each path in `docs[]` where the doc is flagged stale, surface it as `[STALE CONTEXT] <path>` in the Assess summary so the agent notes drift before relying on a handoff/orchestration/continuation doc. The user should never have to ask "is this still relevant?" Script failure → log one warning line; never blocks Assess.
+
+0c. **Memory-staleness triage** (fail-soft, proactive drift notice): run
+
+   ```bash
+   python3 "${CLAUDE_PLUGIN_ROOT}/scripts/memory_staleness_check.py" \
+     --workdir "$PWD" --json
+   ```
+
+   Write the result to `.build-loop/state.json.assess.memoryStaleness`. When `stale: true`, surface `[MEMORY STALE] <slug> N commits behind HEAD — append a milestone/decision` in the Assess summary. Log the finding and continue — do NOT stop. The run should append a milestone or decision entry during Phase 6 Learn (or inline if the goal is memory-focused). Script failure → log one warning line; never blocks Assess.
+
+1. **Detect available plugins and personal skills**: Run `node ${CLAUDE_PLUGIN_ROOT}/skills/build-loop/detect-plugins.mjs`. Write the JSON result into `.build-loop/state.json` under `availablePlugins`. All subsequent routing consults this object.
+2. **Detect project type**: web app, API, library, mobile, CLI, monorepo, **Claude Code plugin**, one-shot new app, existing-app iteration. A plugin is detected by the presence of `.claude-plugin/plugin.json`, `hooks/hooks.json`, `skills/*/SKILL.md`, `commands/*.md`, `agents/*.md`, or `.mcp.json`. If detected, mark the build as "plugin work" in state.json and plan to load the `plugin-dev:*` skills before any manifest/hook/skill/agent/MCP/command/**scripts/** edits. **Any change to a file referenced via `${CLAUDE_PLUGIN_ROOT}/...` counts as plugin work** — this includes `scripts/*.py`, `references/*`, or anything else the plugin manifests, agents, or skills invoke at runtime. These files live in `~/.claude/plugins/cache/<marketplace>/<plugin>/<version>/` at run time; editing only the source repo without syncing the cache leaves the runtime invocation broken (Lessons §5 + §5a in `plugin-hygiene-lessons.md`).
+3. **Set sub-routers**: `uiTarget` (web / mobile / **macos** / null), `platform` (web / apple / react-native / null), `migrationSource` (replit / lovable / bolt / v0 / null). See the Capability Routing §Sub-routers rules. **macOS desktop is a first-class `uiTarget`** — distinct from `mobile` — because macOS has no simulator and routes visual-verify to `native-ax-driver` (or IBR `scan_macos` when present), never to `xcrun simctl`. Folding macOS into `mobile` was the routing bug from session-findings 2026-06-04.
+4. **Detect available tools**: test runners (`package.json` scripts, `pytest.ini`, etc.), linters, deploy targets.
+   - **Deployment policy**: read `.build-loop/config.json.deploymentPolicy` if present. Defaults are `preview: auto`, `testflight: auto`, `production: confirm`, `unknown: confirm`. Use `python3 ${CLAUDE_PLUGIN_ROOT}/scripts/deployment_policy.py --workdir "$PWD" --command "<candidate push/deploy command>"` before any push/deploy. Treat helper errors as `confirm`.
+5. **Map architecture** using best available approach:
+   - If `.navgator/architecture/index.json` exists → invoke `Skill("build-loop:architecture-scan")` to refresh data, then `Skill("build-loop:architecture-impact")` on up to 5 highest-risk components for blast-radius. Output goes to `.build-loop/state.json.architecture.{scan,impact}`. Phase 2 Plan consults this for scoping. Flags high-fan-in hotspots, 2-hop dependents, layer-crossing risks, and prompts-in-scope when `triggers.promptAuthoring` is true.
+   - Else if `gator:*` is available → use those commands.
+   - Else → Explore agents → file reading.
+5a. **Architecture portable handoff** (read on resume; write on fresh scan): after the architecture baseline above, the scan result must also be written to `.build-loop/architecture/handoff.md` as a self-contained snapshot — component map, key connections, runtime topology, LLM use-cases, and data flows — that a FRESH session can consume WITHOUT re-scanning. On a resumed or fresh session, Phase 1 reads `.build-loop/architecture/handoff.md` if it exists and its `updated_at` timestamp is within the staleness threshold (default: same as stale-context check), and skips the full re-scan. The format and field schema are specified in `agents/build-orchestrator.md` (architecture-scout section); this step only wires the read/write reference. Write failure → log one warning; never blocks.
+
+5b. **Reads-from dependency enumeration**: For each component the build will change or add, enumerate every data path, contract, or invariant it reads (config files, state keys, schema fields, API contracts). For each, verify something writes it — grep the repo, check test fixtures, or confirm the schema. Record results in `.build-loop/state.json.assess.readsDependencies[]` as `{path, writer_found: true|false}`. Any path with `writer_found: false` is a BLOCKING unknown that must appear as `unverified` in the plan's `## Depends-on (reads-from)` section and be resolved before Phase 3.
+
+6. **Observability baseline** (informational, no changes): run a stack-appropriate grep to classify the project's logging level (well-instrumented / print-only / silent) and write to `.build-loop/state.json.observability.level`. The orchestrator handles this inline — `Skill("build-loop:logging-tracer")` is reactive only and is loaded later if Review-B / Iterate hits a silent failure.
+6b. **Attribution-layers detection** (informational, advisory only — never blocks, never pauses): run `python3 ${CLAUDE_PLUGIN_ROOT}/scripts/detect_attribution_layers.py --workdir "$PWD"` when the repo has a GitHub origin remote. Write the result to `.build-loop/state.json.attribution`. When `should_advise: true`, surface the returned `advisory` line in the Phase 1 Assess report under `## Notes from judges`. Phase 2 Plan queues an automatic chunk to run `scripts/attribution_stamp.py` when the build scope is ≥ S; smaller scopes only surface the advisory and let the user run it manually. Per `feedback_advisory_checks_are_automated`: this routes to the run report, never to AskUserQuestion or `## Held`. Helper failure → treat as `should_advise: false` and log a one-line warning. The full procedure for stamping is in `skills/attribution-standard/SKILL.md`.
+
+6a. **Runtime-server detection** (informational, no changes): run `python3 ${CLAUDE_PLUGIN_ROOT}/scripts/detect_runtime_server.py --workdir "$PWD" --json` and write the result to `.build-loop/state.json.triggers.runtimeServer` (boolean) plus `.build-loop/state.json.runtimeServerInfo` (full envelope: `server_module`, `sse_route`, `default_port`, `embedded_ui_module`, `event_handler_locations[]`, `evidence[]`). Phase 4 sub-step B Validate consults these for the live HTTP/SSE smoke gate. Helper failure → treat as `runtimeServer: false` and log a one-line warning; never blocks. Silent default for CLIs, libraries, plugins, and static-render web apps. Implements decision `_unscoped/0003` (live smoke required when build-loop touches a runtime server) — closes the pytest-with-mocks blind spot that let example-app ship 27 commits with two real bugs.
+7. **Debugger context priming** (always; native to build-loop): invoke `Skill("build-loop:debugging-memory")` with `{ intent: "list-recent", project: "<current>" }` to summarize recent incidents in this project. One-line output; no action. If cross-project Coding Debugger is installed, the skill may use it; otherwise it falls through to `fallbacks.md#bug-memory`.
+8. **Capture UI state** (if web/mobile): host browser/screenshot tooling or simulator/native-AX evidence when available → showcase capture → manual screenshot. Do not route to IBR unless the user explicitly requested it.
+8a. **UI input/output inventory** (if `uiTarget != null`): load `skills/build-loop/references/ui-io-contract.md` and identify every affected user input and system output before component choices are made. Classify each by structural type, content format, persistence intent, operation/domain verb, component mapping, state matrix, modality fallback, validation/security layer, and traceability. Mirror a compact summary to `.build-loop/state.json.uiIOContract` when practical; the full contract is finalized in Phase 2.
+
+8b. **Load short-term working context (Pillar 0 — structurally loaded first, inside memory bootstrap)**: `context_bootstrap.build_packet()` calls `load_current(workdir)` at its very entry, before any heavier memory work, and attaches the result as `packet['working_context']` (a serialized `WorkingContextEnvelope`). The working context is therefore available as part of the Phase-1 packet without a separate CLI step.
+
+   Consume it directly from the packet:
+
+   ```python
+   wc = packet["working_context"]   # {exists, path, warm_read_latency_ms, parsed, reasons}
+   ```
+
+   Use `wc["parsed"]["links_down"]` as the entry pointers DOWN into long-term memory (P1 hybrid recall + P4 prior-art). Missing / corrupt `current.md` → `wc["exists"] == False` + `wc["reasons"]`; never blocks Phase 1 or bootstrap. Mirror `wc["warm_read_latency_ms"]` into `.build-loop/state.json.assess.workingContextLatencyMs` for the Phase 4G report.
+
+   The standalone CLI (`python3 ${CLAUDE_PLUGIN_ROOT}/scripts/load_current.py --workdir "$PWD" --json`) remains available for manual inspection but is no longer a required Phase-1 step — the enforced path is via `build_packet()`.
+
+9. **Load memory**: Run the automatic context bootstrap before planning:
+
+   ```bash
+   python3 ${CLAUDE_PLUGIN_ROOT}/scripts/context_bootstrap.py \
+     --workdir "$PWD" \
+     --query "<goal-keywords>" \
+     --output "$PWD/.build-loop/context-bootstrap.json" \
+     --json
+   ```
+
+   The packet must include canonical `build-loop-memory` root/project `MEMORY.md` and `constitution.md` files, indexed recall, repo-local `.build-loop/feedback.md`, `.build-loop/state.json`, current plan/goal/intent, Codex memory registry `~/.codex/memories/MEMORY.md` plus linked rollout summaries, and best-effort Rally/coordination state when coordination context exists. If the root constitution is absent, `context_bootstrap.py` seeds it once from the shipped template before reading; it never overwrites existing root or project constitution files. Missing surfaces are recorded in `sources.*.reasons[]`; they do not block Phase 1 by themselves. See `references/memory-systems.md` §"Read protocol — Phase 1 Assess".
+
+   **Cross-project prior art (P4 — payoff)**: the bootstrap also emits `packet.prior_art`, a compact cross-project digest of prior implementations + linked decisions for the task's classified capability. Powered by `scripts/capability_classifier.py` (deterministic, host-LLM-refinable) and `scripts/prior_art.py` (reuses P1 hybrid recall + scans `projects/<slug>/decisions/` and `projects/<slug>/lessons/` across other projects). The digest is compact (hard char cap — `prior_art.DEFAULT_MAX_TOTAL_CHARS`, 4000 chars) and absence-tolerant (empty memory → empty payload, never blocks). `build_packet()` **enforces** the write by calling `context_bootstrap.write_prior_art_to_intent(workdir, digest_text)` immediately after building the packet: when the digest is non-empty AND `<workdir>/.build-loop/` exists, it appends (or idempotently replaces) a `<!-- prior-art:start -->`…`<!-- prior-art:end -->` block in `.build-loop/intent.md` (creating the file when absent). Re-running replaces the block — never duplicates. The agent brief still carries the compact pointer line for quick orientation; the full digest body is in the file. Disable via `BUILD_LOOP_PRIOR_ART=0`.
+
+   Then write the first live handoff snapshot:
+
+   ```bash
+   python3 ${CLAUDE_PLUGIN_ROOT}/scripts/context_snapshot.py \
+     --workdir "$PWD" \
+     --trigger phase_transition \
+     --phase assess \
+     --message "Phase 1 context bootstrap complete" \
+     --if-changed \
+     --json
+   ```
+
+   This refreshes `.build-loop/context/current.md` for later agents. Snapshot failure is a context-quality warning, not a Phase 1 blocker.
+
+9a. **Run identity + multi-session presence (Rally Point)** (always; runs at the Phase 1 preamble before any Rally Point write):
+   1. Generate or resume durable run identity + isolated worktree: `execution = scripts/rally_point/build_loop_id.generate_or_resume(workdir="$PWD", tool="<tool-id>", session_id="<session-id>", provision_worktree=True)`. This writes `state.execution.build_loop_id` and `state.execution.run_label` when missing, preserves them on resume, and updates only `current_session_id`. **`provision_worktree=True` is mandatory: it provisions `.build-loop/worktrees/run-<id>` on `bl/run-<id>` (fail-closed; aborts the run rather than touch the canonical checkout) and records `state.execution.run_worktree_path` for all downstream git/file ops. Structural fix for shared-checkout contamination — see `docs/SPEC-run-worktree-isolation.md`.**
+   2. Resolve the channel: `slug = scripts/rally_point/channel_paths.app_slug(cwd="$PWD")` (D1: worktree/clone-independent — main checkout and every worktree share one channel). Do NOT reimplement slug derivation.
+   3. Write presence: `scripts/rally_point/presence.write_presence(channel, session_id=..., tool="claude_code", model=..., run_id="$RUN_ID", app_slug=slug, phase="assess", files_in_flight=[])`. Codex / Gemini / other hosts substitute their `tool` value. Fire-and-forget. The writer attaches top-level `build_loop_id` and `build_loop_run_label` from `state.execution`.
+   4. Read active peers: `peers = scripts/rally_point/presence.read_active_presence(channel, exclude_session=...)` (also reaps stale presence past the heartbeat window — no daemon).
+   5. Route per `agents/build-orchestrator.md` §Multi-session concurrency — **awareness only, never a hard block (D4)**:
+      - No peers / no `files_in_flight` overlap → log one line per peer (tool, run_id, phase); continue.
+      - Overlap with a peer's `files_in_flight` → surface a `soft-claim` WARNING (peer, files, phase); continue with awareness. Interactive MAY additionally `AskUserQuestion` to coordinate; headless logs + proceeds. No SAFE-STOP sentinel, no non-zero exit.
+   6. Initialize the memory-index cursor: capture the current top-of-log timestamp from `python3 ${CLAUDE_PLUGIN_ROOT}/scripts/memory_index.py tail --limit 1 --json` (used by `--since` in subsequent phases to surface new peer learnings).
+
+   **Supersedes** the legacy `ps aux | grep -c "[c]laude$"` advisory below — Rally Point presence is the canonical signal. Keep the legacy line as a fallback only when Rally Point is unavailable (older plugin cache without `scripts/rally_point/`).
+
+10. **Load PRD if present** (strategic frame check): load `build-loop:prd-bridge`, run its Phase 1 Assess step. If `docs/prd-*.md` exists, the bridge reads frontmatter (`core_principles`, `load_when`, `evolves_when`), Navigation Map, and Section Index, mirrors them to `.build-loop/state.json.prd`, and surfaces staleness signals. If no PRD exists, the bridge writes a one-line recommendation in `state.json.prd.recommendation` pointing to `prd-builder` skill / `/build-loop:start-prd` command — surfaces in Sub-step G Report's `## Held` section, doesn't block. Step 11 below uses PRD as primary source of truth when present; falls back to fresh capture when absent.
+11. **Capture north star + update intent**: When `state.json.prd.core_principles` is non-empty (a PRD was loaded by step 10), use it as the strategic frame; `intent.md` cites the PRD path + revision rather than re-deriving. Otherwise use `references/intent-capability-pack.md` to identify app/repo purpose, primary users, core jobs, update intent, user value, and non-goals fresh. Write `.build-loop/intent.md` and mirror compact fields to `.build-loop/state.json.intent`.
+
+    **Intent restatement protocol (always-on, LLM-judged)**: as part of writing `intent.md`, follow `references/intent-capability-pack.md` § Intent restatement protocol — write a one-line concrete restatement always; when the orchestrator LLM judges the goal genuinely ambiguous (per Step A heuristics), extend with 1-3 approach options + tradeoffs + tagged assumptions. The judgment is the orchestrator LLM's, not a regex or detector script. For a concrete unambiguous goal this is one line and the flow moves on immediately — zero fast-path friction. Never `AskUserQuestion`, never `## Held`, never blocks Phase 1. Fail-safe: any error here is logged as one line; the build continues. Phase 2 Plan's "fork on uncertainty" rule consumes `state.json.intent.approach_options` when the LLM's confidence stays medium/low AND Phase 2 surfaces 2+ viable approaches.
+
+12. **Assess modular structure**: Use `references/modular-systems-pack.md`. Identify current module boundaries, stable interfaces, coupling risks, likely MECE work partitions, and any justified modularity exception. Mirror compact fields to `.build-loop/state.json.structure`.
+12a. **Capture approach lenses**: For any non-trivial architecture, workflow, dependency, UI/product, or long-lived interface recommendation, assess two separate answers before planning:
+    - **Clean-sheet best approach**: what would be best for the use case if prior repo decisions, accumulated tech debt, and current implementation constraints did not exist.
+    - **Current-constraints best approach**: what is best given the repo's existing code, dependencies, tools, debt, team/runtime constraints, migration cost, and delivery horizon.
+    - **Bridge/backcast**: the smallest credible path from current state toward the clean-sheet target, including debt retired, dependencies added/removed, and decision points.
+
+    Prior decisions are evidence, not axioms. Do not discard current constraints; isolate them so Phase 2 can decide whether they justify a compromise. Mirror the compact summary to `.build-loop/state.json.approachLenses` with `clean_sheet`, `current_constraints`, `constraint_delta`, and `bridge_backcast` fields.
+13. **Check prior state**: Read `.build-loop/issues/` and `.build-loop/feedback.md` if they exist. Surface relevant items. If any issue affects the current user's experience, add it to the plan unless too large or risky; otherwise log and defer with user impact.
+14. **Research trigger + depth gate**: run the deterministic classifier and cache the result:
+
+   ```bash
+   python3 "${CLAUDE_PLUGIN_ROOT}/scripts/research_trigger.py" \
+     --workdir "$PWD" \
+     --task "<goal text>" \
+     --effort "<XS|S|M|L|XL>" \
+     --cache-into-state \
+     --json
+   ```
+
+   This writes `.build-loop/state.json.researchGate`. Use
+   `references/research-trigger-policy.md` for trigger policy and t-shirt depth
+   lower bounds. If `research_required: true`, run the Research plugin at the
+   returned depth (`light`/`standard`/`deep`) or record why it was unavailable.
+   If `blocks_final_claims: true`, final current/external/API claims need
+   citations or an explicit unavailable/unverified note.
+14a. **Active task surface**: when the user asks what remains, when Phase 1
+   surfaces open work, or before queue-continuation decisions, run:
+
+   ```bash
+   python3 "${CLAUDE_PLUGIN_ROOT}/scripts/task_surface.py" \
+     --workdir "$PWD" \
+     --json
+   ```
+
+   This is the canonical active view over existing state, queue, and
+   project-scoped memory backlog surfaces. Do not create a second task ledger by
+   default. See `references/task-capture-policy.md`.
+15. **Recovery check**: This used to be a phase-level marker. As of v0.11 the canonical recovery surface is the `--resume` argument and the heartbeat-staleness path documented under §Resume Protocol. The pre-Assess resolver already ran by the time Phase 1 starts; if it returned `decision: "prompt_user"` and the user chose "fresh", proceed normally; if they chose `--resume`, you're not in this code path (the agent is in §0 Resume mode instead).
+16. **Workspace concurrency check** (advisory, no blocking — surface as one-line notes):
+    - **Concurrent sessions**: `ps aux | grep -c "[c]laude$"`. If `>1`, warn that other sessions on this repo can silently revert each other's work; the checkpoint reactions (severity + reason) tell you whether overlap is `merged_residue` / `squash_landed` / `active_conflict`. See `agents/build-orchestrator.md` §Multi-session concurrency.
+    - **Branch divergence**: `git rev-list --count HEAD..origin/main` and `origin/main..HEAD`. If local main is ahead of origin AND a feature branch will be cut, recommend branching from `origin/main` directly (`git checkout -b <name> origin/main`) so unpushed local commits don't ride into the eventual squash and bundle under a misleading title.
+    - **Recovery if symptoms appear during build** (file writes vanish, system reminders flag "intentional" reverts, `git status` clean): pause edits, run `ps aux | grep claude` + `git log --oneline -- <affected paths>` to identify the colliding session/squash, then re-apply dropped work on a fresh branch from `origin/main`.
+
+### UI scope and mockup pre-flight (when uiTarget != null)
+
+**UI pre-flight**: If project has `mockups/` or `.mockup-gallery/` and goal references selected mockups, run the design-rule scanner against the mockup HTML/CSS first to surface conflicts before coding:
+   ```
+   node "${CLAUDE_PLUGIN_ROOT}/skills/build-loop/scanners/audit-design-rules.mjs" --root=<mockups_dir> --platform=html --json
+   ```
+   Log conflicts to `.build-loop/issues/mockup-rule-conflicts.md`. Don't block — agents need to know upfront which rules trump the mockup. Mockups are intent, rules are law. See `phases/ui-validation.md` for full guidance.
+
+### Define goal and scoring criteria
+
+14. **State the goal** in concrete, measurable terms.
+15. **Suggest 3-5 scoring criteria** from: functionality, code quality, UX, performance, security, accessibility, test coverage — select what's relevant to the project and goal. Include intent fidelity/user value when the change affects user experience or product behavior. Include modularity/MECE/scalability when the change spans modules, agents, domains, repo areas, data boundaries, or long-lived interfaces. Show for confirmation.
+
+    **Warning/lint criteria MUST be relative, not absolute** (R4 from the 2026-05-19 iOS retro). An absolute "zero warnings tagged X" criterion false-fires on pre-existing warnings, forcing subagents to either lie, exit-fail honest work, or write apologetic prose. Author as **"no NEW warnings matching `<filter>` vs `git merge-base origin/main HEAD` using the same build command, destination, SDK, and filter"** (Codex correction: baseline only valid when capture and current invocations match). Inline diff helper:
+    `comm -23 <(<current> 2>&1 | grep -E 'warning:' | grep -E '<filter>' | sort -u) <(<baseline> ... | sort -u)`. Persist baselines as plain text under `.build-loop/baselines/warnings-<base-sha>-<filter-slug>.txt` only when one is needed; ad-hoc capture is fine.
+
+   **When `uiTarget != null`, the following criteria are REQUIRED and added automatically (not optional)**:
+   - **UI-1 Design-rule compliance**: scanner exits 0 on changed files (must-fix=0). Grader: code (`audit-design-rules.mjs`).
+   - **UI-2 Reduce Motion compliance**: every animation gated on platform's reduce-motion API. Grader: code (scanner rule `animation-without-reducemotion`).
+   - **UI-3 Theme token usage**: no raw color literals or hardcoded radii outside theme files. Grader: code (scanner rules `uicolor-rgb-outside-theme`, `literal-corner-radius`, `hex-color-outside-theme`).
+   - **UI-4 Accessibility labels**: icon-only graphics have explicit labels. Grader: code (scanner rule `sf-symbol-without-label` or web equivalent).
+   - **UI-5 Input/output contract coverage**: every changed UI surface has a plan row naming user inputs, system outputs, data taxonomy, operation/domain verb, component mapping, states, modality fallback, validation/security, and traceability. Grader: code/document check (`check_checklist.py` Item 17 plus Review read).
+
+   These exist because mockup-parity ≠ design-rule compliance, and component polish does not prove the UI handles the right data. Code that matches the mockup but omits an input, output, state, validation layer, or fallback is not production-ready. See `phases/ui-validation.md` and `references/ui-io-contract.md`.
+
+16. **Design eval graders per criterion** using the grading hierarchy:
+    - **Prefer code-based graders** (fast, deterministic, cheap): test suite pass/fail, lint/type check, build succeeds, schema validation, accessibility audit
+    - **Use LLM-as-judge graders** when code can't check the criterion:
+      - Binary pass/fail only — no Likert scales
+      - One evaluator per dimension — no multi-dimension God Evaluator
+      - Judge reasons in thinking tags, outputs only pass/fail
+      - Use the running host model/session as judge
+    - Each criterion gets: `description | grading method | pass condition | evidence required`
+    - Load `eval-guide.md` in this skill directory for judge prompt template and scorecard format if needed.
+17. **Write goal file**: Save to `.build-loop/goal.md` in the project directory.
+18. **Synthesis-density routing** (REVISED 2026-05-07 round-4 — Phase 1 routing with explicit speed/quality lanes): if a plan file already exists, count its `synthesis_dimensions:` entries via `count_synthesis_dimensions()` in `scripts/plan_verify.py` (shared parser; do NOT write a second). Resolve tier in this priority order:
+   1. **Explicit override** — `.build-loop/config.json.modelOverrides.thinking` or `state.json.config.modelOverrides.thinking` set OR plan/chunk frontmatter declares `tier: thinking` → route to thinking-tier.
+    2. **Auto-escalate on density** — `count > 5` (6+ entries) → `tier: thinking` (synthesis-dense at commit level; fan-out loses cross-dimension coherence).
+    3. **Default — Sonnet fan-out for speed** — `count` 1–5 OR `count == 0` → fan-out. Sonnet's ~33% wall-clock and ~28% token savings are real; C3-C5 backstops catch the residual recall gap.
+    4. **Per-chunk override** — individual chunks may declare `tier: thinking` even when plan-level was fan-out.
+
+   Write to `state.json.synthesisDensity` as `{count, escalated, reason}`. Routing target is `tier: thinking`, **never a hardcoded model name** (`scripts/model_overrides.py`: repo config → state snapshot → orchestrator frontmatter fallback → fail-loud). When `escalated == true`, do NOT fan out; execute inline at thinking-tier.
+
+    **Why this shape:** n=6 A/B experiment (2026-05-07, `~/dev/research/topics/synthesis-decision-delegation/experiment-2026-05-07/`) showed β catches ~40% of α's novels — real quality gap — but also showed β saves ~33% wall-clock and ~28% tokens, and the C3-C5 backstops catch some leaks. Defaulting Opus universally would erase β's velocity; the `> 5` threshold matches the empirical inflection point where β's recall collapses (C5 at 5 dims surfaced 0 novels vs α's 5). Below that, fan-out is the right speed choice; above it, depth dominates. Plan/chunk-level overrides let the operator pick quality > speed when needed without changing the default. See `agents/build-orchestrator.md` Phase 1 for full procedure.
+
+**Output**: Structured state summary + `.build-loop/intent.md` + `.build-loop/goal.md` with criteria. Brief.