@tyroneross/build-loop 0.36.0 → 0.43.0

package/skills/build-loop/references/status-output-format.md

@@ -0,0 +1,207 @@
+<!-- Canonical: how build-loop reports findings, status, and recommendations to a human.
+     Adopted 2026-08-18 after four rounds of correction in one session. The progression
+     is preserved in §7 on purpose — each failed attempt fixed a different level of the
+     Leverage Stack while the sentence stayed unusable, which is the lesson.
+     Companion to references/output-style.md (sentence level) and the style-calibrator
+     "Leverage Stack" profile (message logic). This file governs the SHAPE of a status
+     block; those govern the sentences inside it. Reference this file, do not restate it. -->
+
+# Status & findings output format
+
+## 1. Who this is for, and when it applies
+
+You are an agent emitting a **user-facing report**: findings, open items, status
+updates, recommendations. Your reader is deciding what to do next, not reading for
+comprehension.
+
+**Applies to:** Phase 4 reports, review findings, queue items, handoff documents,
+commit-worthy summaries, any list of open work, any recommendation.
+
+**Does NOT apply to:**
+- Structured internal envelopes (subagent JSON returns, run records, judge
+  decisions, MECE briefs). Those exist for machines and are unconstrained.
+- Conversational replies, single-answer questions, and status one-liners. A
+  question that wants a sentence gets a sentence.
+- Code, commit bodies, and test names, which have their own conventions.
+
+If you are unsure whether a response is a status report, ask: *does the reader have
+to decide or act because of this?* If yes, use this format.
+
+## 2. The governing test — write for a cold reader
+
+**If a new agent with zero context read only this line, would it know what to do?**
+
+Not "is it short." Not "is it plain." Is it *actionable by someone who was not in
+the room*. A sentence fails when the reader cannot tell whether to remember it,
+decide something, act, or ignore it.
+
+This is the rule. Everything in §4 is a consequence of it — a block that satisfies
+every rule in §4 and still fails this test is wrong, and the rules are what yield.
+
+## 3. Three things every sentence carries
+
+| element | what it means | good | bad |
+|---|---|---|---|
+| **Actor — who** | a named person or system | `We`, `you`, `the guard`, `an installed user` | `two lookups`, `the resolvers`, `it` |
+| **Object — what** | concrete enough to build or verify | `one code path per model tier` | `different models`, `some issues` |
+| **Modality — what kind of statement** | requirement / fact / done / decision owed | `We need X`, `Today we have Y`, `I've done Z`, `Should we A or B?` | anything the reader must infer |
+
+**If you cannot name the actor, you do not yet understand the finding.** Go back to
+the code before you write the line.
+
+## 4. The block
+
+```
+[Action-verb phrase naming the specific thing, real numbers/names/dates inline]
+[One sentence: what breaks, for whom, when.]
+ - [Every affected item, named individually, with its own detail]
+ - [The fix, stated as an action]
+ - [The ask: "I've started this and will update you when done"
+          OR "I need your approval to do this" + why]
+```
+
+One block per item. No preamble, no wrap-up paragraph.
+
+### 4.1 Heading is a phrase, not a sentence
+
+Action verb + the concrete noun doing or receiving the action, real values inline.
+No trailing em-dash explainer. The noun carrying the stake is the subject.
+
+- ✅ `2 Groq models shut down on 2026-08-16`
+- ✅ `Unpushed commits keep the fixes off your users' machines`
+- ✅ `Seven broken tests hide the next real break`
+- ❌ `A deliberate expiry alarm on your Groq model facts fired 4 days ago — it's a staleness timer, not a bug.` (sentence + explainer)
+- ❌ `Groq catalog issue` (no verb, no stake)
+- ❌ `The suite has failures` (container as subject, not the stake)
+
+### 4.2 Second line is the consequence, not a restatement
+
+What breaks, for whom, when. Falsifiable and specific.
+
+- ✅ `Work quietly goes to the wrong model instead of erroring.`
+- ✅ `The people installing your plugin are still hitting every problem we fixed.`
+- ❌ `This could cause problems down the line.`
+- ❌ `This is important to address.`
+
+**This line is a relevance filter, not decoration.** If you cannot write it, the
+item does not belong in the response. That is the test for cutting.
+
+### 4.3 Shape: target state first, then the gap
+
+State what should be true, then what is true today. Diagnosis-first framing —
+explaining how the defect works — reads as precision and transfers no decision.
+Mechanism belongs in the fix or the spec; it goes up top ONLY when it changes which
+option the reader picks.
+
+### 4.4 Plain words, not jargon
+
+The test is not "is this technical." It is: **could a competent engineer who has
+never seen this project understand it?**
+
+**KEEP** universal vocabulary — translating it adds nothing and reads as
+condescending: `push to origin`, `push to main`, `merge`, `rebase`, `stash`,
+`pull request`, `regression`, `race condition`, `cache`, `timeout`, `schema`,
+`dependency`, plus filenames, flags, env vars, and anything the reader will type.
+
+**TRANSLATE** project-internal vocabulary, whose meaning lives only in this codebase:
+
+| internal | plain |
+|---|---|
+| `private slugs` | the short names of your private projects |
+| `T3/T4 routing` | which model does the work |
+| `the ratchet baseline` | the list of already-known problems the check ignores |
+| `public-boundary issue` | published in your public repo |
+
+Plain words alone are not enough. A plainer sentence that still fails §2 is not an
+improvement — see the progression in §7.
+
+### 4.5 Name every specific individually
+
+`2 models affected` is a headline, not information. List each with its own date,
+replacement, or detail so the reader can act per item.
+
+### 4.6 Always close with a decision or a status
+
+Two forms only:
+- `I've started this and will update you when done.`
+- `I need your approval to do this.` — and say why approval is needed.
+
+Never end a finding with no disposition.
+
+## 5. Accuracy
+
+State only what you verified, and say how. Mark anything assumed or unchecked.
+If you previously said something wrong, correct it in one plain sentence and move
+on — do not bury it, do not dwell on it.
+
+Do not inflate impact to justify reporting something. **If the real impact is low,
+say it is low.** A reader who catches you inflating once discounts everything after.
+
+## 6. Before you send — verify each block
+
+Run this check on every block. Any "no" means rewrite, not ship.
+
+1. Could an agent with zero context act on the heading alone?
+2. Does every sentence name an actor, a specific object, and its modality?
+3. Is the second line a consequence, or a restatement in different words?
+4. Does the heading lead with the target state rather than the diagnosis?
+5. Is every remaining technical term one the reader will actually type?
+6. Does the block end with a decision or a status?
+7. Would you be comfortable if this line were quoted back with no surrounding text?
+
+## 7. Worked progression — why the near-misses fail
+
+Real sequence from the session that produced this file. Each attempt fixed a
+different level and the sentence stayed unusable, because the defect was in message
+logic the whole time.
+
+**Original (jargon):** *"The resolvers disagree on T3/T4."*
+Project-internal vocabulary; meaningless outside this codebase.
+
+**Attempt 1 — FAILS:** *"Two lookups pick different models."*
+Plainer, and no more useful. No actor, no target, no modality. The reader asks "why
+would they?" and has nothing to do next.
+
+**Attempt 2 — ALSO FAILS:** *"Ask for the same tier two different ways and you get
+two different models back — one path sorts by release date, the other by capability
+rank."*
+Accurate, and still wrong. Diagnosis-first: it explains the internals, so the reader
+now understands the bug and still has to work out what to do about it.
+
+**PASSES:**
+```
+We need one code path per model tier
+Today we have 2+ paths, with inconsistent results
+```
+Actor (`we`), specific object (`one code path per model tier`), modality (`need` =
+requirement). Target state first, gap second. Longer than attempt 1 — length was
+never the goal.
+
+## 8. Worked example — a full block
+
+```
+2 Groq models shut down on 2026-08-16
+Anything still pointing at them fails outright, and the catalog lists them as
+live, so the next person to read it picks a dead model.
+
+ - llama-3.1-8b-instant — shut down 2026-08-16, replacement openai/gpt-oss-20b
+ - llama-3.3-70b-versatile — shut down 2026-08-16, replacements
+   openai/gpt-oss-120b and qwen/qwen3.6-27b
+ - Both were free + developer plan only; enterprise spend unaffected
+ - To fix: re-read Groq's official docs, update all 15 entries, mark those 2
+   retired, and move the re-check date forward
+ - I need your approval — this needs live doc lookups, and I will not move the
+   date without doing them
+```
+
+## 9. Escape hatches
+
+- **Nothing to report.** Say so in one line. Do not manufacture blocks to fill a
+  report.
+- **You cannot name the modality.** That means you do not know whether it is a
+  requirement, a fact, or a decision. Find out before writing, or state the
+  uncertainty explicitly as the finding: *"I do not know whether X is intended
+  behaviour or a defect; deciding needs Y."*
+- **The item is genuinely trivial.** One line, no block. Format overhead on a typo
+  is noise.
+- **A rule fights the cold-read test.** §2 wins. Say which rule you broke and why.

package/skills/build-loop/references/verify-dispatch.md

@@ -15,7 +15,7 @@ Walk this after any dispatched Agent, Task, or orchestrator sub-agent (including
 
 Ground truth comes from commands you run yourself, not from prose the agent returned.
 
-## 5-Step Verification Checklist
+## 6-Step Verification Checklist
 
 Run these yourself. Do not echo the agent's report back as your own finding.
 
@@ -77,9 +77,63 @@ State the outcome in this form:
 
 Never emit "the agent confirmed it passed" as your own verification line. Name which commands you ran and what they returned. If a step was skipped, say why.
 
+### 6 — Re-execute the literal command behind each headline verification claim
+
+Steps 1–3 verify the *repo*. This step verifies the *claim*. A subagent's headline usually names the command it says it ran and the outcome it says it got — re-run that exact command and compare.
+
+```bash
+python3 "${CLAUDE_PLUGIN_ROOT:-.}/scripts/verification_claim_probe.py" \
+    --report-file <the subagent's returned report> --markdown
+```
+
+The probe extracts command-shaped claims (a backticked command sitting next to a verification verb — *verified*, *confirmed*, *reproduced*, *ran*, *tested*, *proved*, *exit N*, *N passed*), re-runs each one, and labels it:
+
+- **`executed:`** — we ran it and every stated expectation held.
+- **`contradicted:`** — we ran it and an expectation failed. **Exit code 1.** This is a real finding; it goes in the report, not in a footnote.
+- **`cited:`** — we did not run it. Either no expectation was stated to check against, or the command is not safely re-executable.
+
+**Exit 2 = `nothing_executed`.** Zero claims extracted, or every claim refused, or every claim ran with no expectation to check — the probe verified nothing. Treat exit 2 as "unverified", never as "clean"; a run we could not observe is not a pass.
+
+The safety layer is an **allowlist, not a deny-list**, because the commands come from LLM-authored report text and you cannot enumerate what a model might emit. Only verification-shaped heads run (`pytest`, `python3`, `node`, `npm test`, `cargo test`, `go test`, `swift test`, `ruff`, `mypy`, `tsc`, `eslint`, `jest`, `vitest`, `jq`, …), any shell metacharacter or redirection refuses outright, and a `git` command is delegated to `scripts/audit_git.py`'s classifier so the two scripts cannot drift on what counts as safe. Everything else is `cited`. Denied commands are **never executed** — the probe must not become the thing that writes to a live store.
+
+Carry the `executed:` / `contradicted:` / `cited:` label into the report for every relayed claim. An unlabeled claim is `cited:` by default — you read it, you did not verify it.
+
+**Why this step exists.** 2026-08-07: four subagent reports arrived with the safety classifier unavailable. One reported a security fix as *"Fixed — guard refuses the live store; verified by reproducing the auditor's exact attack (exit 2, store still 0)."* Running that exact command against the shipped code gave **exit 0 and 49 entries written into the user's live store**. The guard required its flag only on the branch where the path was omitted; naming the path explicitly walked straight past it. Steps 1–3 would all have passed — the commits existed, the tree was clean, the suite was green. Only re-running the claim's own command caught it.
+
+### 7 — Confirm the run record landed in the workdir you dispatched into
+
+A dispatched orchestrator that returns a polished report has not necessarily closed its run. Assert the `runs[]` mutation yourself, against the workdir you dispatched INTO (not your own session's cwd — they differ whenever you dispatch into a sibling repo, a plugin subdirectory, or a worktree):
+
+```bash
+# The envelope named a run_id — assert that exact record:
+python3 "${CLAUDE_PLUGIN_ROOT}/scripts/run_close_lint.py" \
+  --workdir <dispatch-target-workdir> --run-id <run_id> --require-orchestrator --require-learn --json
+
+# No run_id in the envelope (the common shape when Review-G was skipped entirely):
+python3 "${CLAUDE_PLUGIN_ROOT}/scripts/run_close_lint.py" \
+  --workdir <dispatch-target-workdir> --expect-recent-minutes --require-orchestrator --require-learn --json
+```
+
+Exit 1 means the run is not closed and Phase 6 Learn cannot see it. Do not accept the completion: either re-dispatch the orchestrator's Review-G run-close step, or write the record yourself from the envelope's own contents using the printed `remediation` command. A `no_state` status is the loudest case — the target workdir has no `.build-loop/state.json` at all, so that run produced no durable artifact of any kind (check whether the orchestrator actually worked in the workdir you think it did).
+
+Worked evidence (2026-07-16): six sequential dispatched `build-orchestrator` agents in `ObsidianVault/.obsidian/plugins/daily-planner` each completed with a high-quality report and wrote no `runs[]` entry, retrospective, milestone, or feedback line; the only rows in the vault's `state.json` came from Stop hooks. Every report read as success, so nothing surfaced until a retrospective counted the missing records a day later. Step 6 is a single command that would have caught the first one. The orchestrator-side half of this contract is the Review-G assertion in `references/phase-4-review.md` §"Run-close assertion" — that one catches a write that was attempted and failed; this one catches a run that never reached Review-G.
+
+## Auditing verdict / classification claims (DONE · PASS · verified)
+
+When a dispatched agent returns *verdicts* — "DONE", "PASS", "already implemented", "complete", "verified" — audit each verdict against the cited evidence, not against its title. An over-optimistic DONE hides a real gap far more often than a REJECT does; the failure mode is **claiming a nearby mechanism satisfies the requirement when it only partially does** ("adjacent" and "partial" read as DONE).
+
+Run the audit as a **second, adversarial pass — a different model where possible** (e.g. Codex when the harness was Claude), prompted to REFUTE, not confirm:
+
+- For every DONE / PASS, open the cited `path:line` and confirm the named control **actually satisfies the requirement** — not merely that a related file exists or a similar mechanism is nearby.
+- Default to skepticism on DONE; a verdict carrying no `path:line` evidence is unverified by definition.
+- Spend the adversarial budget on the DONE claims; sanity-check the rest (ADOPT genuinely not-yet-done, DEFER not actually adoptable).
+- Report corrections as `<id> · claimed <verdict> · actually <truth> · correct <verdict>` with evidence `path:line`.
+
+Worked evidence (2026-07-08, this repo): a Codex audit of a 13-item triage corrected **3 of 9 "DONE" verdicts to ADOPT** (partial/adjacent), each confirmed against `stop_closeout.py` / `session_end_retro_sweep.py`; a separate pre-push Codex audit caught **3 over-optimistic passes** (fire-scope over-firing on runs, a `tempfile` name the scratch-guard missed, a SessionEnd hook the plugin didn't actually ship). A single self-classification pass would have shipped all six.
+
 ## What this does NOT replace
 
 - **runtime-parity-verification** — that skill cross-checks a running app's UI against backend state. This checklist covers the git/test layer only.
 - **plan-verify** — that skill lints a plan's evidence claims before Phase 2 acceptance. This checklist fires after a dispatch reports completion.
 
-Origin lessons: `feedback_solicited_peer_review_is_not_independent.md`, `feedback_buildloop_verify_auditor_ran.md`, `feedback_verify_running_app_not_compile_green.md`.
+Origin lessons: `feedback_solicited_peer_review_is_not_independent.md`, `feedback_buildloop_verify_auditor_ran.md`, `feedback_verify_running_app_not_compile_green.md`, `feedback_duplicate_claim_pivot_to_verifier.md`.

package/skills/building-with-deepagents/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: building-with-deepagents
-description: Use when building or refactoring an agent that imports OSS `deepagents` (`from deepagents import create_deep_agent`). Covers SubAgent API, middleware, tool scoping, streaming, checkpointing. Not for `.claude/agents/*.md`.
+description: Build or refactor an agent using the OSS `deepagents` framework (SubAgent API, middleware, tool scoping, streaming, checkpointing). Use when the user wants a multi-agent/subagent system built with deepagents, or the code imports it. Not for `.claude/agents/*.md` definitions.
 user-invocable: false
 ---
 

package/skills/claim-scope/SKILL.md

@@ -0,0 +1,185 @@
+---
+name: claim-scope
+description: "Name the LAYER a claim lives at (working tree / repository / deployed / live behavior) and check that your instrument can reach it, before stating any fact about a system. Triggers on assertion words (is / never / only / verified / cannot) and on 'does X exist', 'did X ship'. Not for grading evidence STRENGTH ([measured]/[correlated]/[reasoned]) — that is report_lint's mechanism-claim rule, which this extends with reach. A grep proves what is in one checkout; it can say nothing about what is running. Verify right-to-left: start at observed behavior, walk back toward source."
+user-invocable: false
+companion_scripts:
+  - scripts/claim_scope_lint.py — the deterministic half. Flags a claim whose subject layer exceeds the reach of every instrument named on the line.
+---
+
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# Claim Scope
+
+**The defect this prevents:** an agent runs a correct check, then states a
+conclusion the check could not support, with full confidence and no hedge. The
+check is not wrong. The *reach* of the check is wrong, and nothing in the
+sentence records the difference.
+
+Observed 2026-09-04. An agent grepped `@vercel/blob` in a local checkout of
+a private app repo, found nothing, and reported: *"there is no blob path; the audio
+lives only in Postgres; switching source is not possible."* The grep was
+accurate. The checkout sat on a branch whose last commit was a day old, while
+`origin/main` carried a merged blob migration that was **already deployed to
+production**. The agent had reported a property of one working tree as a
+property of the running system. Existing lint passed it clean, because the
+sentence named its instrument (`grep`) and the mechanism-claim rule accepts
+`grep` as an observation.
+
+**Naming your instrument is not enough. The instrument must be able to see the
+thing you are claiming.**
+
+---
+
+## The four layers
+
+Every claim about a software system lives at exactly one of these. Decide which
+one BEFORE writing the sentence.
+
+| Layer | The claim is about | Nothing below it can prove this |
+|---|---|---|
+| **L1 · working tree** | this branch, this directory, right now | — |
+| **L2 · repository** | origin, every branch, every worktree | L1 sees one branch of many |
+| **L3 · deployed** | what is built and shipped and serving | L2 sees intent, not what shipped |
+| **L4 · live behavior** | what it does when a person touches it | L3 sees the artifact, not its behavior |
+
+The layers are a ladder, not a menu. **A claim at layer N requires an instrument
+that reaches layer N.** Reaching higher is free and always valid; reaching lower
+is the defect.
+
+## Instrument reach — the lookup
+
+Do not reason about this. Look it up.
+
+| Instrument | Reaches | Blind to |
+|---|---|---|
+| `grep`, `cat`, `sed`, Read, Glob, reading a file | **L1** | other branches, other worktrees, what shipped, what it does |
+| `git log`, `git status`, `git diff` (no fetch) | **L1** | anything not yet fetched |
+| `git fetch --all` + `git log HEAD..origin/<branch>` | **L2** | whether it built or shipped |
+| `git worktree list`, `git branch -a`, `gh pr list` | **L2** | same |
+| `vercel ls` / `vercel inspect`, `gh run list`, deploy sha, build log | **L3** | runtime behavior under a real request |
+| `curl -D-`, a real HTTP request, a screenshot, `ibr scan`, an AX probe, a live DB query | **L4** | nothing — this is the ground |
+
+Two instruments that look similar and are not: `git log` reports what you have
+fetched; `git log HEAD..origin/main` after a fetch reports what exists. The
+first is L1. The second is L2.
+
+## Procedure
+
+Run this whenever a claim is about to be stated, not only when you doubt it.
+Doubt is the thing that fails first.
+
+**1. Write the claim as a sentence.** Then read it back and answer: *which layer
+is this a claim about?* If the sentence contains "is deployed", "is running",
+"is broken", "does not exist anywhere", "nothing does X" — it is L3 or L4, no
+matter what you looked at.
+
+**2. Look up the reach of every instrument you actually ran.** Not the ones you
+could have run. The ones in your transcript.
+
+**3. Compare.** If `max(instrument reach) < claim layer`, you have two legal
+moves and no third:
+   - **Go get the higher-layer evidence.** Usually cheap: one `git fetch`, one
+     `curl -D-`, one `vercel ls`.
+   - **Rewrite the claim down to the layer you actually reached**, explicitly:
+     *"no blob dependency in the working tree of `fix/embedding-failures` at
+     `3fe5298`"*. This is honest and often still useful.
+
+   Stating the higher-layer claim anyway is the defect. There is no "probably".
+
+**4. Stamp the time.** An L4 observation is true at its timestamp and nowhere
+else. Record when you looked, not when you are speaking.
+
+**5. Re-run before repeating.** Before restating an earlier L3/L4 result later in
+the same session, re-run it. In the 2026-09-04 incident a correct `curl` at
+05:32Z was still being quoted at 07:47Z; the deploy that falsified it landed at
+07:07Z, inside the same conversation.
+
+## Verify right-to-left
+
+Default direction: **start at L4 and walk left toward source.**
+
+Left-to-right (read source → infer behavior → assert it) manufactures confident
+wrong answers, because the source you are looking at may not be the source that
+is running. You cannot detect that from inside the source.
+
+Right-to-left (observe behavior → explain it from the artifact → trace to the
+code that produced it) cannot make that error. The rightmost layer is the only
+one that cannot be stale about itself.
+
+Worked example, the same incident done correctly:
+
+- **L4 first.** `curl -D- -H "Range: bytes=0-1023"` → `HTTP 200`,
+  `accept-ranges: none`. *Seeking is broken right now.* True regardless of any
+  repo state.
+- **L3 next.** `vercel ls` → production deploy Ready at 00:07:16 PDT.
+  `gh run list` → CI red on that commit. *The blob code shipped.*
+- **L2 next.** `git fetch` + `HEAD..origin/main` → the merge exists. `git
+  worktree list` → the CI fix is stranded on an unpushed branch.
+- **L1 last.** Read the merged route. It 307-redirects when `episode.audioUrl`
+  is set and falls back otherwise. Now the L4 observation is *explained*:
+  today's row predates the deploy, so it has no blob URL.
+
+Reading the route first would have produced "seeking works now," which is false.
+The L4 observation is what made the L1 reading mean anything.
+
+## The pause trigger
+
+These words may not be written until step 1–3 has run:
+
+> is · is not · there is no · does not exist · never · only · nothing ·
+> no code · zero · settled · confirmed · verified · impossible · cannot ·
+> already · still
+
+Seeing one in a draft sentence is a full stop. Answer out loud: *which layer,
+and what instrument reached it?* If you cannot name both, you do not have the
+claim yet.
+
+## Absence claims need a layer, always
+
+"X does not exist" is the single highest-risk shape, because a null result looks
+identical at every layer. `grep` returning nothing and the thing genuinely not
+existing are indistinguishable from inside L1.
+
+Every absence claim ships with its scope written into the sentence: *what was
+searched, at which layer, at what commit or time.* An absence claim with no
+scope is not a weak claim. It is not a claim.
+
+## Escape hatches
+
+- **The higher layer is unreachable** (no credentials, no network, the service
+  is down): say so, state the claim at the layer you reached, and name the exact
+  command that would close it. Never silently downgrade and speak at full
+  confidence.
+- **The user asserts a higher-layer fact that contradicts your lower-layer
+  check** ("there was a migration earlier today"): they are almost certainly
+  right, because they can see layers you did not check. Go check L2 and L3
+  before responding. Do not defend the L1 finding.
+- **A record or prior session says SETTLED.** That is a claim to re-verify, not a
+  fact to inherit — and re-verify it at the layer it is asserted about. See
+  `feedback_reverify_relayed_citations_before_acting`.
+
+## Relationship to the existing gates
+
+This does not replace them. It adds the missing axis.
+
+- `report_lint.py` `mechanism-claim-unobserved` grades **strength and
+  provenance**: did you name an instrument, and is it `[measured]` /
+  `[correlated]` / `[reasoned]`. It accepts `grep` and cannot tell that a grep
+  is blind to L2/L3. `claim_scope_lint.py` grades **reach**, and is the reason
+  the 2026-09-04 sentence would now be caught.
+- `runtime-parity-verification` asserts rendered UI == backing store for a flow
+  you just changed. Same instinct, narrower scope: it fires on shipping work.
+  `claim-scope` fires on *saying things*, including in pure analysis with no
+  diff.
+- `verification_claim_probe.py` re-executes a relayed claim's literal command.
+  Use it when the claim came from a subagent; use `claim-scope` on your own.
+
+## Self-check before emitting
+
+Before any report, answer these three. If any answer is missing, the report is
+not ready.
+
+1. For every factual claim: which layer, and which instrument reached it?
+2. For every L3/L4 claim: what time was it observed, and has anything in this
+   session changed since?
+3. For every absence claim: what exactly was searched, and at which layer?

package/skills/color-engine/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: color-engine
+description: Generate accessible color systems and solve contrast, instead of guessing hex values. Use when picking or fixing colors for any UI, chart, diagram, doc, or artifact — "what colors should this use", "is this readable", "this text fails contrast", "make a dark theme", "pick an accent". Also use before shipping any palette, to PROVE contrast rather than assert it. NOT for choosing layout, typography, or component structure.
+user-invocable: false
+---
+
+# Color Engine
+
+Colors are **outputs**. The design is the set of **relationships** — contrast
+targets, chroma structure, harmony geometry. Fix the relationships and rotate
+the anchor hue and you get an infinite family of distinct-but-equally-valid
+systems, because the design lives in what stays invariant.
+
+Practical consequence: **never hand-pick hex values and hope.** State the
+relationship you want; let the engine solve for the color that satisfies it.
+
+## When to reach for this
+
+- Choosing colors for a UI, chart, artifact, deck, or diagram.
+- Any "is this readable / does this pass contrast" question.
+- A design review where a palette needs to be *proven* accessible.
+- Building a dark theme, or checking that an existing one survives dark mode.
+
+Skip it when the project already has a committed design system — apply that
+system instead. Its tokens win; use this only to fill gaps or verify.
+
+## The three calls
+
+```python
+from color_engine import palette, check, fix
+
+# 1. Give me a valid color system.
+p = palette(hue=250, profile="aurora-deep")
+p["roles"]   # {surface, on_surface, muted, accent, on_accent} — all contrast-solved
+p["ramps"]   # tonal ramps for surfaces/borders
+
+# 2. Is this pair readable?
+check("#6d7379", "#f6fbff")            # -> ratio 4.6, passes True
+check("#888", "#fff", target=7.0)      # AAA
+
+# 3. Make this pair readable.
+fix("#999999", "#ffffff")              # -> "#777676", 2.85 -> 4.53
+```
+
+`fix` moves **lightness only**, preserving hue and chroma, so the result still
+reads as the same color rather than being swapped for a different one. An
+already-passing pair is returned unchanged — it never churns a color that was
+fine. Check `passes_after`: an extreme target on a clipped gamut can still fall
+short, and the engine reports that instead of hiding it.
+
+## Customization — profiles, not forks
+
+A profile is a named set of **relationship defaults**, not a set of colors.
+Register your house style once; callers then ask by intent and get on-brand
+results. Adding a profile never forks the engine.
+
+```python
+from color_engine import register_profile
+register_profile("my-app", {
+    "surface_L": 0.13,          # dark ground
+    "accent_chroma": 0.17,      # vivid accent
+    "on_surface_contrast": 13.0,
+    "muted_contrast": 4.6,      # keep metadata legible, not invisible
+})
+palette(hue=210, profile="my-app")
+```
+
+Built in: `default` · `aurora-deep` (dark glass) · `reading` (long-form, softer
+than max contrast because 21:1 is harsh over minutes) · `wcag-aaa`.
+
+Harmony geometry: `complementary` · `analogous` · `triadic` · `split`.
+
+## Contrast targets
+
+| Target | Use |
+|---|---|
+| 3.0 | Large text, UI boundaries, icons |
+| 4.5 | Body text (WCAG AA) — the default |
+| 7.0 | AAA body text |
+
+Deliberately reduce contrast for metadata and disabled states to build
+hierarchy, but keep it **above 3.0** so it reads as de-emphasized rather than
+broken. Dark mode needs its own audit: a pair that passes on white can fail on
+near-black.
+
+## Installing in another project
+
+Copy this directory. It is **pure stdlib with zero dependencies** — no install
+step, no lockfile, no version conflict. `_core.py` is vendored from
+`groundwork/designer/color/relationships.py` and carries a `source_sha256`
+header; re-hash the source to detect drift. Do not hand-edit `_core.py` —
+extend through `color_engine.py` or a profile.
+
+Verify after copying:
+
+```bash
+python3 -c "import _core; _core._selftest()"   # math anchors + invariance
+python3 color_engine.py                        # the three calls
+```
+
+The self-test checks the property that matters: hue-rotated palettes hold every
+contrast target in **both** light and dark, so the generator spans the space
+instead of enumerating points in it.