workflow-toolkit 1.0.1

package/bin/wtk.js

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+import process from 'node:process';
+import { realpathSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { createInterface } from 'node:readline/promises';
+import { runInstallWizard } from '../scripts/installer/terminal.js';
+
+export const HELP = `Usage: wtk <command>\n\nCommands:\n  install    Install or update Workflow Toolkit modules in the current directory\n\nCanonical invocation: wtk install\nModules: core, quality, extras\nTarget: current working directory\nBackups: existing files are verified under .my-workflow/backups/ before replacement\nRuntime: Node.js 18 or newer`;
+const CANCELLATION = 'Installation cancelled. No files changed.';
+const isReadlineCancellation = (error) => error?.code === 'ABORT_ERR' && error?.name === 'AbortError';
+
+export async function main(argv = process.argv.slice(2), runtime = {}) {
+  const stdin = runtime.stdin || process.stdin; const stdout = runtime.stdout || process.stdout; const stderr = runtime.stderr || process.stderr;
+  if (argv.includes('--help') || argv.includes('-h')) { stdout.write(`${HELP}\n`); return 0; }
+  if (!argv.length || argv[0] !== 'install' || argv.length !== 1) { stderr.write(`${HELP}\n`); return 2; }
+  if (!stdin.isTTY || !stdout.isTTY) { stderr.write('Interactive terminal required; run this command in a TTY.\n'); return 2; }
+  const readlineOutput = process.env.NO_COLOR === undefined ? stdout : new Proxy(stdout, { get(target, property, receiver) { return property === 'write' ? () => true : Reflect.get(target, property, receiver); } });
+  const readline = runtime.readline || createInterface({ input: stdin, output: readlineOutput, terminal: true });
+  try {
+    const result = await runInstallWizard({ targetRoot: runtime.targetRoot || process.cwd(), sourceRoot: runtime.sourceRoot, input: () => readline.question(''), write: (value) => stdout.write(`${value}\n`), width: runtime.width, color: process.env.NO_COLOR === undefined, requireGit: runtime.requireGit ?? true, transaction: runtime.transaction });
+    return result.code ?? 0;
+  } catch (error) { if (isReadlineCancellation(error)) { stdout.write(`${CANCELLATION}\n`); return 0; } stderr.write(`${error.message}\n`); return 1; } finally { if (!runtime.readline) readline.close(); }
+}
+
+if (process.argv[1] && realpathSync(process.argv[1]) === fileURLToPath(import.meta.url)) main().then((code) => { process.exitCode = code; });

package/docs/toolkit/README.md

@@ -0,0 +1,56 @@
+# Workflow tour
+
+Human-facing. Agents run [`AGENTS.md`](../../AGENTS.md) and load a guideline only when its
+condition fires. This folder is the **why**: what each stage is for, what each guideline
+protects, and which trade-off it encodes.
+
+These pages do not restate the rules. The guidelines remain the source of truth for behaviour.
+
+Cross-provider session continuation is owned by the host. Repository files, Git state, feature
+artifacts, and explicit handoff prompts remain the durable semantic context.
+
+## Walk this in order
+
+1. [Purpose — delivery and reliability](purpose.md)
+2. [The loop — stages from spec to merge](loop.md)
+3. [Reviews — three questions, hard caps](reviews.md)
+4. [Decisions — two namespaces, halt vs decide](decisions.md)
+5. [Guidelines — why each file exists](guidelines.md)
+6. [Skills, knowledge, adopt](pack.md)
+7. [Repository intelligence](repository-intelligence.md)
+
+## Map
+
+| You want | Read |
+| --- | --- |
+| The thesis | [purpose.md](purpose.md) |
+| Specify → slice → gate → PR | [loop.md](loop.md) |
+| Verifier, QA, wtk-deep-review, filed issues | [reviews.md](reviews.md) |
+| `AD-NNN` vs architecture invariants | [decisions.md](decisions.md) |
+| One paragraph per guideline | [guidelines.md](guidelines.md) |
+| What is vendored and what is not | [pack.md](pack.md) |
+| Graphify/Graft routing, setup, freshness, and benchmark | [repository-intelligence.md](repository-intelligence.md) |
+| Shared execution contracts | [`wtk/references/`](../../.agents/skills/wtk/references/) |
+| Surface-specific rules | [`docs/toolkit/guidelines/`](guidelines/) |
+| What agents load every turn | [`AGENTS.md`](../../AGENTS.md) |
+
+## The loop at a glance
+
+```
+per slice    implement → scoped gate → atomic commit
+feature      one fresh Technical Verifier over the complete feature range
+resolved     wtk-deep-review groups from wtk-config, before QA
+
+feature      selected QA session (no product code)
+then         selected full/scoped gate → pull request
+```
+
+Public hierarchy: `Feature -> Slice -> Check`. Read
+`.agents/skills/wtk-config/SKILL.md` before dispatch; it resolves cadence and delegated providers.
+
+Repeated review blockers use the immutable fingerprint and independent counter in
+[`REVIEW-ROUNDS.md`](guidelines/REVIEW-ROUNDS.md); this guide does not duplicate that protocol.
+
+A filed issue skips the ceremony: `implement → scoped gate → one commit`.
+Credential-free declarative agent-tool configuration uses the local light path in
+[`validation.md`](../../.agents/skills/wtk/references/validation.md).

package/docs/toolkit/decisions.md

@@ -0,0 +1,61 @@
+# Decisions
+
+Two namespaces, on purpose. Mixing them is how an architecture invariant becomes a reversible
+project call, or a one-feature choice becomes “the way the system is”.
+
+## Where a choice lives
+
+| Kind | Id | Home | Lifetime |
+| --- | --- | --- | --- |
+| **Project decision** | `AD-NNN` (three digits) | `.specs/STATE.md`, append-only | The project. Supersede, never delete, never reuse an id |
+| **Architecture invariant** | Whatever the consuming project uses | `docs/architecture/` | Holds regardless of feature. This pack does not invent those ids |
+| **Feature-local** | Table in `decisions.md` | `.specs/features/<slug>/decisions.md` | Versioned with the feature; promote if it must outlive it |
+
+Always cite **the file** with the label. The same letters in two files are not the same object.
+
+Promote before the pull request, per [artifacts.md](../../.agents/skills/wtk/references/artifacts.md):
+
+- Must outlive the feature as a project call → `AD-NNN`
+- Must outlive it as a product promise → `docs/qa/scenarios/`
+- Must outlive it as an invariant → the architecture docs
+- Must outlive it as an agent rule → `docs/toolkit/guidelines/`
+
+Feature workflow state (`plan.md`, `checks.md`, and `verification.md`) stays under the versioned
+`.specs/features/<slug>/` tree. Workflow memory remains disposable local state.
+
+## Halt vs decide
+
+An unattended run (`wtk-ship`) must **settle or stop** before building:
+
+- If the documents already answer it, proceed.
+- If evidence in the repo is enough, decide, record `AD-NNN` with reasoning, move on.
+- If the remaining choice would **change what gets built**, halt. Write the report. Merge nothing.
+
+A decision recorded with its reasoning is reversible in the morning. A decision made silently
+inside an implementation is found months later.
+
+Ambiguity that does **not** change what gets built is not a halt. Record it in `decisions.md` and
+continue. A phase boundary is not a checkpoint.
+
+## What a recorded decision must carry
+
+For anything an unattended run chose while nobody was watching:
+
+- what was chosen
+- why
+- alternatives rejected, and why
+- cost to change now
+- cost to the user today
+
+Separate the human’s calls from the run’s. A reviewer in the morning needs to know whose they are.
+
+Accepting a security risk is the same shape: explicit approval plus an append-only `AD-NNN`.
+Silence is not acceptance.
+
+## Knowledge
+
+When two source documents disagree, the **source wins** and the wiki concept is wrong. The bundle
+holds the graph and the contradiction; it does not override `docs/` or `.specs/STATE.md`.
+
+Offer to record durable knowledge when it surfaces in conversation. Never write to `knowledge/`
+without a yes. Never skip the offer.

package/docs/toolkit/guidelines/CONTEXT-BUDGET.md

@@ -0,0 +1,64 @@
+# Context Budget
+
+**Read when:** editing `AGENTS.md`, `CLAUDE.md`, or any file in this directory.
+
+**Why this exists:** Instruction files compete with the work for the same window. A previous
+arrangement loaded more than a thousand mandatory lines before any task, most of it irrelevant.
+Dispatch by condition; growing a file with restated prose is a defect.
+
+`AGENTS.md` loads into every Cursor and Codex prompt. `CLAUDE.md` is `@AGENTS.md` — Claude Code
+imports it; Cursor does not expand `@`, so a symlink that duplicates the contract is a defect.
+
+## Rules
+
+1. **Growing an instruction file with restated or redundant prose is a defect.** Adding a rule means
+   finding the one it replaces, or justifying why both must exist.
+2. **`AGENTS.md` carries conditions and dispatch, not content.** If a rule applies only sometimes, it
+   belongs in a guideline behind a trigger. `CLAUDE.md` stays one import line.
+3. **One home per fact.** A guideline references `docs/` — it never copies from it. Two copies of a
+   rule disagree eventually, and the disagreement is discovered by an agent following the wrong one.
+4. **Each guideline states its trigger in its first line.** An agent must be able to decide whether to
+   read it from the title and one sentence.
+5. **Rules are stated once, in the imperative.** No "remember to", no restating the rule as a warning
+   later in the same file, no summary section repeating what the sections said.
+6. **Delete on sight.** A rule that no longer describes how the project works is worse than no rule,
+   because agents follow it.
+
+## Size targets
+
+| File | Target |
+| --- | --- |
+| `AGENTS.md` | Under 200 lines |
+| A rule guideline | Under 120 lines |
+| A reference guideline — one carrying a schema, a surface list, or a protocol | Under 160 lines |
+| All guidelines together | Under 1,500 lines, of which a typical task reads two or three |
+
+A rule guideline states what must be true and can nearly always be shortened. A reference guideline
+carries content that is irreducible — `SECURITY.md` owns the surface list, `QA-SCENARIOS.md` owns a
+field schema, `KNOWLEDGE-WIKI.md` owns four operations. Cutting those does not save context, it just
+moves the lookup somewhere else and costs a round trip.
+
+These are targets, not gates. A file at its limit because nobody pruned it is the problem this
+addresses; a file at its limit because the content is that size is fine.
+
+## The test before adding anything
+
+Ask, in order:
+
+1. **Does a rule already cover this?** Then extend that rule rather than adding a second one.
+2. **Will an agent behave differently because of this line?** If not, it is commentary. Cut it.
+3. **Is this a condition or a rule?** Conditions go in the `AGENTS.md` dispatch table; rules go in the
+   guideline the condition points at.
+4. **Is this durable or is it about right now?** Anything about the current state of the work belongs
+   in workflow memory or the pull request, never in an instruction file.
+
+## What does not belong here
+
+- Status, progress, or plans — those are branch and pull-request concerns
+- History or rationale, except the one sentence needed to stop a rule being undone
+- Anything the repository already states: file structure, available commands, code conventions the
+  linter enforces
+- Speculative rules for problems that have not happened
+
+A rule earns its lines by preventing a defect that occurred, or by resolving an ambiguity an agent
+actually hit.

package/docs/toolkit/guidelines/DX.md

@@ -0,0 +1,67 @@
+# Public Surface Contract
+
+**Read when:** the feature adds or changes a public surface — an HTTP route, a config key, a CLI verb,
+a package export.
+
+**Why this exists:** A surface designed after its internals inherits the internals' shape instead of
+the caller's needs. Writing the contract first — as if it already shipped, failures enumerated —
+surfaces ergonomic problems while they are still free to fix. Internals-only features skip this.
+
+## The artifact
+
+`.specs/features/<feature>/dx.md`, written in Design, before internal design.
+
+```markdown
+# <Feature> Surface Contract
+
+## Routes
+
+### `POST /api/records`
+- **Auth:** none
+- **Request:** `{ name, email, region }`
+- **Success:** `201 { id, createdAt }`
+- **Failures:** `422` validation, field-level detail · `429` rate limited · `500` no detail
+- **Idempotency:** none — duplicate submissions create duplicate rows by design
+
+## Config
+
+| Key | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `PUBLIC_RATE_LIMIT_PER_MINUTE` | integer | 10 | Requests per IP before 429 |
+
+## Exports
+
+What this feature adds to a package's public interface, and what now depends on it.
+
+## Removals
+
+What this feature deletes. Hard cuts, no aliases, no dual fields.
+```
+
+## Rules
+
+1. **Write it as if it shipped.** Present tense, no hedging, no "we could". A surface described in
+   conditionals has not been decided.
+2. **Every failure is enumerated with its status and its body shape.** An unlisted failure ships as a
+   500.
+3. **Error copy is part of the surface.** What the caller reads on failure is designed here, not
+   improvised in a catch block.
+4. **The surface freezes before internals.** Internals are designed to serve it. Reopening it later is
+   an explicit decision, not a quiet adaptation.
+5. **Removals are listed.** This workflow does not preserve backward compatibility — so a change that
+   removes something states exactly what goes, and the same change updates every caller.
+6. **It respects the project's boundary.** The consuming project's architecture docs name the product
+   boundary. A surface that would violate that boundary is wrong at design time, not at build time.
+7. **Write all versioned or published text in English.**
+
+## What to grill before freezing
+
+The questions worth asking about a surface, once the draft exists:
+
+- Does the name say what it does to someone who has not read the spec?
+- Is the failure a caller is most likely to hit the one with the clearest message?
+- What happens on the second call with the same input?
+- What does this look like from a client that cannot retry?
+- Which field will someone want that is not here, and is leaving it out deliberate?
+
+The draft is the question. Rework it between rounds rather than discussing it in the abstract.

package/docs/toolkit/guidelines/FRONTEND.md

@@ -0,0 +1,73 @@
+# Front-End Engineering
+
+**Read when:** writing or reorganizing front-end application code, or working on a mockup under
+`docs/design/`.
+
+**Why this exists:** Feature-specific policy dumped into shared UI, and routes that draw their own
+layout, produce a front-end that cannot tell capability from reuse. Feature folders own capability;
+shared folders own reuse. Appearance still belongs in the project's design docs.
+
+This document owns front-end *code organization*. It does not own appearance or behaviour. The
+consuming project's design docs win on appearance and behaviour. Link to those instead of restating
+them here.
+
+## Feature folders vs shared UI
+
+Routes compose. A route selects a shell, loads route state and composes feature and shared
+components. It does not own reusable layout and does not draw raw landmarks (`header`, `nav`,
+`main`) that a shell already owns.
+
+Feature-specific browser and transport logic lives in a feature folder named for the capability:
+
+- a client adapter for the browser-facing surface;
+- a server-side forwarder only when this app is not itself the product boundary;
+- an explicit marker (suffix, package, or bundler boundary) for modules that must not enter the
+  browser bundle.
+
+Shared folders have narrower roles: generic primitives, compositions used by more than one route,
+feature-neutral helpers. Do not move feature-specific policy into a shared folder to avoid creating
+a feature folder.
+
+Tests stay grouped by execution layer, not by feature folder, unless the consuming project already
+colocate them.
+
+## Component script
+
+Follow this order before writing any application UI:
+
+1. Identify the shell. Exactly one component owns each shell. Select it; do not improvise an
+   equivalent header, navigation or main layout in the route.
+2. If the needed primitive exists, use it without a wrapper whose only purpose is spacing or styling.
+3. If a shared composition exists, use it.
+4. If a generic primitive is missing, add it at the project's primitive layer — follow that layer's
+   generation rules; do not hand-edit generated files.
+5. Express a primitive variation as a variant of that primitive. Do not copy or fork it.
+6. If a product composition is missing, add it with closed props. Use a free slot only when the
+   surface genuinely varies. Consistency-critical content belongs in named, constrained props.
+7. Never add a stylesheet outside the project's canonical style root.
+
+## Mockups
+
+Standalone mockups are implementation references when the project treats them that way, not
+disposable sketches. Reuse the same shell family, component treatment and state vocabulary the
+implementation will use. If the existing pattern cannot express the surface, change the shared
+reference deliberately and extend its conformity test in the same task.
+
+## Browser permanence
+
+Use the cheapest layer that discriminates the outcome. Keep an application e2e permanently only for a
+browser-only or real-stack property, a session/cookie/origin/authorization/checkout boundary, a named
+minimum smoke capability, or a regression that lower layers demonstrably miss. Permanent scenarios
+carry stable `@feature:<slug>` and `@journey:<slug>` tags, own every account/IP/session/resource they
+create, and clean exact resources in `finally` with zero-residue assertions. Temporary probes are
+removed before commit.
+
+Durable regression is a deterministic spec with no model call. Exploratory scripts and agent sessions
+are disposable. Neither their transcript nor a successful session is evidence.
+
+## Vendored skill scope
+
+Vendored skills are advisory. Canonical project documents, installed source and installed dependency
+declarations win when guidance conflicts. Do not edit a vendored skill to record a project exception:
+that changes its lockfile hash and the next upstream refresh can overwrite the edit. Record the
+exception in the consuming project's front-end guideline.

package/docs/toolkit/guidelines/KNOWLEDGE-WIKI.md

@@ -0,0 +1,128 @@
+# Knowledge Wiki
+
+**Read when:** discussing a product rule, domain term, or architecture invariant stated in more than
+one document — which is most of planning — or when durable knowledge surfaces in conversation and
+needs recording.
+
+**Why this exists:** Source documents cannot see each other. The wiki holds the graph and the
+contradictions; it is not a summary of `docs/`. When bundle and source disagree, the source wins.
+Silence when durable knowledge surfaces leaves an existing concept confidently wrong.
+
+`knowledge/wiki/` is an Open Knowledge Format bundle holding what no single source document can: the
+graph between them, and the contradictions no document resolves.
+
+It is not a summary of `docs/`. Its pages synthesize several sources into one answer and cite each
+claim back. A concept that reconciles four product files into a single table and names the failure
+mode in both directions is doing work no source document could, because none of them can see the
+other three.
+
+This pack ships the machinery empty. The consuming project fills concepts as they are earned.
+
+## Reading is automatic and cheap
+
+No permission needed, no schema to load first.
+
+1. Read `knowledge/wiki/index.md` — it is the router, and it lists what exists before you open
+   anything.
+2. Follow the subdirectory index, then the concept.
+3. Answer with its citations, and follow them to the source when the answer must be exact.
+
+Read it when the conversation is about:
+
+- A product rule stated in several places
+- A domain term whose meaning might differ between documents
+- An architecture invariant and what it constrains
+- Why a past decision went the way it did, including the reversals
+
+**Planning a feature that touches those areas is exactly when to read it**, not a reason to skip it.
+
+**The source always wins.** When bundle and source disagree, the source is right and the concept is
+wrong. Say so and note it — never quietly follow the concept.
+
+## Writing: never silently, but never miss it either
+
+Two write paths, and they have different rules because the knowledge comes from different places.
+
+### From the human, in conversation — offer it, every time
+
+When something durable surfaces while talking, **say so and offer to record it**. The schema requires
+this: *"a useful query should leave the bundle better than it found it, not evaporate into the
+transcript."*
+
+The stakes are asymmetric. An observation that contradicts a founding assumption does not merely leave
+the bundle incomplete — it leaves an existing concept confidently wrong. Silence is the expensive
+option.
+
+Offer when any of these appear:
+
+- An observation about real user behaviour that differs from a documented assumption
+- A decision made in conversation that changes a documented rule
+- A contradiction between two sources that the human points out
+- An outside constraint learned from the market, a competitor, or a platform
+- An answer derived at real cost that would cost the same to derive again
+
+Do not offer for: anything a source document already states, implementation detail, or transient
+status.
+
+The offer names the target and waits:
+
+> Users treating the catalogue as a directory rather than a search tool contradicts
+> `product/<concept>.md`, which assumes intent-driven reads. I would write
+> `raw/YYYY-MM-DD-<slug>.md` with the observation, then amend that concept to cite it. Record it?
+
+Then INGEST as the schema defines it: the observation lands in `knowledge/raw/` as
+`YYYY-MM-DD-<slug>` and is **never modified afterwards** — a correction belongs in the concepts citing
+it. Concepts cite sources, so an observation with no `raw/` entry is a claim with no provenance.
+
+**The human always decides. Never write without a yes, and never skip the offer because a feature is
+in progress.**
+
+### From shipped artifacts — explicit request only
+
+HARVEST reads the project's own `.specs/`, commits and docs. Never run it as part of a feature: an
+agent harvesting what it just wrote produces restatements, and the schema bans exactly that — a
+harvested concept must not restate its source.
+
+**At the granularity of a finished feature, never a finished task.** Most tasks produce nothing
+durable. Never harvest `tasks.md` (runner state) or `LESSONS.md` / `lessons.json` (machine-owned).
+
+### Either path loads the schema first
+
+Writing means reading `knowledge/AGENTS.md` in full — it owns frontmatter, citation shape, index and
+log rules. That load is justified for writing and wasted for reading.
+
+## Verifying happens with the write, not with the ship
+
+The knowledge checker (`bun run knowledge` in this pack) runs as the **first step of a harvest**, not
+as part of the consuming project's full gate.
+
+Its conformance, gap and drift reports are useful input when you are about to write to the bundle.
+They are noise when you are trying to merge a bug fix — and the drift check is file-granular against
+entry-granular sources, so an unrelated append to `.specs/STATE.md` restales every concept citing that
+file. Gating a feature on that is gating on bookkeeping.
+
+LINT is the judgment half no script performs — contradictions between concepts, claims superseded by a
+newer source, orphan pages, missing index entries. It runs with the harvest, periodically, and always
+before a large ingest.
+
+## No overlap with the QA tree
+
+Sometimes confused. They ask unrelated questions:
+
+| | Asks | Built from |
+| --- | --- | --- |
+| `knowledge/wiki/` | How do these documents connect, and where do they contradict? | Reading documents |
+| `docs/qa/scenarios/` | What does the product promise users, and what state is each promise in? | Walking the product |
+
+Neither substitutes for the other.
+
+## Summary
+
+| Operation | Trigger | Who decides | Loads |
+| --- | --- | --- | --- |
+| **Read** (QUERY) | Automatic, whenever the topic spans documents | Agent | `index.md` + the concept |
+| **Offer** (INGEST) | Automatic, whenever durable knowledge surfaces in conversation | **Human approves, agent writes** | `AGENTS.md` after the yes |
+| **Harvest** (HARVEST) | Explicit request only, per finished feature | Human | `AGENTS.md` in full |
+| **Verify** (knowledge checker + LINT) | With any write | Agent | — |
+
+Reading and offering are the agent's job without being asked. Deciding is always the human's.

package/docs/toolkit/guidelines/MODELING.md

@@ -0,0 +1,134 @@
+# Domain and Architecture Modeling
+
+**Read when:** a change creates or alters a bounded context, module boundary or dependency direction;
+introduces, replaces or decouples an external provider; changes a port, adapter, queue or inter-module
+message; or models an Entity, Value Object, Aggregate, Domain Service or Domain Event. Simple CRUD,
+local bug fixes and boundary-preserving refactors do not.
+
+**Why this exists:** A domain that imports the web, API, or persistence framework cannot outlive
+those frameworks. Invariants that live only in SQL cannot be exercised without the database. This
+file is how the model is written, not what the product means.
+
+This document owns how the domain is expressed in code. It does not own product language, domain
+rules or architecture decisions. `docs/product/` owns the domain; the consuming project's architecture
+docs own architecture invariants; `.specs/STATE.md` owns project decisions. Those sources win
+whenever skill guidance conflicts.
+
+## Design sequence
+
+1. Ground the change in the canonical product and architecture sources. Use `knowledge/wiki/` only
+   to follow connections or find contradictions; return to the cited source for the rule.
+2. For boundaries, integrations or evolution, record ownership, public contract, port/adapter
+   boundary, consistency model, failure semantics and evolution trigger in the feature design.
+3. When a dependency crosses module or context boundaries, record its strength, distance and
+   volatility, then decide whether to accept, relocate or decouple it.
+4. For behaviour inside one bounded context, apply *Domain expression* below. Record the chosen
+   building blocks, invariants, transaction boundary and domain events in the feature design without
+   restating the product model.
+5. When architectural and tactical modeling both apply, establish the bounded context and its
+   contracts first, then model its internals.
+6. Record a new lasting choice in the correct namespace: project decisions are `AD-NNN` entries in
+   `.specs/STATE.md`; architecture invariants live in the consuming project's architecture docs.
+
+For an auto-sized change without `design.md`, keep the same result in the inline design note.
+
+## Domain expression
+
+These rules fix how the model is written. A rule needing a concrete entity name to be understood
+belongs in `docs/product/` instead.
+
+### One aggregate, one module
+
+An aggregate owns one folder, named for the aggregate. The folder holds the aggregate's behaviour,
+its repository port and every adapter implementing that port, plus whatever else is specific to it.
+Two aggregates in one folder is a folder that must split; one aggregate spread across two folders is
+a boundary error.
+
+Folders carrying no aggregate keep their own names: the HTTP surface, shared technical modules.
+
+### One repository per aggregate root
+
+Only an aggregate root gets a repository. Everything inside the aggregate is loaded and saved through
+that root. The port takes and returns domain values. A persistence row never crosses it.
+
+### Value Object or primitive field
+
+A value becomes a Value Object when a rule must hold everywhere the value appears — a format, a range,
+a normalization, a unit, or two fields only meaningful together. It stays a primitive when its only
+rule is shape already enforced at the trust boundary.
+
+The discriminator is where the value can enter from. A value that reaches the domain only through a
+validated request needs no second guard. A value the domain derives itself, reads back from storage,
+or receives from a job or a provider callback bypasses that boundary, so its rule has to travel with
+it.
+
+Identifiers stay opaque strings unless the project has decided otherwise.
+
+### Where invariants are enforced
+
+An invariant over one aggregate's own state is enforced inside that aggregate, in the method that
+performs the transition, before the state changes. The method is named for the transition in the
+product's language and refuses an illegal one rather than reporting it.
+
+| Layer | Its job |
+| --- | --- |
+| HTTP / command boundary | Rejects malformed input and resolves authority before the command |
+| Aggregate | Decides whether the transition is legal, then performs it |
+| Repository adapter | Persists a decided outcome |
+| Database constraint | Backstop proving the invariant held |
+
+Authority is not an aggregate invariant. The command boundary resolves who may act; an aggregate
+re-deriving it duplicates a rule whose inputs it cannot see.
+
+A database constraint is never a rule's only statement. A rule living solely in SQL cannot be
+exercised without the database and cannot explain its own refusal.
+
+### Transaction boundary
+
+One command mutates one aggregate in one transaction. The application layer opens the transaction and
+the adapter runs inside it. An aggregate receives no handle to the transaction; it computes the next
+state and returns it.
+
+A rule spanning two aggregates resolves through events or jobs, never through a second aggregate
+mutation in the same transaction, unless the architecture docs explicitly allow it.
+
+### What the domain may import
+
+A domain module imports the language standard library and other modules of the same aggregate.
+
+**It does not import the web framework, the API framework, the persistence framework, a provider SDK,
+or the public wire-contract package.** Each is a boundary the domain is meant to outlive. A domain
+type matching a DTO field for field is still declared separately, because a wire contract and an
+internal model change for different reasons.
+
+The consuming project's boundary gate, if it has one, enumerates those module names. Moving business
+rules out of persistence adapters is done as part of the next feature that touches a repository, not
+as a migration of its own.
+
+### Ports and adapters
+
+The domain declares the port and names it for what the domain needs. The adapter conforms. A port
+mirroring a library's API instead of the domain's need has the direction backwards.
+
+A port earns its place when it isolates something the domain must outlive, or when it lets the domain
+be exercised without infrastructure. A collaborator that is neither needs no port.
+
+### Proportional intensity
+
+Match the machinery to the rules a module actually has:
+
+| What the module has | What it gets |
+| --- | --- |
+| Shape rules only | A contract schema, a repository and route handlers |
+| One rule holding on every write | That rule, in one named function in the module |
+| States with legal and illegal transitions, or fields that must agree | An aggregate owning those transitions |
+| A rule spanning aggregates | A domain service, or the architecture doc's event path |
+
+Model behaviour where a rule exists. Before adding an aggregate, name the invariant it protects; when
+no name comes, the module has shape rules and the first row applies.
+
+## Vendored skill scope
+
+Vendored modeling skills are advisory. Their defaults do not become project rules merely because the
+skill is installed. Do not edit a vendored skill to record a project exception. Record conventions
+here after they are adopted.

package/docs/toolkit/guidelines/QA-EXECUTION.md

@@ -0,0 +1,46 @@
+# QA Execution
+
+**Read when:** a feature reaches its closing QA session.
+
+`wtk-qa-plan` and `wtk-qa-execute` own the procedures. This guideline only decides whether QA runs, dispatches
+the existing Verifier, and points to the authorities that keep the contract stable.
+
+## Trigger
+
+QA runs once per feature, at feature close over the integrated tree; no slice runs QA. Run it when
+the feature diff changes an observable UI, API, CLI, mobile surface, public configuration,
+adoption flow, docs-as-interface, or user-facing copy, unless the proportional classifier in
+`.agents/skills/wtk/references/validation.md` selects a narrower route. A behavior-preserving `direct correction` or `UI-only correction`
+is the exception: its targeted integration validation covers the consuming project and it receives no QA Plan/Execute cycle,
+even when the rendered component changes. A browser-only invariant explicitly
+changed by that correction may use one existing targeted scenario. Purely internal refactors receive
+technical verification only. Record `no user-visible change` when no public promise changed.
+
+## Dispatch
+
+After the final implementation wtk-deep-review group, use the provider's existing `verifier` with one
+phase per packet:
+
+1. Send a fresh `phase: wtk-qa-plan` packet to invoke `wtk-qa-plan`, create or refresh durable journeys and
+   scenarios, and create a new dated charter for this cycle. Never edit an existing charter.
+2. Send a distinct fresh `phase: wtk-qa-execute` packet to invoke `wtk-qa-execute` and walk those journeys.
+
+The QA Plan session ends before the product starts. The QA Execute session does not write product
+code. A defect returns to an Implementer; after the fix, a fresh Verifier applies incremental impact
+selection, reruns invalidated technical proofs, retests the affected journey, and resumes the cycle.
+
+## Authorities and adapters
+
+- `docs/toolkit/guidelines/QA-SCENARIOS.md` owns scenario fields, ids, statuses, and flag/reset rules.
+- `docs/qa/README.md` owns the consuming project's public interfaces, existing adapter, setup,
+  authentication, fixtures, cleanup, and limitations.
+- `wtk-qa-execute` selects the declared browser, API, CLI, mobile, or manual adapter. It records the
+  exact path, evidence, and limitation. It does not install tooling or invent commands.
+- Each checkout owns its runtime and raw evidence. Keep durable reports and statuses in `docs/qa/`
+  and keep generated evidence in the consuming project's disposable evidence path.
+- When a selected QA scope carries a visual AC, follow `UI-UX.md#verifying-the-built-screen`, point the
+  report at its feature `uiux.md` row, and record the paired-capture output fields. A manual comparison
+  is evidence, not an automated test; keep behavioral assertions intact.
+
+Read the two skills and `QA-SCENARIOS.md` for the active branch; this bridge deliberately carries no
+duplicate scenario schema or live-walk protocol.