@harness-engineering/cli 2.6.1 → 2.7.1

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).

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

@@ -0,0 +1,58 @@
+name: security-craft
+version: "0.1.0"
+description: LLM-judgment critique of security posture (TS/JS source). Threat-modeling-as-skill — critiques whether trust boundaries are respected, where implicit privilege escalation lurks, whether the code defends in depth, whether least authority is honored. AST-driven signal detection fires only on files with security-relevant constructs; conservative confidence defaults manage the FP risk inherent in judgment-based security. Sixth non-design craft-pipeline ceiling skill (the final sub-project, #10 of 10).
+stability: draft
+cognitive_mode: constructive-architect
+triggers:
+  - manual
+  - on_pr
+  - on_new_feature
+platforms:
+  - claude-code
+tools:
+  - Bash
+  - Read
+  - Glob
+  - Grep
+cli:
+  command: harness security-craft
+  args:
+    - name: path
+      description: Project root path
+      required: false
+    - name: files
+      description: Optional file scope (overrides discovery)
+      required: false
+    - name: packages
+      description: Restrict to specific packages under packages/
+      required: false
+    - name: max-files
+      description: Cap source-file count (default 100)
+      required: false
+    - name: max-signals-per-file
+      description: Cap per-file signal critique (default 10)
+      required: false
+mcp:
+  tool: security_craft
+  input:
+    path: string
+type: rigid
+tier: 2
+phases:
+  - name: discover
+    description: Walk packages/STAR/src/ recursively; exclude tests + build dirs
+    required: true
+  - name: signal
+    description: AST-driven security construct detection (http handlers, middleware, auth APIs, child_process/eval, fs writes, raw queries, network egress, secret handling)
+    required: true
+  - name: critique
+    description: LLM-rubric loop per (file, signal, rubric) with conservative-confidence bias
+    required: true
+  - name: report
+    description: Aggregate findings + cost telemetry + file/signal counts
+    required: true
+state:
+  persistent: false
+depends_on:
+  - harness-security-scan
+  - harness-security-review

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

@@ -0,0 +1,184 @@
+# Spec Craft
+
+> LLM-judgment critique of spec quality (proposals + ADRs) against a curated rubric catalog from the spec-quality canon. Per-section critique with rubric-to-section mapping. Second member of the craft-pipeline initiative; highest-leverage craft skill because spec quality compounds across the entire planning → implementation → review lifecycle below it. Emits 3-axis findings (tier × impact × confidence per ADR 0019).
+
+## When to Use
+
+- During PR review on a new or substantially-rewritten spec
+- After authoring a proposal, before circulating it for review
+- When onboarding a new contributor (audit specs they introduced)
+- Periodically (per-sprint or per-release) to catch spec drift
+- As the cross-cutting spec critic for harness-brainstorming (when newly-authored specs land)
+- NOT for spec-structure enforcement (use `harness-soundness-review` — that's the rule-based floor)
+- NOT for README / general-doc critique (use `docs-craft` #2)
+- NOT for autofix / spec rewriting (this is judgment-only; v1.x may add `align-spec` sibling)
+- NOT for source-code comment critique (use `code-craft` #4 or `docs-craft` #2)
+- NOT for RFCs in v1 (v1.x)
+
+## Process
+
+### Phase 1: DISCOVER — Find spec files
+
+1. **Read project configuration.** Check `harness.config.json` for:
+   - `craft.spec.enabled` — gate (default `true`)
+   - `craft.spec.maxFiles` — doc count cap (default 50)
+   - `craft.spec.maxSectionsPerFile` — per-doc section cap (default 10)
+
+2. **Discover spec files:**
+   - **proposals:** `docs/changes/*/proposal.md` and `docs/changes/*/<sub>/proposal.md` (one level of nesting, for initiatives with sub-projects)
+   - **ADRs:** `docs/knowledge/decisions/*.md` (excluding README)
+   - Restrict via `--kinds proposal` or `--kinds adr` for single-kind runs.
+
+### Phase 2: PARSE — Split into named sections
+
+For each spec file:
+
+1. **Strip YAML frontmatter** (`--- ... ---` block at top, if present).
+2. **Split by H2** (`## ...`) into named sections. Each section captures:
+   - `heading` — original H2 text (e.g., `"Decisions"`, `"Out-of-scope (v1)"`)
+   - `canonical` — normalized form for rubric matching (`"decisions"`, `"out-of-scope-v1"`)
+   - `body` — content between this H2 and the next
+   - `line` / `endLine` — line range
+3. Subsections (H3) stay part of the parent H2's body. v1.x may add per-H3 critique for sections like Decisions that have one row per H3.
+
+### Phase 3: CRITIQUE — Per (file, section, rubric) loop
+
+7 seed rubrics:
+
+| Rubric      | Title                                    | Applies to                               |
+| ----------- | ---------------------------------------- | ---------------------------------------- |
+| `SPEC-R001` | Sharpness vs vagueness                   | `*` (all sections)                       |
+| `SPEC-R002` | Cuts at the joints                       | `decisions`, `scope`, `technical-design` |
+| `SPEC-R003` | Two readers, same understanding          | `decisions`, `success-criteria`          |
+| `SPEC-R004` | Load-bearing decision vs ambient context | `decisions`, `overview`                  |
+| `SPEC-R005` | Honest rationalizations                  | `rationalizations*` (regex)              |
+| `SPEC-R006` | Non-goals are non-goals                  | `out-of-scope*`, `non-goals*` (regex)    |
+| `SPEC-R007` | Stranger in 6 months                     | `*` (all sections)                       |
+
+For each eligible (section, rubric) pair:
+
+1. Build prompt with rubric description + spec file path + section heading + section body (truncated to 2000 chars if longer for cost control).
+2. LLM returns fenced JSON: `null` (rubric doesn't apply / section is fine) OR `{ tier, impact, confidence, message }`.
+3. On non-null: emit a `SpecFinding` with `cite.rubricId` populated for ADR 0020 traceability.
+
+### Phase 4: REPORT — Aggregate + cost telemetry
+
+Emit `SpecCraftOutput`:
+
+```ts
+{
+  findings: SpecFinding[];
+  summary: {
+    phaseRun: ['critique'];
+    durationMs: number;
+    llmCalls: { provider, model, count, costUsd };
+    catalog: { rubricsApplied: string[] };
+    docsScanned: number;
+    sectionsScanned: number;
+    runId: string;
+  }
+}
+```
+
+## Harness Integration
+
+- **`harness spec-craft`** — CLI entry. `--files <glob>` / `--kinds proposal,adr` / `--sections decisions,scope` / `--max-files <n>` / `--max-sections-per-file <n>` / `--json` / `--verbose`.
+- **`mcp__harness__spec_craft`** — MCP tool. Same input/output. Consumed by agents.
+- **Cross-cutting API:** `critiqueSpecFile(file, opts)` exported from `packages/cli/src/spec-craft/index.ts`. Future craft skills (or `harness-brainstorming`) can call this when they have a doc in hand without re-walking the project.
+- **Shared craft infrastructure (extracted on this PR):** `LlmProvider`, `MockLlmProvider`, `derivePriority`, 3-axis types all live in `packages/cli/src/shared/craft/`. design-craft + naming-craft + spec-craft import from there; design-craft + naming-craft keep their old import paths via re-export shims.
+
+## Success Criteria
+
+See `docs/changes/craft-pipeline/spec-craft/proposal.md` for the full 34 success criteria. Highlights:
+
+- 7 seed rubrics ship at `catalog/rubrics/<id>.ts` (file-per-rubric, matches naming-craft)
+- 3-axis output preserved (tier × impact × confidence, never collapsed)
+- `cite.rubricId` populated on every finding (ADR 0020)
+- Section parser strips frontmatter; splits by H2 only
+- Rubric-to-section mapping skips silently when rubric doesn't apply
+- `critiqueSpecFile` cross-cutting API works on a single file without project walk
+- All existing design-craft + naming-craft tests still pass after shared/craft extraction (zero behavior change)
+
+## Examples
+
+### Example: Vague Decisions section
+
+**Input:** A proposal's `## Decisions` section reads:
+
+```
+| Decision | Why |
+|----------|-----|
+| Use modern stack | scalable and clean |
+| Defer auth | not in scope |
+```
+
+**Output (mock LLM):**
+
+```
+SPEC-R001 [polish/medium/medium] ## Decisions:34
+  "Modern stack" and "scalable and clean" are vague — no concrete framework
+  named, no metric for "scalable", no operational definition of "clean".
+  Sharpen: name the framework, state the scale target (req/sec, team size),
+  define what "clean" means in observable terms.
+SPEC-R004 [polish/medium/medium] ## Decisions:34
+  The Decisions section pads load-bearing choices with vague qualifiers
+  rather than naming the trade-off chosen and the rejected alternative.
+```
+
+### Example: Strawmanned Rationalizations
+
+**Input:** A `## Rationalizations to reject` section reads:
+
+```
+| "Use a different framework" | Other frameworks are worse |
+```
+
+**Output:**
+
+```
+SPEC-R005 [foundational/large/high] ## Rationalizations to reject:88
+  "Other frameworks are worse" is a strawman — not stated charitably, not
+  paired with a specific reason. Steelman the rejected position: name the
+  competing framework, name its strongest feature, then explain the specific
+  trade-off that made it unsuitable here.
+```
+
+### Example: Empty project — no specs
+
+**Input:** Project has no `docs/changes/` or `docs/knowledge/decisions/` directory.
+
+**Output:**
+
+```
+No spec findings.
+
+Summary: 0 findings across 0 docs (0 sections, 7 rubrics, 0 LLM calls, $0.0000, 3ms)
+```
+
+## Gates
+
+- **No autofix.** Sibling `align-spec` deferred until signal warrants safe-to-apply rewrites.
+- **No README / general doc critique.** docs-craft (#2) territory.
+- **No source-code comment critique.** code-craft / docs-craft territory.
+- **No B' bootstrap.** Same posture as naming-craft v1.
+- **No graph persistence.** Phase 1 MVP.
+- **No vision/deep mode.** Specs are text.
+- **No structural floor enforcement.** harness-soundness-review checks the floor; spec-craft assumes the floor is satisfied and critiques the ceiling.
+
+## Escalation
+
+- **When LLM cost is too high:** drop `maxSectionsPerFile` to 5 or `maxFiles` to 25. Per-doc cost = sections × rubrics × per-call. Rubric-to-section mapping already prunes most calls; further: use `--sections decisions` to target the highest-value section.
+- **When a rubric produces high false-positive rate:** v1 has no per-rubric disable; v1.x adds `craft.spec.disabledRubrics: ['SPEC-R007']`. Until then: filter findings by `cite.rubricId` in your consumer.
+- **When a spec has intentionally aspirational vagueness (e.g., a manifesto-style Overview):** SPEC-R001 will flag it; low-confidence findings are de-emphasized per ADR 0019. v1.x adds per-section opt-out via `<!-- spec-craft:skip -->` HTML comment.
+- **When you want a doc-level summary instead of per-section findings:** v1 is per-section only; v1.x adds a `--mode doc` opt-in for whole-doc critique.
+- **When you want to critique RFCs:** v1.x. For now, point `--files <rfc.md>` at a single file — the section parser works on any markdown.
+
+## Status
+
+**v1 — in implementation.** See:
+
+- Spec: `docs/changes/craft-pipeline/spec-craft/proposal.md`
+- Roadmap entry: `craft-pipeline sub-project #6` (the highest-leverage craft skill)
+- Sibling craft skills: `harness-design-craft` (design-pipeline #6), `naming-craft` (craft-pipeline #1)
+- Shared infrastructure: `packages/cli/src/shared/craft/` (extracted on this PR)
+- Future: `align-spec` (FIX side), docs-craft (#2), test-craft (#3), code-craft (#4) — each can call `critiqueSpecFile` if they want spec-level critique for a doc they're already processing.

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

@@ -0,0 +1,55 @@
+name: spec-craft
+version: "0.1.0"
+description: LLM-judgment critique of spec quality (proposals + ADRs) against a curated rubric catalog. Per-section critique with rubric-to-section mapping. Second craft-pipeline ceiling skill; highest-leverage because spec quality compounds across the lifecycle below it. Triggered the shared craft infrastructure extraction.
+stability: draft
+cognitive_mode: constructive-architect
+triggers:
+  - manual
+  - on_pr
+  - on_new_feature
+platforms:
+  - claude-code
+tools:
+  - Bash
+  - Read
+  - Glob
+  - Grep
+cli:
+  command: harness spec-craft
+  args:
+    - name: path
+      description: Project root path
+      required: false
+    - name: files
+      description: Optional spec file/glob scope
+      required: false
+    - name: kinds
+      description: Restrict to proposal / adr
+      required: false
+    - name: sections
+      description: Restrict to canonical section names
+      required: false
+mcp:
+  tool: spec_craft
+  input:
+    path: string
+type: rigid
+tier: 2
+phases:
+  - name: discover
+    description: Glob docs/changes/*/proposal.md + docs/knowledge/decisions/*.md
+    required: true
+  - name: parse
+    description: Markdown H2 section splitter (frontmatter-aware)
+    required: true
+  - name: critique
+    description: LLM-rubric loop per (file, section, rubric) where rubric applies
+    required: true
+  - name: report
+    description: Aggregate findings + cost telemetry + doc/section counts
+    required: true
+state:
+  persistent: false
+depends_on:
+  - harness-soundness-review
+  - harness-design-craft