@harness-engineering/cli 2.6.1 → 2.7.0

package/dist/agents/skills/cursor/knowledge-craft/SKILL.md

@@ -0,0 +1,180 @@
+# Knowledge Craft
+
+> LLM-judgment critique of knowledge-entry quality. Critiques `docs/knowledge/` entries (EXCLUDING `decisions/` — that's spec-craft's territory) against a curated rubric catalog: does this state a load-bearing FACT or paraphrase the code? Would deleting it lose specific signal? Does it earn its place in the knowledge graph as `business_fact` / `business_rule` / `business_concept` / `business_decision`? Fifth non-design member of the craft-pipeline initiative (#9 of 10). Emits 3-axis findings (tier × impact × confidence per ADR 0019).
+
+## When to Use
+
+- During PR review on a new or substantially-rewritten knowledge entry
+- After authoring a knowledge entry, before adding it to the index
+- When onboarding a new contributor (audit entries they introduced)
+- Periodically (per-sprint or per-release) to catch knowledge-entry rot
+- As a quality gate before `harness-knowledge-pipeline` ingests an entry into the graph
+- NOT for ADR / proposal critique (use `spec-craft` — `decisions/` is its territory)
+- NOT for AGENTS.md critique (different shape: navigational manifest, not fact-bearing entry — v1.x)
+- NOT for autofix / knowledge-entry rewriting (this is judgment-only; v1.x may add `align-knowledge` sibling)
+- NOT for graph-membership checks (no graph reads at runtime — references the taxonomy in rubric prompts)
+- NOT for source-code comment critique (use `code-craft` #4 or `docs-craft` #2)
+
+## Process
+
+### Phase 1: DISCOVER — Find knowledge entries
+
+1. **Read project configuration.** Check `harness.config.json` for:
+   - `craft.knowledge.enabled` — gate (default `true`)
+   - `craft.knowledge.maxFiles` — entry count cap (default 50)
+   - `craft.knowledge.excludeDirs` — extra subdirs to skip
+
+2. **Walk `docs/knowledge/` recursively:**
+   - Include `*.md` files (case-insensitive `README.md` excluded)
+   - EXCLUDE `decisions/` subdir entirely (spec-craft's territory)
+   - EXCLUDE any user-supplied extra dirs via `--exclude-dirs`
+   - Caller-supplied `--files` overrides discovery for explicit scoping
+
+### Phase 2: CRITIQUE — Per (file, rubric) loop
+
+7 seed rubrics:
+
+| Rubric      | Title                                           |
+| ----------- | ----------------------------------------------- |
+| `KNOW-R001` | States a load-bearing fact (not paraphrase)     |
+| `KNOW-R002` | Truth a code reader could not derive            |
+| `KNOW-R003` | Earns a place in the knowledge graph taxonomy   |
+| `KNOW-R004` | Carries forward a decision that would erode     |
+| `KNOW-R005` | Deleting would lose specific knowledge          |
+| `KNOW-R006` | Concrete and operationally defined              |
+| `KNOW-R007` | A stranger could pick it up six months from now |
+
+For each (file, rubric) pair:
+
+1. Build prompt with rubric description + file path + relative-to-knowledge-root path + entry contents (truncated to 4000 chars for cost).
+2. LLM returns fenced JSON: `null` (rubric doesn't apply / entry is fine) OR `{ tier, impact, confidence, message }`.
+3. On non-null: emit a `KnowledgeFinding` with `cite.rubricId` populated for ADR 0020 traceability.
+
+`KNOW-R003` is the rubric that references the graph taxonomy (`business_fact`, `business_rule`, `business_concept`, `business_decision`) inside its description — the LLM critiques against the taxonomy without knowledge-craft ever reading the graph.
+
+### Phase 3: REPORT — Aggregate + cost telemetry
+
+Emit `KnowledgeCraftOutput`:
+
+```ts
+{
+  findings: KnowledgeFinding[];
+  summary: {
+    phaseRun: ['critique'];
+    mode: 'fast';
+    durationMs: number;
+    llmCalls: { provider, model, count, costUsd };
+    catalog: { rubricsApplied: string[] };
+    counts: { filesScanned, filesSkipped };
+    runId: string;
+  }
+}
+```
+
+## Harness Integration
+
+- **`harness knowledge-craft`** — CLI entry. `--files <glob>` / `--exclude-dirs <dirs...>` / `--max-files <n>` / `--json` / `--verbose`.
+- **`mcp__harness__knowledge_craft`** — MCP tool. Same input/output. Consumed by agents.
+- **Cross-cutting API:** `critiqueKnowledgeFile(file, opts)` exported from `packages/cli/src/knowledge-craft/index.ts`. Future craft skills (or `harness-knowledge-pipeline`) can call this on a single entry without re-walking the project.
+- **Shared craft infrastructure:** `LlmProvider`, `MockLlmProvider`, `derivePriority`, 3-axis types all live in `packages/cli/src/shared/craft/`.
+
+## Success Criteria
+
+See `docs/changes/craft-pipeline/knowledge-craft/proposal.md` for the full 25 success criteria. Highlights:
+
+- 7 seed rubrics ship at `catalog/rubrics/<id>.ts` (file-per-rubric)
+- 3-axis output preserved (tier × impact × confidence, never collapsed)
+- `cite.rubricId` populated on every finding (ADR 0020)
+- `decisions/` subdir is hard-excluded from discovery (spec-craft territory)
+- `KNOW-R003` references graph node types in rubric prompt without graph imports at runtime
+- `critiqueKnowledgeFile` cross-cutting API works on a single file without project walk
+
+## Examples
+
+### Example: Paraphrase entry
+
+**Input:** `docs/knowledge/auth/email-validator.md`:
+
+```
+# Email Validator
+
+The user service validates emails via the EmailValidator class, which
+applies the standard regex pattern and rejects malformed addresses.
+```
+
+**Output (mock LLM):**
+
+```
+KNOW-R001 [foundational/large/medium] auth/email-validator.md
+  This entry restates what a reader would learn from opening
+  EmailValidator.ts. It states no load-bearing fact about the domain:
+  no upstream constraint, no historical reason for the choice, no business
+  rule that necessitated validation. Either rewrite to capture the WHY
+  (e.g., "emails must round-trip through Postmark within 30s for
+  deliverability tracking") or delete — the code already speaks.
+KNOW-R005 [polish/medium/medium] auth/email-validator.md
+  Deleting this entry would lose nothing the code doesn't already convey.
+```
+
+### Example: Decision-bearing entry
+
+**Input:** `docs/knowledge/storage/postgres-over-dynamo.md`:
+
+```
+# Why Postgres over DynamoDB
+
+We chose Postgres over DynamoDB because our access patterns are
+relational (frequent multi-table joins on tenant + user) and our team's
+ops muscle is in SQL. DynamoDB's single-table design was rejected
+because the modeling overhead of GSIs outweighs the latency win for
+our request profile.
+```
+
+**Output:**
+
+```
+(no findings)
+```
+
+This entry carries forward a decision with the alternative AND the reason — KNOW-R004 passes, KNOW-R001 passes (load-bearing fact: the rejected option + the WHY), KNOW-R005 passes (deleting loses knowledge a reader couldn't reconstruct from the schema alone).
+
+### Example: Empty project — no knowledge entries
+
+**Input:** Project has no `docs/knowledge/` directory.
+
+**Output:**
+
+```
+No knowledge-entry findings.
+
+Summary: 0 findings across 0 entries (0 skipped, 7 rubrics, 0 LLM calls, $0.0000, 2ms)
+```
+
+## Gates
+
+- **No autofix.** Sibling `align-knowledge` deferred until signal warrants safe-to-apply rewrites.
+- **No ADR critique.** `decisions/` is spec-craft's territory; double-critique on the same files produces noise.
+- **No AGENTS.md critique.** Navigational manifests need a different rubric vocabulary; v1.x.
+- **No graph reads.** v1 references graph node types in rubric prompts so the LLM critiques against the taxonomy without a runtime graph dependency.
+- **No graph persistence of findings.** Phase 1 MVP.
+- **No per-section / per-claim mode.** v1 is per-file (knowledge entries are typically focused single-topic).
+- **No `.mdx` support.** Different parsing concerns; v1.x.
+- **No B' bootstrap.** Same posture as the rest of the craft family.
+
+## Escalation
+
+- **When LLM cost is too high:** drop `maxFiles` to 25, or scope explicitly with `--files`. Per-entry cost = rubrics × per-call; truncation already caps per-call cost at 4000 input chars.
+- **When a rubric produces high false-positive rate:** v1 has no per-rubric disable; v1.x adds `craft.knowledge.disabledRubrics: ['KNOW-R007']`. Until then: filter findings by `cite.rubricId` in your consumer.
+- **When an entry is intentionally scratchpad / in-progress:** low-confidence findings are de-emphasized per ADR 0019. v1.x adds per-entry opt-out via `<!-- knowledge-craft:skip -->` HTML comment.
+- **When you want graph-aware critique (e.g., "this entry duplicates an existing business_fact node"):** v1.x opt-in mode will read the graph; v1 stays read-free.
+- **When you want to critique an ADR:** use `harness spec-craft` — ADRs are its territory. Knowledge-craft will refuse to walk `decisions/`.
+
+## Status
+
+**v1 — in implementation.** See:
+
+- Spec: `docs/changes/craft-pipeline/knowledge-craft/proposal.md`
+- Roadmap entry: `craft-pipeline sub-project #9`
+- Sibling craft skills: `naming-craft` (#1), `spec-craft` (#6), `copy-craft` (#5), `test-craft` (#3), `harness-design-craft` (design-pipeline #6)
+- Shared infrastructure: `packages/cli/src/shared/craft/`
+- Future: `align-knowledge` (FIX side), AGENTS.md / `.mdx` support, graph-aware mode, composition with `harness-knowledge-pipeline` at ingest time.

package/dist/agents/skills/cursor/knowledge-craft/skill.yaml

@@ -0,0 +1,49 @@
+name: knowledge-craft
+version: "0.1.0"
+description: LLM-judgment critique of knowledge-entry quality (docs/knowledge/, excluding decisions/ which is spec-craft territory). Per-file critique against 7 seed rubrics that ask whether the entry states a load-bearing fact, earns a place in the graph taxonomy, carries forward a decision that would otherwise erode. Fifth non-design craft-pipeline ceiling skill.
+stability: draft
+cognitive_mode: constructive-architect
+triggers:
+  - manual
+  - on_pr
+  - on_new_feature
+platforms:
+  - claude-code
+tools:
+  - Bash
+  - Read
+  - Glob
+  - Grep
+cli:
+  command: harness knowledge-craft
+  args:
+    - name: path
+      description: Project root path
+      required: false
+    - name: files
+      description: Optional file scope (overrides discovery)
+      required: false
+    - name: exclude-dirs
+      description: Extra subdir names to skip under docs/knowledge/ (decisions is always excluded)
+      required: false
+mcp:
+  tool: knowledge_craft
+  input:
+    path: string
+type: rigid
+tier: 2
+phases:
+  - name: discover
+    description: Walk docs/knowledge/ recursively, exclude decisions/ + user-supplied dirs
+    required: true
+  - name: critique
+    description: LLM-rubric loop per (file, rubric) — 7 seed rubrics
+    required: true
+  - name: report
+    description: Aggregate findings + cost telemetry + entry counts
+    required: true
+state:
+  persistent: false
+depends_on:
+  - harness-soundness-review
+  - spec-craft

package/dist/agents/skills/cursor/naming-craft/SKILL.md

@@ -0,0 +1,172 @@
+# Naming Craft
+
+> LLM-judgment skill that critiques identifier names — variables, functions, types, and files — for clarity, concreteness, weight, and predictive power. First member of the craft-pipeline initiative (sub-project #1 of 10). Uses a curated rubric catalog seeded from Martin / Beck / Karlton. Emits 3-axis findings (tier × impact × confidence per ADR 0019).
+
+## When to Use
+
+- During PR review on code that adds or renames identifiers
+- When onboarding a new contributor (audit names they introduced)
+- When refactoring a module (verify renamed names earn their letters)
+- As the cross-cutting naming critic for other craft skills (docs-craft, test-craft, code-craft will call into this)
+- NOT for code-convention enforcement (use ESLint rules — this is ceiling, those are floor)
+- NOT for autofix / rename codemod (this is judgment-only; the v2 sibling `align-naming` ships the fix path)
+- NOT for module / branch / commit-subject naming (v1.x — different infrastructure)
+- NOT for languages beyond TS/JS in v1 (Python/Go/Rust idiom catalogs are v1.x)
+
+## Process
+
+### Phase 1: EXTRACT — Identifier walk
+
+1. **Read project configuration.** Check `harness.config.json` for:
+   - `craft.naming.enabled` — gate (default `true`)
+   - `craft.naming.maxFiles` — file count cap (default 100)
+   - `craft.naming.maxIdentifiersPerFile` — per-file sampling cap (default 15)
+
+2. **Walk project files** (.ts / .tsx / .js / .jsx). Skip `node_modules`, `dist`, `build`, `coverage`, dotdirs.
+
+3. **Extract identifiers per file** via TS Compiler API:
+   - **variable** — `const x =`, `let x =`, destructuring binders
+   - **function** — `function x()`, `const x = () =>`, class methods, arrow functions assigned to a name
+   - **type** — `type X`, `interface X`, `class X`
+   - For each: capture file, line, exported status, scope size (`short` = body ≤10 lines; `long` = otherwise), and ±2 context lines for LLM prompt construction.
+
+### Phase 2: SAMPLE — Convention inference
+
+For each identifier kind, sample up to N=500 identifiers across the project and infer the dominant convention via majority-rule:
+
+- **variables / functions** — camelCase / snake_case / PascalCase
+- **types** — PascalCase / camelCase
+- **files** — kebab-case / camelCase / PascalCase (basenames sans extension)
+
+`>50%` majority threshold per kind. Below threshold → `null` (no dominant convention) and the convention-conformance rubric silently skips.
+
+### Phase 3: CRITIQUE — Per-rubric LLM loop
+
+For each file:
+
+1. **Sample identifiers** weighted by importance:
+   - Exported identifiers first
+   - Then long-scope (file-level, methods on long classes)
+   - Then short-scope random fill
+   - Cap at `maxIdentifiersPerFile` per file (default 15).
+
+2. **For each (identifier, rubric)** in the cross-product:
+   - Build a prompt with rubric description + identifier + context lines + project convention.
+   - LLM returns fenced JSON: either `null` (rubric doesn't apply / name is fine) or `{ tier, impact, confidence, message }`.
+   - On non-null: emit a `NamingFinding` with `cite.rubricId` populated for ADR 0020 traceability.
+
+3. **v1 rubric catalog (6 seed rubrics):**
+   - `NAME-R001` **predictive power** (Martin) — does the name predict the contract?
+   - `NAME-R002` **concreteness** (Martin / Beck) — concrete > vague
+   - `NAME-R003` **verb/noun honesty** (Beck) — verb for functions; noun for types; questions for booleans
+   - `NAME-R004` **convention conformance** (Karlton) — matches project convention
+   - `NAME-R005` **scope match** (Beck) — length proportional to scope
+   - `NAME-R006` **encoded measure** (Pragmatic Programmer) — silent units cause real bugs
+
+### Phase 4: REPORT — Aggregate + cost telemetry
+
+Emit `NamingCraftOutput`:
+
+```ts
+{
+  findings: NamingFinding[];
+  summary: {
+    phaseRun: ['critique'];
+    durationMs: number;
+    llmCalls: { provider, model, count, costUsd };
+    catalog: { rubricsApplied: string[] };
+    convention: { variables, functions, types, files };
+    runId: string;
+  }
+}
+```
+
+## Harness Integration
+
+- **`harness naming-craft`** — CLI entry. `--files <glob>` / `--kinds <variable|function|type|file>` / `--max-files <n>` / `--max-identifiers-per-file <n>` / `--json` / `--verbose`.
+- **`mcp__harness__naming_craft`** — MCP tool. Same input/output. Consumed by agents.
+- **Cross-cutting API:** `critiqueNamesInFile(file, opts)` exported from `packages/cli/src/naming-craft/index.ts`. Future craft skills (docs-craft, test-craft, code-craft) import and invoke this when they want naming critique on a file they're already processing — no project re-walk needed.
+- **LLM provider reuse:** imports design-craft's `LlmProvider` + `MockLlmProvider` directly. v2 extracts to `packages/cli/src/shared/llm/` when a second non-design craft skill needs differences.
+
+## Success Criteria
+
+See `docs/changes/craft-pipeline/naming-craft/proposal.md` for the full 34 success criteria. Highlights:
+
+- 6 seed rubrics ship in `catalog/rubrics/<id>.ts` (file-per-rubric matches design-craft pattern)
+- 3-axis output preserved (tier × impact × confidence, never collapsed) per ADR 0019
+- `cite.rubricId` populated on every finding per ADR 0020
+- Convention sampler returns `null` when no dominant convention (>50% threshold)
+- Cross-cutting `critiqueNamesInFile` API exported for future craft skills
+- LlmProvider / MockLlmProvider IMPORTED from design-craft (no duplication)
+- MCP tool count bumps (running total maintained by parallel PRs)
+
+## Examples
+
+### Example: Vague function name
+
+**Input:** `src/orders/processor.ts`:
+
+```ts
+export function processData(orders: Order[]) { ... }
+```
+
+**Output (mock LLM):**
+
+```
+NAME-R002 [polish/medium/low] function processData:14
+  "processData" is a vague verb-pair where the operation and subject
+  are both unstated. Consider `applyDiscountsToOrders` or
+  `convertOrdersToInvoices` depending on the actual transform.
+NAME-R001 [polish/medium/medium] function processData:14
+  The name predicts neither the input shape (orders) nor the operation.
+```
+
+(Real LLM responses vary; mock provider returns deterministic low-confidence findings for test determinism.)
+
+### Example: Silent unit
+
+**Input:**
+
+```ts
+const timeout = 5000;
+```
+
+**Output:**
+
+```
+NAME-R006 [foundational/medium/high] variable timeout:1
+  "timeout" implies a time measure but the unit is silent. Use
+  `timeoutMs` so the call site can't be misread as seconds.
+```
+
+### Example: Mixed-convention project — convention sampler returns null
+
+**Input:** A project with 60% camelCase, 30% snake_case, 10% PascalCase variables. No >50% camelCase majority (60% IS >50%, so convention=camelCase). But with 45/40/15 split: no convention.
+
+**Output:** convention-conformance rubric (NAME-R004) silently skips for the variables kind. Other rubrics still run.
+
+## Gates
+
+- **No autofix.** This is ceiling-judgment. v2's `align-naming` may add safe-rename codemods.
+- **No NAMING.md authoring.** v1 derives convention from sampling.
+- **No language support beyond TS/JS.** v1.x.
+- **No modules / branches / commit subjects.** v1.x (and commit subjects go to copy-craft #5).
+- **No graph persistence.** Phase 1 MVP posture (matches design-craft).
+- **No deep/vision mode.** Naming is text-only.
+
+## Escalation
+
+- **When LLM cost is too high on a large project:** drop `maxIdentifiersPerFile` to 10 or `maxFiles` to 50. Cost = files × identifiers × rubrics × per-call cost.
+- **When a rubric produces high false-positive rate:** v1 has no per-rubric disable; v1.x adds `craft.naming.disabledRubrics: ['NAME-R005']`. Until then: filter findings by `cite.rubricId` in your consumer.
+- **When the convention sampler misidentifies a mid-migration project:** below 50% threshold returns null and convention rubric skips. Better silent skip than wrong findings. Wait until migration completes; until then disable NAME-R004 in v1.x or filter findings.
+- **When you want naming critique for a single file (e.g. in CI on changed files):** use `--files <glob>` or call `critiqueNamesInFile()` via the cross-cutting API.
+- **When you want module / branch / commit-subject naming today:** manual review. v1.x adds these surfaces.
+
+## Status
+
+**v1 — in implementation.** See:
+
+- Spec: `docs/changes/craft-pipeline/naming-craft/proposal.md`
+- Roadmap entry: `craft-pipeline sub-project #1` (the first member)
+- Sibling: `harness-design-craft` (design-pipeline #6 — the LLM-judgment template this follows)
+- Future cross-cutters: docs-craft (#2), test-craft (#3), code-craft (#4) will call into naming-craft's `critiqueNamesInFile()` for their domain-specific naming critique.

package/dist/agents/skills/cursor/naming-craft/skill.yaml

@@ -0,0 +1,51 @@
+name: naming-craft
+version: "0.1.0"
+description: LLM-judgment skill that critiques identifier names (variables, functions, types, files) against a curated rubric catalog seeded from Martin / Beck / Karlton. First craft-pipeline ceiling skill; cross-cutting (other craft skills call into it for domain-specific naming).
+stability: draft
+cognitive_mode: constructive-architect
+triggers:
+  - manual
+  - on_pr
+  - on_new_feature
+platforms:
+  - claude-code
+tools:
+  - Bash
+  - Read
+  - Glob
+  - Grep
+cli:
+  command: harness naming-craft
+  args:
+    - name: path
+      description: Project root path
+      required: false
+    - name: files
+      description: Optional file/glob scope
+      required: false
+    - name: kinds
+      description: Restrict to variable / function / type / file
+      required: false
+mcp:
+  tool: naming_craft
+  input:
+    path: string
+type: rigid
+tier: 2
+phases:
+  - name: extract
+    description: TS Compiler API walk; gather identifiers + scope metadata + context lines
+    required: true
+  - name: sample
+    description: Derive project naming convention via majority-rule sampling
+    required: true
+  - name: critique
+    description: LLM-rubric loop per (identifier, rubric) pair; emit 3-axis findings
+    required: true
+  - name: report
+    description: Aggregate findings + LLM cost + convention summary
+    required: true
+state:
+  persistent: false
+depends_on:
+  - harness-design-craft

package/dist/agents/skills/cursor/security-craft/SKILL.md

@@ -0,0 +1,205 @@
+# Security Craft
+
+> LLM-judgment critique of security posture for TS/JS source — the ceiling counterpart to `harness-security-scan` (CVE/OWASP rule-based floor) and `harness-security-reviewer` (procedural review). Threat-modeling-as-skill rather than pattern-matching. Critiques whether trust boundaries are respected, where implicit privilege escalation lurks, whether the code defends in depth or just at the gate, whether principle of least authority is honored. Sixth non-design member of the craft-pipeline initiative (#10 of 10; the final sub-project). Emits 3-axis findings (tier × impact × confidence per ADR 0019).
+
+## When to Use
+
+- During PR review on a substantively-changed handler / middleware / privileged op
+- After authoring a new endpoint, before exposing it to traffic
+- When onboarding a new contributor (audit security-relevant code they introduced)
+- Periodically (per-sprint or per-release) to catch security-shape drift
+- For threat-modeling shape questions a CVE scanner doesn't address (trust boundaries, fail-closed, authz ordering)
+- NOT for CVE / dependency scanning (use `harness-security-scan` — rule-based floor)
+- NOT for procedural review checklists (use `harness-security-reviewer`)
+- NOT for IaC critique (v1.x — Dockerfile / k8s / Terraform have different rubric vocabulary)
+- NOT for secret detection (floor concern; existing regex/entropy scanners cover this)
+- NOT for autofix / security rewriting (this is judgment-only; v1.x may add `align-security` with aggressive safeguards)
+- NOT for test files (v1 excludes — test security has a different shape; v1.x with dedicated rubrics)
+
+## Process
+
+### Phase 1: DISCOVER — Find source files
+
+1. Walk `packages/*/src/` recursively.
+2. Include `*.{ts,tsx,js,jsx,mjs,cjs}`; exclude test files (`*.test.*`, `*.spec.*`, `tests/`, `__tests__/`).
+3. Exclude generated / build / coverage dirs (`node_modules`, `dist`, `build`, `coverage`, `.next`, `.turbo`, `__snapshots__`).
+4. Honor `--packages` for explicit package scoping; `--files` overrides discovery.
+
+### Phase 2: SIGNAL — AST-driven security construct detection
+
+For each source file, the TS Compiler API walks the AST once and emits `SecuritySignal`s. Files with zero signals are **skipped entirely** — this is the FP-management strategy from the spec (no path-heuristic fallback).
+
+Detected signal kinds:
+
+| Kind              | What it matches                                                                                                                        |
+| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| `http-handler`    | `(req, res)` / `(req, res, next)` shapes; `app.get/post/...`; `@Get/@Post/...`                                                         |
+| `middleware`      | `(req, res, next) =>` arrow / `(ctx, next)` shapes                                                                                     |
+| `auth-api`        | `jwt.{sign,verify}`, `bcrypt.{hash,compare}`, `argon2.*`, `passport.*`, `req.session.*`, `res.cookie`                                  |
+| `privileged-op`   | `child_process.{exec,spawn,...}`, `eval`, `new Function`, `vm.runIn*`, `fs.{writeFile,unlink,chmod,...}`                               |
+| `data-egress`     | `fetch`, `axios.*`, `http.request`, `https.request`, `net.connect`                                                                     |
+| `raw-query`       | `*.query(\`...${x}...\`)`, `*.raw(...)`, `$queryRaw`, `$executeRaw` with SQL-shaped argument                                           |
+| `secret-handling` | Secret-named variable (`token`, `password`, `apiKey`, …) flowing into `console.*`, `logger.*`, `JSON.stringify`, template-literal sink |
+
+AST awareness (not regex) avoids common false positives: `exec` in a comment, `eval` as a variable name, `token` in a CSS property name.
+
+### Phase 3: CRITIQUE — Per (file, signal, rubric) loop
+
+8 seed rubrics, each declaring `appliesToSignals` so per-signal pre-filtering minimizes LLM cost:
+
+| Rubric     | Title                                           | Applies to signals                                  |
+| ---------- | ----------------------------------------------- | --------------------------------------------------- |
+| `SEC-R001` | Trust boundary respected                        | http-handler, middleware, raw-query, privileged-op  |
+| `SEC-R002` | Principle of least authority honored            | auth-api, privileged-op, http-handler               |
+| `SEC-R003` | Defense in depth (not gate-only)                | auth-api, http-handler                              |
+| `SEC-R004` | Assumed adversary realistic for the deployment  | http-handler, middleware, auth-api                  |
+| `SEC-R005` | Data flow across trust boundaries is visible    | http-handler, raw-query, data-egress, privileged-op |
+| `SEC-R006` | Fail closed, not open                           | auth-api, middleware, http-handler                  |
+| `SEC-R007` | Secrets carried in a shape that resists leakage | secret-handling                                     |
+| `SEC-R008` | Authorization check happens before the action   | http-handler, privileged-op                         |
+
+For each (signal, rubric) pair where the rubric applies:
+
+1. Build a prompt with rubric description + file path + signal info + **1500-char window AROUND the signal line** (not the whole file — security-critical context is local).
+2. **Conservative-confidence system prompt** biases the LLM toward `medium` confidence by default; `high` requires a specific, named anti-pattern or visible missing guard.
+3. LLM returns fenced JSON: `null` (rubric doesn't apply / code is fine) OR `{ tier, impact, confidence, message }`.
+4. On non-null: emit a `SecurityFinding` with `cite.rubricId` populated for ADR 0020 traceability.
+
+### Phase 4: REPORT — Aggregate + cost telemetry
+
+Emit `SecurityCraftOutput`:
+
+```ts
+{
+  findings: SecurityFinding[];
+  summary: {
+    phaseRun: ['critique'];
+    mode: 'fast';
+    durationMs: number;
+    llmCalls: { provider, model, count, costUsd };
+    catalog: { rubricsApplied: string[] };
+    counts: { filesScanned, filesSkippedNoSignal, signalsDetected };
+    runId: string;
+  }
+}
+```
+
+`filesSkippedNoSignal` is tracked separately so report consumers can see how aggressively the AST pre-filter trimmed the corpus.
+
+## Harness Integration
+
+- **`harness security-craft`** — CLI entry. `--files <glob>` / `--packages <names>` / `--max-files <n>` / `--max-signals-per-file <n>` / `--json` / `--verbose`.
+- **`mcp__harness__security_craft`** — MCP tool. Same input/output. Consumed by agents.
+- **Cross-cutting API:** `critiqueSecurityInFile(file, opts)` exported from `packages/cli/src/security-craft/index.ts`. Returns `[]` for files with no security signals (consistent with the orchestrator's FP-management strategy).
+- **Shared craft infrastructure:** `LlmProvider`, `MockLlmProvider`, `derivePriority`, 3-axis types all live in `packages/cli/src/shared/craft/`.
+
+## Success Criteria
+
+See `docs/changes/craft-pipeline/security-craft/proposal.md` for the full 29 success criteria. Highlights:
+
+- 8 seed rubrics ship at `catalog/rubrics/<id>.ts` (file-per-rubric)
+- AST detector emits signals for all 7 signal kinds; comment / string contents don't fire (AST-aware, not regex)
+- Files with zero signals are skipped (`filesSkippedNoSignal` tracked)
+- Per-rubric `appliesToSignals` pre-filter avoids irrelevant LLM calls
+- 3-axis output preserved; confidence defaults to medium per the spec's Decision #3
+- `cite.rubricId` populated on every finding (ADR 0020)
+- `critiqueSecurityInFile` cross-cutting API works on a single file
+
+## Examples
+
+### Example: User input flowing into child_process
+
+**Input:** `packages/api/src/handlers/run-script.ts`:
+
+```ts
+import { exec } from 'child_process';
+import type { Request, Response } from 'express';
+
+export function runScript(req: Request, res: Response): void {
+  const userScript = req.body.script;
+  exec(`bash -c "${userScript}"`, (err, stdout) => {
+    res.json({ output: stdout });
+  });
+}
+```
+
+**Output (mock LLM):**
+
+```
+SEC-R001 [foundational/large/high] child_process.exec:5
+  User-controlled `req.body.script` flows directly into `bash -c "${userScript}"`.
+  This is a textbook command-injection sink. Either reject the entire pattern
+  (no user-supplied shell strings) or move to `execFile` with an allowlist of
+  binaries and pre-validated arg arrays. Never templated into a shell.
+SEC-R005 [foundational/large/high] child_process.exec:5
+  Untrusted input (`req.body.script`) crosses the trust boundary into a
+  privileged sink without any visible validation or escaping step. The crossing
+  is invisible — the variable is named generically and goes straight to exec.
+```
+
+### Example: Auth check after action
+
+**Input:** `packages/api/src/handlers/get-doc.ts`:
+
+```ts
+export async function getDoc(req: Request, res: Response) {
+  const doc = await db.docs.findOne({ id: req.params.id });
+  if (doc.ownerId !== req.user.id) return res.status(403).send();
+  return res.json(doc);
+}
+```
+
+**Output:**
+
+```
+SEC-R008 [foundational/medium/medium] req,res:1
+  The document is loaded BEFORE the authorization check. Even though the
+  response is denied, the load has already executed — observable side effects
+  (audit logs, rate-limit counters, cache populations) leak existence
+  information about documents the caller can't access. Authorize against the
+  identifier first (`req.params.id` + `req.user.id`), then load.
+```
+
+### Example: File with no security signals
+
+**Input:** A pure utility file with no http/auth/exec/fs/network constructs.
+
+**Output:**
+
+```
+No security findings.
+
+Summary: 0 findings across 0 files (12 skipped, 0 signals, 8 rubrics, 0 LLM calls, $0.0000, 4ms)
+```
+
+The 12 files were scanned for signals but skipped because none had security-relevant AST constructs — exactly the FP-management strategy at work.
+
+## Gates
+
+- **No autofix.** Sibling `align-security` deferred to v2 with aggressive FP safeguards (security rewrites have asymmetric downside).
+- **No IaC critique.** Dockerfile / k8s / Terraform need different rubrics; v1.x.
+- **No multi-file auth-flow tracing.** Cross-file privilege-escalation analysis (handler → middleware → service) needs a graph traversal layer; v1.x once cross-file critique pays for itself elsewhere.
+- **No dependency / CVE scanning.** `harness-security-scan` is the floor.
+- **No secret detection** (floor concern).
+- **No test-file critique.** Test security has a different shape; v1.x.
+- **No path-heuristic fallback.** If AST scan finds zero signals, the file is skipped. Tight scoping is part of the FP-management strategy.
+- **No B' bootstrap.**
+
+## Escalation
+
+- **When LLM cost is too high:** drop `maxFiles` to 50 or `maxSignalsPerFile` to 5, or scope explicitly with `--packages <name>`. Per-file cost = (signals × applicable rubrics × per-call); typical handler fires ~3-5 rubrics, not 8.
+- **When a specific rubric produces false positives:** v1 has no per-rubric disable; v1.x adds `craft.security.disabledRubrics: ['SEC-R004']`. Until then: filter findings by `cite.rubricId` downstream.
+- **When the AST detector misses a framework you use** (tRPC, Convex, Cloudflare Workers, Hono RPC): v1 ships baseline coverage for Express / Hono / Fastify / Koa / NestJS-decorator. Adding a framework is a 1-line config in `signals.ts`. Track as v1.x.
+- **When findings are too cautious (confidence floor):** the conservative-by-default is deliberate (FP management); v1.x adds `craft.security.confidenceFloor` to tighten further. Loosening below medium is intentionally not exposed.
+- **When you want IaC critique:** v1.x. For v1, scope explicitly to source files and accept the gap.
+- **When a finding is wrong:** dismiss it in your consumer; signal as a `suppressedAt` entry on the rubric for future catalog evolution.
+
+## Status
+
+**v1 — in implementation.** See:
+
+- Spec: `docs/changes/craft-pipeline/security-craft/proposal.md`
+- Roadmap entry: `craft-pipeline sub-project #10` (the final sub-project; the craft-pipeline initiative completes with this PR)
+- Sibling craft skills: `naming-craft` (#1), `spec-craft` (#6), `copy-craft` (#5), `test-craft` (#3), `knowledge-craft` (#9), `harness-design-craft` (design-pipeline #6)
+- Shared infrastructure: `packages/cli/src/shared/craft/`
+- Future: `align-security` (FIX side; aggressive safeguards), IaC critique, multi-file auth-flow tracing, test-file security, framework expansions (tRPC / Convex / Cloudflare Workers / Hono RPC).