@tyroneross/build-loop 0.30.3 → 0.35.0

package/skills/research/SKILL.md

@@ -53,10 +53,37 @@ Produces a repo-grounded research packet without committing to implementation. U
 [What could go wrong, what's uncertain]
 
 ## Confidence
-- Context coverage: high/medium/low
-- Verification coverage: high/medium/low
-- Evidence quality: high/medium/low
-- Overall: high/medium/low
+
+Rate each axis high/medium/low, then set Overall to the floor of the three —
+and never above Evidence quality when the packet rests on external claims:
+
+- Context coverage — how much of the relevant repo was actually read
+- Verification coverage — share of material claims checked against repo or source
+- Evidence quality — strength of the sources behind external claims (rubric below)
+- Overall — the floor of the above
+
+### Source & claim rubric (apply to every external claim)
+
+Tier each source: **T1** official docs / standards / primary data · **T2**
+recognized experts / official eng blogs · **T3** reputable industry press ·
+**T4** forums / SEO / unattributed. Then grade the claim's corroboration and
+mark it inline:
+
+- ✅ verified — ≥2 *independent* T1/T2 sources agree (independent = different
+  orgs, not mirrors or one syndicated wire)
+- ⚠️ partial — exactly one T1/T2, or only T3/T4 sources
+- ❓ inferred — single source, T4 only, or your own inference
+
+A claim's confidence can never exceed its corroboration.
+
+### Verify before stating (high-risk / max_accuracy)
+
+For security, auth, payment, legal, medical, finance, production, or any
+`max_accuracy` packet: decompose each external claim into atomic checkable
+facts (a number, a version, an API signature, a citation) and verify each
+against a source before the packet states it. An unverifiable atom is labeled
+❓ or removed — never stated as fact. This applies the cite-or-block rule in
+`references/research-trigger-policy.md` claim-by-claim.
 
 ## Next action
 [Concrete first step — could be "run /build-loop" or "investigate X further"]
@@ -70,10 +97,10 @@ Produces a repo-grounded research packet without committing to implementation. U
 
 ## Integration
 
-- Standalone: `/build-loop:research [topic]`
+- Standalone: `/build-loop:research-run [topic]`
 - From build-loop: orchestrator routes RESEARCH-intent requests here instead of the full loop
 - During normal build-loop runs: `scripts/research_trigger.py` decides whether this skill should run, which depth to use, where to persist the packet, and whether current/external claims are blocked until cited. See `references/research-trigger-policy.md`.
-- After packet: user decides — `/build-loop:run` to implement, `/build-loop:optimize` to optimize, or shelve
+- After packet: user decides — `/build-loop:run` to implement, `/build-loop:optimize-run` to optimize, or shelve
 
 ## State
 

package/skills/runtime-parity-verification/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: runtime-parity-verification
+description: Use in Phase 4/5 (Validate/Iterate) for ANY change to a user-visible flow — web, macOS, iOS, agent, or CLI/TUI — before claiming "done". Verifies the RUNNING app's core flow by cross-checking the rendered/queryable UI against the backing source-of-truth (DB/API/daemon/tool-state), screen-independently. Triggers — "verify it works", "confirm the fix", "does X actually work", "nothing happens when I…", "not showing", "shows empty/wrong data", uiTarget != null, or any "action does nothing / data not displaying / stale projection" symptom. Compile-green and a passing unit test do NOT satisfy this; neither does a screenshot alone.
+user-invocable: false
+---
+
+# Runtime Parity Verification
+
+**The recurring failure this prevents:** an agent ships UI/feature work, reports "compiles green / tests pass / committed," and never confirms the **running** app's core flow actually works — or confirms it only by **screenshot**, which is screen-dependent and gets silently deferred (e.g. the user's display locks). The whole "X doesn't work / isn't showing / shows mock/empty despite real data / stale projection" bug class is a **divergence between what the UI renders and the authoritative backend state.** One cheap, headless check catches the entire family.
+
+## The invariant to assert
+
+> For the user's core flow, the **rendered/queryable UI state must equal the authoritative backend state.**
+> - If the backend holds N items and the UI shows 0 / "empty" → **FAIL** (projection diverged).
+> - If an action is supposed to create/change state, assert **both** the backend delta **and** the UI reflecting it.
+
+This is stronger than "did it render" (which UI validators check). It is also stronger than "build + tests pass" (which never exercises the running flow). It must be **screen-independent** so it cannot be skipped when no display is available.
+
+## Platform recipes — source-of-truth (left) ⇄ UI probe (right)
+
+| Platform | Authoritative source-of-truth | Screen-independent UI probe |
+|---|---|---|
+| **Web** | API response JSON / DB row count | Host browser or `ui-validator` / IBR scan; assert via `data-testid` selectors |
+| **macOS** (AppKit/SwiftUI) | backend store / daemon via CLI or socket query | **`native-ax-driver`** Accessibility tree (cursor-free). Reference impl: easy-terminal `tools/smoke_launch.py` |
+| **iOS / watchOS** | backend / store | simulator AX via `idb ui describe-all` or XCUITest queries |
+| **Agent / LLM app** | tool-result or persisted state | the agent's returned/rendered output — assert the claim matches the actual tool/state, not just that text was produced |
+| **CLI / TUI** | process / file / db state | captured stdout / TUI buffer |
+
+## Procedure
+
+1. **Identify the core flow** changed (the thing a user does: launch a thing, submit a form, see a list, run an action).
+2. **Capture source-of-truth** before and (if the flow mutates) after the action — a query that does NOT go through the UI layer.
+3. **Probe the UI headlessly** with the platform driver and extract the rendered state (counts, presence/absence of an empty state, the new item).
+4. **Assert parity**: rendered == source-of-truth. On a mutating flow, assert the backend delta AND the UI reflecting it.
+5. **Encode it as a per-repo smoke** (a script that returns non-zero on divergence). **Validate the smoke is real**: confirm it returns non-zero on a known-broken state, not just zero on green — a check that cannot fail is worthless.
+6. **Gate on it**: run the smoke before any "done" claim. Never substitute compile-green, a passing unit test, or a screenshot.
+
+## Anti-patterns (each one shipped a real bug)
+
+- "Build is green, committed — done." → compile ≠ runtime; never exercised the flow.
+- "Here's a screenshot, looks right." → screen-dependent; deferred when the screen locks; can't diff against truth.
+- "The UI rendered something." → rendering ≠ correct data; an empty state renders fine while the backend has 100 rows.
+- Verifying only the backend (CLI/API works) without the UI, or only the UI without the backing truth — the bug lives in the **gap between them**.
+
+## Build-loop integration
+
+- **Phase 4 Review sub-step B / Phase 5 Iterate**: when `uiTarget != null` OR the diff touches a user-visible flow, a runtime parity check is **required**. The existing drivers do the probing — web: `ui-validator`; macOS: `native-ax-driver` / IBR `scan_macos`; iOS: `idb`. THIS skill adds the missing step: **cross-check the probe against source-of-truth**, and keep a validated per-repo smoke.
+- **Phase 4 sub-step G (`verification-before-completion`)**: for app/UI changes, "confirm output" includes the runtime parity smoke, not only test/build/lint.
+- The `verify` skill ("run the app and observe behavior") is the manual counterpart; this skill is the automatable, source-of-truth-anchored form.
+
+Origin lesson: build-loop-memory `lessons/2026-06-08-pattern-runtime-ui-source-of-truth-parity-verification.md` (easy-terminal launch/no-pane bug — UI projection diverged from daemon, missed across a whole UI pass because verification was compile-green + screenshot-only).

package/skills/spec-writing/SKILL.md

@@ -314,6 +314,24 @@ If no UI surface is in scope, write "N/A: no UI surface."
 
 ---
 
+### Item 18 — Dispatch tier per work item (WP-B)
+
+**Prompt:** Assign `dispatch_tier:` per work item — one of `script | haiku | sonnet | opus | frontier` — plus a one-line justification. The tier names which executor the orchestrator dispatches; the justification states why that tier fits the work's nature. `frontier` requests the Frontier tier (resolves to Fable via `scripts/model_overrides.py`) for a work item whose generative reasoning compounds — plan synthesis / re-planning / a decomposition call where a wrong answer ripples downstream. It routes to the Advisor dispatch ladder (`references/advisor-dispatch-ladder.md`); use it sparingly, only on genuinely high-stakes generative work.
+
+**Eligibility test for `script` (ALL must hold):** machine-checkable output; fully enumerable inputs; the tool exists OR is ≤~50 LOC plus a colocated test. If any fails, the task needs a model tier (judgment), not a script. Escalate on evidence (2 failures or surfaced ambiguity) with the failure evidence attached; never patch a script mid-run to absorb ambiguity.
+
+**Effect:** `plan_verify.py` runs two ADVISORY checks (never block, user-confirmed 2026-06-09): `tier-sanity-judgment-on-script` (a judgment-flavored task pinned to `script` — rigidity) and `tier-sanity-mechanical-on-opus` (a rote task pinned to `opus` — waste). Both are WARN flags in the report, surfaced for the author to reconsider.
+
+**How to check:**
+
+```bash
+grep -n "dispatch_tier:" docs/plans/<feature-slug>.md
+```
+
+Each value must be exactly one of `script | haiku | sonnet | opus | frontier`. Omit the field for an item whose tier is obvious from context; the checks fire only on a declared tier that fights its task description. (`frontier` never trips a sanity WARN — it is the top judgment tier, never a "waste" smell.)
+
+---
+
 ## Frontmatter fields used by routing
 
 These fields appear in plan or chunk frontmatter and affect orchestrator routing decisions. They are validated by `scripts/plan_verify.py`.
@@ -322,6 +340,7 @@ These fields appear in plan or chunk frontmatter and affect orchestrator routing
 |-------|------|--------|
 | `risk_reason:` | one of 5 canonical strings | Routes chunk to `tier: thinking` regardless of `synthesis_dimensions` count (see Item 16). |
 | `modifies_api: true\|false` | boolean | When `true`, the orchestrator runs a mandatory scope-auditor gate before Phase 3 dispatch. Any public function, component, type, route, or CLI-flag signature change qualifies. When set without a companion `scope_auditor_status:` field in the plan body, `plan_verify.py` emits a WARN (`scope-audit-required`) to surface the missing audit trail. |
+| `dispatch_tier:` | one of `script\|haiku\|sonnet\|opus\|frontier` | Names the executor tier for the work item (Item 18). `frontier` resolves to Fable (`scripts/model_overrides.py`) and routes the item to the Advisor dispatch ladder for high-stakes generative work. `plan_verify.py` emits an advisory WARN when the tier fights the task: judgment on `script` (`tier-sanity-judgment-on-script`) or a mechanical task on `opus` (`tier-sanity-mechanical-on-opus`). `frontier` never trips a WARN. Never blocks. |
 
 ---
 

package/templates/memory/README.md

@@ -0,0 +1,65 @@
+# build-loop-memory — public seed (scaffolding only)
+
+This folder is the **self-contained seed** for a build-loop-memory store. It is the
+single place that holds everything build-loop ships for memory setup: the generic
+templates, the privacy allowlist (`manifest.json`), and this layout spec.
+
+**What ships vs. what does not.** The memory *store* itself is **private and never
+ships** — it holds personal lessons, project decisions, raw artifacts, and operator
+paths. Only this **scaffolding** ships in the public plugin: generic `*.template`
+files + an allowlisted manifest. `scripts/install_memory.py` *materializes* the store
+from this seed at a **separate root** (`$BUILD_LOOP_MEMORY_ROOT` → legacy
+`~/dev/git-folder/build-loop-memory` → fresh `~/.build-loop-memory`), seeding only
+missing files (idempotent, never overwrites).
+
+## Files in this seed (all of them)
+
+| File | Role |
+|------|------|
+| `manifest.json` | Privacy allowlist + the complete structure spec. `install_memory.py --validate-seed` rejects any seed file not allowlisted here, and scans for secret/PII deny-patterns. |
+| `constitution.md.template` | First-run rule scaffold → `constitution.md` in the store. |
+| `MEMORY.md.template` | Global memory-index scaffold → `MEMORY.md` in the store. |
+| `charter.md.template` | Project-charter scaffold (North Star + commander's-intent + invariants) → `charter.md`. Placeholder bodies; filled per project at run time. |
+| `README.md` | This document. |
+
+Empty directories are **not** shipped (git can't track them, and the manifest is
+strict-allowlist); they are **generated** by `install_memory.py` at setup. The full
+target layout is below and is declared machine-readably in `manifest.json` →
+`generated`.
+
+## Store layout that install_memory.py generates
+
+```
+<memory-root>/                     # private, separate root — NEVER the plugin cache
+├── constitution.md                # from constitution.md.template
+├── MEMORY.md                      # from MEMORY.md.template
+├── charter.md                     # from charter.md.template (optional)
+├── indexes/                       # rebuildable local indexes
+└── projects/
+    ├── README.md                  # generated project-lane guide
+    └── <slug>/                    # one per project (--ensure-project <slug>)
+        ├── raw/                   # raw-source lanes:
+        │   ├── documents/  data/  db/  runtime/
+        │   └── agent-artifacts/  artifacts/  files/
+        ├── apps/        assets/      architecture/  context/
+        ├── decisions/   docs/        features/      formats/
+        ├── indexes/     lessons/     plugins/       product/
+        ├── prompts/     research/    semantic/      skills/
+        └── sources/     testing/     tradeoffs/
+```
+
+`raw/` lanes (7): documents, data, db, runtime, agent-artifacts, artifacts, files.
+Per-project topic dirs (20): apps, assets, architecture, context, decisions, docs,
+features, formats, indexes, lessons, plugins, product, prompts, raw, research,
+semantic, skills, sources, testing, tradeoffs.
+
+## Setup
+
+```bash
+python3 scripts/install_memory.py                      # bootstrap store + seed missing files
+python3 scripts/install_memory.py --ensure-project foo # add projects/foo/ scaffold
+python3 scripts/install_memory.py --check              # status, no writes
+python3 scripts/install_memory.py --validate-seed      # validate THIS seed (allowlist + deny-scan)
+```
+
+The store is the durable, private half; this seed is the public, structure-only half.

package/templates/memory/charter.md.template

@@ -0,0 +1,46 @@
+# Project Charter — {{PROJECT}}
+
+The durable North Star + posture + invariants + key architecture decisions that
+outlive any single run. Canonical here in memory; mirrored to `.build-loop/charter.md`
+each run. Facts ACCRETE: each carries provenance (`inferred` until user-confirmed
+or stable across N runs) and, where it locks a decision, the falsifier that would
+unseat it (decision-quality rule 8).
+
+This is a template — replace the bodies with the project's actual content. Depth
+scales by `stakes`: a low-stakes skill/agent/toy needs none of this; a thin charter
+(North Star + posture) suits medium-stakes web/mobile; a high-stakes system fills
+every section and graduates risk-naming non-goals to enforced invariants.
+
+## North Star
+
+- **Purpose**: <what this product is for and who it serves>
+- **Primary users**: <roles affected>
+- **Core jobs**: <the tasks users rely on most>
+
+## Posture (commander's intent)
+
+- **audience**: <who> — provenance: inferred
+- **stakes**: <low|medium|high> — provenance: inferred
+- **priority_order**: <ordered subset of security/reliability/speed/cost/simplicity/polish>
+  - notes: <free-text expressiveness the fixed vocab can't carry>
+- **acceptable_tradeoffs**: <what is OK to cut under pressure>
+- **non_goals**: <what is never cut>
+  - <at stakes:high, a non_goal that names a REAL risk is an ENFORCED invariant>
+
+## Invariants
+
+Stable rules cited by advisory judges via stable IDs (mirror the constitution
+shape). At `stakes: high`, risk-naming entries are deterministically enforced.
+
+- **INV-<DOMAIN>/<name>**: <rule body> — provenance: <inferred|user-confirmed>
+  - falsifier: <the observation that would unseat this>
+
+## Key architecture decisions
+
+- **<decision>**: <what was decided and why> — provenance: <inferred|user-confirmed>
+  - falsifier: <what would prove it wrong; the revisit trigger>
+
+<!-- Provenance legend: `inferred` (LLM-derived, not yet confirmed) graduates to
+     `user-confirmed` on explicit user statement OR to `stable` after N
+     unchallenged runs. The run is the single writer (from canonical); a user
+     hand-edit of the repo mirror promotes to canonical authored_by:user. -->

package/templates/memory/manifest.json

@@ -1,8 +1,8 @@
 {
   "schema_version": "1.0.0",
   "kind": "build-loop-memory-public-seed",
-  "seed_version": "2026-06-07",
-  "description": "Privacy-safe scaffolding for a fresh build-loop-memory store. This manifest allowlists only generic templates and generated directories; it must not include personal lessons, project decisions, raw files, indexes, or operator-specific content.",
+  "seed_version": "2026-06-12",
+  "description": "Self-contained, privacy-safe seed for a fresh build-loop-memory store. Ships the generic templates + this manifest + README; install_memory.py materializes the store at a separate private root. This manifest allowlists only generic templates/docs and declares (in 'generated') the complete directory structure install_memory.py creates. It must not include personal lessons, project decisions, raw files, indexes, or operator-specific content.",
   "sources": [
     {
       "source": "constitution.md.template",
@@ -15,6 +15,18 @@
       "target": "MEMORY.md",
       "required": true,
       "purpose": "Generic global-memory index scaffold for first-run installs."
+    },
+    {
+      "source": "charter.md.template",
+      "target": "charter.md",
+      "required": false,
+      "purpose": "Generic project-charter scaffold (North Star + commander's-intent posture + invariants). Placeholder bodies only; filled per project by the run (WP-F)."
+    },
+    {
+      "source": "README.md",
+      "target": "README.md",
+      "required": false,
+      "purpose": "Human-readable seed + complete layout documentation (allowlisted so --validate-seed passes)."
     }
   ],
   "generated": [
@@ -26,14 +38,22 @@
       "target": "projects/README.md",
       "purpose": "Generic project-scoped memory lane guide generated by install_memory.py."
     },
+    {
+      "target": "projects/<slug>/",
+      "purpose": "Per-project memory lane, created by --ensure-project <slug>."
+    },
     {
       "target": "projects/<slug>/raw/{documents,data,db,runtime,agent-artifacts,artifacts,files}/.gitkeep",
-      "purpose": "Empty raw-source lane placeholders created only when --ensure-project is passed."
+      "purpose": "Empty raw-source lane placeholders (7 lanes) created when --ensure-project is passed."
+    },
+    {
+      "target": "projects/<slug>/{apps,assets,architecture,context,decisions,docs,features,formats,indexes,lessons,plugins,product,prompts,raw,research,semantic,skills,sources,testing,tradeoffs}/",
+      "purpose": "Per-project topic lanes (20) — canonical structure spec, mirrors install_memory.py PROJECT_TOPIC_DIRS."
     }
   ],
   "privacy": {
     "classification": "scaffolding-only",
-    "rule": "The public build-loop package ships templates and empty scaffolds only. Personal memory files, private repository contents, project-specific decisions, raw artifacts, generated indexes, and local operator paths are excluded.",
+    "rule": "The public build-loop package ships templates, this manifest, and the README only. Personal memory files, private repository contents, project-specific decisions, raw artifacts, generated indexes, and local operator paths are excluded. Empty directories are generated at install time, never shipped.",
     "deny_patterns": [
       "(?i)BEGIN (OPENSSH|RSA|DSA|EC) PRIVATE KEY",
       "(?i)\\b(api[_-]?key|secret|password|token)\\s*[:=]\\s*['\\\"][^'\\\"]{8,}",

package/codex-skills/debug-loop/SKILL.md

@@ -1,18 +0,0 @@
----
-name: debug-loop
-description: "Main Build Loop debugging entrypoint. Use for root-cause analysis, failing fixes, crashes, exceptions, broken behavior, and validation failures that need an iterative diagnose-fix-verify loop."
----
-
-<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
-
-# Debug Loop
-
-This is the public Codex entrypoint for Build Loop debugging. The canonical
-implementation remains internal:
-
-```text
-../skills/debug-loop/SKILL.md
-```
-
-Start with diagnosis, use evidence to identify root cause, apply the smallest
-targeted fix, and verify with the repo's native tests or runtime checks.

package/codex-skills/handoff/SKILL.md

@@ -1,22 +0,0 @@
----
-name: handoff
-description: "Main Build Loop handoff entrypoint. Use to compose a durable, fixed-template handoff from the current build-loop run state — intent, goal, live checklist, git state, queues, and gotchas — so a fresh session can resume without losing context. Optionally launches a fresh session in the stable checkout."
----
-
-<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
-
-# Handoff
-
-This is the public Codex entrypoint for Build Loop run handoffs. The canonical
-implementation remains internal:
-
-```text
-../skills/handoff/SKILL.md
-```
-
-Compose the handoff from real `.build-loop/` state (intent, goal, `state.json`
-checklist, git status/log, the followup/backlog/ux-queue/issues queues, and
-recorded gotchas) into the fixed template. Carry the live checklist across the
-boundary verbatim so the next session resumes without re-deriving state. The
-optional launch step targets the stable checkout, never a worktree that may be
-garbage-collected.

package/codex-skills/knowledge/SKILL.md

@@ -1,21 +0,0 @@
----
-name: knowledge
-description: "Main Build Loop knowledge entrypoint. Use when recording decisions, ADRs, lessons, procedural memory, or repo-local knowledge that should be durable across future runs — AND when reviewing existing memory: surfacing the review queue, detecting decision rot, finding stale procedures, or resolving open conflicts."
----
-
-<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
-
-# Knowledge
-
-This is the public Codex entrypoint for Build Loop knowledge capture. The
-canonical implementation remains internal:
-
-```text
-../skills/knowledge/SKILL.md          # capture: decisions, ADRs, lessons, procedures
-../skills/knowledge-review/SKILL.md   # review: review queue, decision rot, stale procedures, open conflicts
-```
-
-Keep captures factual, scoped to the current repo or decision, and validated
-against the files or commands that prove the lesson. Use the review path when
-asked to surface what's gone stale or conflicting in existing memory rather than
-to record something new.

package/codex-skills/optimize/SKILL.md

@@ -1,18 +0,0 @@
----
-name: optimize
-description: "Main Build Loop optimization entrypoint. Use when the user wants to make something faster, cheaper, smaller, simpler, or better against a measurable metric."
----
-
-<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
-
-# Optimize
-
-This is the public Codex entrypoint for Build Loop optimization. The canonical
-implementation remains internal:
-
-```text
-../skills/optimize/SKILL.md
-```
-
-Define the metric first, identify factors, measure each run, keep only changes
-that improve the metric, and revert changes that do not.

package/codex-skills/research/SKILL.md

@@ -1,18 +0,0 @@
----
-name: research
-description: "Main Build Loop research entrypoint. Use for pre-build research, option evaluation, API/framework investigation, and repo-grounded decision packets before implementation."
----
-
-<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
-
-# Research
-
-This is the public Codex entrypoint for Build Loop research. The canonical
-implementation remains internal:
-
-```text
-../skills/research/SKILL.md
-```
-
-Ground claims in the repo first, then use current external docs only when the
-decision depends on unstable or third-party behavior.