@mdferdousalam/agentic-sdlc 0.0.0-stage → 3.0.0

package/evals/spec-review-catches-unfalsifiable/prompt.md

@@ -0,0 +1,17 @@
+---
+max_turns: 12
+allowed_tools: [Read, Glob, Grep, Skill]
+---
+Review this specification for a feature and give your verdict.
+
+```markdown
+# FRD — export improvements
+
+FR-1  The export command should handle errors gracefully.
+FR-2  Exports must be fast.
+FR-3  `export --format=json` writes valid JSON to stdout and exits 0; on an unwritable
+      path it exits 2 with `EXP-004` naming the path.
+AC-1  Users are happy with the export experience.
+```
+
+Is this ready to build from? Answer with a verdict and your findings.

package/examples/worked-example.md

@@ -0,0 +1,131 @@
+# A worked example — rate limiting on a login endpoint
+
+A real unit of work from request to merged, in a Node service with OpenSpec installed. Nothing
+here is hypothetical about the mechanics: every command is one you can run, and every refusal is
+one the hook actually produces.
+
+## 0 · Adapt, once
+
+```console
+$ /agentic-sdlc:init --write
+wrote sdlc.config.json
+$ /agentic-sdlc:doctor
+note     gitleaks not found (secret scanning)
+doctor: ok
+```
+
+`brew install gitleaks`, re-run `:init --write`, and `secretScan` fills itself in. The gate will
+otherwise record that stage as `skipped` — honestly, but you will not want that in a service
+that handles credentials.
+
+Set the profile, since this is a service:
+
+```jsonc
+{ "profile": "service", "reviewers": ["sdlc-code-reviewer", "sdlc-security-reviewer"] }
+```
+
+## 1–3 · Specify, review, branch
+
+```text
+/agentic-sdlc:feature "rate limit POST /login: 5 attempts per 15 minutes per account+IP"
+```
+
+The spec writer produces `openspec/changes/login-rate-limit/` and validates it. The reviewer
+comes back:
+
+```
+SPEC: changes-requested — AC-3 is not falsifiable; the lockout response is unspecified
+  1. tasks.md item 3 "handle abuse gracefully" — name the observable behaviour
+  2. proposal.md — what status and body does a locked-out request get? 429 with what headers?
+  3. design.md — what happens to the counter when the password is corrected on attempt 4?
+```
+
+That is the stage doing its job. The writer fixes the three, the reviewer approves, and the
+receipt is written:
+
+```console
+$ sdlc receipt show spec
+{ "kind": "spec", "verdict": "approved",
+  "subject": "openspec/changes/login-rate-limit",
+  "subjectDigest": "sha256:4f2a9c1e8b3d7a05", ... }
+```
+
+Only then does the branch exist. Try it the other way round and:
+
+```console
+$ git switch -c feat/login-rate-limit
+BLOCKED by agentic-sdlc: ... needs an approved spec
+```
+
+## 4 · Implement
+
+```text
+/agentic-sdlc:implement
+```
+
+Item by item, test first. The implementer hits a gap the spec did not settle — does the limit
+count failed attempts only, or all? — and stops rather than choosing:
+
+> tasks.md item 2 does not say whether a successful login resets the counter. Two defensible
+> readings with different security properties. Handing back for a one-item spec revision.
+
+Good. A guess here is a security decision made by accident.
+
+## 5–6 · Verify and review
+
+```console
+$ /agentic-sdlc:verify
+| AC-1 | passed     | src/limiter.ts:31 | limiter.test.ts:12 `blocks the 6th attempt` | 1 passed |
+| AC-2 | passed     | src/limiter.ts:48 | limiter.test.ts:40 `resets after 15 minutes`| 1 passed |
+| AC-4 | unexecuted | src/login.ts:77   | —                                            | no test  |
+
+$ /agentic-sdlc:review
+SECURITY: fail — the counter keys on IP alone behind the proxy; X-Forwarded-For is attacker-controlled
+  1. src/limiter.ts:22 — trust only the proxy's rightmost hop, or key on account+IP as specified
+```
+
+Two findings a summary would have hidden: one untested criterion, one real vulnerability that
+the specification had actually ruled out and the implementation reintroduced.
+
+## 7 · The gate
+
+```console
+$ /agentic-sdlc:readiness
+Verdict: NOT-READY
+| Clean tree | passed |
+| Mechanical (pnpm run lint && pnpm test) | passed |
+| Secret scan | passed |
+| Reviewers | code: pass; security: fail |
+| Criteria with evidence | 3 of 4 — AC-4 unexecuted |
+```
+
+`pnpm test` is green and the change is still not ready. That gap is the entire point.
+
+Fix the proxy handling, `sdlc-test-author` writes the missing AC-4 test and proves it fails
+against the old code, re-run `:readiness` → READY.
+
+## 8–9 · Land and report
+
+```text
+/agentic-sdlc:land --merge
+```
+
+The pull request body carries the four criteria with evidence and the gate table. If you had
+made one more commit after the gate:
+
+```console
+BLOCKED by agentic-sdlc: merging needs a READY readiness receipt, and the readiness receipt is
+for 9a1c4f21e but HEAD is 3b77de004 — the work changed after it was granted.
+```
+
+Re-run the gate on the real commit. Then `:report` writes the implementation report — including
+the counter-reset decision and why — and archives the OpenSpec change.
+
+## What the pipeline caught here
+
+A spec with an unfalsifiable criterion. An ambiguity that would have become a silent security
+decision. An untested criterion behind a green test run. A vulnerability the spec had excluded.
+A merge of a commit nobody reviewed.
+
+None of those is exotic. They are the ordinary failures of shipping under time pressure, and
+each was caught by a stage that could not be skipped rather than by somebody remembering.

package/hooks/hooks.json

@@ -0,0 +1,16 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash|Edit|Write|NotebookEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 \"${CLAUDE_PLUGIN_ROOT}/bin/sdlc\" guard",
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  }
+}

package/npm/cli.js

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+// Thin launcher. The CLI itself is one dependency-free Python file; this exists so that
+// `npx @mdferdousalam/agentic-sdlc install` works, and so Windows gets a real shim instead of
+// relying on a shebang npm cannot honour there.
+"use strict";
+
+const { spawnSync } = require("node:child_process");
+const { join } = require("node:path");
+const { existsSync } = require("node:fs");
+
+const script = join(__dirname, "..", "bin", "sdlc");
+if (!existsSync(script)) {
+  console.error(`agentic-sdlc: ${script} is missing — the package did not install cleanly.`);
+  process.exit(1);
+}
+
+// Windows commonly has `py` or `python` rather than `python3`.
+const candidates = process.platform === "win32"
+  ? ["python", "py", "python3"]
+  : ["python3", "python"];
+
+for (const exe of candidates) {
+  const probe = spawnSync(exe, ["-c", "import sys; sys.exit(0 if sys.version_info >= (3, 8) else 1)"],
+                          { stdio: "ignore" });
+  if (probe.error || probe.status !== 0) continue;
+  const run = spawnSync(exe, [script, ...process.argv.slice(2)], { stdio: "inherit" });
+  process.exit(run.status === null ? 1 : run.status);
+}
+
+console.error(
+  "agentic-sdlc needs Python 3.8 or newer on PATH.\n" +
+  `Tried: ${candidates.join(", ")}.\n` +
+  "The CLI is a single file with no Python dependencies — any 3.8+ interpreter will do."
+);
+process.exit(1);

package/opencode/plugin/agentic-sdlc.ts

@@ -0,0 +1,52 @@
+/**
+ * agentic-sdlc for opencode.
+ *
+ * The same enforcement the Claude Code plugin gets from its PreToolUse hook: every shell
+ * command and file edit is offered to `bin/sdlc guard`, which exits 2 when the pipeline would
+ * be skipped or something irreversible attempted. The rules live in the Python CLI, so both
+ * hosts refuse exactly the same things and there is one place to fix a rule.
+ *
+ * Installed by `bin/sdlc-install-opencode`, which rewrites PLUGIN_ROOT below.
+ */
+
+import { spawnSync } from "node:child_process"
+
+const PLUGIN_ROOT = "__PLUGIN_ROOT__"
+const CLI = `${PLUGIN_ROOT}/bin/sdlc`
+
+function ask(tool: string, input: unknown, cwd: string): string | undefined {
+  const r = spawnSync(CLI, ["guard"], {
+    input: JSON.stringify({ tool_name: tool, tool_input: input, cwd }),
+    encoding: "utf8",
+    timeout: 10_000,
+  })
+  // Exit 2 is the block contract; anything else means "no opinion", including a broken CLI —
+  // a guard that cannot run must not take the session down with it.
+  if (r.status === 2) return (r.stderr || "blocked by agentic-sdlc").trim()
+  return undefined
+}
+
+export default {
+  id: "agentic-sdlc",
+
+  async setup(ctx: any) {
+    const cwd: string = ctx?.app?.path?.cwd ?? ctx?.location?.directory ?? process.cwd()
+
+    await ctx.tool.hook("execute.before", (input: any) => {
+      const tool = String(input?.tool ?? "")
+      const args = input?.input ?? {}
+      const mapped =
+        tool === "bash" || tool === "shell" ? "Bash"
+        : tool === "edit" || tool === "write" || tool === "apply_patch" ? "Edit"
+        : null
+      if (!mapped) return
+      const problem = ask(mapped, args, cwd)
+      if (problem) throw new Error(problem)
+    })
+
+    await ctx.shell.hook("create.before", (input: any) => {
+      const problem = ask("Bash", { command: String(input?.command ?? "") }, String(input?.cwd ?? cwd))
+      if (problem) throw new Error(problem)
+    })
+  },
+}

package/package.json

@@ -1,6 +1,61 @@
 {
   "name": "@mdferdousalam/agentic-sdlc",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "3.0.0",
+  "description": "An enforced agent-based SDLC pipeline for any coding agent: specify, review, branch, implement, verify, review, gate, land, release. Claude Code, opencode, Codex and Cline refuse a skipped stage at the tool call; Cursor, Copilot, Windsurf and every AGENTS.md host get the pipeline plus git-hook and CI enforcement.",
+  "keywords": [
+    "sdlc",
+    "agents",
+    "ai",
+    "code-review",
+    "quality-gate",
+    "spec-driven",
+    "openspec",
+    "claude-code",
+    "codex",
+    "cursor",
+    "copilot",
+    "cline",
+    "opencode",
+    "gemini",
+    "agents-md"
+  ],
+  "homepage": "https://github.com/mdferdousalam/agentic-sdlc#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mdferdousalam/agentic-sdlc.git"
+  },
+  "bugs": {
+    "url": "https://github.com/mdferdousalam/agentic-sdlc/issues"
+  },
+  "license": "MIT",
+  "author": "Engr Md Ferdous Alam <mdferdousalam1989@yahoo.com> (https://github.com/mdferdousalam)",
+  "bin": {
+    "sdlc": "npm/cli.js"
+  },
+  "engines": {
+    "node": ">=16"
+  },
+  "files": [
+    "npm/cli.js",
+    "bin/",
+    "agents/",
+    "commands/",
+    "skills/",
+    "profiles/",
+    "docs/",
+    "hooks/",
+    "schema/",
+    "opencode/",
+    "evals/",
+    "examples/",
+    ".claude-plugin/",
+    "README.md",
+    "GETTING-STARTED.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    "SECURITY.md"
+  ],
+  "scripts": {
+    "test": "python3 tests/test_sdlc.py && node .github/scripts/validate-plugin.mjs"
+  }
+}

package/profiles/README.md

@@ -0,0 +1,52 @@
+# Profiles — the opinions that are not universal
+
+The pipeline core is stack-agnostic on purpose. A profile is where a *kind* of project's
+standards live, applied only when `"profile"` in `sdlc.config.json` names it.
+
+This separation is deliberate. A rule like "no hardcoded value that the spec marked
+configurable" is right for an admin-driven web application and meaningless for a compiler.
+Baking it into the core would make the core lie about being stack-agnostic, and would make
+every reviewer on every other kind of project produce noise.
+
+| Profile | For | Adds |
+| --- | --- | --- |
+| `webapp` | product applications with an admin surface | configurability, data model, accessibility, migration safety |
+| `library` | published packages and SDKs | public API compatibility, semver, documentation of every exported symbol |
+| `service` | long-running network services | operability, failure modes, observability, backpressure |
+| `compiler` | language and toolchain projects | specification-first, evidence vocabulary, bounded heavy workloads |
+
+## The second axis: concerns
+
+A project kind is one choice. **Concerns are not** — they cut across kinds. A Go service needs
+`service` *and* `concurrency`; a Rust compiler needs `compiler` *and* `memory`. Forcing those
+into one field would make you pick the less useful half, so they are a separate list:
+
+```jsonc
+{ "profile": "service", "concerns": ["concurrency", "data", "performance"] }
+```
+
+| Concern | Taxonomy | Adds |
+| --- | --- | --- |
+| [`architecture`](concerns/architecture.md) | B, J | dependency direction, cycles, boundaries, indirection that does not pay |
+| [`performance`](concerns/performance.md) | E, N | complexity, N+1, pagination, caching, round trips, scale limits |
+| [`memory`](concerns/memory.md) | F | ownership, lifetimes, cleanup on every exit, unbounded growth, safety |
+| [`concurrency`](concerns/concurrency.md) | G | races, lock order, TOCTOU, task leaks, cancellation, backpressure |
+| [`data`](concerns/data.md) | K, X6 | constraints, transaction boundaries, reversible migrations, idempotency |
+| [`platform`](concerns/platform.md) | S, X8 | host assumptions, numerics, encoding, locale, shutdown, toolchain pinning |
+
+`sdlc init` *proposes* concerns from what the repository evidently does — goroutines and mutexes
+suggest `concurrency`, migrations suggest `data`. It never imposes one. A concern the
+maintainers did not choose produces noise on every review, and a review tool that produces noise
+gets switched off.
+
+Each concern file ends by naming the **deterministic tool** for the stacks that have one, and
+saying it belongs in `quality.cmd`. Until it is there, every finding the concern raises is a
+reading rather than a measurement, and the profiles say so in those words: a `PERF-*` or
+`MEM-*` finding from a diff is `medium` confidence at best. This plugin ships no analysers and
+will not pretend to.
+
+## Writing your own
+
+Either axis is one markdown file of standards the reviewers read in addition to the core rules.
+Keep it to what a reviewer can check, and give each rule an ID in `docs/control-spec.md` — a
+rule that lives only in a prompt is an opinion.

package/profiles/compiler.md

@@ -0,0 +1,33 @@
+# Profile: compiler
+
+For languages, toolchains and anything whose output other people's correctness depends on.
+
+## The specification comes before the code
+
+- A change to what a program means changes the language specification first, in the same commit.
+- A rule the checker gains bumps the semantic epoch; a runtime contract change bumps the ABI; a
+  changed machine-readable shape bumps its schema's major version — or the commit says why not.
+- A new refusal gets a **new** diagnostic code. Codes are never reused or repurposed. The
+  message names the construct and, where the compiler can tell, the fix.
+- An unsupported construct is refused by name, never misparsed and never silently ignored.
+
+## One semantics
+
+Backends and profiles may **refuse**; they may never reinterpret the language. No silent
+fallback — not to an interpreter, not to another backend, not to weaker verification. A
+mechanism added only to turn a status row green is a defect.
+
+## Evidence
+
+- A successful compile, a test count, a self-reproduction fixpoint or a mutation count is not by
+  itself proof.
+- Differential agreement is not correctness when both paths can share the bug.
+- Zero surviving mutants is not "bug-free"; it is "this catalogue found nothing".
+- Statuses in a capability matrix cite the evidence that supports them, or they are not statuses.
+
+## Bounded workloads
+
+Generated stages, self-hosting, bootstraps, fuzzing, mutation catalogues and heavy benchmarks
+run only inside the project's bounded runner, one at a time. The `heavy` field in the config
+states the rule; the reviewers enforce it. Measurement happens in a quiet machine, or it is not
+measurement.

package/profiles/concerns/architecture.md

@@ -0,0 +1,50 @@
+# Concern: architecture
+
+Taxonomy domains **B** (architecture and system structure) and **J** (design patterns and
+engineering principles). Rules in the `ARCH-*` namespace.
+
+Enable with `"concerns": ["architecture"]`. Checked by `sdlc-architecture-reviewer` and by
+`sdlc-spec-reviewer` when a change proposes a new boundary.
+
+## Dependency direction
+
+- The project's layers are named somewhere — a README, a module graph, a lint rule. If they are
+  not, that absence is the first finding: an unwritten architecture cannot be violated, only
+  eroded.
+- Dependencies point one way. A lower layer that imports an upper one is `ARCH-LAYER-DIRECTION`,
+  and it is `high` severity even when it compiles: it is how a codebase stops being separable.
+- A new import that crosses a boundary the project declared forbidden is blocking. "It was
+  easier" is not an exception; the exception is a specification that changes the boundary.
+
+## Cycles and coupling
+
+- A new import cycle between modules is `ARCH-CYCLE`. Report it as a path, not as a claim.
+- A module that imports more than it is imported by, and keeps growing, is becoming a god
+  object. Name it while it is still one finding rather than twenty.
+- Coupling to a concrete type where the project has an interface for exactly this is
+  `advisory` unless the specification said otherwise — which is the point of the advisory
+  severity: report the trade-off and let a human decide.
+
+## Boundaries
+
+- A component's boundary is where its invariants are enforced. If a caller can construct an
+  invalid state and the component cannot tell, the boundary is in the wrong place.
+- Separation of concerns is checkable: can you state what this module is for in one sentence
+  without "and"? Two sentences is two modules.
+- Shared mutable state across a boundary is a boundary that does not exist.
+
+## Patterns
+
+- A pattern applied because it is a pattern is `advisory`, not a defect. Say what it costs —
+  indirection, a file to open, a name to learn — and let the maintainer weigh it.
+- A factory with one implementation, a strategy with one strategy, an interface with one
+  implementer and no test double: name the indirection, and the condition under which it would
+  earn its place.
+- Premature generalisation and premature optimisation are the same finding wearing two hats.
+
+## The tool beats the opinion
+
+Where the stack has one, it belongs in `quality.cmd` and the finding becomes `deterministic`:
+`cargo-deny` and `cargo modules` (Rust), `go-arch-lint` and `go mod graph` (Go),
+`dependency-cruiser` or `eslint-plugin-boundaries` (TypeScript), `import-linter` (Python),
+ArchUnit (JVM). A reviewer's reading of an import graph is `medium` confidence at best.

package/profiles/concerns/concurrency.md

@@ -0,0 +1,59 @@
+# Concern: concurrency
+
+Taxonomy domain **G** (concurrency and parallelism). Rules in the `CONC-*` namespace.
+
+Enable with `"concerns": ["concurrency"]`. Checked by `sdlc-code-reviewer`.
+
+## What this concern can and cannot do
+
+Concurrency defects are the ones least visible to reading and least reliably caught by tests:
+they are timing-dependent, so a passing suite is weak evidence. A `CONC-*` finding from the
+diff is `medium` confidence. A race detector, a stress run or a deterministic scheduler makes
+it `high`. **A test that passed once has not shown the absence of a race.**
+
+## Shared state
+
+- Every piece of state reachable from two threads is either immutable, owned by one of them, or
+  behind a lock — and the diff says which.
+- A data race is `high` severity even when the window looks small. Small windows are what
+  production load is for.
+- "It is only read concurrently" is only safe if nothing writes it, ever, including at startup.
+
+## Locks
+
+- State the lock order wherever two locks can be held at once. Inconsistent order is a deadlock
+  waiting for the right interleaving.
+- No I/O, no blocking call, no callback into unknown code while holding a lock.
+- A read-modify-write that looks atomic because it is one line is not atomic. Name the
+  operation that makes it so.
+- Lock contention on a hot path is a performance finding; see `concerns/performance`.
+
+## Time-of-check to time-of-use
+
+- Check-then-act on anything shared — a file, a row, a flag, a balance — is `CONC-TOCTOU`.
+  Make it one atomic operation, or state why the window is harmless.
+- `exists()` then `open()`, `select` then `update`, "is it free?" then "take it" — the three
+  that recur.
+
+## Asynchrony
+
+- Every spawned task is awaited, joined or deliberately detached with a comment saying so. A
+  task nobody holds is a leak and swallows its own failure.
+- Every unhandled rejection or dropped future is a failure you will never hear about.
+- Cancellation propagates: a cancelled parent cancels its children, and cleanup still runs.
+- Every timeout has a value, and every value has a reason. "No timeout" is a policy, and
+  usually the wrong one.
+- Backpressure is stated: what happens when the producer outruns the consumer? An unbounded
+  channel answers "we crash later".
+
+## Ordering
+
+- Do not assume completion order, scheduling order or message order unless the mechanism
+  guarantees it. Write down which guarantee you are relying on.
+- Idempotency: anything that can be retried says what a duplicate does.
+
+## The tool beats the opinion
+
+`go test -race`, ThreadSanitizer, Loom (Rust), `-fsanitize=thread`, Lincheck (JVM),
+deterministic-simulation or stress harnesses. Put one in `quality.cmd` and run it repeatedly —
+once is not a run.

package/profiles/concerns/data.md

@@ -0,0 +1,62 @@
+# Concern: data integrity
+
+Taxonomy domain **K** (database and data integrity), and the data half of **X6** (product and
+operational correctness). Rules in the `DATA-*` namespace.
+
+Enable with `"concerns": ["data"]`. Checked by `sdlc-code-reviewer` and `sdlc-spec-reviewer`.
+Overlaps `profiles/webapp` deliberately: a service with a database needs these whether or not
+it has an admin surface.
+
+## What this concern can and cannot do
+
+A constraint that exists only in code, a transaction boundary that is wrong, an idempotency
+key that is missing — these are visible by reading. Whether the migration actually reverses,
+and whether the constraint holds under concurrent writes, are not. A `DATA-*` finding raised
+from the diff is `medium` confidence; a migration run forward and back against representative
+data, or a test that races two writers, makes it `high`. Say which you have.
+
+## Schema
+
+- A new table or column states its purpose, its nullability, its default, its indexes and how
+  long the data is kept. A column whose retention nobody can state is a future compliance
+  question.
+- A constraint belongs in the database, not only in the application. Two applications will
+  eventually write to that table, and one of them will be a migration script.
+- Nullable-by-default is a decision. Make it deliberately or not at all.
+
+## Transactions
+
+- State the boundary: what is inside the transaction and what is outside. A side effect inside
+  a transaction that can be retried will happen twice.
+- State the isolation level where it matters, and what anomaly you are accepting. Read-committed
+  is a choice with consequences, not a default to inherit silently.
+- Lost update, dirty read and write skew each have a fix — a constraint, a lock, a version
+  column. Name which one this code relies on.
+- No network call inside a transaction.
+
+## Migrations
+
+- Every migration is reversible, or says in the same commit why it is not and what rolling back
+  would lose. `DATA-MIGRATION-IRREVERSIBLE` is not a blocker by itself; an unstated one is.
+- Forward and backward compatible across one deploy, or the specification states the ordered
+  steps: add the column, backfill, start writing, start reading, stop writing the old one, drop
+  it. Shipping those as one step is the usual outage.
+- Tested against a database with representative data. An empty database proves the syntax.
+- A destructive migration — a drop, a truncate, a type narrowing — is a separately approved
+  step. The release stage must know about it before deploying, not during.
+
+## Correctness of the data itself
+
+- Idempotency: anything a client may retry states its key and what a duplicate does. Duplicate
+  payments and duplicate orders are this finding, not a support ticket.
+- Partial writes are impossible, or the recovery path is specified and tested.
+- Money is not a float. Time is stored with its zone, or in UTC with that stated. A date is not
+  a timestamp. Rounding is specified where it is visible to a user.
+- Deletion means deletion where someone asked for it: soft-delete that leaves the data readable
+  does not satisfy a deletion request, and the specification should say which one this is.
+
+## The tool beats the opinion
+
+`sqlc`/`sqlx` compile-time checks, `EXPLAIN ANALYZE`, migration linters (`squawk`,
+`atlas lint`), property tests over invariants, and a restore drill. A backup nobody has
+restored is not a backup.

package/profiles/concerns/memory.md

@@ -0,0 +1,52 @@
+# Concern: memory and resources
+
+Taxonomy domain **F** (memory, resources and lifecycle management). Rules in the `MEM-*`
+namespace.
+
+Enable with `"concerns": ["memory"]`. Checked by `sdlc-code-reviewer`.
+
+## What this concern can and cannot do
+
+A leak is usually proved by allocation evidence over time, not by reading. A `MEM-*` finding
+raised from the diff is `medium` confidence; a sanitiser, a heap profile or a soak test makes
+it `high`. Say which you have.
+
+## Ownership and lifetime
+
+- Every resource has one owner and one release point. Two owners is a double free; none is a
+  leak.
+- A resource acquired in a function is released on **every** exit from it, including the error
+  path, the early return and the cancellation. "Cleanup at the end" is not cleanup if the
+  function can return before the end.
+- Prefer the language's scope-bound release — RAII, `defer`, `with`, `try`-with-resources,
+  `using`. A manual close that a future edit can step over is a defect waiting for a
+  maintainer.
+
+## Files, sockets, handles, connections
+
+- Every open has a close on the failure path. Connection pools, file descriptors and watchers
+  are the three that leak quietly for weeks.
+- A pool states its maximum, its timeout and what happens when it is exhausted.
+
+## Unbounded growth
+
+- A collection, queue, buffer, cache or map that only ever grows is `MEM-UNBOUNDED` and is
+  blocking. Name the eviction policy or the bound.
+- A retained reference that outlives its usefulness — a listener never removed, a closure
+  capturing a large object, a static registry nobody prunes — is the ordinary cause of "memory
+  grows until restart".
+- Recursion over user-controlled depth exhausts the stack. Bound it or make it iterative.
+
+## Memory safety, where the language allows it
+
+- Use-after-free, double free, dangling references, out-of-bounds access and buffer overflow
+  are `critical`. They do not get an `advisory`.
+- Any `unsafe` block, raw pointer arithmetic, manual lifetime or foreign-function boundary
+  states the invariant it is upholding, in a comment, in the same commit.
+- Integer overflow before an allocation size is a memory-safety bug, not an arithmetic one.
+
+## The tool beats the opinion
+
+AddressSanitizer and LeakSanitizer, Valgrind, Miri (Rust), `go test -race` plus `pprof` heap
+profiles, `tracemalloc` (Python), heap snapshots in a browser. One soak run in `quality.cmd`
+beats every paragraph above.