@stdd/plugin 0.9.0

package/runtime/method/reference-commands.md

@@ -0,0 +1,147 @@
+# Reference: review and worker command internals
+
+The mechanics behind `stdd review` and the worker commands: how a request is
+stored and settled, what each dispatch route does, and what a managed sandbox
+copies and collects. The method states the contract; this document states the
+implementation.
+
+## Brief construction
+
+The brief carries a complete changed-file manifest (the diff body
+may truncate beyond a size bound; the manifest never does, and it names
+every untracked path too — symlinks and other non-regular files carry a
+skipped marker, so nothing the reviewer was not told about can exist),
+the diff, the contents of untracked regular files
+(a new file is part of the change even before `git add`; symlinks are
+skipped and large files are read only up to a bound), and a **governing
+docs** section (the canonical docs are the standing spec: docs changed
+in this branch are named as the spec delta to read first, and when none
+changed the configured `canonicalDocs` globs are named instead — the
+reviewer is read-only in the repository and reads them itself; contents
+are never inlined).
+
+## The review result contract
+
+The reviewer's output is a single JSON object with required `summary` and
+`findings` fields. `summary` and every finding's required `message` must be
+non-empty printable single lines; ordinary Unicode, including ZWNJ/ZWJ and
+emoji, remains valid. Each finding has `severity: blocking | advisory`,
+`path` absent or null or a non-empty printable single line, and `line`
+absent or null or a positive safe integer. An absent location field is
+normalized to null for findings not tied to one location. For a
+control-bearing repository path that cannot cross this inline boundary, the
+reviewer omits `path` rather than emitting unsafe text. Any wrong field type
+or output shape rejects the whole result.
+
+## Brief storage and settlement
+
+The brief is written outside the repository, in a
+private temporary directory with owner-only permissions — it can carry
+source contents and must not be world-readable. A `review-request` event
+records the route, snapshot, brief hash, and a versioned, lossless identity
+for the OS temp root, private directory, and every owned artifact. Codex's
+`last-message.txt` is created owner-only before that event and read only
+through a descriptor whose identity still matches the request. If the branch
+or active task changes
+while a CLI reviewer runs, the command records a terminal cancellation
+against the captured original request rather than attaching a verdict to
+the new context or leaving an orphan request. The cancellation and verdict
+paths share the ledger lock, so exactly one terminal outcome wins.
+
+Private-artifact settlement verifies the recorded directory and artifact
+identities, including that every artifact's recorded and observed owner equals
+the recorded review-directory owner, then overwrites each captured file through a helper-held writable
+capability, flushes it, truncates it to zero, and flushes again. It then moves
+the zeroed directory into an owner-private, non-loadable OS-temp quarantine.
+After the terminal ledger outcome is durable, that identity-bound zeroed tree
+remains for explicit operator removal. A crash leaves the quarantine
+recoverable by `review --cleanup`; unknown siblings, changed identities, or
+legacy requests without complete identity provenance fail closed before
+mutation and require explicit operator remediation. Settlement never follows
+or recursively deletes a replaceable final basename.
+
+## Dispatch routes
+
+- `--via codex` dispatches `codex exec --sandbox read-only` itself —
+  stdin closed, wall-clock bounded (`--timeout <seconds>`, default
+  600) — parses the reviewer's final message, and recomputes the
+  snapshot once the runner returns: a checkout that changed while the
+  reviewer ran records stale, the same as on submit.
+- `--via claude` dispatches `claude -p --safe-mode --tools Read,Glob,Grep --permission-mode dontAsk`
+  headless in the same way — brief over stdin, bounded, and tool-enforced read-only — for
+  repositories driven from Codex, or as a second perspective; like codex it
+  requires the `crossCli` capability.
+- `--via subagent` prints the brief path for the orchestrating agent to
+  hand to a fresh read-only subagent; the reviewer's JSON comes back via
+  `stdd review --result <file|->`, which grades it against the **open
+  subagent request**: a snapshot mismatch with the current checkout
+  records the result as stale and rejects it, and a CLI-dispatched
+  request (codex or claude) can never be completed by `--result` — its
+  runner is its only mouth, so a hand-fed file cannot forge its provenance.
+  Submitting a result securely settles the private temporary artifacts. An
+  abandoned request is cancelled and settled with `stdd review --cleanup`;
+  cleanup also reaches an interrupted CLI request and retries settlement
+  when a terminal cancellation outlived its private-artifact move.
+
+## Declaring a scope
+
+`stdd slice new` declares a scope inside the existing checkout;
+`stdd worker create <directory>` declares the same scope and builds a managed
+filesystem snapshot without `.git`. Both accept `--frozen` (globs the slice
+must not touch) and `--allowed` (globs the slice may touch — anything outside
+is a violation), and both record a `scope` event carrying the globs and a
+baseline. Every glob crosses the same printable-single-line
+boundary as other persisted identifiers; control, bidi, and invisible
+formatting characters are rejected before durable state is written.
+
+## Managed worker sandboxes
+
+A managed worker sandbox created by `stdd worker create` requires an active
+task and an already recorded docs
+decision. Its destination must not exist. Managed create and collect use the
+native mutation helper and fail before mutation when the destination
+filesystem cannot provide the required capability guarantees. Creation copies
+the checkout's tracked and non-ignored untracked files at
+current bytes, excluding Git metadata and the private ledger/plan. Ignored dependencies, credentials, and
+build output are deliberately absent; run the repository's readiness setup in
+the sandbox before trusting tests. `.stdd/worker.json` binds the sandbox ID,
+source task and branch, scope, source HEAD, and every copied path fingerprint;
+the parent ledger records the metadata hash. The sandbox receives a minimal
+local ledger for the same task, so `status --local`, `red`, `verify`, `note`,
+`scope`, and `doctor --readiness` work without source Git authority. Task boundaries, docs decisions, nested worker
+creation, review, evidence, and delivery commands are rejected there.
+
+`stdd worker collect <directory>` runs only from the source checkout. It
+rejects a missing or changed metadata binding, any non-ignored `.git` entry,
+unsafe file type, scope violation, source task/branch/HEAD drift, or concurrent source
+edit to a worker-touched path before applying anything. A complete preflight
+then imports only worker-introduced file changes and the worker's red/verify/
+note evidence. Collection never stages, commits, switches branches, pushes, or
+otherwise changes Git history. Import is idempotent: a rerun accepts paths
+already at the sandbox result and completes any remaining paths after an
+interruption; any third state is a conflict. Deleted source bytes move into an
+owner-private, Git-ignored `.stdd/worker-deletions/` recovery quarantine.
+Interrupted collection reuses exact deletion baselines for the next idempotent
+run; completed baselines remain recognizable for explicit operator removal.
+A readable metadata-v1 sandbox may replace file content while retaining its
+exact validated baseline mode, including a legacy mode such as `0664`; this
+compatibility authority never permits a sandbox-selected mode change and does
+not relax metadata-v2 creation modes. The orchestrator still runs fresh
+verification and review in the source checkout. STDD never removes the
+sandbox automatically; the orchestrator deletes it explicitly only after
+reviewing the collected result.
+
+## The scope postflight
+
+`stdd scope` is the postflight check against the recorded baseline rather than
+a ref: Git checkouts compare HEAD plus dirty paths, while managed sandboxes
+compare their bound file manifest. Only **worker-introduced** changes count — a
+change to a frozen path, or outside the allowed paths, fails. Dirt inherited
+from before the slice (a file already modified at baseline, byte-identical
+now) is reported separately and never blamed on the slice. A declared slice
+exempts only the ledger, plan, and exact shape-validated private internal
+transaction names;
+tracked config, generated files, and reset-name near misses under `.stdd/`
+remain ordinary scope inputs. The same exact exemption boundary applies to
+checkout and review snapshots. A declared slice appears in `stdd status`,
+which names the postflight as the next step once the loop is complete.

package/runtime/method/reference-generated-state.md

@@ -0,0 +1,151 @@
+# Reference: generated state and durable mutation
+
+How STDD proves that its generated files are the ones it wrote, and how it
+mutates a namespace without losing state to a crash. The method summarizes the
+guarantee; this document holds the mechanism.
+
+## Manifest hashes and generated-file cleanup
+
+Manifest hashes prove that generated bytes have not changed since init; for
+the installed method, `check` and `doctor` also compare those bytes with the
+canonical method shipped by the running CLI, so a stale method and a matching
+stale manifest cannot authenticate each other. Generated-looking method,
+snippet, and native-skill files without a manifest are a partial install and
+also fail the check, even when an exact generated path is occupied by a
+directory, symlink, or other unsafe object. A malformed manifest — including a wrong generator or
+version shape, a non-object document, an invalid generated path or exact
+`sha256:<64 lowercase hex>` file hash, or malformed present target metadata —
+is an actionable adoption finding in both `check` and `doctor`, never an
+uncaught runtime error. Legacy manifests may omit target metadata; when
+present, it must contain the complete known target schema. Every listed
+output is inspected as a readable regular file without following symlinks;
+directories, non-regular files, unreadable paths, and paths replaced during
+inspection are stale findings rather than runtime errors. Profile cleanup
+uses the same inspection boundary and never deletes an output it cannot
+safely identify. Retirement is confined to a filesystem capability held by
+the native mutation helper: the verified inode is moved out of its agent or
+CI load path to an unpredictable quarantine name. That quarantine is a
+durable safety and crash-recovery boundary; STDD never turns a final basename
+check into automatic recursive deletion. Before the first quarantine rename,
+init atomically publishes and fsyncs `.stdd/cleanup-transaction.json`
+with each output's original and quarantine paths, expected hash, and captured
+parent and file identities. Every later phase is durably recorded. A
+manifest-publish failure rolls back all quarantines; after a durable manifest
+commit the exact quarantined trees remain hash-accounted outside their former
+load paths for explicit operator removal. A crash leaves the journal
+authoritative, and the next init reconstructs whether to resume or roll back.
+If recovery cannot prove the exact identities, it blocks without forgetting
+an orphan. `check` and `doctor` report pending or malformed cleanup journals;
+`doctor` also inventories recognized retained quarantines and gives manual
+removal guidance. Neither treats a quarantine as active generated output. A hand-edited formerly generated file is preserved and
+remains listed and reported stale until its owner removes or relocates it.
+The journal is repo-local, single-linked, owner-private, and replaced
+atomically. Journal reads bind metadata, bytes, and the final pathname to one
+helper-held file capability. Recovery rollback and retirement use captured
+parent capabilities, so a concurrent logical-parent swap cannot redirect
+either operation. The replacement manifest is committed in durable order:
+held-parent temp creation, file flush, held-parent atomic rename, directory
+flush, then logical-parent and manifest-identity verification. Only after
+that proof may the zeroed journal itself move to a retained, non-loadable
+quarantine. An indeterminate post-rename failure leaves all state for
+deterministic recovery.
+
+## The bundled `stdd-fs` helper
+
+Namespace mutations that require a stable parent run through one bundled
+`stdd-fs` helper session per CLI command. The helper exposes a versioned JSONL
+capability protocol; opaque handles and expected identity tokens, not logical
+pathnames, authorize mutation. STDD's JavaScript runtime retains policy, WAL
+schemas, operation ordering, and user-facing diagnostics. The helper binaries
+for Linux x64/arm64, macOS x64/arm64, and Windows x64/arm64 are included in
+both `@stdd/cli` and the universal plugin. Release CI builds every target and
+verifies the packaged artifact manifest. Before spawning one, STDD verifies
+the exact platform/architecture selection, regular non-symlinked file shape,
+SHA-256, and protocol handshake. The installed package tree is part of the
+trusted code boundary, like the JavaScript runtime itself; integrity checks
+detect static corruption but do not claim to defeat a same-user process that
+can rewrite executing package code. Target-repository namespace races remain
+untrusted after the helper session starts. A missing, damaged, or incompatible
+helper fails before target mutation; read-only commands do not require it except
+when `doctor` capability-inspects exact ledger-proven retained review or worker
+quarantine locations. Those inspections use only read operations through the
+verified helper session; discovery or helper failures become doctor findings.
+
+The helper preflights the target filesystem metadata and OS primitive set for stable file identities,
+no-follow traversal, same-volume atomic rename, and durable file and directory
+flushes. Unix binds owner and mode through descriptor-relative operations.
+Windows binds volume/file IDs, rejects reparse points, and creates private
+state with a protected current-user DACL. Symbolic-link inspection is a
+protocol-v1, capability-relative `read-link` operation over a held parent and
+one validated child name: it never follows the link, requires the caller's
+expected symlink identity, returns bounded raw target bytes as base64, and
+rejects an identity change across the read. Unix uses bounded `readlinkat`
+retries with an identity postflight. Windows accepts only recognized symbolic
+link reparse tags and binds the exact reparse identity before and after parsing.
+Symbolic-link creation uses the same held-parent authority and no-replace
+publication. On Windows it selects file or directory link semantics without
+following an external target, applies the exact owner and protected DACL,
+verifies the published reparse identity, and flushes and postflights the
+parent. Missing privilege or developer-mode support fails with a structured
+unsupported or access error before partial publication. Probe evidence covers
+both link operations consistently. Managed-worker creation performs that
+preflight against the held, probed destination parent after preparing the
+complete source snapshot and before creating the destination root whenever the
+snapshot contains a symbolic link; regular-only snapshots skip it.
+Protocol-v1 also exposes an expected-identity-bound `set-mode` mutation for a
+held regular file on Unix. It uses descriptor-relative `fchmod`, rejects type
+or special bits outside the legacy metadata-v1 mode range, and returns a stat
+postflight with committed mutation reporting after the syscall. Windows
+returns a structured unsupported result because managed metadata-v1 workers
+are Linux-only. Collection may use this operation only to restore the exact
+mode inherited from the validated metadata-v1 baseline for that file; a worker
+cannot select a different mode. Metadata-v2 and new file creation remain
+restricted to `0600`, `0644`, and `0755`. A filesystem without those
+capabilities fails closed; there is no best-effort pathname fallback. New
+quarantines always record enough provenance for deterministic recovery and
+operator inventory. Existing manifest, journal, worker, review, ledger, and
+plugin quarantines are never discovered by a broad temp-directory scan;
+recognized locations are reported, while provenance-less leftovers remain
+untouched.
+
+## The printable-text boundary
+
+Inline identifiers and adapter metadata share one printable-text boundary
+before they reach task state, logs, or generated files. It accepts ordinary
+Unicode, including ZWNJ/ZWJ and emoji sequences, but rejects line/control
+characters, unpaired surrogate code units, Unicode `Bidi_Control` code points,
+and a fixed denylist of invisible or deprecated formatting controls. The
+denylist includes soft-hyphen/grapheme-joiner controls, zero-width space,
+word/invisible-operator controls, interlinear/shorthand/music formatting
+controls, and BOM, so visually identical or reordered text cannot spoof those
+outputs without broadly rejecting Unicode format characters.
+
+## Ledger transactions and retained quarantines
+
+Reset publishes its two task
+boundaries with one same-directory atomic rename. Its exact internal
+active transaction names (`.ledger-reset-` and `.ledger-prepared-`, each
+followed by 32 lowercase hex characters and `.tmp`) are owner-only. A trusted
+stranded active temp moves under the next ledger lock to
+`.stdd/ledger-quarantines/.ledger-recovered-<same-token>.tmp/`, an owner-private
+retained directory containing a single-linked `0600` payload and matching
+`0600` `inventory.json`. Active temps and those two retained files are ignored
+by checkout/review snapshots only after their complete shape, token-bound
+provenance, and exact directory contents are verified. Unix recognition also
+binds uid and exact modes; Windows relies on the protected current-user DACL
+and owner check enforced by the native creator because Node exposes only
+synthetic POSIX uid/mode values there. They are deliberately not hidden by
+`.gitignore`, so a symlink, non-regular or hard-linked file, extra sibling,
+malformed inventory, near-miss name, or (on Unix) foreign owner/non-private
+mode remains visible and is rejected rather than trusted. `stdd doctor` inventories verified retained ledger quarantines with
+manual-removal guidance. Repository transaction-temp recovery, reset commit,
+and settlement use
+one native-helper session with held `.stdd` capabilities for the snapshot,
+active and prepared temps, final ledger publication, and identity-conditioned
+quarantine retirement. A crash leaves the exact temp recoverable; a completed
+transaction moves it out of every active transaction namespace but does not
+recursively delete its final quarantine basename. Ordinary task start, finish, and
+recorder appends use the same portable publication boundary when they need a
+namespace mutation. A SIGKILL-stranded active temp is a non-authoritative copy
+recovered under the next ledger lock only after its owner-only, single-link
+regular-file shape is validated, which is why a review snapshot may exempt it.

package/runtime/method/reference-integration.md

@@ -0,0 +1,233 @@
+# Reference: installation, agent hosts, and automation
+
+What `stdd init` and `stdd configure` write, what each agent host receives,
+and how the optional CI and lifecycle-hook adapters behave. The method states
+that these surfaces exist; this document states what they do.
+
+## Choosing the profile: `init` and `configure`
+
+`stdd init
+--capabilities <list>` writes the profile without hand-editing JSON
+(named capabilities on, the rest off), and `stdd init --interview` asks
+one question at a time — recommended answer first — then runs the same
+init. The interview also picks the reviewer route (`review.via`) and,
+for the selected native agents (Claude Code, Codex, and Pi), offers the
+lifecycle integration.
+When `crossCli` is selected, the first selected native host is the driver for
+the repository-level reviewer default and its opposite CLI is recorded:
+Claude → codex, Codex → claude, Pi → claude. Per-host generated skills use the
+same opposite-host rule explicitly, so a repository compiling multiple hosts
+never teaches Claude Code or Codex to review itself; Pi is a driver host, not a
+`stdd review --via` runner. With no dispatch capability, generated skills omit
+the `[review:]` claim and review commands entirely; manual self-review is never
+presented as an independent-review fallback.
+
+`stdd configure` re-runs the interview over an existing install, with
+the **current** values as the defaults. It edits only the capability
+profile and the review route — every other config key is preserved —
+and recompiles the same generated targets the last init produced (the
+manifest remembers them). It does not install or remove CI workflows,
+change CI target selection, or remove lifecycle hooks. Stop hooks are the
+explicit exception: a remembered Stop-hook target is maintained (and restored
+if missing), while `--stop-hook` opts in and may install it for the selected
+agents. Configure never adds pre-push or session hooks. Flag forms skip the
+questions: `--capabilities <list>`,
+`--review-via subagent|codex|claude`, `--max-rounds <n>` (the review
+budget; 0 = unlimited), `--stop-hook`. When the profile has a dispatch
+capability, an incompatible route (codex or claude without `crossCli`,
+subagent without `subagents`) is an error, never a silent downgrade to
+self-review. A profile with no dispatch capability may retain a dormant
+route because it emits no review claim; invoking or claiming review still
+requires an available route.
+
+## Agent host outputs
+
+For Codex (`--tools codex`), init compiles every active playbook to
+`.agents/skills/<name>/SKILL.md`, where Codex can select it implicitly from
+its description or the user can invoke it explicitly as `$<name>`. Init also
+maintains the repo's `AGENTS.md`: the short STDD section is written between
+`stdd:begin`/`stdd:end` marker comments. The file is created when absent, the
+marked section is replaced in place when present, and content outside the
+markers is never touched. The section is also saved to
+`.stdd/AGENTS-snippet.md` for manual composition.
+
+For Claude Code (`--tools claude`), the same playbooks compile to
+`.claude/skills/<name>/SKILL.md`, invocable as `/<name>` or selected
+implicitly. Init maintains the same short invariant block in `CLAUDE.md`,
+between the same managed markers, and saves it as
+`.stdd/CLAUDE-snippet.md`. `AGENTS.md` and `CLAUDE.md` stay user-owned and
+are never manifest-tracked; the generated snippets and native skills are
+manifest-tracked. The full method is never injected into every prompt:
+always-on files point to `.stdd/method.md`, while skills load their detailed
+workflow only when used.
+
+For Pi (`--tools pi`), init uses the Agent Skills standard registry at
+`.agents/skills/<name>/SKILL.md`, which Pi discovers natively and invokes as
+`/skill:<name>`. That output is byte-identical to Codex's skill files, so a
+repository selecting both hosts has one shared generated copy rather than
+duplicate skill names. Pi's short router lives in `.pi/APPEND_SYSTEM.md`, not
+`AGENTS.md`: this keeps Pi's `/skill:` syntax from overwriting Codex's `$`
+syntax when both hosts are selected. The append-system file is user-owned;
+init maintains only its marked STDD section and saves the generated source as
+`.stdd/PI-snippet.md`.
+
+## Adoption modes and the universal bundle
+
+STDD has three cumulative adoption modes. **Personal plugin** use installs the
+universal STDD bundle once through Codex, Claude Code, or Pi and changes no
+repository; its lazy skills remain available, while lifecycle integrations stay
+dormant outside a checkout containing `.stdd/`.
+**Shared repository contract** use runs `init` once and commits `.stdd/`, native
+agent routing, and repository policy. **Enforced contract** use explicitly adds
+repository-owned hooks or a CI adapter; ordinary `init` never creates CI, and
+CI reads checkout and review-request facts rather than the private ledger or
+agent state.
+
+Repo-local generated skills remain a valid team contract and need no plugin.
+The optional universal bundle at `plugins/stdd/` distributes one generated set
+of conservative-profile skills and one CLI runtime through native Codex and
+Claude Code plugin manifests or the `@stdd/plugin` Pi package. The runtime is
+generated from the same source and version as `@stdd/cli`; the adopting
+repository does not install that CLI package. The bundle never owns repository
+state: its lifecycle integration acts only when the checkout contains
+`.stdd/`; init, task state, policy, and optional CI stay with the repository.
+
+Codex and Claude Code use the bundle's fail-open SessionStart and Stop command
+hooks. If the bundled runtime cannot read an adopting checkout, SessionStart
+reports fixed update-or-reinitialize guidance and exits successfully; Stop
+returns the host's allow response without forwarding runtime output. Pi loads
+the same skills plus a package extension. On `session_start` and
+`session_compact`, that extension queues successful local status output for
+the next model turn; on `agent_settled`, it queues at most one corrective
+follow-up when the gate blocks. Runtime errors remain fail-open and are never
+sent into a model turn. The installed bundle version governs all three hosts'
+lifecycle commands.
+
+Repository-generated pre-push/session/stop hooks are a separate integration and continue to require the exact project-local package
+for pinned offline execution. The source-checkout command
+`npm run build:plugin` validates every host manifest and publishes the shared
+skills, Pi extension, runtime, and all six native mutation helpers through the
+same capability boundary as the CLI. Retired stale skills move to an
+identity-bound, non-loadable quarantine that remains available for explicit
+operator removal; subsequent builds keep recognized quarantines stable.
+
+## Project-local recipes
+
+Project-specific recipes live in `.stdd/playbooks/local/` — markdown
+playbooks with the same frontmatter contract (`name`, `description`,
+`when`, optional `requires`), owned by the repository and never
+overwritten by `stdd init`. They compile through the same pipeline as
+the kit's playbooks — capability blocks included — into each selected host's
+native skill registry. Always-on AGENTS/CLAUDE blocks remain a fixed, minimal
+router: they name the method, the project-local runner, and `.stdd/policy.md`,
+and do not enumerate either kit or project skills. A local recipe that
+reuses a kit playbook's `name` replaces it: project knowledge outranks the kit.
+Local recipe names must otherwise be unique; init rejects duplicates before
+writing generated state and names both conflicting source files.
+The three skills named by that router (`stdd-start-change`, `stdd-implement`,
+and `stdd-finish-change`) are mandatory; init rejects a profile or local
+override that would make one inactive. Other inactive local overrides still
+shadow their kit playbook intentionally.
+
+## CI adapters
+
+CI integration is an explicit, optional transport adapter around
+provider-neutral CLI contracts. `init` without `--ci` creates no provider file;
+a team may instead place the printed generic commands in an existing quality
+job. Every configured provider runs `stdd check`; a review pipeline pipes its
+live PR/MR description to `stdd check-pr - --base <ref>`. CI uses read-only
+repository and review-request access. It never attempts to prove the agent's
+reasoning, consume the ignored ledger, dispatch workers, or mutate Git: it
+grades only facts derivable from the checkout and review request.
+
+On GitHub, `stdd init --ci github` writes the canonical workflow for these
+gates and installs an explicit supported Node runtime. It fetches the PR body
+live from the API and re-runs on body edits —
+a workflow reading `github.event.pull_request.body` validates a payload
+frozen at trigger time, so an edited body is never re-checked and a re-run
+replays the stale text. The fetch uses node, not the gh CLI — node is
+already required to run stdd, while self-hosted runners often lack gh —
+and the step sets `pipefail`, so a failed fetch fails the gate as a fetch
+error instead of feeding check-pr an empty body that misreports as a
+missing evidence line. `stdd doctor` flags the frozen-payload form, and flags a PR
+template carrying an unquoted evidence label at the start of a line, since
+its placeholder residue would pass the gate on every PR.
+
+On GitLab, `stdd init --ci gitlab` writes an includeable
+`.gitlab/stdd.gitlab-ci.yml` job. It uses the merge-request API to fetch the
+live description, pipes it to `check-pr -`, and passes
+`CI_MERGE_REQUEST_DIFF_BASE_SHA` as the base. The job enables `pipefail`, so
+an API failure fails the gate instead of being mistaken for an empty body.
+Same-project pipelines authenticate with the short-lived `CI_JOB_TOKEN`.
+Because fork merge-request pipelines normally run in the source project, the
+target must allowlist that source for job-token access. A controlled trusted
+fork may instead supply a masked and hidden target-project
+`STDD_GITLAB_READ_API_TOKEN` with only `read_api`; target credentials are
+never safe in an untrusted fork pipeline. Authentication failure names the
+required setup instead of pretending fork access is automatic.
+`stdd init --ci generic` writes no provider file; it prints and records the
+portable command contract for teams to compose into Jenkins, Buildkite, or an
+existing pipeline. Provider templates are adapters, never dependencies of
+the method or public SDK.
+
+## Local hooks
+
+Locally, `stdd init --hooks` writes a pre-push hook that runs exactly one
+fast, offline command: `stdd check`. Nothing network-bound belongs in a
+hook — a flaky gate's false positives train `--no-verify`. The hook file
+is user-owned after generation (like `config.json`, it is not
+manifest-tracked and never overwritten), so teams append their own steps.
+stdd never touches `.git/`: install it via
+`git config core.hooksPath .stdd/hooks`, or call `stdd check` from an
+existing hook manager. `stdd doctor` reports whether the hook is wired
+up — informationally, never as a failure.
+
+Generated hooks invoke the project-local package offline and name the scoped
+package explicitly:
+`npm exec --offline --package=@stdd/cli@<generated-version> -- stdd`. They
+never ask npm to resolve the unrelated unscoped package `stdd`. Install
+`@stdd/cli` as an exact development dependency before wiring hooks. The
+`@stdd/cli` source repository is the one dogfood exception: its generated
+automation invokes `node "$(git rev-parse --show-toplevel)/cli/stdd.mjs"`
+directly, because the checkout being tested is the package source and may not
+exist in npm's offline cache yet.
+
+For selected native agents, `stdd init --session-hook` wires the session-start
+ritual mechanically. Claude Code and Codex each get one `SessionStart` hook
+(`startup|resume|clear|compact`) in their native settings. Pi gets a
+project-local `.pi/extensions/stdd.js` extension that runs the same command on
+`session_start` and `session_compact`, then queues its output for the next
+model turn. The `compact` source is the single context-restoration path;
+re-init removes older managed Claude `PostCompact` entries to avoid running the
+ritual twice, while preserving unrelated user hooks. Each integration runs
+`stdd status --local`, which never calls a forge or the network, so every fresh
+context opens with local loop state and the next step already in it — recorded
+state instead of recall. Hook entries are merged into existing valid files
+without duplication. A conflicting Pi extension or invalid JSON settings are
+left untouched and a manual instruction is printed instead. Codex hooks and
+Pi project extensions remain subject to their host's repository trust review.
+
+`stdd init --stop-hook` (opt-in, also offered by the interview and
+`stdd configure`) wires the other end of the selected native agents. Claude
+Code and Codex receive a `Stop` hook running the agent-specific
+`stdd stop-hook` protocol, which applies the same judgment as `status --gate`
+when the agent tries to finish. Pi has no pre-stop veto event; its project
+extension checks the same gate at `agent_settled` and queues at most one
+corrective follow-up turn when blocked. It then fails open rather than creating
+an unbounded feedback loop, so this is visible corrective continuation, not a
+hard stop guarantee. Broken claims — a
+checked-but-unproven `[review:]` item, a changes-requested or stale
+verdict — block the stop with the reasons fed back; unfinished work
+never does, the same as the gate. The command respects
+`stop_hook_active` (a blocked stop is never re-blocked into a loop) and
+fails open: an internal error exits zero, because a broken hook must
+not trap the session. Claude blocks with exit 2 and stderr; Codex exits 0
+with its documented `Stop` continuation JSON (`decision: "block"` plus
+`reason`); an empty JSON object allows a clean stop. The Codex boundary accepts
+exactly `{}`, or exactly the two keys `decision` and `reason`, where the
+decision is `"block"` and the reason is a string with non-whitespace content.
+It emits compact JSON without changing valid reason text. Extra or missing
+keys, whitespace-only reasons, arrays, primitives, malformed or empty output,
+and nonzero child results all fail open as `{}`.
+Pi treats command failures as fail-open and never sends their output into a
+model turn. Merging rules match the session hook.

package/runtime/package.json

@@ -0,0 +1,65 @@
+{
+	"name": "@stdd/cli",
+	"version": "0.9.0",
+	"description": "Spec + Test Driven Development — a markdown-first methodology kit for teams building software with AI coding agents",
+	"type": "module",
+	"exports": {
+		".": {
+			"types": "./sdk/index.d.ts",
+			"import": "./sdk/index.mjs"
+		}
+	},
+	"types": "./sdk/index.d.ts",
+	"bin": {
+		"stdd": "cli/stdd.mjs"
+	},
+	"files": [
+		"cli/",
+		"sdk/",
+		"method/",
+		"playbooks/",
+		"templates/",
+		"adapters/",
+		"prebuilds/"
+	],
+	"scripts": {
+		"test": "node --test",
+		"test:harness": "node scripts/agent-contract.mjs",
+		"build:plugin": "node scripts/build-plugin.mjs",
+		"check": "biome ci .",
+		"format": "biome check --fix .",
+		"selfcheck": "node cli/stdd.mjs check ."
+	},
+	"engines": {
+		"node": ">=20"
+	},
+	"keywords": [
+		"sdd",
+		"tdd",
+		"stdd",
+		"spec-driven-development",
+		"test-driven-development",
+		"ai-agents",
+		"claude-code",
+		"codex",
+		"pi-coding-agent",
+		"methodology",
+		"workflow"
+	],
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/vsem-azamat/stdd.git"
+	},
+	"bugs": {
+		"url": "https://github.com/vsem-azamat/stdd/issues"
+	},
+	"homepage": "https://github.com/vsem-azamat/stdd#readme",
+	"author": "Azamat Almazbek uulu",
+	"license": "MIT",
+	"devDependencies": {
+		"@biomejs/biome": "^2.3.8"
+	},
+	"directories": {
+		"test": "test"
+	}
+}

package/runtime/playbooks/brainstorming.md

@@ -0,0 +1,46 @@
+---
+name: stdd-brainstorming
+description: Shape a fuzzy idea into an agreed behavior contract before any plan or code
+when: A non-trivial change is requested and the requirements, scope, or approach are not yet pinned down.
+---
+
+# Brainstorming
+
+The goal is agreement on **what** and **why** before anyone invests in **how**.
+The output is not a document — it is a shared understanding that becomes a
+docs edit and a PR description.
+
+## Process
+
+1. **Understand the current state first.** Read the relevant docs and the code
+   the change will touch. Questions asked from ignorance waste the other
+   side's time; questions asked from knowledge sharpen the idea.
+2. **Ask one question at a time.** Prefer questions that eliminate whole
+   branches of the design space: who is it for, what triggers it, what must
+   never happen, what is explicitly out of scope. When the answer space is
+   enumerable, offer it as a closed choice with your recommendation first —
+   a closed question costs the other side seconds, an open one minutes.
+   Keep open questions for genuinely open design space.
+3. **Challenge scope creep in both directions.** If the idea is bigger than
+   the need, say so and propose the smaller version. If the stated need hides
+   a larger real problem, surface it.
+4. **Propose 2–3 approaches with a recommendation.** For each: one paragraph,
+   the trade-off that actually matters, and what it costs later. Recommend
+   one; do not present a menu without an opinion.
+5. **Converge on the behavior contract.** State the agreed behavior as rules
+   precise enough to test. Confirm them explicitly.
+
+## Output
+
+- The agreed rules become the **docs edit** (the spec) — the first commit of
+  the branch.
+- The rationale, rejected alternatives, and scope decisions go into the
+  **PR description** when the branch opens.
+- Nothing from this conversation is committed as a standalone file.
+
+## Anti-patterns
+
+- Jumping to implementation detail while behavior is still unsettled.
+- Asking multiple stacked questions at once.
+- Writing a "spec document" instead of editing the real docs.
+- Agreeing silently: if you disagree with the direction, say so with reasons.