orchestrix-skills 0.3.0 → 0.5.0

package/README.md

@@ -15,11 +15,15 @@ hosting, and team features are the premium layer — see below.
 intent
   └─ orchestrate (root: warm context, wires skills by output→input, enforces gates)
        ├─ brainstorm ──(needs facts?)─→ research
+       ├─ (existing repo?) ──→ map-codebase (brownfield entry: evidence-based map → registry)
        ├─ (has UI?) ──→ design-system (once) → design-ui
        ├─ (arch decision?) ──→ design-architecture
-       └─ draft-story → implement → run-tests → review-code → commit
-                                      ↑ verify         ↑ design-review (UI only)
-                                      (objective)      ↑ accept (batched)
+       ├─ draft-story → implement → run-tests → review-code → commit
+       │                              ↑ verify         ↑ design-review (UI only)
+       │                              (objective)      ↑ accept (batched)
+       ├─ (verify failing, cause unknown?) ──→ investigate (root cause → rework)
+       ├─ (runnable app?) ──→ smoke-test (drive real flows, evidence captured)
+       └─ (accepted + ship it?) ──→ deploy (inline gate, rollback-first)
 ```
 
 Human gates are front-loaded (planning = direction) and at the end (acceptance);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "orchestrix-skills",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Capability-first AI development skill graph — Anthropic-native skills that run in any agent runtime.",
   "type": "module",
   "bin": {

package/project-scaffold/core-config.yaml

@@ -12,7 +12,11 @@ work: # work products — skills WRITE these (outputs:), humans review at gates
   stories: docs/stories # <slug>.md (flat, origin tag)
   research: docs/research # research briefs
 
-runtime: .orchestrix/runtime # ledger + step handoff files (ephemeral, gitignored)
+# FIXED platform protocol — the orchestrate skill writes, and the platform polls,
+# `.orchestrate/ledger.jsonl` + `.orchestrate/verify/` at this literal path. It is
+# NOT a remappable namespace: changing it breaks live progress rendering. Listed
+# here for transparency only.
+runtime: .orchestrate # ledger + verify logs (ephemeral, gitignored)
 
 # Org-level cascade (shared taste/standards across many products) is intentionally
 # NOT enabled yet (YAGNI). When needed: add an `extends:` base that project paths

package/project-scaffold/knowledge/taste/coding-standards.md

@@ -1,16 +1,19 @@
 # taste/coding-standards
 
 Rules `implement` and `review-code` read as their taste slice. Terse rules, each
-with provenance. Not prose. Seed examples below — replace with this project's.
+with provenance. Not prose. Seed is empty — this is honest: no project
+preferences exist yet. Rows enter via human seeding (orchestrate's first-run
+preflight offers this) or the metabolism loop — never as unapproved defaults.
 
-| id            | rule                                                                | rationale                                  | source | added      | approved_by |
-| ------------- | ------------------------------------------------------------------- | ------------------------------------------ | ------ | ---------- | ----------- |
-| ts-strict     | TypeScript strict mode on; no `any` without an inline justification | Catches runtime errors at compile time     | human  | 2026-06-27 | dorayo      |
-| named-exports | Named exports only; no default exports                              | Refactor-safe imports, better autocomplete | human  | 2026-06-27 | dorayo      |
-| no-swallow    | Never swallow errors; handle or rethrow with context                | Silent failures are undebuggable           | human  | 2026-06-27 | dorayo      |
-| pure-io-split | Keep I/O at the edges; core logic pure and testable                 | Testability, fewer mocks                   | human  | 2026-06-27 | dorayo      |
+| id  | rule | rationale | source | added | approved_by |
+| --- | ---- | --------- | ------ | ----- | ----------- |
 
 <!--
+Row shape (copy per rule — every row needs real provenance):
+
+| ts-strict     | TypeScript strict mode on; no `any` without inline justification | Catches runtime errors at compile time     | human | <date> | <who> |
+| named-exports | Named exports only; no default exports                            | Refactor-safe imports, better autocomplete | human | <date> | <who> |
+
 Metabolism: when a human corrects taste at the accept gate, append or supersede a
 row here (source: <skill or human>, with date + approver). Supersede, don't
 delete — keep what the org learned visible.

package/skills/brainstorm/SKILL.md

@@ -29,8 +29,9 @@ but always presented and approved.
 
 ## Process
 
-1. **Explore context.** Read the relevant `knowledge/*` slices and existing
-   code before asking anything.
+1. **Explore context.** Read the relevant knowledge slices (`taste/*`,
+   `architecture/*`, `registry/*` — physical paths from `core-config.yaml`,
+   default under `knowledge/`) and existing code before asking anything.
 2. **Scope check first.** If the intent spans independent subsystems, say so and
    help decompose into sub-projects — each gets its own spec → stories → build.
    Don't refine details of something that should be split.

package/skills/deploy/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: deploy
+description: Use when an ACCEPTED deliverable must be shipped to a live environment. Never mid-run, never on unaccepted work.
+license: MIT
+allowed-tools: [Read, Bash]
+metadata:
+  contract:
+    inputs: [accepted_deliverable, target]
+    reads: [registry/deploy]
+    outputs: [deploy_report]
+    authority: "Run the project's DOCUMENTED deploy command for the named target, and its rollback. No infra provisioning, no DNS/billing/secret changes, no undocumented deploy paths."
+    verify: "A real request against the LIVE target succeeds post-deploy (the deploy tool's own 'success' does not count), and one core flow responds correctly."
+    accept:
+      when: "always — deploying is irreversible and user-facing."
+      timing: inline
+---
+
+# Deploy (Ship Accepted Work, With a Way Back)
+
+The most dangerous skill in the graph. Everything here is designed around two
+facts: deploys are user-facing, and the only safe deploy is one you can undo.
+
+**Core principle:** No rollback plan, no deploy. If you cannot state the exact
+command that undoes this deploy, you are not ready to run the one that does it.
+
+## Preconditions — ALL must hold, verify each now
+
+1. **The work is accepted.** Final acceptance happened; you are not deploying
+   to "see if it works" (that is `smoke-test`'s job, locally).
+2. **The tree is clean and tested.** `git status` clean; `run-tests` green on
+   the exact commit being shipped (fresh run, not remembered).
+3. **The deploy method is documented** in `registry/deploy` (or the project's
+   own deploy config/scripts). Not documented → STOP and ask the human how this
+   project ships. NEVER guess a deploy path — a guessed deploy against the
+   wrong target is the worst failure this graph can produce.
+4. **The target is unambiguous.** "Deploy" without a named target defaults to
+   asking, not to production.
+
+## Process
+
+1. **Write the rollback plan first.** Record: the currently-live version
+   identifier (commit/tag/deployment id) and the exact rollback command.
+   Put both in the report BEFORE deploying.
+2. **Inline human gate (this skill's accept).** Present: target, version to
+   ship, one-line change summary, rollback command. Deploy only on explicit
+   sign-off. This gate cannot be batched or deferred.
+3. **Deploy** with the documented command. Capture the full output to
+   `.orchestrate/verify/deploy-<target>.log`.
+4. **Post-verify against the LIVE target.** A real HTTP request (or the
+   platform equivalent) to the deployed URL: correct status AND expected
+   content, plus one core flow. The deploy tool saying "success" is step 3,
+   not step 4.
+5. **On post-verify failure: roll back immediately** with the recorded
+   command, re-verify the old version is live again, and report honestly.
+   A failed deploy cleanly rolled back is a good outcome; a broken prod
+   left up while you debug is not.
+
+## Output: `deploy_report`
+
+```markdown
+# Deploy — <target>
+
+Shipped: <version/commit> (previous live: <version>)
+Command: <documented command used>
+Post-verify: <request + result> — passed/failed
+Rollback: <command> — standing by | EXECUTED at <time>, old version re-verified live
+Log: .orchestrate/verify/deploy-<target>.log
+```
+
+## Red flags — stop
+
+- Deploying work that has not passed final acceptance
+- Guessing the deploy method because `registry/deploy` is empty
+- No recorded rollback command before deploying
+- Treating the deploy tool's success message as proof the site works
+- An ambiguous target resolved to production by default
+- Debugging a broken deploy IN production instead of rolling back first
+
+## Done
+
+Live target verified serving the new version (or cleanly rolled back), report
+written. Durable facts learned (the deploy command, the health URL) go back to
+`registry/deploy` via the metabolism rules.

package/skills/draft-story/SKILL.md

@@ -7,8 +7,8 @@ metadata:
   contract:
     inputs: [requirement, context]
     reads: [taste/coding-standards, registry/api, registry/db, front-end-spec?]
-    outputs: [docs/stories/<slug>.md]
-    authority: "Write one flat story file at docs/stories/<slug>.md. No folders. No source code. No production. No spend."
+    outputs: [stories/<slug>.md]
+    authority: "Write one flat story file in the stories namespace (physical path from core-config.yaml; default docs/stories/). No folders. No source code. No production. No spend."
     verify: "Every requirement maps to at least one acceptance criterion; constraints are copied verbatim; no placeholders (no TBD/TODO/'handle edge cases')."
     accept:
       when: "Always — this output sets the direction the whole build rests on."
@@ -25,7 +25,8 @@ implement it without guessing.
 
 ## Output
 
-Write ONE flat Markdown file: `docs/stories/<slug>.md` — `<slug>` is a kebab
+Write ONE flat Markdown file in the stories namespace (physical path from
+`core-config.yaml`, default `docs/stories/`): `<slug>.md` — `<slug>` is a kebab
 handle from the title. No folders, no `epic.story` numbering. Produce exactly
 these sections (with frontmatter) and nothing more.
 
@@ -76,9 +77,9 @@ What this story deliberately does NOT do.
 ## Rules
 
 - **One story, one coherent deliverable.** If it spans independent subsystems,
-  split into separate stories — each its own `docs/stories/<slug>.md`, all
-  sharing the same `origin` so the set is queryable as one group.
-- **Flat, no hierarchy.** One file per story under `docs/stories/`. Grouping is
+  split into separate stories — each its own `<slug>.md` in the stories
+  namespace, all sharing the same `origin` so the set is queryable as one group.
+- **Flat, no hierarchy.** One file per story in the stories dir. Grouping is
   the `origin` field (a query the AI runs), never a folder. Order comes from
   Interfaces (dependencies), never from a number.
 - **No placeholders.** "Add validation", "handle errors", "TBD" are failures.
@@ -101,6 +102,7 @@ What this story deliberately does NOT do.
 
 ## Done
 
-Write `docs/stories/<slug>.md`. Hand off its path for direction confirmation
+Write the story file in the stories namespace. Hand off its path for direction
+confirmation
 (this skill's `accept` is `inline`): the human approves the direction, or sends
 it back, before `implement` begins.

package/skills/investigate/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: investigate
+description: Use when something is broken and the CAUSE is unknown — a repeatedly failing verify, a bug report, a regression — before any fix is attempted.
+license: MIT
+allowed-tools: [Read, Bash, Grep, Glob]
+metadata:
+  contract:
+    inputs: [symptom, context?, prior_attempts?]
+    reads: [registry/architecture, taste/coding-standards]
+    outputs: [root_cause_report]
+    authority: "Read code and run diagnostics/reproductions. Temporary instrumentation is allowed but MUST be reverted before finishing. No fixes — the fix belongs to a re-dispatched implement."
+    verify: "The report contains a reproduction command that fails, and a mechanism that explains every observed symptom (not just the loudest one)."
+    accept:
+      when: "never — informational; it feeds the rework loop."
+      timing: deferred
+---
+
+# Investigate (Root Cause Before Any Fix)
+
+Debugging is not "try changes until it passes". It is locating the mechanism.
+
+**Core principle:** A fix you cannot explain mechanistically is not a fix — it
+is a coincidence that will regress.
+
+## The Iron Law
+
+```
+NO FIX WITHOUT A ROOT CAUSE STATED AS:
+"X happens BECAUSE Y — evidenced by Z (something I observed this session)"
+```
+
+## Process
+
+1. **Reproduce.** Find the exact command/steps that show the symptom, run them,
+   capture the output verbatim. Read the error LITERALLY — the message usually
+   says what is wrong, not what you assume is wrong. Cannot reproduce → that IS
+   the finding (report the conditions tried; do not "fix" what you cannot see).
+2. **Localize.** Shrink the search space with evidence, not intuition:
+   - `git log`/`git bisect` when it used to work — what changed?
+   - Binary-search the pipeline: add temporary instrumentation (prints/asserts)
+     at midpoints to find where good state becomes bad state.
+   - Minimize the reproduction — smallest input that still fails.
+3. **Hypothesize and FALSIFY.** For each hypothesis, design the observation
+   that would DISPROVE it, then run it. A hypothesis you only sought
+   confirmation for is not tested. Two failed rounds on the same theory →
+   the bug is in an assumption one level deeper (the config, the framework
+   contract, the data, the environment) — widen, don't re-try harder.
+4. **State the root cause** in the iron-law form, plus:
+   - the minimal fix scope (which file/function, what change class),
+   - the regression test that would have caught it,
+   - any OTHER symptoms this mechanism predicts (check them — a mechanism
+     that doesn't explain all symptoms is incomplete).
+5. **Revert your instrumentation.** `git diff` must be clean when you finish.
+
+## Output: `root_cause_report`
+
+```markdown
+# Root cause — <symptom, one line>
+
+## Reproduction — exact command; fails with <output tail>.
+## Mechanism — X happens because Y. Evidence: Z (file:line / captured output).
+## Fix scope — <file(s)>, <change class>. Explicitly NOT needed: <what a shotgun fix would have touched>.
+## Regression test — <the test to add so this cannot silently return>.
+## Ruled out — <hypotheses falsified and how> (saves the next person re-walking them).
+```
+
+## Red flags — stop and re-localize
+
+- "Probably" / "might be" in the mechanism line
+- A symptom fix: retry loops, sleeps, broad try/catch, widened types — with no
+  mechanism behind it
+- Changing several things at once and observing "it passes now"
+- A mechanism that explains one symptom but not the others
+- Finishing with instrumentation still in the diff
+
+## Done
+
+Report written; reproduction demonstrably fails; diff clean. The orchestrator
+re-dispatches `implement` with this report as `qa_feedback` — same capability,
+now with a target instead of a guess.

package/skills/map-codebase/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: map-codebase
+description: Use when entering an EXISTING codebase (brownfield) before designing or changing anything — build an evidence-based map of its architecture, conventions, and hazards.
+license: MIT
+allowed-tools: [Read, Bash, Grep, Glob]
+metadata:
+  contract:
+    inputs: [repo_path, focus?]
+    reads: []
+    outputs: [codebase_map, registry_updates]
+    authority: "Read-only on source; non-mutating commands only (ls, grep, git log, test discovery). Writes go ONLY to the registry/* namespace (physical path from core-config.yaml; default knowledge/registry/)."
+    verify: "Every architectural claim in the map cites a file path you actually read; the traced flows exist in code, not in the README."
+    accept:
+      when: "never — informational; it feeds design and implement."
+      timing: deferred
+---
+
+# Map Codebase (Brownfield Entry)
+
+Greenfield runs start from intent; brownfield runs start from SOMEONE ELSE'S
+decisions. Changing code you haven't mapped produces changes that fight the
+codebase — wrong layer, wrong convention, duplicated machinery.
+
+**Core principle:** The map comes from reading code, not from directory names
+or the README. A README describes what the project wishes it were; `git log`
+and the source describe what it is.
+
+## Process
+
+1. **Inventory.** Layout, manifests (`package.json`/`pyproject`/`go.mod`…),
+   scripts, CI config, generated/vendored dirs (mark them DO-NOT-EDIT).
+2. **Trace one or two REAL flows end to end** (guided by `focus` if given):
+   entry point → routing/dispatch → business logic → persistence/IO. Read the
+   actual files; record the chain as `file:symbol → file:symbol`. This step is
+   what separates a map from a guess.
+3. **Extract conventions from evidence** — for each, cite the example file you
+   derived it from: naming, module boundaries, error handling style, test
+   location and framework, how config/env is read, commit message style.
+4. **Hazards.** Migrations and how they run; generated code and what generates
+   it; global state; areas with no test coverage; anything `git log` shows as
+   churn-heavy (bug-prone) or untouched-for-years (fragile assumptions).
+5. **Write back to the `registry/*` namespace** (physical path from
+   `core-config.yaml`; default `knowledge/registry/`) following the metabolism
+   governance in `orchestrate` (read-before-write, update-don't-append, facts
+   only):
+   - `registry/architecture.md` — the traced structure
+   - `registry/conventions.md` — the evidenced conventions
+   Registry holds FACTS about this codebase. Opinions and preferences belong
+   in `taste/*`, and only via a human correction — not from this skill.
+
+## Output: `codebase_map`
+
+```markdown
+# Codebase map — <repo> @ <commit>
+
+## Shape — <stack, top-level layout, one paragraph>
+## Traced flows
+- <flow>: entry `a.ts:handler` → `b.ts:service` → `c.ts:repo` → <storage>
+## Conventions (evidence-cited)
+- <convention> — see <file>
+## Hazards
+- <hazard> — <why it bites> — <file/dir>
+## Where a change like "<focus>" belongs — <layer/files>, following <convention>
+```
+
+## Red flags — stop
+
+- Architecture described from folder names without opening the files
+- Repeating a README/document claim without spot-checking it in code
+- A "convention" cited from zero examples
+- Writing preferences/judgments into `registry/` (facts only)
+- Editing anything outside the `registry/*` namespace
+
+## Done
+
+Map written with citations; registry updated. Downstream `design-architecture`
+and `implement` read the registry and MUST follow the documented conventions —
+that is the point of having mapped them.

package/skills/orchestrate/SKILL.md

@@ -4,10 +4,10 @@ description: Use when a goal must be delivered end-to-end by composing skills, w
 license: MIT
 allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Task]
 metadata:
-  version: 3
+  version: 5
   contract:
     inputs: [intent, constraints?]
-    reads: [skill-registry, taste/*]
+    reads: [core-config, skill-registry, taste/*]
     outputs: [accepted_deliverable, run_ledger]
     authority: "Dispatch leaf skills, each within its own authority. Do not directly touch source, production, or spend — leaf skills do that, gated. Enforce every accept gate."
     verify: "Every dispatched skill's verify passed; final review is clean; all inline accepts were obtained."
@@ -32,14 +32,17 @@ no step above intent.
 ## The loop
 
 1. **Bind intent.** Read the human's goal and constraints. This is the only
-   place intent enters.
+   place intent enters. Then run the first-run preflight (below) before any
+   wiring.
 2. **Select.** Read the skill registry. Pick skills by their `description`
    (when-to-use). Load a skill's full `contract` only when it is a candidate —
    never load every contract at once.
 3. **Wire (emergent, not hardcoded).** Build the path by matching one skill's
    `outputs` to the next skill's `inputs`. Skills do not know each other; only
    you do. Do not assume a fixed pipeline — wire what this intent needs.
-4. **Dispatch.** Hand the skill exactly the `inputs` it declares, as files. Run
+4. **Dispatch.** Hand the skill exactly the `inputs` it declares, as files —
+   resolving each logical namespace it reads/writes to a physical path via
+   `core-config.yaml` (see Namespace resolution). Run
    it as a fresh subagent for isolation. Choose the cheapest model that can do
    the step. **Dispatch independent steps in PARALLEL** (whose `inputs` don't
    depend on each other) — as concurrent FOREGROUND subagents awaited together in
@@ -66,6 +69,49 @@ no step above intent.
 8. **Final acceptance.** Present the batched deferred accepts and a final review
    to the human, once. Apply corrections (see Metabolism), then deliver.
 
+## Namespace resolution (`core-config.yaml`)
+
+Skill contracts address knowledge and work products by **logical namespace**
+(`taste/*`, `architecture/*`, `registry/*`, `specs/*`, `stories/*`,
+`research/*`), never by physical path. At run start, read `core-config.yaml`
+once and build the logical→physical map. When you dispatch a skill, resolve
+every namespace in its `reads:` / `outputs:` / `updates:` to a real path via
+that map, and hand the resolved files as its inputs. If `core-config.yaml` is
+absent, fall back to the scaffold defaults (`knowledge/taste`,
+`knowledge/architecture`, `knowledge/registry`, `docs/specs`, `docs/stories`,
+`docs/research`).
+
+This is what makes brownfield work: a project keeps its brain wherever it
+already lives, the mapping changes, the skills do not.
+
+**Exception — the ledger/verify path is a FIXED platform protocol, not a
+namespace.** Always write to `.orchestrate/ledger.jsonl` and
+`.orchestrate/verify/…` literally. The platform polls that exact path to render
+live progress; it is NOT resolved through `core-config.yaml` and must not be
+remapped.
+
+## First-run preflight (brownfield guard)
+
+Emergent wiring alone can silently skip brownfield entry. So after binding
+intent, run two DETERMINISTIC checks (cheap: one `ls`/`test -d` each on the
+resolved paths):
+
+1. **Empty registry + existing code → map-codebase is MANDATORY.** If the
+   resolved `registry/*` namespace is empty or missing AND the repo already
+   contains source code, wire `map-codebase` before any design or build skill.
+   This is a hard rule, not a description-match: building on an unmapped
+   codebase produces changes that fight it.
+2. **Empty taste → surface it once.** If the resolved `taste/*` namespace is
+   empty — no project-specific entries; file headers, shape comments, and
+   unedited scaffold examples do NOT count — tell the human at the front gate: the brain has no preferences yet;
+   offer to draft `taste/coding-standards` from existing material (CLAUDE.md,
+   lint configs, review conventions) for their approval. Never seed taste
+   without human sign-off (opinions enter the brain only through a human —
+   same rule as Metabolism). If they decline, proceed with defaults and do not
+   ask again this run.
+
+Both checks are per-run and idempotent: a populated brain makes them no-ops.
+
 ## Accept gate
 
 | Skill's `accept.timing` | Skill's `authority`                                               | Action                                                                                        |
@@ -83,6 +129,12 @@ A failed `verify` or a `changes_requested` review is not a separate "fix" step.
 Re-dispatch the same skill with the feedback as an input (e.g. `qa_feedback`).
 Same capability, new input.
 
+**Rework without understanding is a coin flip.** If a verify failure's CAUSE
+is not understood after the first failed attempt, dispatch `investigate` before
+spending the next attempt — its `root_cause_report` becomes the re-dispatch's
+`qa_feedback`. An attempt aimed at a stated mechanism converges; an attempt
+aimed at a symptom re-rolls the dice.
+
 **Hard cap: 3 attempts per step.** If a step's verify still fails on attempt 3,
 STOP the run — do not burn a 4th attempt. Write a `gate` event to the ledger
 (`{"e":"gate","kind":"rework_exhausted","question":"step <n> (<skill>) failed 3
@@ -90,11 +142,34 @@ attempts: <one-line why>"}`), summarize the three failures for the human, and
 report AWAIT. A step that cannot pass its own verify after three tries needs a
 human decision (wrong approach, wrong spec, or wrong verify), not more tokens.
 
-## Metabolism
+## Metabolism — governed writeback
 
 When the human corrects something at final acceptance ("not on-brand", "wrong
-tone"), write the correction back into the relevant `taste/*` knowledge base, so
-the next run reads the improved taste. The run teaches the organization.
+tone"), fold it back into `taste/*` (preferences) or `registry/*` (facts about
+this codebase), so the next run starts smarter. The run teaches the
+organization — but memory rots without curation, so writeback is GOVERNED:
+
+1. **Read before write.** Open the target file first. An existing entry on the
+   same topic gets UPDATED in place — never append a near-duplicate.
+2. **Contradiction = replacement.** A correction that contradicts an existing
+   entry REPLACES it (add a short `supersedes: <old rule> (<date>)` note).
+   Never leave both standing — two contradictory rules poison every later run
+   that reads them.
+3. **Durable preferences only.** Taste holds style/architecture/process
+   preferences that apply to FUTURE runs. One-off task facts, transient state,
+   and anything the repo or ledger already records do not belong there.
+4. **One lesson per entry** — imperative phrasing, a one-line why, and a date.
+5. **Size bound: ~100 lines per file.** If a write would push past it,
+   consolidate in the same edit (merge near-duplicates, drop obsolete entries)
+   — never blind-append to a bloated file.
+6. **The human sees the diff.** taste/registry changes made during a run are
+   part of final acceptance: present what changed and why, so a bad lesson can
+   be vetoed before it contaminates future runs.
+
+`taste/*` vs `registry/*`: taste is HOW we prefer things done (opinions,
+overridable); registry is WHAT is true of this project (facts, verifiable).
+A correction usually lands in taste; a discovered fact (the deploy command,
+the test runner) lands in registry.
 
 ## The ledger (`.orchestrate/ledger.jsonl`)
 
@@ -138,4 +213,8 @@ a false claim.
 - Ending a run without a `run_end` ledger line
 - Marking a step done on the subagent's say-so, without your own verify command
 - A 4th rework attempt on the same step (cap is 3 — stop and gate)
+- A second rework attempt with no `investigate` when the failure isn't understood
+- Appending to `taste/*` without reading it first (duplicate/contradiction risk)
+- Dispatching a design/build skill in an existing codebase while `registry/*`
+  is empty (first-run preflight skipped)
 - Marking the run complete without every step's `verify` evidence

package/skills/smoke-test/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: smoke-test
+description: Use when the deliverable is a runnable app or service and its real user flows must be proven working from the OUTSIDE (browser/HTTP/CLI) before acceptance — unit tests passing is not that proof.
+license: MIT
+allowed-tools: [Read, Bash, Grep, Glob]
+metadata:
+  contract:
+    inputs: [run_instructions, flows, qa_feedback?]
+    reads: [registry/app]
+    outputs: [smoke_report, verify_evidence]
+    authority: "Start and stop the app locally; drive it via browser automation, HTTP, or CLI. Read-only on source. No deploy, no external spend, no mutations outside the app's own local state."
+    verify: "self — this skill PRODUCES the acceptance evidence; every flow verdict points at a captured artifact."
+    accept:
+      when: "never — the evidence feeds final acceptance; it does not replace it."
+      timing: deferred
+---
+
+# Smoke Test (Prove It Works From the Outside)
+
+Unit tests prove functions; a smoke test proves the PRODUCT. Launch the real
+app and walk the real flows the user will walk.
+
+**Core principle:** A flow is "passed" only when you drove it yourself and
+captured the evidence. "The tests are green so it probably works" is a claim,
+not a smoke test.
+
+## The Iron Law
+
+```
+UNTESTED IS NOT PASSED. Every flow ends in exactly one of:
+passed (with evidence) | failed (with evidence) | untested (with the reason)
+```
+
+## Process
+
+1. **Discover how to run it.** `registry/app` first; else the project's
+   manifest (`package.json` scripts, `Makefile`, `README`). If the launch
+   method is genuinely undocumented and unguessable, report `untested:
+   cannot launch` — do not invent a server.
+2. **Launch in the background, capture logs.** Redirect stdout/stderr to
+   `.orchestrate/verify/smoke-server.log`. Record the PID. Pick a free port if
+   configurable (avoid colliding with anything already running).
+3. **Wait for readiness, bounded.** Poll the health endpoint / port / ready
+   line for up to ~60s. Not ready → flow verdicts are `failed: app did not
+   start`, attach the server log, skip to cleanup.
+4. **Exercise EVERY listed flow** with the best driver available, in order of
+   fidelity:
+   - **Browser automation** (a Playwright/Chrome MCP tool, if available in
+     this session) — for UI flows: navigate, interact, assert on rendered
+     state, screenshot.
+   - **HTTP** (`curl`) — assert status code AND response content (a 200
+     serving an error page is a fail; check for a string the flow implies).
+   - **CLI** — invoke the command, assert exit code and output.
+   Use the highest-fidelity driver the flow needs: an interactive UI flow
+   "verified" by curling `/` is `untested`, not `passed`.
+5. **Capture evidence per flow** to `.orchestrate/verify/smoke-<flow-slug>.log`
+   (the exact command/steps + relevant output tail, or the screenshot path).
+6. **ALWAYS clean up** — kill the processes you started (and only those),
+   remove temp state you created. Cleanup runs even when flows fail.
+
+## Output: `smoke_report`
+
+```markdown
+# Smoke Report — <app> @ <commit>
+
+| Flow | Verdict | Evidence |
+|---|---|---|
+| signup happy path | passed | .orchestrate/verify/smoke-signup.log |
+| checkout | failed — 500 on POST /pay | .orchestrate/verify/smoke-checkout.log |
+| admin export | untested — needs OAuth I can't complete | (reason) |
+
+Server log: .orchestrate/verify/smoke-server.log
+Started/stopped: <pid(s)>, cleaned up: yes
+```
+
+## Red flags — stop
+
+- Reporting `passed` for a flow you did not drive
+- A UI flow "verified" with a single `curl /` status check
+- Conflating "the app is broken" with "my harness is broken" — say which
+- Leaving the server (or any process you spawned) running after the report
+- Only testing the happy path when `flows` lists error/edge flows
+
+## Done
+
+Every flow has a verdict + evidence artifact; processes cleaned up. `failed`
+and `untested` are honest, valid results — report them verbatim, never rounded
+up. The report feeds the orchestrator's verify gate and final acceptance.