@luizsantiago/spec-guardrails 4.8.0 → 5.0.0

package/README.md

@@ -21,7 +21,7 @@ You keep control: the agent proposes; you approve specs and tasks; push, merge,
 
 **Platform adapters.** The same kit installs into the skill tree your agent already reads — **Cursor** (`.cursor/skills/`), **Claude Code** (`.claude/skills/`), **GitHub Copilot** (`.github/skills/`), **OpenAI Codex** (`.codex/skills/`), plus root `AGENTS.md` for other tools. By default `install` detects one platform and writes **one** tree; use `--all-platforms` when the repo serves multiple agents. Existing trees are preserved when you switch IDEs.
 
-npm: [`@luizsantiago/spec-guardrails`](https://www.npmjs.com/package/@luizsantiago/spec-guardrails) **4.8.x**
+npm: [`@luizsantiago/spec-guardrails`](https://www.npmjs.com/package/@luizsantiago/spec-guardrails) **5.0.x**
 
 **Docs:** [Overview](docs/guide/Overview.md) · [Quick start](docs/guide/Quick-start.md) · [Full guide index](docs/guide/README.md)
 

package/index.js

@@ -67,6 +67,14 @@ import {
   listPresets,
   loadPresetText,
 } from "./lib/presets.js";
+import {
+  formatLoopListJson,
+  formatLoopPattern,
+  formatLoopRunBrief,
+  getLoopPattern,
+  listLoopPatterns,
+  loadLoopCatalog,
+} from "./lib/operational-loops.js";
 
 const USAGE = `Usage: ${CLI_NAME} <command> [args]
 
@@ -85,6 +93,7 @@ Commands:
     [--domains a,b,c]                Explicit domain slugs (overrides auto-detect)
     [--no-domains]                   Skip .specs/domains/ scaffolding
     [--no-project]                   Skip PROJECT.md generation
+    [--no-code-index]                Skip code-index rebuild after init
     [--force]                        Overwrite generated project/domain/config files
     [--dry-run]                      Print scan results without writing files
   feature-init "<description>"       Allocate NNN-slug feature, STATE, local branch (Tier 0)
@@ -188,6 +197,13 @@ Commands:
   analyze-artifacts [feature]        Cross-artifact consistency before task approval
   validate-tasks [tasks.md|feature]  Granularity gate for a task breakdown
   loop-plan [tasks.md|feature]       Next Execute wave — parallel groups + sub-agent hints
+  loop list                          Operational loop patterns (repo health, CI, triage)
+    [--json]                         Machine-readable catalog
+  loop show <pattern-id>             Show one operational loop pattern
+    [--json]                         Machine-readable output
+  loop run <pattern-id>              Print agent brief for an operational loop
+    [--dry-run]                      Same output (explicit no-op label)
+    [--json]                         Machine-readable brief
     [--json]                         Machine-readable plan for agents
   validate-traceability [feature]    REQ → tasks → validation coverage chain
   validate-ship-surface [feature]    Ship Surface + AI Surface when infra/AI paths in tasks
@@ -335,11 +351,83 @@ if (command === "--version" || command === "-v" || command === "version") {
     console.error(`❌ ${err.message}`);
     process.exit(1);
   }
+} else if (command === "loop") {
+  try {
+    const sub = args[0];
+    const rest = args.slice(1);
+    const json = rest.includes("--json");
+    const dryRun = rest.includes("--dry-run");
+    const positional = rest.filter((arg) => !arg.startsWith("--"));
+
+    if (sub === "list") {
+      const patterns = await loadLoopCatalog();
+      if (json) {
+        console.log(JSON.stringify(formatLoopListJson(patterns), null, 2));
+      } else {
+        const ids = await listLoopPatterns();
+        console.log("Operational loop patterns:");
+        for (const id of ids) {
+          const pattern = patterns[id];
+          console.log(`  ${id} — ${pattern.title} (${pattern.tier}, ${pattern.cadence})`);
+        }
+        console.log(`\nShow detail: ${CLI_NAME} loop show <pattern-id>`);
+      }
+      process.exit(0);
+    }
+
+    if (sub === "show") {
+      const id = positional[0];
+      if (!id) {
+        throw new Error("Usage: loop show <pattern-id> [--json]");
+      }
+      const pattern = await getLoopPattern(id);
+      if (!pattern) {
+        const available = (await listLoopPatterns()).join(", ");
+        throw new Error(`Unknown pattern "${id}". Available: ${available}`);
+      }
+      if (json) {
+        console.log(JSON.stringify({ id, ...pattern }, null, 2));
+      } else {
+        console.log(formatLoopPattern(id, pattern));
+      }
+      process.exit(0);
+    }
+
+    if (sub === "run") {
+      const id = positional[0];
+      if (!id) {
+        throw new Error("Usage: loop run <pattern-id> [--dry-run] [--json]");
+      }
+      const pattern = await getLoopPattern(id);
+      if (!pattern) {
+        const available = (await listLoopPatterns()).join(", ");
+        throw new Error(`Unknown pattern "${id}". Available: ${available}`);
+      }
+      if (json) {
+        console.log(
+          JSON.stringify(
+            { id, dry_run: dryRun, brief: formatLoopRunBrief(id, pattern, { dryRun }) },
+            null,
+            2,
+          ),
+        );
+      } else {
+        console.log(formatLoopRunBrief(id, pattern, { dryRun }));
+      }
+      process.exit(0);
+    }
+
+    throw new Error("Usage: loop list | loop show <pattern-id> | loop run <pattern-id>");
+  } catch (err) {
+    console.error(`❌ ${err.message}`);
+    process.exit(1);
+  }
 } else if (command === "project-init") {
   try {
     const initOptions = {
       skipDomains: false,
       skipProject: false,
+      skipCodeIndex: false,
       force: false,
       dryRun: false,
     };
@@ -361,6 +449,8 @@ if (command === "--version" || command === "-v" || command === "version") {
         initOptions.skipDomains = true;
       } else if (arg === "--no-project") {
         initOptions.skipProject = true;
+      } else if (arg === "--no-code-index") {
+        initOptions.skipCodeIndex = true;
       } else if (arg === "--force") {
         initOptions.force = true;
       } else if (arg === "--dry-run") {

package/lib/brownfield.js

@@ -3,6 +3,7 @@ import path from "node:path";
 
 import { domainSpecStub } from "./delta-merge.js";
 import { ensureDir, readFileSafe, writeFileIfMissing, writeFileSafe } from "./fs-utils.js";
+import { runGuardrailsScriptCapture } from "./gates.js";
 import { initGuardrailsMemory } from "./memory.js";
 import { initProjectConfig } from "./presets.js";
 import { assertSafeDomainSlug, slugifyDomain } from "./slug-utils.js";
@@ -508,6 +509,28 @@ export async function projectInit(options = {}) {
     planned.push(`.specs/config.yaml (replaced, preset: ${preset})`);
   }
 
+  if (!options.skipCodeIndex) {
+    const roots = stack.roots?.length ? stack.roots : ["src", "lib"];
+    try {
+      const { code, stdout, stderr } = await runGuardrailsScriptCapture(
+        "code-index",
+        ["rebuild", "--roots", roots.join(",")],
+        { cwd },
+      );
+      if (code === 0) {
+        planned.push(
+          `.specs/memory/code-index.json (rebuilt, roots: ${roots.join(", ")})`,
+        );
+      } else {
+        planned.push(
+          `code-index rebuild skipped (exit ${code})${stderr ? `: ${stderr.trim().slice(0, 120)}` : ""}`,
+        );
+      }
+    } catch {
+      planned.push("code-index rebuild skipped (Python gates unavailable)");
+    }
+  }
+
   return {
     dryRun: false,
     repoName,

package/lib/operational-loops.js

@@ -0,0 +1,119 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { readFileSafe } from "./fs-utils.js";
+import { NPX } from "./constants.js";
+
+const PACKAGE_ROOT = path.resolve(
+  path.join(path.dirname(fileURLToPath(import.meta.url)), ".."),
+);
+
+export const LOOPS_CATALOG_PATH = path.join(
+  PACKAGE_ROOT,
+  "templates/loops/catalog.json",
+);
+
+/**
+ * @typedef {object} LoopPattern
+ * @property {string} title
+ * @property {string} tier
+ * @property {string} cadence
+ * @property {string} posture
+ * @property {string} description
+ * @property {string[]} constraints
+ * @property {string[]} stop_rules
+ * @property {string[]} suggested_steps
+ */
+
+/**
+ * @returns {Promise<Record<string, LoopPattern>>}
+ */
+export async function loadLoopCatalog() {
+  const raw = await readFileSafe(LOOPS_CATALOG_PATH);
+  const parsed = JSON.parse(raw);
+  return parsed.patterns ?? {};
+}
+
+/**
+ * @returns {Promise<string[]>}
+ */
+export async function listLoopPatterns() {
+  const patterns = await loadLoopCatalog();
+  return Object.keys(patterns).sort();
+}
+
+/**
+ * @param {string} id
+ * @returns {Promise<LoopPattern | null>}
+ */
+export async function getLoopPattern(id) {
+  const patterns = await loadLoopCatalog();
+  return patterns[id] ?? null;
+}
+
+/**
+ * @param {string} id
+ * @param {LoopPattern} pattern
+ * @returns {string}
+ */
+export function formatLoopPattern(id, pattern) {
+  const lines = [
+    `${pattern.title} (${id})`,
+    `Tier: ${pattern.tier} · Cadence: ${pattern.cadence}`,
+    "",
+    pattern.description,
+    "",
+    `Posture: ${pattern.posture}`,
+    "",
+    "Constraints:",
+    ...pattern.constraints.map((item) => `  - ${item}`),
+    "",
+    "Stop rules:",
+    ...pattern.stop_rules.map((item) => `  - ${item}`),
+    "",
+    "Suggested steps:",
+    ...pattern.suggested_steps.map((item) => `  - ${item}`),
+  ];
+  return lines.join("\n");
+}
+
+/**
+ * @param {string} id
+ * @param {LoopPattern} pattern
+ * @param {{ dryRun?: boolean }} [options]
+ * @returns {string}
+ */
+export function formatLoopRunBrief(id, pattern, options = {}) {
+  const prefix = options.dryRun ? "[dry-run] " : "";
+  const lines = [
+    `${prefix}Operational loop: ${pattern.title} (${id})`,
+    "",
+    "This command prints a structured brief for the agent — it does not run automation.",
+    "",
+    formatLoopPattern(id, pattern),
+    "",
+    "Harness hooks:",
+    `  ${NPX("doctor")}`,
+    `  ${NPX(`classify-change "${pattern.title}"`)}`,
+    "",
+    "Feature work still uses: feature-init → Specify → Tasks → loop-plan → Verify.",
+    "See docs/guide/loop-patterns.md for combining operational and feature loops.",
+  ];
+  return lines.join("\n");
+}
+
+/**
+ * @param {Record<string, LoopPattern>} patterns
+ * @returns {object}
+ */
+export function formatLoopListJson(patterns) {
+  return {
+    patterns: Object.entries(patterns).map(([id, pattern]) => ({
+      id,
+      title: pattern.title,
+      tier: pattern.tier,
+      cadence: pattern.cadence,
+    })),
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@luizsantiago/spec-guardrails",
-  "version": "4.8.0",
+  "version": "5.0.0",
   "description": "Governed spec-driven development for AI coding agents: spec-first workflow, optional Python gates (Brakes), repo memory in .specs/, and an optional python-platform preset when Python features touch deploy/infra and/or AI paths.",
   "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_feature_overview.test.js test/test_feature_pr_body.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_feature_pr_body.test.js test/test_operational_loops.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/scripts/_project_config.py

@@ -93,6 +93,11 @@ def load_project_config(cwd: Path | str | None = None) -> dict:
             "require_brief": False,
             "require_brief_complex": True,
             "require_nfr_complex": "warn",
+            "require_test_plan_complex": "warn",
+        },
+        "converge": {
+            "every_n_tasks": 5,
+            "mode": "suggest",
         },
     }
 
@@ -144,6 +149,12 @@ def load_project_config(cwd: Path | str | None = None) -> dict:
             index += 1
             continue
 
+        if stripped == "converge:":
+            section = "converge"
+            section_indent = indent
+            index += 1
+            continue
+
         if section and indent <= section_indent and not stripped.endswith(":"):
             section = None
 
@@ -189,6 +200,19 @@ def load_project_config(cwd: Path | str | None = None) -> dict:
                 config["elicitation"]["require_nfr_complex"] = str(
                     _parse_scalar(match.group(1))
                 ).lower()
+            match = re.match(r"^require_test_plan_complex:\s*(.+)$", stripped)
+            if match:
+                config["elicitation"]["require_test_plan_complex"] = str(
+                    _parse_scalar(match.group(1))
+                ).lower()
+
+        if section == "converge":
+            match = re.match(r"^every_n_tasks:\s*(.+)$", stripped)
+            if match:
+                config["converge"]["every_n_tasks"] = int(_parse_scalar(match.group(1)))
+            match = re.match(r"^mode:\s*(.+)$", stripped)
+            if match:
+                config["converge"]["mode"] = str(_parse_scalar(match.group(1))).lower()
 
         index += 1
 
@@ -205,3 +229,9 @@ def load_elicitation_config(cwd: Path | str | None = None) -> dict:
     """Return elicitation policy with defaults for validate_spec and req-analysis."""
 
     return load_project_config(cwd)["elicitation"]
+
+
+def load_converge_config(cwd: Path | str | None = None) -> dict:
+    """Return converge policy for loop-plan hints."""
+
+    return load_project_config(cwd)["converge"]

package/scripts/loop_plan.py

@@ -24,6 +24,7 @@ import sys
 from pathlib import Path
 
 from _common import resolve_artifact, visible_markdown
+from _project_config import load_converge_config
 from validate_tasks import parse_dependencies, parse_fields, parse_files, split_tasks
 
 GATE = "loop-plan"
@@ -132,9 +133,39 @@ def build_plan(text: str, *, task_graph_text: str | None = None) -> dict:
         "blocked": blocked,
         "all_done": not incomplete,
         "recommend_sub_agents": any(group["sub_agents"] for group in groups),
+        "completed_count": len(completed),
     }
 
 
+def apply_converge_hint(plan: dict, tasks_path: Path) -> None:
+    """Attach /converge suggestion when completed tasks hit configured threshold."""
+
+    feature_dir = tasks_path.parent
+    if feature_dir.parent.name != "features":
+        return
+
+    root = feature_dir.parent.parent.parent
+    policy = load_converge_config(root)
+    mode = str(policy.get("mode", "suggest")).lower()
+    every = int(policy.get("every_n_tasks", 5) or 0)
+
+    if mode == "off" or every <= 0:
+        return
+
+    completed = plan.get("completed_count", len(plan.get("completed", [])))
+    if completed <= 0 or completed % every != 0:
+        return
+
+    plan["converge_suggest"] = True
+    plan["converge_mode"] = mode
+    plan["converge_hint"] = (
+        f"{completed} tasks complete — run /converge: analyze-artifacts, append gaps, "
+        "feature-overview --write"
+    )
+    if mode == "warn":
+        plan["converge_warning"] = True
+
+
 def format_plan(plan: dict) -> str:
     lines: list[str] = []
 
@@ -179,6 +210,11 @@ def format_plan(plan: dict) -> str:
             waiting = ", ".join(item["waiting_on"])
             lines.append(f"  {item['id']}: after {waiting}")
 
+    if plan.get("converge_hint"):
+        lines.append("")
+        prefix = "Converge (warn): " if plan.get("converge_warning") else "Converge (suggest): "
+        lines.append(prefix + plan["converge_hint"])
+
     return "\n".join(lines)
 
 
@@ -200,6 +236,7 @@ def main(argv: list[str] | None = None) -> int:
         graph_path.read_text(encoding="utf-8") if graph_path.is_file() else None
     )
     plan = build_plan(text, task_graph_text=graph_text)
+    apply_converge_hint(plan, path)
 
     if args.json:
         print(json.dumps(plan, indent=2))

package/scripts/validate_spec.py

@@ -87,6 +87,10 @@ NFR_HEADING = re.compile(
     r"^(?P<level>#{2,6})\s*Non-Functional Requirements\b",
     re.MULTILINE | re.IGNORECASE,
 )
+TEST_PLAN_HEADING = re.compile(
+    r"^(?P<level>#{2,6})\s*Test Plan\b",
+    re.MULTILINE | re.IGNORECASE,
+)
 FEATURE_BRIEFS = Path(".specs/project/feature-briefs")
 PROJECT_BRIEF = Path(".specs/project/requirements-brief.md")
 COMPLEX_TASK_FLOOR = 10
@@ -184,6 +188,32 @@ def validate_nfr_section(report: Report, visible: str, feature_dir: Path) -> Non
         report.warn(message)
 
 
+def validate_test_plan_section(report: Report, visible: str, feature_dir: Path) -> None:
+    root = feature_dir.parent.parent.parent
+    policy = load_elicitation_config(root)
+    mode = str(policy.get("require_test_plan_complex", "warn")).lower()
+    if mode == "off" or not is_complex_tier(feature_dir):
+        return
+
+    body = section_body(visible, TEST_PLAN_HEADING)
+    if body and body.strip() and not re.fullmatch(
+        r"\s*[-*]?\s*(none|n/a)\s*",
+        body.strip(),
+        re.IGNORECASE,
+    ):
+        report.ok("Test Plan section present")
+        return
+
+    message = (
+        "Complex-tier feature missing ## Test Plan "
+        "(acceptance scenarios per REQ before tasks)"
+    )
+    if mode == "error":
+        report.error(message)
+    else:
+        report.warn(message)
+
+
 def is_delta_spec(text: str) -> bool:
     visible = visible_markdown(text)
     return any(has_section(visible, heading) for heading, _ in DELTA_SECTIONS)
@@ -437,6 +467,7 @@ def build_report(target: str, text: str, feature_dir: Path | None = None) -> Rep
 
     if feature_dir is not None and not delta:
         validate_nfr_section(report, visible, feature_dir)
+        validate_test_plan_section(report, visible, feature_dir)
 
     for malformed in MALFORMED_ID.finditer(visible):
         raw = malformed.group(0).lstrip("# ").strip()

package/skills/references/converge.md

@@ -41,6 +41,7 @@ Updated `tasks.md` with new tasks for uncovered work (append only — do not rew
 - Never weaken tests to match partial implementation.
 - New tasks need Requirement, Files, Depends on, Tests, Gate, Done when.
 - Re-run `validate_tasks.py` after editing tasks.
+- When `loop-plan --json` shows `converge_suggest`, run this procedure before more Execute.
 
 ## Next
 

package/skills/references/project-init.md

@@ -25,6 +25,7 @@ Map an existing codebase into `.specs/` project memory before the first `/specif
 - `.specs/project/ROADMAP.md` — planned domain drafting items
 - `.specs/domains/[domain]/spec.md` — brownfield stubs (one per detected/manual domain)
 - `.specs/config.yaml` — from auto-detected or chosen preset (when missing)
+- `.specs/memory/code-index.json` — shallow symbol map (unless `--no-code-index`)
 
 ## Procedure
 
@@ -47,6 +48,7 @@ Map an existing codebase into `.specs/` project memory before the first `/specif
 | `--domains a,b` | Manual domain list (overrides auto-detect) |
 | `--no-domains` | Skip domain folder scaffolding |
 | `--no-project` | Skip `PROJECT.md` |
+| `--no-code-index` | Skip `code-index rebuild` after init |
 | `--force` | Overwrite generated project/domain/config files |
 
 ## Rules

package/templates/config.yaml.example

@@ -77,6 +77,13 @@ elicitation:
   require_brief_complex: true
   # warn | error | off — NFR section on Complex-tier full specs
   require_nfr_complex: warn
+  # warn | error | off — Test Plan section on Complex-tier full specs
+  require_test_plan_complex: warn
+
+# Converge hints during Execute (loop-plan --json)
+converge:
+  every_n_tasks: 5
+  mode: suggest   # suggest | warn | off
 
 # Soft OS sandbox (optional — policy, not containers; enforced via sandbox CLI)
 sandbox:

package/templates/loops/catalog.json

@@ -0,0 +1,151 @@
+{
+  "patterns": {
+    "daily-triage": {
+      "title": "Daily triage",
+      "tier": "quick",
+      "cadence": "daily",
+      "posture": "Read-only scan → short report; no feature folder unless a fix ships",
+      "description": "Inbox, issues, and open threads pile up — produce a prioritized snapshot without coding.",
+      "constraints": [
+        "One pattern per session — no mixing with dependency sweeps",
+        "Read-only until owner approves a fix scope",
+        "Cap output to one screen of findings"
+      ],
+      "stop_rules": [
+        "Stop after the report is written",
+        "Escalate to feature-init only when owner picks an item to ship"
+      ],
+      "suggested_steps": [
+        "Run doctor for readiness baseline",
+        "Scan open issues / PR comments / failing CI badges",
+        "classify-change on any fix candidate before Specify"
+      ]
+    },
+    "pr-babysitter": {
+      "title": "PR babysitter",
+      "tier": "medium",
+      "cadence": "per PR",
+      "posture": "Watch CI on open PRs; propose minimal fixes",
+      "description": "Open PRs waiting on CI — diagnose failures and suggest the smallest fix.",
+      "constraints": [
+        "One PR at a time",
+        "No scope expansion beyond the PR intent",
+        "Prefer Medium tier with tasks when the fix touches 3+ files"
+      ],
+      "stop_rules": [
+        "Stop when CI is green or owner defers",
+        "Never force-push main"
+      ],
+      "suggested_steps": [
+        "List open PRs and failing checks",
+        "Reproduce the failure locally",
+        "If fix needs spec/tasks → feature-init or append tasks on existing feature"
+      ]
+    },
+    "ci-sweeper": {
+      "title": "CI sweeper",
+      "tier": "medium",
+      "cadence": "on red main",
+      "posture": "Cautious fixes — one failure at a time",
+      "description": "Main branch or default pipeline is red or flaky — restore green before new features.",
+      "constraints": [
+        "Fix the first failing job only",
+        "Record discrimination sensor notes when behavior changes",
+        "No drive-by refactors"
+      ],
+      "stop_rules": [
+        "Stop when quality.checks pass",
+        "Hand off to feature loop if root cause needs product spec"
+      ],
+      "suggested_steps": [
+        "Run quality-checks or project test command",
+        "Isolate the failing step from CI logs",
+        "check-suppressions before any commit"
+      ]
+    },
+    "dependency-sweeper": {
+      "title": "Dependency sweeper",
+      "tier": "simple",
+      "cadence": "weekly",
+      "posture": "Patch-only bumps; run full test suite",
+      "description": "Outdated packages — apply patch/minor bumps with tests.",
+      "constraints": [
+        "Patch (and agreed minor) only — no major without owner",
+        "One ecosystem at a time (npm OR pip, not both)",
+        "Lockfile commits are atomic"
+      ],
+      "stop_rules": [
+        "Stop after one bump wave passes tests",
+        "Defer breaking upgrades to a Specify feature"
+      ],
+      "suggested_steps": [
+        "Audit outdated deps (npm outdated / pip list --outdated)",
+        "Bump one package or group",
+        "Run project test command + check-commit"
+      ]
+    },
+    "changelog-drafter": {
+      "title": "Changelog drafter",
+      "tier": "quick",
+      "cadence": "pre-release",
+      "posture": "Summarize merged work — docs only",
+      "description": "Before release — draft CHANGELOG / release notes from merged PRs.",
+      "constraints": [
+        "No code changes",
+        "Link PR numbers and owner-facing outcomes",
+        "Match semver section in CHANGELOG"
+      ],
+      "stop_rules": [
+        "Stop when draft is ready for owner review",
+        "Owner publishes — agent never npm publish"
+      ],
+      "suggested_steps": [
+        "git log since last tag",
+        "Group by feat/fix/docs",
+        "Align with docs/CHANGELOG.md format"
+      ]
+    },
+    "post-merge-cleanup": {
+      "title": "Post-merge cleanup",
+      "tier": "quick",
+      "cadence": "after large merge",
+      "posture": "Dead code, TODOs, format — stay inside merged scope",
+      "description": "After a large merge — hygiene pass without new features.",
+      "constraints": [
+        "Only files touched by the merge",
+        "No behavior changes without tests",
+        "Quick tier unless scope grows"
+      ],
+      "stop_rules": [
+        "Stop after validate-quick or owner says done",
+        "Promote to Medium if 4+ files need logic changes"
+      ],
+      "suggested_steps": [
+        "Review merge diff for stray TODOs and debug logs",
+        "Run linter/format on touched paths",
+        "check-commit with chore scope"
+      ]
+    },
+    "issue-triage": {
+      "title": "Issue triage",
+      "tier": "quick",
+      "cadence": "backlog grooming",
+      "posture": "Label, dedupe, propose — no code",
+      "description": "Backlog grooming — organize issues without implementing.",
+      "constraints": [
+        "No code commits",
+        "Propose feature slugs for ROADMAP candidates",
+        "Use Explore, not Execute"
+      ],
+      "stop_rules": [
+        "Stop when triage report is written",
+        "Elicit only when owner picks an issue to specify"
+      ],
+      "suggested_steps": [
+        "Dedupe and label open issues",
+        "classify-change per candidate",
+        "Append ROADMAP.md candidates (owner approves)"
+      ]
+    }
+  }
+}