@luizsantiago/spec-guardrails 4.5.2 → 4.6.0

package/README.md

@@ -10,7 +10,7 @@
 
 Spec Guardrails installs a working method into your repository: the agent writes down what it is going to build, gets your approval, implements in small waves, and proves the result before calling it done. Nothing about your stack changes — you get written requirements, a task plan, and verification evidence stored as files in the project.
 
-npm: [`@luizsantiago/spec-guardrails`](https://www.npmjs.com/package/@luizsantiago/spec-guardrails) **4.5.x**
+npm: [`@luizsantiago/spec-guardrails`](https://www.npmjs.com/package/@luizsantiago/spec-guardrails) **4.6.x**
 
 ---
 
@@ -60,7 +60,7 @@ In short: Python turns "trust the agent" into "the agent has to prove it."
 
 Which checks exist and what each one requires: [Gates](docs/guide/gates.md) · [Guarantees matrix](docs/guide/Guarantees-matrix.md)
 
-Read more: [Quick start](docs/guide/Quick-start.md) · [Platform parity](docs/guide/Platform-parity.md) · [CHANGELOG](docs/CHANGELOG.md)
+Read more: [Quick start](docs/guide/Quick-start.md) · [Tutorials](docs/guide/tutorials/README.md) · [Platform parity](docs/guide/Platform-parity.md) · [CHANGELOG](docs/CHANGELOG.md)
 
 ---
 

package/index.js

@@ -25,6 +25,10 @@ import {
   savePolicyState,
 } from "./lib/execution-policy.js";
 import { featureInit } from "./lib/feature.js";
+import {
+  featureOverview,
+  formatFeatureOverview,
+} from "./lib/feature-overview.js";
 import { featureStatus, formatFeatureStatus } from "./lib/feature-status.js";
 import { GATE_COMMANDS, AUX_COMMANDS, runGate, runGuardrailsScript } from "./lib/gates.js";
 import { install } from "./lib/install.js";
@@ -105,6 +109,9 @@ Commands:
     [--json]                         Machine-readable output
   feature-status [feature]           Artifact checklist + next step for a feature
     [--json]                         Machine-readable output
+  feature-overview [feature]           REQ → task → evidence dashboard (markdown)
+    [--write]                        Save .specs/features/<feature>/overview.md
+    [--json]                         Machine-readable output (no markdown body)
   phase-context <phase>              Print .specs/config.yaml context + rules for a phase
   doctor [path]                      Audit guardrails readiness (score + next actions)
     [--json]                         Machine-readable output
@@ -1079,6 +1086,33 @@ if (command === "--version" || command === "-v" || command === "version") {
     console.error(`❌ ${err.message}`);
     process.exit(1);
   }
+} else if (command === "feature-overview") {
+  try {
+    let json = false;
+    let write = false;
+    const positional = [];
+    for (const arg of args) {
+      if (arg === "--json") {
+        json = true;
+      } else if (arg === "--write") {
+        write = true;
+      } else {
+        positional.push(arg);
+      }
+    }
+    const overview = await featureOverview(positional[0], { write });
+    if (json) {
+      console.log(JSON.stringify(overview, null, 2));
+    } else {
+      process.stdout.write(formatFeatureOverview(overview));
+      if (overview.writtenTo) {
+        process.stderr.write(`\nWrote ${overview.writtenTo}\n`);
+      }
+    }
+  } catch (err) {
+    console.error(`❌ ${err.message}`);
+    process.exit(1);
+  }
 } else if (AUX_COMMANDS.includes(command)) {
   try {
     const code = await runGuardrailsScript(command, args);

package/lib/agent-contract.js

@@ -28,7 +28,7 @@ When planning architecture, specs, or multi-step features, read the hub first:
 Deterministic gates (\`python3\`, non-zero exit means STOP):
 
 - Scripts in \`.specs/guardrails/scripts/\` — the **agent** runs them at phase boundaries (see hub).
-- Humans: \`install\` once; optional \`feature-init\`, \`project-init\`, \`doctor\`, \`classify-change\`, \`feature-status\`.
+- Humans: \`install\` once; optional \`feature-init\`, \`project-init\`, \`doctor\`, \`classify-change\`, \`feature-status\`, \`feature-overview\`.
 - Full CLI: \`npx @luizsantiago/spec-guardrails --help\`
 - Onboarding: \`.specs/GETTING_STARTED.md\`
 

package/lib/feature-overview.js

@@ -0,0 +1,237 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import { readFileSafe } from "./fs-utils.js";
+import { featureStatus } from "./feature-status.js";
+import { featureDir, resolveFeatureId } from "./specs-utils.js";
+
+const REQ_ID = /\b[A-Z][A-Z0-9]{1,9}-\d{2,4}\b/g;
+const TASK_HEADING = /^#{2,6}\s*(T\d+)[:\s]+(.+)$/gim;
+const TASK_FIELD =
+  /^\s*[-*]?\s*\*{0,2}([A-Za-z][A-Za-z ]+?)\*{0,2}\s*:\s*(.+?)\s*$/gim;
+const EVIDENCE = /[\w./\\-]+\.[A-Za-z][A-Za-z0-9]{0,9}:\d{1,6}\b/g;
+
+/**
+ * @param {string} text
+ * @returns {string[]}
+ */
+function uniqueReqIds(text) {
+  return [...new Set(text.match(REQ_ID) ?? [])];
+}
+
+/**
+ * @param {string} tasksText
+ * @returns {Array<{ id: string, title: string, requirement: string | null, complete: boolean }>}
+ */
+function parseTasks(tasksText) {
+  const headings = [...tasksText.matchAll(TASK_HEADING)];
+  /** @type {Array<{ id: string, title: string, requirement: string | null, complete: boolean }>} */
+  const tasks = [];
+
+  for (let i = 0; i < headings.length; i += 1) {
+    const start = headings[i].index ?? 0;
+    const end = headings[i + 1]?.index ?? tasksText.length;
+    const block = tasksText.slice(start, end);
+    const id = headings[i][1];
+    const title = headings[i][2].trim();
+    let requirement = null;
+    for (const match of block.matchAll(TASK_FIELD)) {
+      if (match[1].trim().toLowerCase() === "requirement") {
+        requirement = match[2].trim();
+        break;
+      }
+    }
+    const complete = /-\s*\[x\]\s*complete\b/i.test(block);
+    tasks.push({ id, title, requirement, complete });
+  }
+  return tasks;
+}
+
+/**
+ * @param {string} validationText
+ * @param {string} reqId
+ * @returns {string | null}
+ */
+function evidenceForReq(validationText, reqId) {
+  for (const line of validationText.split(/\r?\n/)) {
+    if (!line.includes(reqId)) {
+      continue;
+    }
+    const hit = line.match(EVIDENCE);
+    if (hit?.[0]) {
+      return hit[0];
+    }
+  }
+  return null;
+}
+
+/**
+ * @param {string} specText
+ * @returns {string | null}
+ */
+function summarizeGoal(specText) {
+  const title = specText.match(/^#\s+(.+)$/m)?.[1]?.trim();
+  if (title && !/^spec/i.test(title)) {
+    return title;
+  }
+  const firstReq = specText.match(
+    /^###\s+([A-Z][A-Z0-9]{1,9}-\d{2,4})\b[^\n]*\n+([^\n#]+)/m,
+  );
+  if (firstReq) {
+    return `${firstReq[1]} — ${firstReq[2].trim()}`;
+  }
+  return title ?? null;
+}
+
+/**
+ * @param {string} [featureArg]
+ * @param {{ cwd?: string }} [options]
+ */
+export async function buildFeatureOverview(featureArg, options = {}) {
+  const cwd = options.cwd ?? process.cwd();
+  const featureId = await resolveFeatureId(featureArg, cwd);
+  const status = await featureStatus(featureId, { cwd });
+  const dir = featureDir(featureId, cwd);
+
+  let specText = "";
+  let tasksText = "";
+  let validationText = "";
+
+  try {
+    specText = await readFileSafe(path.join(dir, "spec.md"));
+  } catch {
+    // optional until Specify
+  }
+  try {
+    tasksText = await readFileSafe(path.join(dir, "tasks.md"));
+  } catch {
+    // optional until Tasks
+  }
+  try {
+    validationText = await readFileSafe(path.join(dir, "validation.md"));
+  } catch {
+    // optional until Verify
+  }
+
+  const reqIds = uniqueReqIds(specText);
+  const tasks = tasksText ? parseTasks(tasksText) : [];
+  const reqToTasks = new Map();
+  for (const task of tasks) {
+    if (!task.requirement) {
+      continue;
+    }
+    for (const reqId of uniqueReqIds(task.requirement)) {
+      const list = reqToTasks.get(reqId) ?? [];
+      list.push(task.id);
+      reqToTasks.set(reqId, list);
+    }
+  }
+
+  const traceability = reqIds.map((reqId) => ({
+    reqId,
+    tasks: reqToTasks.get(reqId) ?? [],
+    evidence: validationText ? evidenceForReq(validationText, reqId) : null,
+  }));
+
+  return {
+    featureId,
+    generatedAt: new Date().toISOString(),
+    goal: specText ? summarizeGoal(specText) : null,
+    status,
+    tasks,
+    traceability,
+  };
+}
+
+/**
+ * @param {Awaited<ReturnType<typeof buildFeatureOverview>>} overview
+ * @returns {string}
+ */
+export function formatFeatureOverview(overview) {
+  const { status } = overview;
+  const artifactRows = Object.entries(status.artifacts)
+    .map(([name, present]) => `| ${name} | ${present ? "present" : "missing"} |`)
+    .join("\n");
+
+  const taskRows =
+    overview.tasks.length > 0
+      ? overview.tasks
+          .map(
+            (task) =>
+              `| ${task.id} | ${task.title} | ${task.requirement ?? "—"} | ${task.complete ? "done" : "open"} |`,
+          )
+          .join("\n")
+      : "| — | — | — | — |";
+
+  const traceRows =
+    overview.traceability.length > 0
+      ? overview.traceability
+          .map((row) => {
+            const tasks =
+              row.tasks.length > 0 ? row.tasks.join(", ") : "—";
+            return `| ${row.reqId} | ${tasks} | ${row.evidence ?? "—"} |`;
+          })
+          .join("\n")
+      : "| — | — | — |";
+
+  const taskSummary = status.tasks
+    ? `${status.tasks.complete}/${status.tasks.total} complete (${status.tasks.open} open)`
+    : "—";
+
+  return `# Feature overview: ${overview.featureId}
+
+> Generated ${overview.generatedAt}. Refresh with \`feature-overview ${overview.featureId} --write\`.
+
+## Summary
+
+| Field | Value |
+| --- | --- |
+| Goal | ${overview.goal ?? "—"} |
+| Phase | ${status.phase ?? "—"} |
+| Branch | ${status.branch ?? "—"} |
+| Tasks | ${taskSummary} |
+| Validation | ${status.verdict ?? "—"} |
+| Next | ${status.next} |
+
+## Artifacts
+
+| Artifact | Status |
+| --- | --- |
+${artifactRows}
+
+## Tasks
+
+| Task | Title | Requirement | Status |
+| --- | --- | --- | --- |
+${taskRows}
+
+## Traceability (REQ → task → evidence)
+
+| REQ | Task(s) | Test evidence |
+| --- | --- | --- |
+${traceRows}
+
+_Evidence rows populate after \`validation.md\` exists. Structural gaps are caught by \`validate-traceability\`._
+`;
+}
+
+/**
+ * @param {string} [featureArg]
+ * @param {{ cwd?: string; write?: boolean }} [options]
+ */
+export async function featureOverview(featureArg, options = {}) {
+  const cwd = options.cwd ?? process.cwd();
+  const overview = await buildFeatureOverview(featureArg, { cwd });
+  const markdown = formatFeatureOverview(overview);
+
+  if (options.write) {
+    const outPath = path.join(
+      featureDir(overview.featureId, cwd),
+      "overview.md",
+    );
+    await fs.writeFile(outPath, markdown, "utf8");
+    overview.writtenTo = outPath;
+  }
+
+  return overview;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@luizsantiago/spec-guardrails",
-  "version": "4.5.2",
+  "version": "4.6.0",
   "description": "Governed spec-driven development for AI coding agents. Your agent writes the spec, gets your approval, builds in small waves, and proves the result — plans and project memory stored as files in your repo.",
   "type": "module",
   "bin": {
@@ -12,7 +12,7 @@
   "scripts": {
     "guardrails": "node index.js",
     "test": "npm run test:node && npm run test:gates",
-    "test:node": "node --test test/install.test.js test/test_platform_detect.test.js test/test_feature_init.test.js test/test_config.test.js test/test_archive.test.js test/test_delta_merge.test.js test/test_presets.test.js test/test_brownfield.test.js test/test_doctor.test.js test/test_token_cost.test.js test/test_next_steps.test.js test/test_classify_change.test.js test/test_feature_status.test.js test/test_agent_contract.test.js test/test_gates_python.test.js test/test_specs_utils.test.js test/test_validation_verdict.test.js test/test_execution_policy.test.js test/test_workspace_isolation.test.js test/test_adapter_registry.test.js test/test_context_guard.test.js test/test_solution_exploration.test.js test/test_memory_doctor.test.js test/test_cursor_hooks_cleanup.test.js test/test_sandbox_policy.test.js test/test_req_analysis.test.js",
+    "test:node": "node --test test/install.test.js test/test_platform_detect.test.js test/test_feature_init.test.js test/test_config.test.js test/test_archive.test.js test/test_delta_merge.test.js test/test_presets.test.js test/test_brownfield.test.js test/test_doctor.test.js test/test_token_cost.test.js test/test_next_steps.test.js test/test_classify_change.test.js test/test_feature_status.test.js test/test_feature_overview.test.js test/test_agent_contract.test.js test/test_gates_python.test.js test/test_specs_utils.test.js test/test_validation_verdict.test.js test/test_execution_policy.test.js test/test_workspace_isolation.test.js test/test_adapter_registry.test.js test/test_context_guard.test.js test/test_solution_exploration.test.js test/test_memory_doctor.test.js test/test_cursor_hooks_cleanup.test.js test/test_sandbox_policy.test.js test/test_req_analysis.test.js",
     "test:gates": "node test/run-gate-tests.mjs",
     "prepublishOnly": "npm test"
   },

package/skills/agent-architecture.md

@@ -67,6 +67,7 @@ Structural gates run **before** owner review, so they cannot drift when the mode
 | Quick mode evidence | `python3 .specs/guardrails/scripts/validate_quick.py [feature]` |
 | After Verify PASS | `npx @luizsantiago/spec-guardrails archive-feature [feature]` (Tier 0) |
 | Before a phase procedure (optional) | `npx @luizsantiago/spec-guardrails phase-context <phase>` |
+| Feature dashboard (human-readable) | `npx @luizsantiago/spec-guardrails feature-overview [feature] [--write]` |
 | After a FAIL verdict | `python3 .specs/guardrails/scripts/lessons.py add --source .specs/features/[feature]/validation.md` |
 
 Gates accept a feature name, a feature directory, or a path to the artifact. With no argument they auto-detect when the project has exactly one feature; with several they list candidates and exit 2. A spec is rejected unless every criterion uses `SHALL` or `MUST` and `## Assumptions` is present.

package/skills/references/converge.md

@@ -28,10 +28,12 @@ Updated `tasks.md` with new tasks for uncovered work (append only — do not rew
 
 1. **Re-read the spec** — list every REQ and whether tests exist for its outcome.
 2. **Audit the diff** — files changed outside task `Files` fields are scope drift or missing tasks.
-3. **Run analyze** — `analyze_artifacts.py [feature]`.
-4. **Append tasks** for gaps using the standard task template in `tasks.md`.
-5. **Update STATE** Next Step to the first open task.
-6. **Commit** `.specs/` changes (Tier 0) — no push.
+3. **Living-spec drift (lightweight)** — when `domains/<slug>/spec.md` exists, spot-check that files still match declared globs or modules; append a task if production code moved without updating domain memory.
+4. **Run analyze** — `analyze_artifacts.py [feature]`.
+5. **Append tasks** for gaps using the standard task template in `tasks.md`.
+6. **Refresh dashboard** — `npx @luizsantiago/spec-guardrails feature-overview [feature] --write`.
+7. **Update STATE** Next Step to the first open task.
+8. **Commit** `.specs/` changes (Tier 0) — no push.
 
 ## Rules
 

package/skills/references/implement.md

@@ -64,8 +64,9 @@ loop-plan → dispatch (parallel sub-agents | inline) → merge → loop-plan
 2. **Dispatch**
    - **Parallel group (2+ tasks):** one sub-agent per task with the worker brief in `sub-agents.md`. Cap at 3 workers + 1 verifier (see `task-graph-engineering.md`).
    - **Single task:** run the per-task cycle below inline (or as sole worker).
-3. **Merge** — After a parallel round, confirm every task is `[x]`, commits exist, and the project harness passes once on the integrated tree.
-4. **Repeat** — Run `loop-plan` again until all tasks are complete, then close Execute.
+3. **Two-stage batch review** — After workers return and before merge, the orchestrator reviews each batch twice (see `sub-agents.md`): spec compliance, then code quality. Do not merge until both pass.
+4. **Merge** — Confirm every task is `[x]`, commits exist, and the project harness passes once on the integrated tree.
+5. **Repeat** — Run `loop-plan` again until all tasks are complete, then close Execute.
 
 Do not start the next wave until the current wave is fully committed. Parallelism is **inside** a wave only when `Files` do not overlap.
 
@@ -194,8 +195,9 @@ docs(spec): record validation report for auth
 When the last task is complete:
 
 1. Run the full project harness once more (tests, linter, build).
-2. Trigger `/verify` with a fresh context — mandatory, never prompted. See `validate.md`.
-3. Do not declare the feature done until `validate_state.py` passes.
+2. Refresh the feature dashboard: `npx @luizsantiago/spec-guardrails feature-overview [feature] --write` (writes `overview.md`).
+3. Trigger `/verify` with a fresh context — mandatory, never prompted. See `validate.md`.
+4. Do not declare the feature done until `validate_state.py` passes.
 
 ## Next
 

package/skills/references/sub-agents.md

@@ -69,6 +69,23 @@ Every worker returns this shape — no narrative dump:
 - Blockers: none | [gate output excerpt]
 ```
 
+## Two-stage batch review (orchestrator)
+
+After workers return and **before** merge, the orchestrator runs both stages. Workers do not self-certify merge readiness.
+
+| Stage | Question | Evidence |
+| --- | --- | --- |
+| **1 — Spec compliance** | Does each commit satisfy its task `Done when` and the REQ IDs on that task? | Re-read task blocks + diff; compare to spec criteria |
+| **2 — Code quality** | Is the integrated harness green, free of new suppressions, and scoped to task `Files`? | Project harness + `check_suppressions.py` on staged diff |
+
+| Outcome | Action |
+| --- | --- |
+| Stage 1 FAIL | Send worker back, or rewrite the task — do not merge |
+| Stage 2 FAIL | Fix or revert before merge — do not weaken tests |
+| Both PASS | Merge owner integrates worktrees, runs harness once, proceeds |
+
+Pattern adapted from [Superpowers subagent-driven-development](https://github.com/obra/superpowers) — compliance before polish.
+
 ## Failure handling
 
 | Event | Action |

package/skills/security-review.md

@@ -26,6 +26,22 @@ For changes with **no** auth, API, user input, payments, or infrastructure impac
 
 Full OWASP checklist remains mandatory for anything touching auth, data, APIs, or infra.
 
+## Third-party agent skills (supply chain)
+
+Spec Guardrails ships skills you install with `npx @luizsantiago/spec-guardrails install`. When adding **other** skill packs from GitHub, marketplaces (`skills.sh`, plugin stores), or zip files:
+
+1. **Read before trust** — inspect `SKILL.md` and any bundled scripts; skills run with agent privileges.
+2. **Scan when risk is non-trivial** — use [NVIDIA SkillSpector](https://github.com/NVIDIA/SkillSpector) for static (and optional LLM) analysis before install:
+
+   ```bash
+   skillspector scan https://github.com/user/some-skill --no-llm
+   ```
+
+3. **Prefer signed catalogs** — NVIDIA Verified Skills and official plugin marketplaces reduce supply-chain risk; still review high-privilege skills.
+4. **Never bypass Brakes** — third-party skills do not replace Spec Guardrails gates (`check-suppressions`, `validate-state`, …).
+
+For publication-quality skill evaluation (overlap detection, live agent eval), see [SkillEvaluator](https://github.com/NVIDIA/SkillEvaluator) — complementary to this package, not a replacement.
+
 ## Pre-Review Setup
 
 - Verifier must have **clean context** (not the code author).

package/skills/task-graph-engineering.md

@@ -72,6 +72,7 @@ The shape serious systems converge to for splittable work:
 | --- | --- | --- |
 | Plan | Single planner | Produces `tasks.md` + `task-graph.md` |
 | Workers | 1–3 parallel agents | Disjoint file ownership only |
+| Batch review | Orchestrator (two stages) | Spec compliance, then code quality — before merge |
 | Verify | Fresh verifier context | Never the code author |
 | Merge | One merge owner | Resolves conflicts, runs harness |
 | Result | Commits + evidence | Handoff to `/archive` when done |