@mdferdousalam/agentic-sdlc 0.0.0-stage → 3.0.0

package/docs/control-spec.md

@@ -0,0 +1,269 @@
+# The Agent Engineering Control Specification
+
+Version 1. Every agent in this pipeline is held to this document, and no agent may invent a
+standard that contradicts it. [`docs/rules.md`](rules.md) is the prose every stage reads; this
+is the machine-facing half — the vocabularies, the repair policy, and the rule table that says
+how each class of problem is detected, what evidence it needs, and who is allowed to fix it.
+
+It exists because a security reviewer, an architecture reviewer and a repair agent that each
+decide for themselves what "high severity" means will disagree in ways nobody can audit.
+
+---
+
+## 1. The four vocabularies
+
+They are separate on purpose. Collapsing any two of them is how an unverified fix gets shipped
+as a verified one.
+
+### 1.1 Outcome of a criterion — the five words
+
+**`passed` · `failed` · `skipped` · `refused` · `unexecuted`**
+
+Defined in [`docs/rules.md`](rules.md) §3 and unchanged by this document. They describe whether
+an acceptance criterion holds. A test that did not run is `unexecuted`, never `passed`.
+
+### 1.2 Outcome of a finding — the six words
+
+A finding is a claim about the code, so it closes differently from a criterion.
+
+| Word | Means |
+| --- | --- |
+| `open` | Raised, not yet addressed. |
+| `fixed` | The behaviour changed and a test proves it. |
+| `refused` | The finding is wrong, with the reason and the evidence. |
+| `deferred` | Real, out of this unit of work's scope, filed where it will be seen. |
+| `unexecuted` | The fix could not be verified. **This is not closed.** |
+| `escalated` | Awaiting a human decision. |
+
+`fixed`, `refused`, `deferred` and `unexecuted` are the words `sdlc-remediator` already uses;
+`open` and `escalated` extend them for findings that have not reached the remediator yet.
+
+### 1.3 Severity — how bad it is if real
+
+| Severity | Examples |
+| --- | --- |
+| `critical` | Authentication bypass, data corruption, exploitable injection. |
+| `high` | Memory-safety defect, race condition, broken authorization, destructive migration. |
+| `medium` | Performance regression, missing edge case, incorrect retry policy. |
+| `low` | Formatting, lint, a safe mechanical refactor. |
+| `advisory` | An architectural trade-off, a speculative optimisation, a disputed pattern. |
+
+`advisory` is not a weak `low`. It means **report evidence and alternatives; do not force a code
+change.** An agent that turns an advisory into a commit has exceeded its authority.
+
+### 1.4 Confidence — how sure we are it is real
+
+| Confidence | Earned by |
+| --- | --- |
+| `high` | A deterministic tool said so, or there is a reproduction. |
+| `medium` | A strong reading of the code, without execution. |
+| `low` | A pattern match or a suspicion. |
+
+**Severity and confidence are independent, and this is the point of the whole document.** A
+low-confidence fix for a critical vulnerability is not safe merely because the agent believes it
+has solved the problem. Never raise confidence to justify a repair you want to make.
+
+### 1.5 Detection method
+
+`deterministic` (compiler, analyser, scanner) · `test` · `runtime` (profiler, sanitiser,
+production telemetry) · `llm`.
+
+Recorded on every finding, because a reader weighs the four differently. The standing rule —
+[`docs/rules.md`](rules.md) and the brief both say it — is **tools before opinions**: prefer a
+compiler diagnostic, a static analyser, a scanner or a reproducible test to an unsupported
+claim. An `llm` finding is not worthless; it is a finding whose confidence has not yet been
+earned by anything but reading.
+
+---
+
+## 2. The repair policy
+
+What an agent may do about a finding is a function of **severity and confidence together**,
+never severity alone.
+
+| | `high` confidence | `medium` confidence | `low` confidence |
+| --- | --- | --- | --- |
+| **`critical`** | Fix on an isolated branch, full verification, **human approval to merge** | Escalate with evidence | Escalate; do not touch the code |
+| **`high`** | Fix, full verification, human approval where the project asks for one | Fix only with a reproduction first; otherwise escalate | Escalate |
+| **`medium`** | Fix and regression-test | Fix if the repair is constrained; otherwise report | Report |
+| **`low`** | Fix automatically when deterministic rules and tests establish safety | Fix | Report |
+| **`advisory`** | Report evidence and alternatives. Never an automatic code change, at any confidence. | — | — |
+
+`proposedRepair.autofixEligible` on a finding is this table's answer, written down. An agent that
+sets it to `true` outside this table is making a policy decision it does not own.
+
+### 2.1 Constraints on every repair
+
+These hold whatever the cell above says:
+
+1. **Minimal.** Do not rewrite a module to fix a localised defect.
+2. **Reproduce first.** A finding you cannot reproduce may be wrong. Say so rather than changing
+   code to satisfy a reviewer you do not believe.
+3. **A failing test first**, where the finding is behavioural. A fix with no failing test behind
+   it is a guess that happens to compile.
+4. **Re-verify the patch itself.** Evidence from before the change does not validate the change.
+5. **One finding per commit**, so each can be reverted or reviewed alone.
+6. **Never weaken the gate.** No deleted test, no weakened assertion, no suppressed warning, no
+   lowered threshold, no newly excluded path — unless the suppression *is* the correct
+   resolution and the commit message says why. This is the one failure the pipeline exists to
+   prevent, and `TEST-SUITE-WEAKENED` below detects it mechanically rather than trusting the
+   prohibition.
+7. **Bounded retries.** After three real attempts at the same finding, stop and report. The
+   specification or the approach is usually the problem, not the code.
+
+---
+
+## 3. The taxonomy, and what this pipeline actually checks
+
+Findings are addressed by domain. Being honest about coverage is part of the specification: an
+auditor needs to know what was *not* looked for.
+
+| Domain | Subject | Checked by | Coverage |
+| --- | --- | --- | --- |
+| **A** | Requirements and system design | `sdlc-spec-writer`, `sdlc-spec-reviewer`, `sdlc-verifier` | full |
+| **B** | Architecture and system structure | `sdlc-architecture-reviewer`, `concerns/architecture` | review-level |
+| **C** | Code correctness and implementation | `verifyCmd`, `sdlc-code-reviewer` | compile/type full, logic review-level |
+| **D** | Security and trust boundaries | `sdlc-security-reviewer`, `secretScan` | full |
+| **E** | Performance and computational efficiency | `concerns/performance` | review-level; no runtime measurement |
+| **F** | Memory, resources and lifecycle | `concerns/memory` | review-level; no allocation tracing |
+| **G** | Concurrency and parallelism | `concerns/concurrency` | review-level; no race detector |
+| **H** | Testing and verification | `sdlc-verifier`, `sdlc-test-author`, `TEST-*` rules | full |
+| **I** | Code quality and maintainability | `sdlc-code-reviewer`, `quality.cmd` | depends on your analyser |
+| **J** | Design patterns and principles | `concerns/architecture` | review-level |
+| **K** | Database and data integrity | `concerns/data`, `profiles/webapp` | review-level |
+| **L** | APIs and integration contracts | `sdlc-code-reviewer`, `profiles/library` | review-level |
+| **M** | Reliability and fault tolerance | `profiles/service` | review-level |
+| **N** | Scalability and capacity | `concerns/performance` | review-level |
+| **O** | Build, dependencies, supply chain | `sdlc-security-reviewer`, your dependency audit | partial — no SBOM, no licence check |
+| **P** | Infrastructure, deployment, configuration | `sdlc-release-manager` | deploy and rollback only |
+| **Q** | Observability and diagnostics | `profiles/service` | review-level |
+| **R** | Frontend, UX, accessibility | `profiles/webapp` | review-level |
+| **S** | Platform-specific correctness | `concerns/platform` | review-level |
+| **T** | Documentation, governance, compliance | `sdlc-reporter`, receipts, `sdlc trace` | full |
+| **U** | AI, LLM and agent-specific risks | the hook, per-agent tool limits, `docs/rules.md` §7 | full |
+
+### Cross-cutting domains
+
+| Domain | Subject | Control |
+| --- | --- | --- |
+| **X1** | Change impact analysis | `sdlc-impact-analyst` |
+| **X2** | Compatibility and versioning | `profiles/library`, `IMPACT-PUBLIC-SHAPE` |
+| **X3** | Developer/agent concurrency | dirty-tree refusal, upstream-drift check, worktree isolation |
+| **X4** | Automated repair correctness | §2.1 above, `TEST-SUITE-WEAKENED` |
+| **X5** | Cost and resource economics | `budget` in `sdlc.config.json` |
+| **X6** | Product and operational correctness | `profiles/webapp`, `concerns/data` |
+| **X7** | Agent economics and execution safety | `budget`, bounded retries, `sdlc feedback` |
+| **X8** | Environment and toolchain integrity | environment fingerprint on every receipt |
+| **X9** | Human-agent collaboration and git hygiene | path-scoped commits, PR body contract, finding dedup |
+| **X10** | State resilience and checkpointing | `sdlc checkpoint`, receipt revalidation |
+| **X11** | Test reliability and semantic regression | baseline comparison, `TEST-*` rules |
+| **X12** | Change governance and review quality | receipts, `.sdlc/audit.log`, `sdlc trace` |
+
+**Review-level** means an agent reads the diff against written standards. It is real review and
+it finds real defects, but it is not a measurement. A memory leak usually needs allocation
+evidence; a performance claim needs a representative workload; a race usually needs a detector.
+Where the stack has such a tool, put it in `quality.cmd` and the finding becomes `deterministic`.
+This plugin ships no analysers and must not pretend otherwise.
+
+---
+
+## 4. The rule table
+
+Rules the pipeline enforces today. Each has a stable `ruleId` that a finding cites, so a rule can
+be traced across versions. A renamed rule is a new rule.
+
+| Rule ID | Domain | Detection | Default severity | Autofix | Evidence required |
+| --- | --- | --- | --- | --- | --- |
+| `SPEC-UNFALSIFIABLE` | A.6 | llm | high | no | the requirement, and why it cannot fail |
+| `SPEC-SCOPE-UNSTATED` | A.7 | llm | medium | no | the missing "out of scope" section |
+| `SPEC-DUPLICATE` | A.7 | llm | medium | no | the adjacent spec that owns it |
+| `SPEC-INVALID` | A.6 | deterministic | high | no | `openspec validate --strict` output |
+| `BUILD-FAILS` | C.19 | deterministic | critical | no | `verifyCmd` output |
+| `TYPE-ERROR` | C.20 | deterministic | high | yes (low risk only) | the type-checker diagnostic |
+| `CODE-SCOPE-CREEP` | A.7 | llm | medium | no | the hunk no requirement asked for |
+| `CODE-ERROR-SWALLOWED` | C.25 | llm | high | no | `file:line` of the swallowed path |
+| `SEC-AUTHORITY` | D.30 | llm | critical | no | the bypassable check, at `file:line` |
+| `SEC-INJECTION-SQL` | D.31 | llm | critical | no | the interpolation site |
+| `SEC-INJECTION-SHELL` | D.31 | llm | critical | no | the interpolation site |
+| `SEC-UNTRUSTED-INPUT` | D.38 | llm | high | no | the parser and its hostile-input test, or its absence |
+| `SEC-SECRET-PRESENT` | D.36 | deterministic | critical | no | `secretScan` output |
+| `SEC-DEPENDENCY-NEW` | O.151 | llm | medium | no | the lockfile diff and the justification |
+| `SEC-DATA-EXPOSURE` | D.41 | llm | high | no | what now reaches a log or a response |
+| `SEC-DOS-UNBOUNDED` | D.42 | llm | high | no | the unbounded allocation, query or loop |
+| `TEST-CRITERION-UNEXECUTED` | H.76 | test | high | no | the criterion with no test outcome |
+| `TEST-ASSERTION-ABSENT` | H.77 | llm | high | no | the test that asserts only that code ran |
+| `TEST-SUITE-WEAKENED` | X4 | deterministic | critical | **never** | the diff hunk deleting or weakening the check |
+| `TEST-BASELINE-REGRESSION` | H.79 | deterministic | high | no | baseline comparison showing a newly failing test |
+| `QUALITY-BUDGET` | I.97 | deterministic | medium | no | `quality.cmd` output |
+| `IMPACT-PUBLIC-SHAPE` | X2 | llm | high | no | the changed interface and its consumers |
+| `IMPACT-DEPENDENT-BROKEN` | X1 | llm | high | no | the dependent that no longer compiles or holds |
+| `ARCH-LAYER-DIRECTION` | B.12 | llm | high | no | the import that crosses the wrong way |
+| `ARCH-CYCLE` | B.11 | llm | medium | no | the cycle, as a path |
+| `ENV-TOOLCHAIN-DRIFT` | X8 | deterministic | medium | no | the expected and actual tool versions |
+| `BUDGET-EXCEEDED` | X7 | deterministic | high | no | the limit and the measurement |
+| `GIT-WORK-DESTROYED` | X3 | deterministic | critical | **never** | the refused command |
+
+### Concern rules
+
+Raised only where `concerns` in the config enables them. Each concern profile names the
+deterministic tool for the stacks that have one; until that tool is in `quality.cmd`, these are
+`llm` findings at `medium` confidence at best, and must say so.
+
+| Rule ID | Domain | Detection | Default severity | Autofix | Evidence required |
+| --- | --- | --- | --- | --- | --- |
+| `ARCH-UNDECLARED` | B.18 | llm | advisory | no | that the project states no structure anywhere |
+| `ARCH-BOUNDARY-REACH` | B.14 | llm | medium | no | the access past the interface |
+| `ARCH-COHESION` | B.13 | llm | advisory | no | the module's second responsibility |
+| `ARCH-INDIRECTION-UNPAID` | J.104 | llm | advisory | no | the abstraction and its single user |
+| `PERF-N-PLUS-ONE` | E.50 | llm | high | no | the query inside the loop |
+| `PERF-UNPAGINATED` | E.51 | llm | high | no | the list endpoint with no bound |
+| `PERF-HOT-PATH-WORK` | E.43 | llm | medium | no | the work repeated per call |
+| `PERF-CACHE-UNSPECIFIED` | E.52 | llm | medium | no | the missing invalidation answer |
+| `PERF-SCALE-LIMIT-UNSTATED` | N.144 | llm | medium | no | the unbounded dimension |
+| `MEM-UNBOUNDED` | F.62 | llm | high | no | the collection with no eviction or bound |
+| `MEM-LEAK` | F.60 | runtime | high | no | allocation evidence over time |
+| `MEM-CLEANUP-MISSING` | F.63 | llm | high | no | the exit path with no release |
+| `MEM-SAFETY` | F.57 | deterministic | critical | no | the sanitiser or checker output |
+| `CONC-DATA-RACE` | G.66 | runtime | high | no | the detector's report |
+| `CONC-DEADLOCK-ORDER` | G.67 | llm | high | no | the two lock orders |
+| `CONC-TOCTOU` | G.68 | llm | high | no | the check and the act, with the window |
+| `CONC-TASK-LEAK` | G.72 | llm | medium | no | the spawned task nobody holds |
+| `CONC-NO-TIMEOUT` | G.73 | llm | medium | no | the call with no bound |
+| `CONC-BACKPRESSURE` | G.74 | llm | medium | no | the unbounded channel or queue |
+| `DATA-CONSTRAINT-MISSING` | K.110 | llm | medium | no | the invariant held only in code |
+| `DATA-TRANSACTION-BOUNDARY` | K.111 | llm | high | no | the side effect inside the transaction |
+| `DATA-MIGRATION-IRREVERSIBLE` | K.114 | llm | high | no | the step with no stated way back |
+| `DATA-IDEMPOTENCY` | K.116 | llm | high | no | the retryable operation with no key |
+| `DATA-PRECISION` | K.117 | llm | medium | no | the float money, or the zoneless time |
+| `PLAT-HOST-ASSUMPTION` | S.189 | llm | medium | no | the hardcoded path, separator or case |
+| `PLAT-NUMERIC` | S.191 | llm | high | no | the overflow or narrowing cast |
+| `PLAT-LOCALE` | S.194 | llm | medium | no | the locale-dependent comparison |
+| `PLAT-SHUTDOWN` | S.195 | llm | medium | no | the in-flight work on termination |
+
+### Adding a rule
+
+A new rule needs: an ID in an existing namespace, a taxonomy address, a detection method, a
+default severity, an autofix answer that follows §2, and the evidence a finding must carry. Add
+the row here first. A rule that exists only inside an agent's prompt is not a rule — it is that
+agent's opinion, and the next agent will disagree with it.
+
+---
+
+## 5. The finding contract
+
+Every finding, from an agent or a tool, validates against
+[`schema/finding.schema.json`](../schema/finding.schema.json) and is written with:
+
+```sh
+sdlc finding write --rule SEC-INJECTION-SQL --severity critical --confidence high \
+  --file src/db/query.ts --line 42 --summary "user input is concatenated into SQL"
+sdlc finding list --open
+sdlc finding close F-1a2b3c4d --outcome fixed --commit <sha>
+```
+
+Findings live in `.sdlc/findings/`. They are local to a working copy, like receipts — see the
+honest limits in [`docs/compliance.md`](compliance.md).
+
+**Require structured results, and independently validate every one.** Valid JSON is not proof of
+correct reasoning. The readiness gate checks the evidence behind a finding; it does not accept
+the classification an agent gave itself.

package/docs/install.md

@@ -0,0 +1,75 @@
+# Installing
+
+Six ways in. They all land on the same CLI; pick whichever matches how you already install
+things. Everything needs `git` and Python 3.8+ — there are no Python dependencies.
+
+| Route | Command | Needs |
+| --- | --- | --- |
+| **Claude Code plugin** | `/plugin marketplace add mdferdousalam/agentic-sdlc` then `/plugin install agentic-sdlc` | Claude Code |
+| **Shell** | `curl -fsSL https://raw.githubusercontent.com/mdferdousalam/agentic-sdlc/main/install.sh \| sh` | curl |
+| **npm** | `npx @mdferdousalam/agentic-sdlc install` | Node 16+ |
+| **PyPI** | `uvx --from agentic-sdlc-cli sdlc install` or `pipx install agentic-sdlc-cli` | Python |
+| **Homebrew** | `brew install mdferdousalam/tap/agentic-sdlc` | macOS/Linux |
+| **Codex plugin** | `codex plugin marketplace add mdferdousalam/agentic-sdlc` then `codex plugin add agentic-sdlc@agentic-sdlc` | Codex CLI |
+| **Gemini extension** | `gemini extensions install https://github.com/mdferdousalam/agentic-sdlc` | Gemini CLI |
+| **Git clone** | `git clone … && agentic-sdlc/bin/sdlc install` | git |
+
+Then, in the repository you work in:
+
+```sh
+sdlc install     # detect your agents, set each one up, add the git hooks
+sdlc doctor      # what is configured, what is missing, and the command for each gap
+```
+
+## A note on the Codex plugin route
+
+Installing the Codex plugin brings its `PreToolUse` hook with it, but **Codex will not run a
+plugin's hook until you trust it**. On your next interactive session Codex shows the hook for
+review; trust it once and enforcement is live. Verified: untrusted, only `Stop` fires and a
+`git stash` goes through; trusted, the same command is refused.
+
+If you would rather not deal with the review prompt, `sdlc install codex` writes the hook into
+your own `~/.codex/hooks.json` instead, which Codex treats as already trusted because it is
+your configuration. That path is verified working, including the receipt-dependent push gate.
+
+Never pass `--dangerously-bypass-hook-trust` as a workaround. It disables review for *every*
+hook in the session, not just this one.
+
+## A note on `curl | sh`
+
+Piping a script from the internet into a shell is a real risk and you should not take anyone's
+word for it. [`install.sh`](../install.sh) is about sixty lines, and it downloads a release
+into `~/.agentic-sdlc`, links `sdlc` into a bin directory already on your `PATH`, and touches
+nothing in your repository. No sudo. Read it first if you prefer:
+
+```sh
+curl -fsSL https://raw.githubusercontent.com/mdferdousalam/agentic-sdlc/main/install.sh -o install.sh
+less install.sh && sh install.sh
+```
+
+Pin a version with `AGENTIC_SDLC_VERSION=v2.2.0`, or relocate it with `AGENTIC_SDLC_HOME`.
+
+## Uninstalling
+
+```sh
+sdlc uninstall              # remove our blocks and the files we own from this repository
+rm -rf ~/.agentic-sdlc      # shell install
+npm rm -g @mdferdousalam/agentic-sdlc
+pipx uninstall agentic-sdlc-cli
+brew uninstall agentic-sdlc
+```
+
+`sdlc uninstall` removes only our marked blocks and the files we own. Your `AGENTS.md`,
+Copilot instructions and existing git hooks keep everything that was yours.
+
+## Maintainer: cutting a release
+
+```sh
+packaging/build-pypi.sh --check     # builds dist/, installs the wheel in a venv, runs it
+python3 -m twine upload dist/*      # PyPI
+npm publish --access public         # npm
+```
+
+Then bump `url`, `version` and `sha256` in `packaging/homebrew/agentic-sdlc.rb`
+(`curl -fsSL <url> | shasum -a 256`) and copy it into the tap. `package.json` and
+`.claude-plugin/plugin.json` must agree on the version — CI checks that.

package/docs/maturity.md

@@ -0,0 +1,129 @@
+# The four levels, and how to configure each one
+
+Adopting this pipeline is not a switch. The industry framing that holds up best describes the
+human's role changing as a platform matures — from executor, to validator, to orchestrator, to
+constraint-setter. The stages do not disappear; what changes is who initiates them and what
+governs the handoff.
+
+Here that is not an abstraction: each level is a configuration. Start at the level that matches
+the trust you actually have, and move up when the metrics say you have earned it.
+
+## Level 1 — the human executes, agents assist
+
+You direct the work and approve each step. The pipeline runs, but you are inside every stage.
+
+```jsonc
+{ "approvals": { "merge": "human", "release": "human" },
+  "enforce": { "pushToTrunkNeedsGate": true, "mergeNeedsReadiness": true,
+               "branchNeedsApprovedSpec": false } }
+```
+
+Specifications are optional here; the refusals that protect your working tree are not. Use
+`/agentic-sdlc:feature` by hand, read every diff.
+
+**Move up when:** you stop finding surprises in the diffs.
+
+## Level 2 — the human validates
+
+Agents produce whole units of work; you verify behaviour rather than inspect every line. This
+is where the pipeline starts to pay for itself, and where most teams should sit.
+
+```jsonc
+{ "approvals": { "merge": "human", "release": "human" },
+  "enforce": { "branchNeedsApprovedSpec": true, "mergeNeedsReadiness": true },
+  "reviewers": ["sdlc-code-reviewer", "sdlc-security-reviewer"],
+  "quality": { "cmd": "<your static analysis>", "coverageNewPct": 80 } }
+```
+
+The specification becomes mandatory, because at this level an unclear intent does not slow
+someone down — it produces a confident, wrong pull request. Validation becomes a loop:
+candidate → gate → failure routed back as enriched context → retry. `sdlc feedback` is what
+makes the retry smarter than the attempt before it.
+
+**Move up when:** `sdlc metrics` shows the gate passing first-time more often than not, and the
+refusals that fire are near-misses rather than workflow problems.
+
+## Level 3 — the human orchestrates
+
+Agents run long tasks unattended. Work arrives from signals — a failing dependency check, an
+advisory, a pattern in production telemetry — through `/agentic-sdlc:triage`. You set the rules
+and review the exceptions.
+
+```jsonc
+{ "approvals": { "merge": "agent", "release": "human" },
+  "enforce": { "branchNeedsApprovedSpec": true, "mergeNeedsReadiness": true },
+  "release": { "deployCmd": "...", "smokeCmd": "...", "rollbackCmd": "...",
+               "environments": ["staging", "production"] } }
+```
+
+Merging becomes rule-based for work that passed every gate; **deployment stays human**. The
+constraint stops being review bandwidth and becomes the quality of your gates: at this level
+the readiness gate is the only thing between an agent and your trunk, so a gate that does not
+really check is now a direct risk rather than a missed opportunity.
+
+**Move up when:** your post-deploy evidence is good enough that you would trust a rollback
+decision made without you. Most teams should not.
+
+## Level 4 — the human sets constraints
+
+Paths run from signals without a human trigger, inside boundaries you defined. This is a
+horizon, not a destination to rush: it requires evaluation infrastructure, workspace isolation,
+cost governance and incident response that most organisations have not built. This plugin gives
+you the gates and the audit trail; it does not give you those.
+
+Be honest about where you are. Running at level 3 with level 1 gates is not maturity, it is
+unmanaged risk with better vocabulary.
+
+## What this still does not give you
+
+Being specific about the gaps is part of the tool. Each of these is real, each is named in the
+research this pipeline is built from, and none of them can be honestly claimed by a package of
+markdown and one dependency-free script.
+
+**Detection precision and recall.** `sdlc metrics` reports what the pipeline *did*, never how
+much it *missed*. Precision and recall need a corpus of seeded defects with known answers, and
+no repository has that about itself. If you need the numbers: take a tagged commit, inject a
+set of defects you choose — an off-by-one, a missing authorization check, an unbounded
+collection, a race — run the pipeline against each, and count what it found and what it
+invented. Run it again when you change a prompt. Without that, "the reviewers are good" is an
+impression.
+
+**Runtime evidence.** Profiling, allocation tracing, race detection under load, fuzzing,
+mutation testing and fault injection all need to *run* the system under conditions this tool
+does not create. The concern profiles name the tool for each and point at the `quality.cmd`
+seam; putting one there is what turns a `medium`-confidence reading into a `high`-confidence
+measurement. Until you do, `PERF-*`, `MEM-*` and `CONC-*` findings are careful opinions.
+
+**Token and money accounting.** `budget` counts tool calls and wall-clock because those are
+observable from inside a repository. It cannot see your host's token meter. A ceiling that
+stops the work is worth more than a number that describes the overspend afterwards, but it is
+not the same thing as cost control, and this does not pretend otherwise.
+
+**Workspace isolation at scale.** `git worktree` separates two tasks. It does not sandbox an
+agent's filesystem or network, and the hook is not a security boundary against a process that
+simply does not call it. See `docs/compliance.md`.
+
+**Anything outside the repository.** Incident response, on-call, vendor risk, organisational
+policy, training, and the people who have to live with a bad deploy.
+
+## What to watch as you climb
+
+```sh
+sdlc metrics --since 2026-01-01
+```
+
+- **First-pass gate rate rising** → the specifications are getting clearer.
+- **First-pass rate at 100%** → your gate is not checking anything. That is a finding.
+- **The same refusal firing repeatedly** → a workflow problem, not a near-miss. Fix the
+  workflow, do not relax the rule.
+- **Blocking findings rising while velocity rises** → the verification debt the research warns
+  about. Slow down before it compounds.
+- **`unexecuted` findings accumulating** → fixes are being declared without being proved. This
+  is the number that quietly becomes a lie, because every one of them *looks* closed.
+- **False-fix rate above zero** → work is coming back after being closed `fixed`. One is
+  normal; a trend means the verification step is not verifying.
+- **Reproducible share falling** → findings are increasingly claims rather than observations,
+  and the repair policy will escalate more of them. That is the policy working, and a sign the
+  reviewers need a deterministic tool rather than more prompt.
+- **`sdlc tests audit` firing often** → the gate is being treated as an obstacle rather than a
+  standard. Find out why before raising the threshold back.

package/docs/opencode.md

@@ -0,0 +1,45 @@
+# Using the pipeline with opencode
+
+[opencode](https://opencode.ai) has agents, commands and plugins, but no plugin marketplace, so
+the same pipeline is installed by copying it in:
+
+```sh
+bin/sdlc-install-opencode            # ~/.config/opencode by default
+opencode reload                      # a stale background server shows none of it
+sdlc doctor                          # in the repository you will work in
+```
+
+Options: `--prefix <dir>`, `--model <provider/model>` (pin every agent to one model),
+`--dry-run`.
+
+## What the installer changes, and why
+
+| Claude Code | opencode |
+| --- | --- |
+| `tools: [Read, Bash, Grep]` in frontmatter | `permission: { edit: deny, bash: allow }` |
+| `${CLAUDE_PLUGIN_ROOT}` | this checkout's absolute path |
+| `hooks/hooks.json` → `PreToolUse` | `plugins/agentic-sdlc.ts` → `tool.execute.before` and `shell.create.before` |
+| `/agentic-sdlc:land` | `/sdlc-land` |
+
+An agent whose Claude Code frontmatter lists no writing tool becomes `edit: deny` — so the
+reviewers and the gate genuinely cannot edit, which in opencode is enforced by the host rather
+than by the agent's good intentions.
+
+## One rule set, two hosts
+
+Both hosts call the same `bin/sdlc guard` with the same JSON and treat exit code 2 as a block.
+There is one place to fix a rule and no way for the two to drift. If the guard cannot run at
+all, it stays silent rather than taking the session down — enforcement that breaks your editor
+gets uninstalled, and then you have none.
+
+## Re-running
+
+Re-run the installer after pulling a new version. It overwrites only the files it owns:
+`agents/sdlc-*.md`, `commands/sdlc-*.md`, `plugins/agentic-sdlc.ts`.
+
+## With free or small models
+
+The pipeline was built partly for this case. Small models are not careless so much as
+forgetful: they skip a stage, not out of malice but because nothing stopped them. Receipts and
+the hook are exactly that stop. Pin the bigger model you have to the reviewers and the gate
+(`reviewers` in the config, `--model` at install) and let a cheaper one implement.

package/docs/openspec.md

@@ -0,0 +1,58 @@
+# OpenSpec integration
+
+[OpenSpec](https://github.com/Fission-AI/OpenSpec) is spec-driven change governance: proposals,
+designs, task lists and delta specs in a layout tools can read. This pipeline uses it as the
+specification engine whenever it is present, because three of its properties are things a
+pipeline needs and prose cannot give.
+
+## Why it earns its place here
+
+**A validator.** `openspec validate <id> --strict --json` fails on a malformed
+specification. The spec reviewer runs it first and quotes the failure, so "changes-requested"
+is sometimes a machine's verdict rather than a model's opinion.
+
+**A task list that is the acceptance criteria.** `tasks.md` is one checklist item per
+deliverable. The implementer ticks each in the commit that did it; the verifier maps each to
+`file:line` and a test outcome; the readiness gate treats a ticked unfinished item as a blocker.
+Progress stops being a feeling.
+
+**An archive.** `openspec archive <id>` moves a landed change out of the active list, so
+`openspec list` keeps describing reality rather than accumulating finished work.
+
+## Setup
+
+```sh
+npm install -g @fission-ai/openspec    # or your package manager of choice
+openspec init                          # once per repository
+/agentic-sdlc:init --write             # detects openspec and sets spec.engine
+```
+
+## The mapping
+
+| Pipeline idea | OpenSpec artefact |
+| --- | --- |
+| Why this work exists | `openspec/changes/<id>/proposal.md` |
+| What was chosen, over what | `<id>/design.md` |
+| Acceptance criteria | `<id>/tasks.md` |
+| Requirements on a published capability | `<id>/specs/<capability>/spec.md` |
+| Well-formed | `openspec validate <id> --strict` |
+| Done | every task ticked, in the commit that did it |
+| History | `openspec archive <id>` |
+
+## Writing `tasks.md` so the rest works
+
+Each item must be one deliverable with an observable outcome.
+
+> ✗ Wire up the parser
+> ✓ `parse()` refuses an unterminated string with `E0012`, naming line and column, with a test
+
+The first cannot be verified, so the verifier will mark it `unexecuted` and the gate will block.
+The second tells the implementer what to build, the test author what to assert, and the verifier
+what to look for.
+
+## Without OpenSpec
+
+`spec.engine` falls back to `prd-frd`: a PRD (what and why) and an FRD with numbered `FR-n` and
+`AC-n`. Everything downstream behaves identically — the verifier addresses requirements by
+identifier either way. Adopt OpenSpec when you want the validator and the archive; the pipeline
+does not require it.