workflow-toolkit 1.0.1

package/docs/toolkit/guidelines/WORKFLOW-MEMORY.md

@@ -0,0 +1,73 @@
+# Workflow Memory
+
+**Read when:** starting any task in a multi-task feature.
+
+**Why this exists:** Atomic slices make review cheap and ramp-up expensive: every task is a fresh
+agent that rebuilds the system from zero, then throws that reasoning away. Shared memory is how
+constraints survive the boundary without becoming a second spec.
+
+## The two files
+
+Both live at `.specs/features/<feature>/memory/`.
+
+| File | Scope | Owner |
+| --- | --- | --- |
+| `MEMORY.md` | Durable, cross-task | Every task promotes into it |
+| `task_NN.md` | Local, operational | The task that is running |
+
+## Timing
+
+**Read both before the first code edit. Update before any completion claim or commit.**
+
+That order is the whole mechanism. Memory read after implementation has already failed to prevent the
+rediscovery it exists to prevent.
+
+## What goes in shared memory
+
+A constraint, decision or risk earns promotion only when all three are true:
+
+1. Another task needs it to avoid a mistake or a rediscovery.
+2. It is durable across runs, not just this execution.
+3. It is **not** already obvious from the spec, the task file, or the repository.
+
+If any answer is no, it stays in task memory.
+
+Belongs in `MEMORY.md`:
+
+- A constraint discovered during implementation that affects later tasks — "the repository serializes
+  writes per region; batch inserts must chunk by region"
+- A cross-cutting decision made while coding, not at design time — "chose a discriminated union over
+  a status enum because the public contract rejects bare strings"
+- An open risk later tasks must account for — "the onboarding migration assumes the accounts backfill
+  has run; it has not in this checkout"
+
+Belongs in `task_NN.md`:
+
+- Files touched during this task
+- Debugging steps taken to resolve a task-specific failure
+- This task's objective and acceptance-criteria snapshot
+- A workaround scoped to this task only
+
+## Hard rules
+
+- **Never invent history**, decisions, or status that did not happen.
+- **Never copy** code blocks, stack traces, or spec text into memory. Reference them by path.
+- **Never duplicate** what the repository, the diff, the task file or the spec already says.
+- **Never read another task's memory file** unless `MEMORY.md` points at it.
+- When memory conflicts with the repository, **the repository wins** — then correct the memory file.
+
+## Compaction
+
+When a file grows noisy, compact it in place. Shared memory first, then task memory — the shared file
+sets the context the task file must not duplicate.
+
+- **Keep:** current state, durable decisions, reusable learnings, open risks, handoff notes.
+- **Cut:** repetition, stale notes, command transcripts, anything derivable from the repo or spec.
+- **Rewrite** what remains as short factual bullets. Never a chronological log.
+
+## Lifecycle
+
+Memory is scratch. It lives and dies with the feature branch and is not a durable artifact — see
+`.agents/skills/wtk/references/artifacts.md`. Anything that must outlive the feature is promoted to a real
+home before the pull request: a project decision to `.specs/STATE.md` as `AD-NNN`, a durable lesson to
+the lessons layer, a product promise to `docs/qa/scenarios/`.

package/docs/toolkit/guidelines.md

@@ -0,0 +1,50 @@
+# Guidelines
+
+Shared execution contracts live in `.agents/skills/wtk/references/`; the remaining surface-specific
+guidelines stay in `docs/toolkit/guidelines/`. Each is loaded by its condition. `AGENTS.md` and `wtk`
+dispatch to the owner; this page is the catalog, not a second copy of the rules.
+
+## Instruction cost
+
+| File | Why it exists |
+| --- | --- |
+| [CONTEXT-BUDGET.md](guidelines/CONTEXT-BUDGET.md) | Instruction files load into prompts. A previous arrangement dumped more than a thousand mandatory lines before any task. Growing a file with restated prose is a defect. Dispatch by condition. |
+
+## How work is cut and kept
+
+| File | Why it exists |
+| --- | --- |
+| [git.md](../../.agents/skills/wtk/references/git.md) | `type/slug` names the behaviour, never `main`, delete after merge. Isolated checkouts must not share a runtime. |
+| [artifacts.md](../../.agents/skills/wtk/references/artifacts.md) | Planning artifacts are finished when the code exists. Durable store is code, `AD-NNN`, `docs/qa/`, product/architecture/design. The inverted arrangement gated drift on documents nobody read. |
+| [WORKFLOW-MEMORY.md](guidelines/WORKFLOW-MEMORY.md) | Small slices are cheap to review and expensive to ramp. Shared memory is how reasoning survives the task boundary without becoming a second spec. |
+| [validation.md](../../.agents/skills/wtk/references/validation.md) | Proportional scoped gates; full gate only when selected. It also owns the credential-free declarative agent-tool configuration path. Never skip a test to go green. Cached evidence only for the exact tree. |
+
+## Proof
+
+| File | Why it exists |
+| --- | --- |
+| [test-contract.md](../../.agents/skills/wtk/references/test-contract.md) | “All branches covered” cannot be audited. `UT-001` assigned to one task can. Cases come from the spec; tests assert the contracted outcome. Coverage-only tests are forbidden. |
+| [evidence.md](../../.agents/skills/wtk/references/evidence.md) | Completion without a fresh command is a false report. Scope binds. Secrets in a diff are an absolute stop. |
+| [REVIEW-ROUNDS.md](guidelines/REVIEW-ROUNDS.md) | See [reviews.md](reviews.md). Caps, monotonic findings, filed issues. |
+| [SECURITY.md](guidelines/SECURITY.md) | Security that lives only in a review at the end is theatre. Eleven surfaces, declared at Specify, become `SEC-` cases. Review looks for what the table missed. The lock icon on this filename is an editor convention, not extra secrecy. |
+
+## Surfaces people meet
+
+| File | Why it exists |
+| --- | --- |
+| [UI-UX.md](guidelines/UI-UX.md) | Internals designed first get redesigned when the screen moves. `uiux.md` enumerates states so a design agent can execute, and so QA knows the feature is UI-bearing. |
+| [DX.md](guidelines/DX.md) | Same idea one layer down: routes, config, CLI, exports — written as if already shipped, failures enumerated, then internals serve that contract. |
+| [FRONTEND.md](guidelines/FRONTEND.md) | Feature folders own capability; shared UI owns reuse. Routes compose, they do not draw layout. Keeps front-end organization portable (no framework names). |
+| [MODELING.md](guidelines/MODELING.md) | The domain must outlive the web, API, and persistence frameworks. One aggregate, one module; invariants in the transition, not only in SQL. |
+| [QA-SCENARIOS.md](guidelines/QA-SCENARIOS.md) | Feature verification dies with the feature. A scenario holds a verdict that survives, and goes stale when a diff invalidates it. Content-addressed ids so parallel branches do not collide. |
+| [QA-EXECUTION.md](guidelines/QA-EXECUTION.md) | A green automated suite can still fail its user. Persona, independent confirmation, dated report. Auto-fix only when the change is contained, unambiguous, and regression-tested. |
+
+## Durable understanding
+
+| File | Why it exists |
+| --- | --- |
+| [KNOWLEDGE-WIKI.md](guidelines/KNOWLEDGE-WIKI.md) | Source documents cannot see each other. The wiki holds the graph and the contradictions. Source always wins. Harvest is explicit and per finished feature, never part of `make check`. |
+
+## How to add a guideline
+
+Do not. Extend an existing file, or justify why both must exist, in [CONTEXT-BUDGET.md](guidelines/CONTEXT-BUDGET.md). A rule earns lines by preventing a defect that occurred, or by resolving an ambiguity an agent actually hit.

package/docs/toolkit/loop.md

@@ -0,0 +1,77 @@
+# The loop
+
+`wtk` routes discovery, integrated Lean, and distinct modular entries. Auto-size still holds:
+a one-line change gets no feature artifacts; a multi-component feature gets full planning.
+
+Workflow work starts with `ponytail` at `full`; `AGENTS.md` carries the activation and session
+persistence rule, while the [Ponytail skill](../../.agents/skills/ponytail/SKILL.md) owns its
+explicit stop commands. The same instinct as “delete rather than bridge” and “no test without an
+invariant”.
+
+Public hierarchy: `Feature -> Slice -> Check`. Resolve cadence with `wtk-config` before dispatch.
+
+## Stages
+
+Walk these in order. The imperative detail lives in `AGENTS.md` and the guideline named in the
+last column.
+
+| # | Stage | What it is for | Skip when | Rule |
+| --- | --- | --- | --- | --- |
+| 1 | **Plan / Checks** | Freeze `plan.md`, `checks.md`, and proof selectors | Auto-sized skip (tiny, obvious change) | `wtk-lean` |
+| 2 | **Slice** | One observable behaviour plus the checks that prove it | — | `AGENTS.md` |
+| 3 | **Build** | The cheapest code that makes the slice true | — | `ponytail` |
+| 4 | **Scoped gate** | Prove *this* diff, not the whole product | Escalate if the selector cannot scope it | [validation.md](../../.agents/skills/wtk/references/validation.md) |
+| 5 | **Atomic commit** | One Conventional Commit after the applicable Lean check state is current | — | `AGENTS.md` |
+| 6 | **Technical Verifier** | One fresh independent pass proves every check over the complete feature range; mutants must die at the approved profile | Filed-issue path; no product code in final QA session | [REVIEW-ROUNDS.md](guidelines/REVIEW-ROUNDS.md) |
+| 7 | **Deep-review** | Correct, safe, maintainable — resolved groups, blocking findings only | Cadence `skip` (no groups; human runs `wtk-deep-review` later), or proportional classifier selects scoped validation | [REVIEW-ROUNDS.md](guidelines/REVIEW-ROUNDS.md) |
+| 8 | **QA session** | The finished feature, as a person meets it: one `wtk-qa-plan` and one `wtk-qa-execute` packet | Feature has no public, UI, API, CLI, or adoption change | [QA-EXECUTION.md](guidelines/QA-EXECUTION.md) |
+| 9 | **Full gate** | The product gate, once, when the proportional classifier selects it | Scoped gate is sufficient | [validation.md](../../.agents/skills/wtk/references/validation.md) |
+| 10 | **Remote delivery** | `wtk-ship` authorizes the feature-branch push, one pull request, and merge after readiness is rechecked | Readiness is evidence, not authorization for deploy/release, production mutations, force-push, direct `main` push, and unrelated remote actions; those need explicit instruction | [evidence.md](../../.agents/skills/wtk/references/evidence.md) |
+
+The feature-closing step is the QA session when the proportional classifier selects a public walk;
+no slice runs QA. Implementation slices remain vertical and independently committed; the Technical Verifier reads the
+complete feature after implementation; wtk-deep-review follows resolved
+groups when selected, then QA and the full/scoped gate follow the route rather than file count or feature wording.
+
+The selected route records its gate and limitation in the handoff.
+
+## Why slices, not “the whole feature”
+
+Review cost explodes with diff size. Every round re-reads the whole change; every fix moves what
+the next round reads. Three rounds over one behaviour is a signal about that behaviour. Twenty
+over a finished feature is the size talking.
+
+One pull request still. The slice is how much each reading has to hold.
+
+A slice that is not observable or not complete is not a slice. Tests are never a separate task.
+e2e is only for a journey nothing else already walks; a second slice in the same journey proves
+itself at integration.
+
+## Work classes
+
+| Work | Path |
+| --- | --- |
+| **Feature** — a capability the product lacks | The full table above |
+| **Direct correction** — one exact, unambiguous invariant | The narrowest applicable check in [validation.md](../../.agents/skills/wtk/references/validation.md) |
+| **Filed issue** — already reviewed, then parked | `implement → scoped gate → one commit` |
+| **Credential-free declarative agent-tool configuration** | The local light path in [validation.md](../../.agents/skills/wtk/references/validation.md) |
+
+A defect nobody filed is a feature at auto-sized depth. A “one-line fix” that opens a schema or a
+design question stopped being a filed issue; say so and take the feature path.
+
+## Seven rules that hold at every size
+
+Copied as orientation; `AGENTS.md` is canonical:
+
+1. The gate decides done, not self-assessment.
+2. One atomic commit per task.
+3. The Verifier is a different actor than the author.
+4. A round contains only findings not already raised.
+5. Only Critical and Major trigger a remediation check.
+6. Stages never loop into each other; review caps and post-fix escalation follow `REVIEW-ROUNDS.md`.
+7. Every count or measurement cites the command that produced it.
+
+## Isolated checkouts
+
+If the project isolates checkouts, each owns its runtime. Never `reuseExistingServer: true` across
+siblings — a gate in one checkout must not silently test another’s application.

package/docs/toolkit/purpose.md

@@ -0,0 +1,51 @@
+# Purpose
+
+This workflow exists to **keep shipping without pretending the product is safer than it is**.
+
+Two failure modes showed up in the same kind of work:
+
+- **Delivery without a floor.** A green linter, a coverage number, a paraphrase of the spec. The
+  feature merges. Users hit a journey nobody walked. Security is “we thought about it”.
+- **Reliability without an end.** Every nitpick is remediating in the same iteration. Each fix
+  changes the diff. The next round finds new nits. Thirty rounds is not thoroughness; it is a loop
+  that cannot converge.
+
+The pack is the floor plus the end condition.
+
+## What “balance” means here
+
+**Delivery** is: a change small enough to implement by vertical slice, a gate cheap enough to run
+per slice, one fresh independent Verifier over the complete feature, review cadence selected by
+wtk-config, and merge authority that stays with the human.
+
+**Reliability** is: tests derived from acceptance criteria, security surfaces named and given
+`SEC-` cases, one Verifier that is not the author over the complete feature, a persona walk for
+anything a user can see when the classifier selects it, and a full gate once when the classifier selects it.
+
+Neither side is optional for features. A feature that skips the final Verifier is not this
+workflow; neither is one that re-reviews Trivials until the diff stops moving. Credential-free
+declarative agent-tool configuration is a separate maintenance path defined by
+[`validation.md`](../../.agents/skills/wtk/references/validation.md).
+
+## What the caps buy
+
+| Cap | Protects |
+| --- | --- |
+| One fresh full-feature Verifier | Stops self-certified or incomplete proof from reaching delivery |
+| Deep-review once, remediation check per batch, Critical/Major only | Stops nitpick churn from being called “quality” |
+| Stages do not loop into each other | Review groups bound repeated reading, then a human |
+| Proportional gate selection | Stops low-risk maintenance from paying for unrelated product checks |
+| Approval is local-only | Stops an agent from pushing, merging, or deploying on a spec yes |
+
+Escalate is a result after the required post-cap remediation and gate. Shipping past a cap with a
+reproducible blocker is not.
+
+The review ledger counts failed remediation cumulatively per immutable finding fingerprint while
+the live remediation bound counts consecutive stalls; see
+[`REVIEW-ROUNDS.md`](guidelines/REVIEW-ROUNDS.md) for the accounting rule.
+
+## What this pack is not
+
+It is not a product, a stack, or a starter app. The consuming project fills one paragraph in
+`AGENTS.md` and owns `make check`. Reliability rules here are process: they do not name a
+framework.

package/docs/toolkit/repository-intelligence.md

@@ -0,0 +1,53 @@
+# Repository intelligence
+
+Graphify and Graft are standard development tools, not application dependencies. Specs and current
+checkout source remain authoritative; generated context is bounded evidence.
+
+## Routing
+
+1. Existing file, symbol, API, caller, and callee pointers: retrieve nothing.
+2. Architectural trigger (module or domain boundary, responsibility transfer, shared abstraction,
+   central flow, or unresolved architectural risk): query Graphify first.
+3. Unknown implementation location or call relationship: query Graft before broad native search.
+4. Exact-text question: use exact native search.
+
+Graphify output can feed a bounded Graft query. Deep Review always prepares fresh Graft context when
+selected; it prepares one Graphify context only for an explicit architectural question. It does not
+run Graphify for local review work.
+
+## Setup and freshness
+
+The installer reports remediation but does not execute package managers:
+
+```bash
+npm install --save-dev --save-exact @nanonets/graft@0.10.1
+uv tool install graphifyy==0.9.14
+python3 .agents/skills/wtk-config/scripts/repository_intelligence.py \
+  graphify-setup --root . --backend <backend> --mode deep
+```
+
+Semantic Graphify extraction requires an explicit backend. Setup discloses the backend, source root,
+indexed file count, and ignored roots before extraction; credentials stay environment-owned.
+
+Queries validate the exact supported version, active checkout, indexed-source manifest, and current
+working-tree fingerprint. Tool-native refresh runs before a result is returned. Missing, failed,
+stale, partial, insufficient, interrupted, or incompatible state reports one degraded reason and
+continues through targeted native inspection. It never silently presents stale context as ready.
+
+Generated graphs, caches, backend metadata, and benchmark scratch records stay checkout-local and
+ignored under `graft/`, `graphify-out/`, and `.repository-intelligence/`. They never become runtime
+dependencies or committed product artifacts.
+
+## Retention pilot
+
+Record one JSONL event per controlled terminal task in ignored
+`.repository-intelligence/benchmark.jsonl`. Each record carries task ID and category, configuration
+(`baseline`, `graft`, or `routed`), repository snapshot, prompt and acceptance hashes, provider,
+model, effort, input/output/total tokens, repository-intelligence and native-search calls, files read,
+wall-clock time, gate result, Verifier result, review findings, rework count, and terminal outcome.
+
+Compare baseline→Graft and Graft→routed runs only when snapshot, prompt, provider, model, effort, and
+acceptance contract match. A report requires 10–20 distinct terminal tasks, groups comparisons by
+category, and rejects missing controls or independent gate/Verifier evidence. The result is
+directional, not statistically conclusive. Removing routing requires a later explicit project
+decision covering provisioning, configuration, generated state, and QA promises together.

package/docs/toolkit/reviews.md

@@ -0,0 +1,77 @@
+# Reviews
+
+Review is how reliability gets a **second reader** without getting an infinite loop.
+
+An unbounded loop was measured at 30 rounds on one feature. The rule that caused it sounded
+responsible: remediate every confirmed finding **and every nitpick** in the same iteration. Each
+nit changes the diff; the next round finds new nits. The loop is unbounded by construction.
+
+[REVIEW-ROUNDS.md](guidelines/REVIEW-ROUNDS.md) is the protocol. This page is the choice.
+
+The public hierarchy is `Feature -> Slice -> Check`. Before dispatch, read
+`.agents/skills/wtk-config/SKILL.md`; it resolves the feature's review groups.
+
+## One Verifier role, several phases
+
+The provider `verifier` executes one phase per packet. Deep-review is a separate stage, not a Verifier phase.
+Remediation identity, independent counters, and halt behavior follow `REVIEW-ROUNDS.md`; the fingerprint is requirement + root cause + failure path.
+
+| Reviewer | Question only it can answer | Cap |
+| --- | --- | --- |
+| **Technical Verifier** (feature close) | Does one fresh independent pass prove every check over the complete feature range? | One full-feature pass after the last code-changing slice |
+| **Deep-review** (resolved groups; none under cadence `skip`) | Is the code correct, safe, maintainable? | Discovery once; remediation checks until no Critical/Major is open or `stall_attempts` halts |
+| **QA session** (feature closing step when the public surface changes) | Does the finished feature feel right, through the declared adapter? | One `wtk-qa-plan` and one `wtk-qa-execute` session; no slice runs QA |
+
+A documentation-only slice follows the proportional classifier in [validation.md](../../.agents/skills/wtk/references/validation.md):
+accuracy and affected-link checks close pure maintenance, while mixed changes run canonical tests for
+changed executable behavior. Deep-review and QA require named concrete risk or changed public promise;
+file count and the word "feature" do not escalate them.
+
+Technical Verifier reads the integrated final tree over the complete feature range. Deep-review reads the integrated
+commit range, and the closing session's fresh QA Plan/Execute packets read the integrated final tree. The coordinator records
+distinct author and proof identities; the last implementer supplies a handoff and never certifies
+the integrated result.
+
+They do not send work back to each other. A wtk-deep-review finding never restarts the Verifier. A
+Critical/Major finding is fixed under the approved loop and its scoped gate, then proven by a one-job
+remediation check (incremental wtk-deep-review); batch and check repeat until none is open or
+`stall_attempts` halts. Remediation follows the stall bound: each attempt runs the scoped gate, a smaller failing
+test set resets the counter, and an equal-size or larger set increments it. An unavailable gate
+halts immediately; a reached nonzero threshold halts with the normalized signature, attempt count,
+and fixes tried. If a wtk-deep-review fix changes user-visible behaviour, re-walk **the affected scenario
+rows only**.
+
+## What blocks, what files
+
+| Severity | Remediation check? | Feature delivery |
+| --- | --- | --- |
+| `Critical` | Yes | Fix now |
+| `Major` | Yes | Fix now |
+| `Minor` | No | Fix in one current-run batch, scoped gate, one commit |
+| `Trivial` | No | File an issue |
+
+Every wtk-deep-review defect is fixed inside the feature run. Minor fixes start no new proof round.
+Filed Trivial issues are real backlog, not a disposal bin; they do **not** re-enter Verifier + QA +
+wtk-deep-review because that ceremony already happened.
+
+A user-visible fix still flags and walks its scenario. A fix that grows into a design or schema
+change is a feature.
+
+## Why the Verifier is not the author
+
+A model that implemented the change will defend it. The Verifier re-derives coverage from `plan.md` and
+`checks.md` and injects behavioural mutants. Enumerated cases in `checks.md` prove coverage *exists*; mutants
+prove it is *real*.
+
+A green gate is not a met requirement. Reviewers compare the deliverable to `plan.md`, `checks.md`,
+`verification.md`, and `uiux.md` / `dx.md` field by field. Paraphrase is not parity.
+
+## Evidence
+
+[evidence.md](../../.agents/skills/wtk/references/evidence.md): no completion claim without a
+fresh command. Scope binds — unit tests do not justify “feature complete”. A passing review over a
+red gate is void.
+
+Escalate when the scoped gate is unavailable or the configured stall threshold is reached. An
+open Critical alone does not halt while remediation is making measurable progress. A halt report is
+a result.