crewforth 0.0.1 → 3.0.0-rc.1

package/kit/skills/spec-planning/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: spec-planning
+description: |
+  Spec-first planning: task breakdown, measurable acceptance criteria, dependency order, risk priority.
+  crew-planner applies it; the plan goes to docs/PLAN.md.
+  Use when the scope is unclear or the work spans more than one change.
+---
+
+# Spec-First Planning
+
+<!-- routing-eval reads the next line; why it sits in the body: AGENT_TEMPLATE.md -->
+Trigger phrases: "plan", "spec", "task breakdown", "acceptance criteria", "roadmap", "how do we split this"
+
+Before writing code: what will be done, how it counts as "done", and in what order to proceed become clear.
+
+## Steps
+1. **Purpose & scope:** the problem being solved in a single sentence; also write the out-of-scope explicitly (prevent scope creep).
+2. **Split into vertical slices:** the smallest end-to-end working pieces (not horizontal layers). Each slice delivers value on its own.
+3. **A contract for every task:** input · output · **measurable acceptance criterion** (testable) · estimated risk.
+4. **Dependency graph:** which task waits on what; no cycles. **Bring the riskiest/most-unknown to the front** (fail-fast).
+5. **Uncertainties:** assumption list + open questions; do not fill ambiguous spots with a guess, ask with explicit options.
+
+## Output (docs/PLAN.md)
+```
+# <Feature> — Plan
+## Acceptance criteria
+- [ ] AC-1: <measurable outcome>
+- [ ] AC-2: <measurable outcome>
+## Tasks (order)
+1. <task> — satisfies: AC-1 — dependency: <none/#n> — risk: <low/medium/high>
+## Assumptions / Open questions
+- ...
+```
+
+**Every criterion carries a stable id, and every task names the ids it satisfies.** The id is what makes the plan
+checkable later: "AC-2 is only partly built" can be said, argued about and tracked; "the second checkbox" cannot,
+and renumbering a list silently re-points every reference to it. Never reuse or renumber an id — a dropped
+criterion keeps its id with a strike-through and a one-line reason. A criterion no task satisfies, and a task that
+satisfies no criterion, are both findings before a line of code is written.
+
+## Mark what you do not know — do not fill it in
+Where a requirement admits more than one reading, write the marker **`[NEEDS CLARIFICATION: <the question>]`** at
+that exact spot in the plan. Do not resolve it with the likeliest interpretation and move on.
+
+This is the difference between a discipline and a hope. "Stop and ask when unsure" (§1) depends on noticing the
+uncertainty in the moment; a marker survives into the artifact, where the user, a reviewer and a later session
+can all see it. A plausible assumption silently written into a spec is indistinguishable from a decision, and
+that is exactly how the wrong feature gets built correctly.
+
+Rules that keep it honest:
+- The marker carries the **question**, not the label. `[NEEDS CLARIFICATION: does an expired invite count as
+  used, or can it be re-sent?]` is actionable; `[NEEDS CLARIFICATION: invites]` is noise.
+- A plan may ship with markers — that is the point. It may **not** ship with a marker inside an acceptance
+  criterion: a criterion nobody can evaluate is not a criterion.
+- Resolve by asking, never by choosing. When the user answers, replace the marker with the answer *and* record
+  which reading was rejected — the alternative is what a future reader needs.
+- Zero markers on a genuinely ambiguous brief is a smell, not a win.
+
+## Converge — before the work is called done, hold the code up against the plan
+
+Tests prove the code does what the tests say. Nothing so far proves it does what the PLAN said: a criterion can be
+quietly half-built with every test green, and code nobody asked for can ride along unremarked. So when a plan
+exists, closing the work includes one pass that reads each criterion against the code as it now stands.
+
+Bound the pass to what the plan names — the criteria, the tasks, and the files and components they point at. Do not
+widen the audit into the rest of the codebase. For each `AC-n`, look at the code in that scope and record a finding
+**only where there is a gap**, classified as exactly one of:
+
+| Gap | Means |
+|---|---|
+| **missing** | nothing in the code implements the criterion |
+| **partial** | something does, but not all of what the criterion states |
+| **contradicts** | the code does something that conflicts with the criterion or a plan decision |
+| **unrequested** | the code contains work no criterion or task called for |
+
+`unrequested` is the one that is easy to skip and should not be: it is scope creep made visible (principle 3,
+"surgical change"). It is surfaced, never deleted by this pass — the user decides whether it stays, and if it
+does, it gets a criterion.
+
+Report it as a table — `AC-n | gap | evidence (file/area) | remaining work` — then either:
+- **Converged:** zero findings. Say so in one line, with how many criteria were checked.
+- **Not converged:** append each remaining item to the plan as a task that names its `AC-n`, and go back to
+  producing. Repeat the pass after that work, until it converges or the user accepts a named gap explicitly.
+
+This is model discipline, not a gate: no exit code can judge "partially built". What makes it hold is the table —
+a pass that produced no table did not run.
+
+## DoD (this skill's contribution)
+- Every task's "done" is testable; ordering and dependencies are visible; the riskiest work has been brought to the front.
+- Every unresolved ambiguity carries a `[NEEDS CLARIFICATION: …]` marker; no acceptance criterion contains one.
+- Every criterion has a stable `AC-n` id and at least one task that satisfies it; at close, a converge pass
+  has run and either reported **Converged** or left its remaining items in the plan as tasks.

package/kit/skills/systematic-debugging/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: systematic-debugging
+description: |
+  Root-cause a bug before touching a fix: reproduce, isolate, form and test a hypothesis, confirm the cause,
+  then fix and verify. Stops guess-driven patching. For persistent, intermittent, or "already tried a few things" bugs.
+---
+
+# Systematic Debugging
+
+<!-- routing-eval reads the next line; why it sits in the body: AGENT_TEMPLATE.md -->
+Trigger phrases: "debug", "root cause", "why is this failing", "intermittent bug", "can't reproduce", "is broken", "crashes"
+
+One rule holds the whole skill together: **no fix without a confirmed root cause.** A patch that makes the symptom
+disappear without a proven cause is not a fix — it's a coin flip that hides the bug until it returns somewhere worse.
+This skill is the discipline that turns "try things until it works" into "understand, then change one thing."
+
+> **Crewforth adaptation (local, .claude/):** Distinct from `iterate` (a self-correction loop over a *task*) and `reflect`
+> (meta-review of an approach) — this skill is for a *defect*. §4 Prohibitions apply; a fix still goes through the
+> project's review/test gates. Don't disable a test or a gate to make a symptom pass (that is masking, not fixing).
+
+## The loop (do them in order — skipping a step is why bugs come back)
+1. **Reproduce** — a reliable, minimal repro. Can't reproduce → that IS the first problem; see `references/techniques.md` (intermittent/heisenbug).
+2. **Isolate** — shrink the surface until the failure is in the smallest possible slice (bisect commits, halve the input, disable half the system).
+3. **Hypothesize** — state ONE falsifiable cause: "X fails because Y." Write it down. A vague hunch is not a hypothesis.
+4. **Test the hypothesis** — the cheapest observation that would *disprove* it (a log, a breakpoint, a probe). If it survives, you have the cause; if not, back to 3.
+5. **Confirm the root cause** — you can explain the full chain symptom←…←cause, and you can turn the bug on and off by touching the cause.
+6. **Fix** — the smallest change at the cause (not the symptom). Consider what else shares that cause.
+7. **Verify** — the original repro now passes, a regression test locks it, and nothing nearby broke.
+
+## Checklist
+- [ ] Reliable repro captured (exact steps/input/env)
+- [ ] Failure isolated to the smallest slice
+- [ ] One falsifiable hypothesis written down
+- [ ] Hypothesis tested by observation (not by applying a fix and seeing)
+- [ ] Root cause confirmed (can toggle the bug via the cause; full chain explained)
+- [ ] Fix at the cause + regression test added
+- [ ] Original repro passes; no new failures
+
+## Anti-patterns (each is guess-driven patching wearing a disguise)
+- **Shotgun debugging** — changing several things at once; now you can't tell what mattered. One change at a time.
+- **Symptom patching** — a `try/catch`, a null-guard, a retry that swallows the failure without explaining it.
+- **"It works now"** without knowing *why* it broke — the bug is dormant, not dead.
+- **Blaming the environment/flake** before isolating — sometimes true, but only *after* step 2, never as the first move.
+- **Deleting/skipping the failing test** to go green — that is masking; the gate exists to catch exactly this.
+
+---
+
+## Techniques by symptom
+Bisecting (git + input + system), instrumentation vs. debugger, intermittent/heisenbugs (timing, state, ordering,
+resource), the hypothesis log, and when to stop and ask for a second pair of eyes: **`references/techniques.md`**.
+
+## Invariant rules
+1. **No fix without a confirmed root cause** — the one rule; everything else serves it.
+2. **One change at a time** — isolate cause and effect; never shotgun.
+3. **Fix the cause, not the symptom** — a guard that hides the failure is not a fix.
+4. **Lock it with a regression test** — the repro becomes a test so it can't silently return.
+5. **Never mask to go green** — don't disable a test/gate/assertion to make the symptom pass.

package/kit/skills/systematic-debugging/references/techniques.md

@@ -0,0 +1,44 @@
+# Debugging techniques by symptom
+
+Loaded on demand — the SKILL.md loop is the method; this is the toolbox for a specific kind of bug.
+
+## Isolation: how to shrink the surface (step 2)
+
+- **git bisect** — a regression that "used to work". `git bisect start; git bisect bad; git bisect good <rev>` then let it binary-search the commit that introduced it. Automate with `git bisect run <cmd>` where `<cmd>` exits 0 on good, non-zero on bad.
+- **Binary-search the input** — halve the failing input until the smallest reproducing case remains. A 10k-row file that fails narrows to the one row; a 500-line config to the one key.
+- **Halve the system** — disable half the middleware / feature flags / plugins. Failure gone → it's in the disabled half. Repeat.
+- **Minimal repro** — rebuild the failure in isolation (a scratch script, a single failing unit test). If it won't reproduce in isolation, the cause is in the *environment/state* you left out — that's a finding, not a dead end.
+
+## Instrumentation vs. debugger
+
+- **Logging/print** — best for intermittent, timing, production, and "can't attach" cases; leaves a trace across runs. Log the *hypothesis-relevant* value, not everything. Remove or gate the probes before committing.
+- **Debugger/breakpoint** — best for a reliable, local repro where you want to inspect live state and step. Conditional breakpoints (`x == badValue`) skip the noise.
+- **Assertions/invariants** — add a check that *should* always hold; the point it fires is upstream of the symptom.
+- **Bisect on values** — binary-search *when* a value goes wrong: log at start/middle/end of the pipeline, then narrow.
+
+## Intermittent / heisenbugs (can't reliably reproduce)
+
+The cause is almost always one of:
+- **Timing / races** — order of concurrent operations; add delays/logging to widen the window and expose it. A bug that vanishes when you add a log is a timing bug (the log changed the timing).
+- **Shared/leaked state** — a previous test/run left state behind; run the case in full isolation and in a different order (`--shuffle`).
+- **Ordering dependence** — passes alone, fails in the suite → cross-test coupling. Bisect the test order.
+- **Resource / environment** — memory pressure, disk, clock, locale, network flake, an unpinned dependency version. Pin and compare.
+- **Uninitialized / nondeterministic** — reads of uninitialized memory, map iteration order, unseeded randomness, `Date.now()`.
+
+Make it reproducible *first* (loop the case 100×, add stress, shuffle). An intermittent bug you can't trigger on demand can't be confirmed fixed.
+
+## The hypothesis log
+
+For a bug that resists a few rounds, write it down — it stops you from re-testing the same dead hypothesis and reveals patterns:
+
+```
+Symptom: <exact observable failure>
+Repro:   <steps / input / env>
+H1: <cause> → test: <observation> → RESULT: disproved (saw X, not Y)
+H2: <cause> → test: <observation> → RESULT: CONFIRMED (toggles bug)
+Root cause: <the confirmed chain>  Fix: <change at cause>  Test: <regression test>
+```
+
+## When to stop and get a second pair of eyes
+
+After ~3 disproved hypotheses with no new information, or when you've been staring at the same 20 lines — you likely hold a wrong assumption you can't see. Escalate: hand over the hypothesis log (not "it's broken") so the next person starts from what's *already ruled out*, not from zero. In Crewforth, that handover is the `handoff` skill.

package/kit/skills/teamboard/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: teamboard
+description: |
+  Experimental: a shared team board. Claim a work item, hand it over, finish it; the claim is a git-ref
+  lock, so two people cannot take the same item.
+metadata:
+  experimental: true
+---
+
+# Team Board (shared claims + shared item memory)
+
+<!-- routing-eval reads the next line; why it sits in the body: AGENT_TEMPLATE.md -->
+Trigger phrases: "team board", "who is working on", "claim", "take this item", "pick up a task", "sprint item", "release the item", "hand the item over", "is anyone on", "board", "of us are working", "stepping on each other", "who is doing what", "who else is working"
+
+## The problem this closes
+Every teammate runs Crewforth **locally**. `docs/PLAN.md` and `docs/SESSION_STATE.md` are gitignored, so the fact
+that Ali started item #1 two hours ago exists nowhere the other sessions can see. Two people start the same item;
+a blocked item gets picked up before its dependency lands; whoever inherits half-finished work rebuilds the
+context from scratch. The board makes those three facts shared.
+
+## The engine (all commands go through it)
+`bash .claude/hooks/board.sh <cmd>` — `status` · `show <id>` · `claim <id>` · `done <id> [note]` ·
+`drop <id> <note>` · `note <id> <text>` · `add <id> <title> [deps] [external]` · `init` · `sync`.
+Never hand-edit the board; every write must go through the engine or it loses its atomicity.
+
+## Why a claim is a real lock, not a convention
+The board lives on a git ref (`refs/crew/board`), not in the worktree. A claim is a commit pushed to that ref, and
+`git push` is fast-forward-only: when two people claim the same item from the same base, **one push is rejected**
+and that session re-reads the board and refuses. This is an atomic compare-and-swap with no server, no token and
+no daemon. The engine builds its commits with git plumbing, so claiming **never touches your working tree,
+index, branch or stash** — you can claim mid-feature with dirty files.
+
+## Off by default; on when a team asks for it
+A repo that never ran `init` **has no board and no gates** — no claim, no commit gate, no edit gate, nothing at
+session start. Solo work is unchanged, and so is every project that installed Crewforth before this existed. Do not
+create a board because a repo merely has more than one contributor; create one when the user says the team keeps
+colliding. Creating one, choosing between its three levels and the ref-namespace fallback: **`references/setup.md`**
+— one person runs it once, and everybody else configures nothing.
+
+Already have a board and want it out of the way? `/crew-board off` (add `--global` for every repo) releases **all
+three** gates and leaves the board itself intact; `/crew-board on` restores it. `CREW_NO_BOARD=1` does the same for
+one session. This half stays here on purpose: someone a gate has just stopped needs the answer without opening a
+second file.
+
+## The rules
+1. **Claim before you touch code.** `claim <id>` fails if someone else holds it, if it is done, or if a
+   dependency is unfinished — with the reason and the list of what *is* claimable. Do not argue with a refusal;
+   take a free item.
+2. **Two gates, not one, and the early one is the point.** The first file edit is refused while you hold no item
+   (`guard-write.sh`) — unclaimed work is caught at minute one, not at commit time after an afternoon of it. The
+   commit then has to carry `[#<id>]` for an item you hold and that is `in_progress`, or `[chore]` for work
+   belonging to no item. In a repo with no board neither gate exists. `CREW_NO_BOARD=1` disables both for a
+   session; say so out loud if you set it.
+3. **Never release silently.** `drop` REQUIRES a handover note, because the whole cost of a handover is the
+   context the next person does not have: where exactly it stands, which files, and *why* the rejected approach
+   was rejected. `done` takes a completion note (what shipped, commit/PR).
+4. **Never steal a stale claim.** A claim with no heartbeat for `stale_hours` (default 8) is reported as STALE.
+   Stale means *ask the owner*, not *take it*. Surface it to the user and let them decide.
+5. **Read before you plan.** At session start the board summary is injected automatically. Before proposing what
+   to work on, run `status` — recommending an item somebody already holds is the failure this exists to prevent.
+
+## Redaction — the board is shared
+Everything written here is pushed to a remote the whole team reads. `handoff`'s `<private>…</private>` rule
+applies unchanged: strip secrets, tokens, credentials and personal notes, leave `[redacted]`, and point at
+*where* a value lives (env var, secret manager, the person to ask) rather than the value.
+
+## Filling the board
+Items come from either direction, and both end at `add`:
+- **From a plan:** `crew-planner` + `spec-planning` produce `docs/PLAN.md` with measurable acceptance criteria and
+  a dependency order; each task becomes one `add <id> <title> <deps>`. Keep the plan's dependency edges — they
+  are what makes `claim` able to refuse blocked work.
+- **By hand:** the user dictates the items.
+
+## Tracker link (honest boundary)
+Teams use Jira, Trello, Linear, GitHub Issues or nothing, so Crewforth **binds to none of them**. An item carries an
+optional `external:` field, which is a link and nothing more — no sync, no import, no write-back. A team that
+wants two-way sync writes an executable `.crew/board-adapter.sh` answering two verbs: `import` (emit
+`<id>|<title>|<deps>|<external>` lines to be fed to `add`) and `export <id> <status>` (push the state outward).
+Crewforth ships no adapter; do not claim integration Crewforth does not have.
+
+## When the remote is unreachable
+Claims stay local and are labelled `UNSHARED` — meaning **the team cannot see them**, so the lock is not in force.
+Say that plainly rather than reporting success, and re-run `sync` once the network is back.
+
+## DoD
+- Work started only on an item held by this user; the board shows it `in_progress`.
+- An item left for any reason carries a handover note a stranger could resume from.
+- `done` recorded with what shipped, and the dependents it unblocked named to the user.

package/kit/skills/teamboard/references/setup.md

@@ -0,0 +1,37 @@
+# Setting a board up — one person, one command
+
+Read this only when a board is being created or its level changed. Claiming, dropping and finishing an item never
+need it: a teammate who clones the repo configures nothing.
+
+## Who runs what
+
+- **Whoever starts it:** `/crew-board init`, then add the items. It probes what the server accepts, creates the
+  board on the code repo's own `origin`, and that is the whole setup — no account, no token, no service.
+- **A separate board repository:** `/crew-board init --remote <url>` (or an existing remote's name). Use it when
+  the board is shared across several repos, or when people who must claim work cannot push to the code repo. It
+  gets its own `crew-board` remote and never touches `origin`.
+- **Everyone else: nothing.** They clone as usual. Session start fetches the board on its own (detached), the
+  ref namespace is auto-detected including the orphan-branch fallback, and `/crew-board` fetches on the spot if
+  the background refresh has not landed yet. Never tell a teammate to run `init` — a second `init` is how a team
+  ends up with two boards.
+
+## The ref namespace, and the fallback
+
+`init` first probes whether the server accepts a custom ref namespace (`refs/crew/board`); if it does not, it
+falls back to the orphan branch `refs/heads/crew-board`, which every server accepts and which enforces the same
+fast-forward rule. Do not merge that branch into code.
+
+## Which level to create
+
+Do not create a board because a repo merely has more than one contributor; create one when the user says the team
+keeps colliding. Three levels, and the user picks:
+
+| | Effect |
+|---|---|
+| no board (default) | nothing at all |
+| `require_item: referenced` in the board's `config` | claims and the shared memory, but no gate: a commit is only checked when it names an item |
+| `require_item: all` (what `init` writes) | claim before you edit, and every commit names an item or `[chore]` |
+
+A board with no remote is fine too — you get the item list, the dependency order and the gates, just nothing
+shared. Turning the gates off on an existing board is in SKILL.md, not here: someone a gate has just stopped
+needs that answer without opening a second file.

package/kit/skills/testing/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: testing
+description: |
+  The how of testing: pyramid, AAA, isolation, risk coverage, determinism. Guarantees the DoD's "tests are
+  green". crew-test-expert applies it.
+  Use when writing or changing tests, or when a suite is flaky, slow or green for the wrong reason.
+---
+
+# Testing Discipline
+
+<!-- routing-eval reads the next line; why it sits in the body: AGENT_TEMPLATE.md -->
+Trigger phrases: "write a test", "run the tests", "coverage", "are the tests green", "unit test", "integration test", "tests pass locally", "flaky test", "test is flaky"
+
+Goal: **behavior correctness** — test real behavior without breaking product code just to make a test pass.
+
+## Principles
+- **Pyramid:** many unit, fewer integration, few end-to-end (e2e). Limit e2e to critical flows.
+- **AAA:** Arrange-Act-Assert; **one test = one behavior**.
+- **Isolation & determinism:** external dependencies are mocked/faked; time and randomness are fixed; test order is independent.
+- **Risk-coverage:** risk, not metrics. Critical path + **boundary** + **negative** + **authorization (IDOR/404)** scenarios.
+- **Naming:** `what_it_tests_under_which_condition_what_it_expects` — on failure it is clear what broke.
+- **Red-green:** first a failing test, then the implementation.
+
+## Watch out
+- **Flaky = bug:** an occasionally failing test is not tolerated; it is fixed at the root.
+- In snapshot/golden-file tests, avoid needless brittleness (assert only the meaningful output).
+
+## Tests that cannot fail
+
+Green is evidence only if the test could have gone red. Shapes that check nothing:
+- **Assertion restates the code:** it recomputes the implementation's own expression, so it moves with every change.
+- **Setup guarantees the result:** arrange plants the value the assert reads back; it holds even if the act never ran.
+- **Expected value derived the way the code derives it:** same formula, query or parser — the same wrong assumption on
+  both sides still matches.
+- **A double asserted against its own stub:** the fake is told to return X and the test asserts X; only the fake runs.
+- **No assertion:** it passes because nothing threw. If *not throwing* is the behavior under test, assert that.
+
+**Prove it can fail:** break what the test covers — invert a condition, return a wrong constant — confirm it goes red,
+then restore. Still green means the test is documentation, not a gate: fix it or delete it, never count it as coverage.
+
+## Flaky triage
+An intermittent failure gets exactly one outcome, decided the day it is seen: **fix** it, **quarantine** it (out of
+the gating lane, never out of the suite, with an owner and a date), or **escalate** it as the product defect it
+signals. Infrastructure flakes may get a bounded, logged retry; product flakes never do. Classifying them, the retry
+rule, and what a quarantine entry must carry: **`references/flaky-triage.md`**.
+
+## DoD (this skill's contribution)
+- The project's own test command is green — read it off the manifest/CI (`dotnet test` · `npm test` · `pytest` ·
+  `go test ./...`), don't assume one; critical paths are covered; no empty/meaningless tests.

package/kit/skills/testing/references/flaky-triage.md

@@ -0,0 +1,51 @@
+# Flaky test triage
+
+Loaded on demand — SKILL.md holds the rule (`Flaky = bug`); this is the decision procedure for one that has already
+failed intermittently. A test that passes and fails on the same commit gates nothing, and every red run it produces
+teaches the team to ignore red runs. Triage it the day it is seen and record the outcome.
+
+## 1 · Classify first: infrastructure or product
+The two kinds get opposite treatment, so this call comes before the outcome.
+
+- **Infrastructure flake** — fails the same way regardless of the test's logic, and clusters in time. Signals:
+  identical error text across unrelated tests (connection refused, image pull, no disk, name resolution); a whole
+  run or one machine fails and the next run passes with no code change; the assertion is never reached.
+- **Product flake** — follows the data or the ordering. Signals: it tracks one case, fixture or seed; it appears
+  only under randomized order or parallel execution; it reproduces in a loop on one machine; the assertion *is*
+  reached and the value is wrong.
+- Cannot tell yet → treat it as a product flake. Guessing "infrastructure" is how a real race gets a retry put
+  around it.
+
+## 2 · Retry policy follows that classification
+- **Infrastructure: a bounded retry is allowed** — a fixed cap decided once and written down, applied where the
+  resource is owned (readiness wait, fixture setup, the job step), never around an assertion. Log every retry that
+  fires: a retry nobody can see is a failure nobody counts, and a rising count means the label was wrong.
+- **Product: never retry.** A retry there turns a real bug into a slower green — the defect ships and the suite
+  reports success. Widening a timeout and sleeping until it passes are the same move under another name.
+
+## 3 · Three outcomes — pick exactly one, in writing
+| Outcome | Use when | What it requires |
+|---|---|---|
+| **Fix** | the test or the code under it is genuinely wrong: unfrozen clock, unseeded randomness, shared state, order dependence, an assertion on something unordered | the change, plus a run that reproduced the old failure (loop, shuffle, parallel) and now holds |
+| **Quarantine** | the failure is real but not yet understood, and blocking every other change on it costs more than the coverage it holds | a named owner, a date, a linked issue — and the test still executing |
+| **Escalate** | the flake is a symptom, not a test defect: a race, a leak, a resource limit, an unsafe ordering in the code under test | hand it over as a product defect and root-cause it (`systematic-debugging`) |
+
+Escalate means the change lands in product code. Rewriting the test to step around the race deletes the only
+evidence that the race exists, and it resurfaces in production instead of in CI.
+
+## 4 · Quarantine has a shape, or it is deletion
+- **Scoped, not removed.** The test leaves the *gating* lane, not the suite: it keeps running in a non-gating or
+  scheduled job, so its failure rate stays visible and the fix can be proven.
+- **Owner and date, always** — both stored next to the test (marker, tag, or an explicit list the gating job filters
+  on) and re-read on that date. If nobody will own it and no date fits, the honest outcome was Fix or Escalate.
+- **Re-decide on the date**, choosing again from the three. A quarantined test nobody returns to is worse than a
+  deleted one: it reports coverage that is not being checked.
+- Deleting the test deliberately, with the reason recorded, is a legitimate end state. Silent expiry is not.
+- Quarantine is not a way to go green for a release; an escalate-class flake blocks the release it belongs to.
+
+## Boundary with the rest of the discipline
+- Disabling or skipping a red test to finish a task is masking, not quarantine: masking removes the signal,
+  quarantine relocates it and puts a date on it.
+- Making an intermittent failure reproduce on demand — loop the case, randomize order, add stress, widen the timing
+  window — is `systematic-debugging/references/techniques.md`. Triage without a repro is a guess.
+- The quarantine list is a debt list. If it only grows, nothing is being fixed: report the count and the oldest entry.

package/kit/skills/threat-model/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: threat-model
+description: |
+  Scope a security audit BEFORE scanning, to cut false positives: map assets, entry points, trust boundaries
+  and 5-8 domain-specific attack classes into a parseable THREAT_MODEL.md. A threat survives a patch; a
+  vulnerability is only evidence for one. Feeds security-scan.
+---
+
+# Threat Model
+
+<!-- routing-eval reads the next line; why it sits in the body: AGENT_TEMPLATE.md -->
+Trigger phrases: "threat model", "attack surface", "scope the audit", "trust boundary"
+
+Scope first, scan second. A security scan with no map produces noise; a threat model tells the scanner (and
+`security-scan`) **where to look and what matters** — the single biggest lever on false positives.
+
+The one idea to keep — the litmus test: **if patching one line of code makes an entry disappear, it was a
+vulnerability, not a threat.** Threats survive patching (they name *what an attacker wants and the surface they
+arrive through*); a vulnerability is only **evidence** that raises a threat's likelihood.
+
+> **Crewforth adaptation (local, .claude/):** `crew-security-expert` runs this to scope before `security-scan`. Output
+> `docs/THREAT_MODEL.md` is internal (§4.3). Stack-agnostic. §4 Prohibitions apply.
+
+## When
+- Before a first `security-scan` of a system, or when scan output is noisy / unscoped.
+- After a significant new surface — a new API, a new integration, a new trust boundary.
+
+## Two modes
+- **interview** — the owner is available: ask the four questions below, one at a time.
+- **bootstrap** — no owner: derive the model from code + past advisories, then flag what only the owner can confirm.
+
+## Method — the four questions (Shostack), one at a time
+Never dump a questionnaire; ask, capture into the schema, move on. Mirror the user's language.
+1. **What are we building?** system context, assets worth protecting, entry points and trust boundaries.
+2. **What can go wrong?** open-ended first; then, per entry point, fall back to **STRIDE**; derive **5-8
+   domain-specific attack classes** at the right granularity — "IDOR on dataset rows", "integer overflow on
+   length fields" — not "web vulnerabilities".
+3. **What are we doing about it?** impact · residual likelihood · status · controls per threat; "accept the
+   risk, with a written reason" (`risk_accepted`) is a valid answer.
+4. **Did we do a good job?** read the ranked table back; coverage-check that every entry point appears.
+
+Tag every fact **`[Code-verified]`** or **`[Owner-states]`**; each owner claim that moves a score becomes an
+open question with a "Verify by:" note.
+
+## Output
+Write `docs/THREAT_MODEL.md` to the parseable contract in **`references/schema.md`** (fixed sections; a threats
+table with enumerated columns; residual-likelihood scoring; class-level mitigations). The interview flow, the
+STRIDE table, and the bootstrap steps live in **`references/interview.md`**.
+
+## Principles
+- **Evidence raises likelihood; it is not the threat.** Score the *residual* likelihood after current controls;
+  a stated-but-unverified control does not lower it — it becomes an open question.
+- **Prefer a control that survives the next bug** over a patch for the last one (class-level mitigations).
+- **Feeds forward:** `security-scan` reads `THREAT_MODEL.md` to scope its fronts and bias severity.
+
+## DoD
+- `docs/THREAT_MODEL.md` exists; every entry point covered; each threat scored; provenance tagged; scope handed to `security-scan`.

package/kit/skills/threat-model/references/interview.md

@@ -0,0 +1,51 @@
+# Threat-model interview + bootstrap
+
+## Interview mode — Shostack four questions, ONE at a time
+Never present a questionnaire. Ask, capture into the schema, move on. Mirror the user's language.
+
+### 1 · What are we building?
+System context, assets, entry points, trust boundaries. Draw the boundary explicitly: *"untrusted input crosses
+into trusted code HERE."* List every entry point — this becomes section 3 and the coverage checklist.
+
+### 2 · What can go wrong?
+Open-ended first ("what would hurt most if it broke?"). Then, per entry point with nothing yet, walk **STRIDE**:
+
+| STRIDE | asks |
+|---|---|
+| **S**poofing | can someone pretend to be another principal? |
+| **T**ampering | can data / requests be modified in transit or at rest? |
+| **R**epudiation | can an action be denied, or does it go unlogged? |
+| **I**nformation disclosure | can data leak across a trust boundary? |
+| **D**enial of service | can availability be exhausted (beyond plain volumetric floods)? |
+| **E**levation of privilege | can a lower role reach a higher-privilege action? |
+
+Derive **5-8 domain-specific attack classes** at the right granularity — "IDOR on dataset rows", "integer
+overflow on length fields", "tenant bleed via a missing scope check" — **not** "web vulnerabilities". Granularity
+test: a class should name *a surface + a mechanism*, so the scanner knows exactly what to grep for.
+
+### 3 · What are we doing about it?
+For each threat: `impact`, residual `likelihood`, `status`, `controls`. "Accept the risk, with a written reason"
+(`risk_accepted`) is a legitimate status — record the reason verbatim in section 6.
+
+### 4 · Did we do a good job?
+Read the ranked table back to the owner. **Coverage check:** every entry point from Q1 appears in ≥1 threat's
+`surface`. Add anything missing before you emit.
+
+**Provenance discipline:** tag every fact **`[Code-verified]`** (you read it) or **`[Owner-states]`** (they said
+it). Every owner claim that changes a score becomes an open question in section 6 with **"Verify by: <how>."**
+
+## Bootstrap mode — no owner available
+1. **Map** (in parallel where the codebase is large): docs, the entry-point surface, infra / IAM, the assets,
+   and past advisories — `git log --all -i --grep=<stack keywords>`, `gh api repos/<o>/<r>/security-advisories`.
+2. **Generalize** each past vulnerability into a *threat*: cluster by `(entry point, bug class, asset reached)`.
+   Run a **variant scan** — grep for siblings of each vulnerable pattern — to estimate how much of the surface
+   shares it (more siblings → higher likelihood; sibling locations become **scan leads, not evidence**).
+3. **Gap-fill with STRIDE** for every entry point that still has no threat ("past vulnerabilities are biased
+   toward what has already been found"). Invariant: the final table must contain **≥1 threat with empty
+   evidence**, or the gap-fill step did not actually run.
+4. **Flag** every scored owner-would-know claim as an open question, so a later 10-minute interview closes it.
+
+## Handing scope to security-scan
+`security-scan` reads `docs/THREAT_MODEL.md`: section 3 (entry points) and section 5 (attack classes) become its
+focus areas; the threat `impact`/`likelihood` bias which findings it treats as high severity. No threat model →
+`security-scan` falls back to its own Front 0 discovery.

package/kit/skills/threat-model/references/schema.md

@@ -0,0 +1,42 @@
+# THREAT_MODEL.md — parseable contract
+
+A **map, not a bug list.** Fixed sections in this order so `security-scan` and a reviewer can parse it.
+
+## Sections
+1. **System** — one paragraph: what it does, who uses it, where it runs.
+2. **Assets** — what is worth protecting (data · money · availability · reputation/trust), each with a *why*.
+3. **Entry points & trust boundaries** — every place untrusted input crosses into more-trusted code
+   (route · API · form · file upload · CLI arg · queue message · webhook · IAM/role boundary). This is the surface.
+4. **Threats** — the ranked table (below).
+5. **Attack classes** — the 5-8 domain-specific classes derived, each mapped to the entry points it applies to.
+6. **Open questions** — owner claims still to verify, each with a "Verify by: <how>".
+7. **Mitigations** — class-level controls (table below).
+8. **Coverage** — assert every section-3 entry point appears in ≥1 threat's `surface`.
+
+## Threats table
+Pipe-separated columns:
+
+`id | threat | actor | surface | asset | impact | likelihood | status | controls | evidence`
+
+Enumerated value sets (keep parseable):
+- **actor** ∈ `external-anon · external-auth · insider · supply-chain · operator · automated · physical`
+- **impact** ∈ `low · moderate · high · severe · existential`
+- **likelihood** ∈ `very_rare · rare · possible · likely · almost_certain`
+- **status** ∈ `unmitigated · partial · mitigated · risk_accepted`
+
+Rules:
+- Sort by `(impact, likelihood)` descending — worst first.
+- **`evidence` raises `likelihood`; it is not the threat.** A row may have empty evidence (a threat with no
+  found vulnerability yet is still real). Score the **residual** likelihood *after* current `controls`.
+- `risk_accepted` requires a reason recorded verbatim in section 6.
+
+## Scoring guide
+| axis | how to score |
+|---|---|
+| **impact** | realistic worst case for *this* asset. `low`=cosmetic · `moderate`=recoverable loss · `high`=serious breach/outage · `severe`=major data/financial loss · `existential`=business-ending. |
+| **likelihood** | *after* current controls (residual). A control the owner *states* but that is not code-verified does **not** lower it — record it as an open question instead. |
+
+## Mitigations table
+`mitigation | threat_ids | closes_class (yes/no) | effort`
+
+Prefer a control that **closes a whole class** (`closes_class = yes`) over a one-line patch for the last bug.

package/kit/skills/token-budget/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: token-budget
+description: |
+  Context/token discipline: subagent isolation, output = summary, move-to-file, delegation threshold, lean skills.
+---
+
+# Token & Context Discipline
+
+<!-- routing-eval reads the next line; why it sits in the body: AGENT_TEMPLATE.md -->
+Trigger phrases: "token budget", "token cost", "context window", "context management", "context is full", "clear context", "running out of context"
+
+A subagent exists for context management: it runs in its own window and returns **only its summary**
+to the main thread — intermediate noise (file reads, searches, logs) never enters the main context.
+
+**Warning — measured, not guessed.** Each subagent re-pays its **full context from scratch**: in a real
+transcript the first turn was `cache_read=0`, every token `cache_creation` — nothing is shared with the main
+thread's cache. A **no-op** subagent (task = "reply DONE") already cost **~10k tokens with restricted tools and
+~16k with full tool access**; that floor is base system prompt + tool schemas, paid fresh every time. Of the
+always-on material only the **skill listing (~2.5–3k tokens) is inherited** by a subagent — the discipline
+(`DISCIPLINE.md`/CLAUDE.md) and the agent descriptions are **not** injected into it. So a delegation is worth it
+for **isolation / parallelism / a clean window**, or when the isolated work would otherwise cost the main thread
+**more than that ~10–16k floor** — never by default.
+
+## Rules
+1. **Output = summary.** The agent returns a short, structured summary to the main thread; it does **not** return raw logs / file dumps / long code.
+2. **Move to a file.** Heavy output (a plan, scan report, inventory) is written to `docs/*.md`; a **summary + pointer** comes back. (local, in gitignore)
+3. **Delegation threshold.** Noisy/heavy work (reading many files, scanning, research) → subagent. A single tool-call / small work → **main thread**. Concretely: if the isolated work won't save the main thread more than the **~10–16k fresh-context floor** a subagent costs, keep it on the main thread — delegate for isolation, not to shave a few reads.
+4. **A RESUMED agent re-pays its GROWN context, not its floor.** Continuing an agent that already ran keeps its
+   whole history, so the next turn starts from wherever it got to. Measured across four turns of one agent:
+   167k → 187k → 207k → **211k tokens**, and that last turn was a single word of seed text. The floor in rule 3
+   is the cost of a FRESH agent; a long-running one passes it many times over. Continue it for the context it
+   holds — a running verification, a migration it is mid-way through — and open a fresh one, or stay on the main
+   thread, for a small correction that does not need any of that history.
+5. **Built-in agents are on this budget too.** `Explore`, `general-purpose` and the rest cost exactly what a Crewforth
+   agent costs; one repo-mapping `Explore` measured 520 s and ~150k tokens. Crewforth owns no search agent, so
+   reaching for a built-in is correct — just size the request the way rule 3 sizes any other delegation.
+6. **Least tooling.** An agent holds only the tools it needs; extras accidentally pollute the context + burn the limit.
+7. **Lean SKILL.md.** Skills load into the main context; heavy reference goes to a separate file, only when needed.
+8. **Targeted reading.** Instead of reading a whole file, pinpoint with Grep/Glob.
+9. **Measure fill, don't guess.** `bash .claude/hooks/context-usage.sh` reads it from the transcript; crew-session-manager recommends continue or handoff+clear; the user runs `/clear` at a phase boundary.
+10. **Bound what a command hands back.** All of the rules above govern the context's own footprint; none of them
+   govern what a single `Bash` call dumps into it. A `find` over a monorepo, an unfiltered log, a full test run —
+   each returns everything to the main thread whether or not any of it is read. Ask for the answer, not the
+   corpus: `grep -c` over `grep`, `| tail -20` over the whole file, `--quiet`/`--porcelain` where the tool has
+   one, and a redirect to a file plus a pointer when the output is genuinely needed later (rule 2).
+11. **Cut what nothing reaches — with evidence, not a hunch.** Every installed skill spends its name and
+   description in EVERY session, forever. `bash .claude/eval/utilization.sh` reports which skills actually fired
+   in this project's transcripts and how many bytes the cold ones cost, which is the list `doctor.sh` §4a's
+   `skillOverrides: name-only` advice needs and never had. Read it as evidence, not a verdict: a skill that only
+   fires during an incident is doing its job by existing. `--all-projects` widens the scope; by default it reads
+   this project only and prints names and counts, never paths or content.