cyber-sdd 0.0.0

package/skills/manage-ignore/scripts/manage-ignore.mts

@@ -0,0 +1,294 @@
+#!/usr/bin/env node
+// manage-ignore — the concrete curation engine for `.agents/sdd/.sddignore`, the optional
+// gitignore-syntax file `resolve-tracking` consults to decide whether an artifact is tracked or
+// ignored. It reads/writes ONLY `.agents/sdd/.sddignore` — never a spec.md, status, approval, or
+// freeze.
+//
+// Operations:
+//   --list                  print every rule in file order (a missing file prints nothing)
+//   --add <pattern>         validate + append a well-formed gitignore rule (creates the file)
+//   --remove <pattern>      drop a matching rule, preserving the order of the rest (absent = no-op)
+//   --induce <path>         offer a literal-path candidate + a ** generalization (persists nothing)
+//   --preview <pattern>     list the working-tree paths the pattern would ignore / re-track
+//
+// `.sddignore` is gitignore syntax: a plain pattern => ignored, a leading `!` => re-included, `#`
+// comments and blank lines allowed. Order is MEANINGFUL (last-match-wins), so rules are NEVER
+// re-sorted — add appends, remove keeps the surviving order.
+// Pure functions are exported for node:test; running the file directly drives the CLI. No deps
+// (the repo's node-≥23.6 convention).
+
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+
+const IGNORE_FILE = '.agents/sdd/.sddignore'
+const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', '.turbo', '.next', 'coverage'])
+
+// ── the ignore file (raw-line preserving so order + comments survive CRUD) ──
+
+// Split into lines, dropping the single trailing empty produced by a final newline.
+export function splitLines(text: string): string[] {
+	const lines = text.split('\n')
+	if (lines.length > 0 && lines[lines.length - 1] === '') lines.pop()
+	return lines
+}
+
+export function readIgnoreLines(root: string): string[] {
+	const file = join(root, IGNORE_FILE)
+	if (!existsSync(file)) return []
+	try {
+		return splitLines(readFileSync(file, 'utf8'))
+	} catch {
+		return []
+	}
+}
+
+function writeIgnoreLines(root: string, lines: string[]): void {
+	const file = join(root, IGNORE_FILE)
+	mkdirSync(dirname(file), { recursive: true })
+	writeFileSync(file, lines.length === 0 ? '' : `${lines.join('\n')}\n`)
+}
+
+// A line is a rule when it is not blank and not a `#` comment. `!re-track` rules are rules.
+export function isRuleLine(line: string): boolean {
+	const t = line.trim()
+	return t !== '' && !t.startsWith('#')
+}
+
+// ── list ──
+
+// Every rule in file order; comments and blank lines are omitted (a missing file yields []).
+export function listRules(root: string): string[] {
+	return readIgnoreLines(root)
+		.filter(isRuleLine)
+		.map((l) => l.trim())
+}
+
+// ── validation ──
+
+// True when the bracket expression opened at some `[` is never closed by a later `]`.
+function hasUnclosedBracket(s: string): boolean {
+	let i = 0
+	while (i < s.length) {
+		if (s[i] === '\\') {
+			i += 2
+			continue
+		}
+		if (s[i] === '[') {
+			const close = s.indexOf(']', i + 1)
+			if (close === -1) return true
+			i = close + 1
+			continue
+		}
+		i++
+	}
+	return false
+}
+
+// A well-formed gitignore pattern: non-empty after stripping a leading `!` and surrounding space,
+// not a comment, and with no unclosed `[…]` bracket expression.
+export function isValidPattern(pattern: string): boolean {
+	let s = pattern
+	if (s.startsWith('!')) s = s.slice(1)
+	s = s.replace(/^\s+|\s+$/g, '')
+	if (s === '' || s.startsWith('#')) return false
+	if (hasUnclosedBracket(s)) return false
+	return true
+}
+
+// ── add / remove (CRUD, order-preserving) ──
+
+export type CrudResult =
+	| { ok: true; changed: boolean; rules: string[]; message: string }
+	| { ok: false; reason: string }
+
+// Append a well-formed rule after the existing lines (creating the file when absent). Existing
+// order is preserved; a duplicate is a no-op.
+export function addRule(root: string, pattern: string): CrudResult {
+	const p = pattern.trim()
+	if (!isValidPattern(p)) return { ok: false, reason: 'malformed gitignore pattern' }
+	const lines = readIgnoreLines(root)
+	if (lines.some((l) => l.trim() === p)) {
+		return { ok: true, changed: false, rules: listRules(root), message: 'already present' }
+	}
+	const next = [...lines, p]
+	writeIgnoreLines(root, next)
+	return { ok: true, changed: true, rules: next.filter(isRuleLine).map((l) => l.trim()), message: `added ${p}` }
+}
+
+// Drop every line whose rule text equals the pattern, keeping the order of the rest. Removing an
+// absent rule leaves the file byte-for-byte unchanged.
+export function removeRule(root: string, pattern: string): CrudResult {
+	const p = pattern.trim()
+	const lines = readIgnoreLines(root)
+	const next = lines.filter((l) => l.trim() !== p)
+	if (next.length === lines.length) {
+		return { ok: true, changed: false, rules: listRules(root), message: 'nothing was removed' }
+	}
+	writeIgnoreLines(root, next)
+	return { ok: true, changed: true, rules: next.filter(isRuleLine).map((l) => l.trim()), message: `removed ${p}` }
+}
+
+// ── induce ──
+
+export type InduceResult = { ok: true; candidates: string[] } | { ok: false; reason: string }
+
+// From a sample repo-relative path, offer a literal-path candidate and a `**` generalization that
+// ignores the same basename anywhere in the tree. Persists nothing; refuses a path not under the
+// repo (leading slash or a `..` escape).
+export function inducePatterns(_root: string, samplePath: string): InduceResult {
+	const normalized = samplePath.trim().replace(/\\/g, '/')
+	if (normalized.startsWith('/')) return { ok: false, reason: 'path is not repo-relative (absolute)' }
+	const rel = normalized.replace(/\/+$/g, '')
+	if (rel === '' || /(^|\/)\.\.(\/|$)/.test(rel)) {
+		return { ok: false, reason: 'path is not repo-relative' }
+	}
+	const base = rel.split('/').pop() ?? rel
+	const generalized = `**/${base}`
+	const candidates = generalized === rel ? [rel] : [rel, generalized]
+	return { ok: true, candidates }
+}
+
+// ── preview ──
+
+export type PreviewResult = { ok: true; negated: boolean; matches: string[] } | { ok: false; reason: string }
+
+// Compile one gitignore pattern (already `!`-stripped) to a full-match RegExp. `**` spans
+// separators, `*`/`?` stay within one segment, a leading `/` (or an internal `/`) anchors to the
+// repo root, a trailing `/` marks a dir. Every match also covers the node's descendants.
+export function gitignoreToRegExp(pattern: string): RegExp {
+	let pat = pattern
+	if (pat.endsWith('/')) pat = pat.slice(0, -1) // trailing-slash dir marker
+	let anchored = pat.startsWith('/')
+	if (anchored) pat = pat.slice(1)
+	if (pat.includes('/')) anchored = true // an internal separator anchors to root
+	let body = ''
+	for (let i = 0; i < pat.length; i++) {
+		const c = pat[i]
+		if (c === '*') {
+			if (pat[i + 1] === '*') {
+				i++
+				if (pat[i + 1] === '/') {
+					i++
+					body += '(?:.*/)?' // `**/` spans zero or more directory segments
+				} else {
+					body += '.*' // `**` spans separators
+				}
+			} else {
+				body += '[^/]*' // `*` stays within a segment
+			}
+		} else if (c === '?') {
+			body += '[^/]'
+		} else if (c === '[') {
+			let j = i + 1
+			let cls = '['
+			if (pat[j] === '!') {
+				cls += '^'
+				j++
+			}
+			while (j < pat.length && pat[j] !== ']') {
+				cls += /[\\^\]]/.test(pat[j]) ? `\\${pat[j]}` : pat[j]
+				j++
+			}
+			cls += ']'
+			body += cls
+			i = j
+		} else {
+			body += c.replace(/[.+^${}()|\\]/g, '\\$&')
+		}
+	}
+	const prefix = anchored ? '^' : '^(?:.*/)?' // unanchored patterns match at any depth
+	return new RegExp(`${prefix}${body}(?:/.*)?$`) // also cover everything below the matched node
+}
+
+export function matchesPattern(pattern: string, path: string): boolean {
+	const body = pattern.startsWith('!') ? pattern.slice(1) : pattern
+	return gitignoreToRegExp(body).test(path)
+}
+
+// Every repo-relative path (files and dirs) reachable from the root, skipping SKIP_DIRS.
+function walkTree(root: string): string[] {
+	const out: string[] = []
+	const walk = (rel: string): void => {
+		let entries: import('node:fs').Dirent[]
+		try {
+			entries = readdirSync(join(root, rel), { withFileTypes: true })
+		} catch {
+			return
+		}
+		for (const e of entries) {
+			if (SKIP_DIRS.has(e.name)) continue
+			const child = rel ? `${rel}/${e.name}` : e.name
+			out.push(child)
+			if (e.isDirectory()) walk(child)
+		}
+	}
+	walk('')
+	return out.sort()
+}
+
+// List the working-tree paths a candidate pattern would ignore. For a `!pattern`, the same paths
+// are the ones it would RE-TRACK (re-include). Persists nothing; a malformed pattern is refused.
+export function previewPattern(root: string, pattern: string): PreviewResult {
+	const p = pattern.trim()
+	if (!isValidPattern(p)) return { ok: false, reason: 'malformed gitignore pattern' }
+	const negated = p.startsWith('!')
+	const matches = walkTree(root).filter((path) => matchesPattern(p, path))
+	return { ok: true, negated, matches }
+}
+
+// ── CLI ──
+
+function flag(argv: string[], name: string): string | undefined {
+	const i = argv.indexOf(name)
+	return i === -1 ? undefined : argv[i + 1]
+}
+
+export function main(argv: string[]): number {
+	const root = flag(argv, '--root') ?? '.'
+	const w = (s: string) => process.stdout.write(`${s}\n`)
+
+	if (argv.includes('--list')) {
+		for (const rule of listRules(root)) w(rule)
+		return 0
+	}
+	if (argv.includes('--add')) {
+		const r = addRule(root, flag(argv, '--add') ?? '')
+		w(r.ok ? r.message : `refused: ${r.reason}`)
+		return r.ok ? 0 : 1
+	}
+	if (argv.includes('--remove')) {
+		const r = removeRule(root, flag(argv, '--remove') ?? '')
+		w(r.ok ? r.message : `refused: ${r.reason}`)
+		return r.ok ? 0 : 1
+	}
+	if (argv.includes('--induce')) {
+		const r = inducePatterns(root, flag(argv, '--induce') ?? '')
+		if (!r.ok) {
+			w(`unusable: ${r.reason}`)
+			return 1
+		}
+		w('Candidate ignore patterns:')
+		for (const c of r.candidates) w(`  ${c}`)
+		return 0
+	}
+	if (argv.includes('--preview')) {
+		const r = previewPattern(root, flag(argv, '--preview') ?? '')
+		if (!r.ok) {
+			w(`invalid: ${r.reason}`)
+			return 1
+		}
+		const verb = r.negated ? 're-track' : 'ignore'
+		if (r.matches.length === 0) {
+			w(`This pattern would ${verb} no path.`)
+			return 0
+		}
+		w(`This pattern would ${verb}:`)
+		for (const m of r.matches) w(`  ${m}`)
+		return 0
+	}
+
+	w('usage: manage-ignore --list | --add <p> | --remove <p> | --induce <path> | --preview <p>')
+	return 0
+}
+
+if (import.meta.main) process.exit(main(process.argv.slice(2)))

package/skills/manage-scenario-bridge/README.md

@@ -0,0 +1,20 @@
+# manage-scenario-bridge
+
+The concrete engine for `<project-path>/.agents/sdd/scenario-bridge.toml` — the one-time
+per-project wiring the `verify-scenarios` bridge and the impl-judge step-0 consumption both read. A
+non-user-invocable skill, loaded in-session by the `manage` gateway (Setup & discovery), carrying a
+self-contained `.mts` script that lists / scaffolds / adds sources so users never hand-author the
+config.
+
+- **Skill contract:** [`SKILL.md`](./SKILL.md)
+- **Script:** [`scripts/manage-scenario-bridge.mts`](./scripts/manage-scenario-bridge.mts)
+- **Tests:** [`scripts/manage-scenario-bridge.test.mts`](./scripts/manage-scenario-bridge.test.mts) (`node:test`)
+
+```bash
+node scripts/manage-scenario-bridge.mts --project-path packages/cyberlegion --list
+node scripts/manage-scenario-bridge.mts --project-path packages/cyberlegion --scaffold \
+  --adapter junit --command "vitest run --reporter=junit --outputFile=.agents/.scenario-report.xml" \
+  --report-path .agents/.scenario-report.xml
+node scripts/manage-scenario-bridge.mts --project-path packages/cyberlegion --add \
+  --adapter junit --report-path .agents/.other-report.xml
+```

package/skills/manage-scenario-bridge/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: manage-scenario-bridge
+description: "Partial Skill: invoke by name only — the curation engine for a project's scenario-bridge.toml — loaded by the manage gateway (Setup & discovery), not triggered by users directly."
+user-invocable: false
+metadata:
+  internal: true
+---
+
+# Manage Scenario Bridge
+
+The concrete engine for `<project-path>/.agents/sdd/scenario-bridge.toml` — the one-time
+per-project wiring the [`verify-scenarios`](../verify-scenarios/) bridge and the `sdd-impl-judge`
+step-0 consumption both read. It is the **write** side of that config (`verify-scenarios` is the
+read side). It exists so a user wires a project's scenario bridge through a clean interface instead
+of hand-authoring the TOML. Loaded **in-session** by the `manage` gateway (Setup & discovery group);
+it carries a self-contained `.mts` script (the repo's node-≥23.6 / no-deps convention).
+
+## The file it curates
+
+`<project-path>/.agents/sdd/scenario-bridge.toml` is an array-of-tables of result **sources**,
+mirroring `verify-scenarios`' own config shape — never diverge the format:
+
+```toml
+[[source]]
+adapter    = "junit"
+command    = "pnpm build && vitest run src --reporter=junit --outputFile=.agents/.scenario-report.xml"
+reportPath = ".agents/.scenario-report.xml"
+```
+
+A colocated project's `project-path` is its own repo root, so the config lands at the familiar
+`.agents/sdd/scenario-bridge.toml` — no behavior change for a single-project repo. A monorepo
+member's config sits at `<project-path>/.agents/sdd/scenario-bridge.toml`, beside the code and
+reports it covers.
+
+## Run an operation
+
+```bash
+node "<skill>/scripts/manage-scenario-bridge.mts" --project-path <dir> <operation>
+```
+
+| Operation | Effect |
+|---|---|
+| `--list` | print every configured `[[source]]` block in order; a missing file lists nothing, no error |
+| `--scaffold --adapter <a> [--command <c>] --report-path <p>` | create the config under the project's `project-path` with one source block; refused when the file already exists |
+| `--add --adapter <a> [--command <c>] --report-path <p>` | append a source block to an existing config; refused when the file does not exist (names `--scaffold` as the entry point) |
+
+A `--scaffold` or `--add` missing `--adapter` or `--report-path` is refused — no source block is
+written.
+
+## Boundaries
+
+Writes **only** `<project-path>/.agents/sdd/scenario-bridge.toml` — never a `spec.md`, `status`,
+`approval`, or a freeze; it is operational config, not spec content (so `manage`'s write-ownership
+guard holds). It does not author the binding tests a source reports on (the impl-producer does,
+`sdd:impl-producer-governance`), and does not run the bridge or judge anything (`verify-scenarios`
+and the impl-judge do).
+
+When `node` is absent, an agent performs the same edits by hand: read the file, apply the
+list/scaffold/add, and refuse a scaffold over an existing file or a request missing a required
+field.

package/skills/manage-scenario-bridge/scripts/manage-scenario-bridge.mts

@@ -0,0 +1,156 @@
+#!/usr/bin/env node
+// manage-scenario-bridge — the concrete curation engine for `<project-path>/.agents/sdd/scenario-bridge.toml`,
+// the one-time per-project wiring the verify-scenarios bridge and the impl-judge step-0 consumption
+// both read. It reads/writes ONLY that one project's scenario-bridge.toml — never a spec.md, status,
+// approval, or a freeze; it never runs the bridge or a test.
+//
+// Operations:
+//   --list                                        print every configured [[source]] block in order
+//   --scaffold --adapter <a> [--command <c>] --report-path <p>
+//                                                  create the config with one source block; refused
+//                                                  when the file already exists
+//   --add --adapter <a> [--command <c>] --report-path <p>
+//                                                  append a source block to an existing config;
+//                                                  refused when the file does not exist
+//
+// Every read/write is resolved beneath --project-path (a colocated project's project-path is its own
+// repo root, so the config lands at the familiar .agents/sdd/scenario-bridge.toml there).
+//
+// Reuses the verify-scenarios bridge's own SourceConfig/parseSourcesToml shape — never diverge the
+// format the reader (verify-scenarios) and the writer (this engine) agree on.
+//
+// Pure functions are exported for node:test; running the file directly drives the CLI. No deps (the
+// repo's node-≥23.6 convention).
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { parseSourcesToml, type SourceConfig } from '../../verify-scenarios/scripts/verify-scenarios.mts'
+
+export type { SourceConfig }
+
+const CONFIG_REL_PATH = '.agents/sdd/scenario-bridge.toml'
+
+export function configPath(projectPath: string): string {
+	return join(projectPath, CONFIG_REL_PATH)
+}
+
+// ── list ──
+
+// Every configured source in file order; a missing config lists nothing without error.
+export function listSources(projectPath: string): SourceConfig[] {
+	const file = configPath(projectPath)
+	if (!existsSync(file)) return []
+	try {
+		return parseSourcesToml(readFileSync(file, 'utf8'))
+	} catch {
+		return []
+	}
+}
+
+// ── render one [[source]] block ──
+
+function renderBlock(source: { adapter: string; command?: string; reportPath: string }): string {
+	const lines = [
+		'[[source]]',
+		`adapter    = "${source.adapter}"`,
+		...(source.command !== undefined ? [`command    = "${source.command}"`] : []),
+		`reportPath = "${source.reportPath}"`,
+	]
+	return lines.join('\n')
+}
+
+// ── scaffold / add ──
+
+export interface NewSourceInput {
+	adapter?: string
+	command?: string
+	reportPath?: string
+}
+
+export type MutateResult = { ok: true; message: string; sources: SourceConfig[] } | { ok: false; reason: string }
+
+function validateInput(
+	input: NewSourceInput,
+): { ok: true; adapter: string; command?: string; reportPath: string } | { ok: false; reason: string } {
+	if (!input.adapter || !input.reportPath) {
+		return { ok: false, reason: 'a source needs both adapter and reportPath' }
+	}
+	return { ok: true, adapter: input.adapter, command: input.command, reportPath: input.reportPath }
+}
+
+// Creates <project-path>/.agents/sdd/scenario-bridge.toml with one [[source]] block. Refuses when the
+// file already exists (use `add` instead) or when adapter/reportPath is missing — no source block is
+// written in the refused case.
+export function scaffoldSource(projectPath: string, input: NewSourceInput): MutateResult {
+	const valid = validateInput(input)
+	if (!valid.ok) return valid
+	const file = configPath(projectPath)
+	if (existsSync(file)) {
+		return { ok: false, reason: 'scenario-bridge.toml already exists; use add to append a source' }
+	}
+	mkdirSync(dirname(file), { recursive: true })
+	writeFileSync(file, `${renderBlock(valid)}\n`)
+	const sources = listSources(projectPath)
+	return { ok: true, message: `scaffolded ${file}`, sources }
+}
+
+// Appends a [[source]] block to an existing config, leaving the existing sources untouched. Refuses
+// when the config does not exist yet (names scaffold as the entry point) or when adapter/reportPath
+// is missing.
+export function addSource(projectPath: string, input: NewSourceInput): MutateResult {
+	const valid = validateInput(input)
+	if (!valid.ok) return valid
+	const file = configPath(projectPath)
+	if (!existsSync(file)) {
+		return { ok: false, reason: 'scenario-bridge.toml does not exist yet; use scaffold to create it first' }
+	}
+	const existing = readFileSync(file, 'utf8')
+	const sep = existing.endsWith('\n') ? '' : '\n'
+	writeFileSync(file, `${existing}${sep}\n${renderBlock(valid)}\n`)
+	const sources = listSources(projectPath)
+	return { ok: true, message: `added a source to ${file}`, sources }
+}
+
+// ── CLI ──
+
+function flag(argv: string[], name: string): string | undefined {
+	const i = argv.indexOf(name)
+	return i === -1 ? undefined : argv[i + 1]
+}
+
+function inputFromArgv(argv: string[]): NewSourceInput {
+	return {
+		adapter: flag(argv, '--adapter'),
+		command: flag(argv, '--command'),
+		reportPath: flag(argv, '--report-path'),
+	}
+}
+
+export function main(argv: string[]): number {
+	const projectPath = flag(argv, '--project-path') ?? '.'
+	const w = (s: string) => process.stdout.write(`${s}\n`)
+
+	if (argv.includes('--list')) {
+		for (const s of listSources(projectPath)) {
+			w(`${s.adapter}${s.command ? ` (${s.command})` : ''} -> ${s.reportPath}`)
+		}
+		return 0
+	}
+	if (argv.includes('--scaffold')) {
+		const r = scaffoldSource(projectPath, inputFromArgv(argv))
+		w(r.ok ? r.message : `refused: ${r.reason}`)
+		return r.ok ? 0 : 1
+	}
+	if (argv.includes('--add')) {
+		const r = addSource(projectPath, inputFromArgv(argv))
+		w(r.ok ? r.message : `refused: ${r.reason}`)
+		return r.ok ? 0 : 1
+	}
+
+	w(
+		'usage: manage-scenario-bridge --project-path <dir> --list | --scaffold --adapter <a> [--command <c>] --report-path <p> | --add --adapter <a> [--command <c>] --report-path <p>',
+	)
+	return 0
+}
+
+if (import.meta.main) process.exit(main(process.argv.slice(2)))

package/skills/manage-spec-anchors/README.md

@@ -0,0 +1,18 @@
+# manage-spec-anchors
+
+The concrete engine for the SDD **spec-anchors** config — the opt-in registry of extra spec anchors
+`discover-specs` scans on top of the three fixed conventions (ADR-0019). A non-user-invocable skill,
+loaded in-session by the `manage` gateway (Housekeeping), carrying a self-contained `.mts` script
+that lists / CRUDs / induces / previews the anchors so users never hand-edit
+`.agents/sdd/spec-anchors.toml`.
+
+- **Skill contract:** [`SKILL.md`](./SKILL.md)
+- **Script:** [`scripts/manage-spec-anchors.mts`](./scripts/manage-spec-anchors.mts)
+- **Tests:** [`scripts/manage-spec-anchors.test.mts`](./scripts/manage-spec-anchors.test.mts) (`node:test`)
+
+```bash
+node scripts/manage-spec-anchors.mts --list
+node scripts/manage-spec-anchors.mts --induce curriculum/web/react/s-01
+node scripts/manage-spec-anchors.mts --preview 'curriculum/*/*/<project>'
+node scripts/manage-spec-anchors.mts --add 'curriculum/*/*/<project>'
+```

package/skills/manage-spec-anchors/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: manage-spec-anchors
+description: "Partial Skill: invoke by name only — corpus/spec-anchors' curation engine for SDD's extra spec-discovery anchors — loaded by the manage gateway (Housekeeping), not triggered by users directly."
+user-invocable: false
+metadata:
+  internal: true
+---
+
+# Manage Spec Anchors
+
+The concrete engine for the SDD **spec-anchors** config — the opt-in registry of **extra** spec
+anchors that `discover-specs` scans on top of the three fixed conventions (ADR-0019). It exists so a
+user curates those anchors through a clean interface instead of hand-editing
+`.agents/sdd/spec-anchors.toml`. Loaded **in-session** by the `manage` gateway (Housekeeping group);
+it carries a self-contained `.mts` script (the repo's node-≥23.6 / no-deps convention).
+
+## The config it curates
+
+`.agents/sdd/spec-anchors.toml` carries one key — `anchors = [ … ]` — a list of repo-relative
+directory patterns. `*` globs one segment; `**` globs **zero or more** segments (any depth,
+including zero); `<project>` globs **and captures** a segment as the spec's name. Each pattern names
+a directory the engine probes for `spec.md`. The three fixed conventions (`.agents/spec/`,
+`.agents/specs/<project>/`, `<project-path>/.agents/spec/`) are **implicit and always scanned** —
+never listed here, and never curatable.
+
+## Run an operation
+
+```bash
+node "<skill>/scripts/manage-spec-anchors.mts" [--root .] <operation>
+```
+
+| Operation | Effect |
+|---|---|
+| `--list` | list the three fixed anchors (each explained) + every custom anchor, flagged fixed/custom |
+| `--add <pattern>` | validate + append a custom anchor (creates the config if absent); refuses a fixed convention or a malformed pattern |
+| `--remove <pattern>` | drop a custom anchor; a no-op (config unchanged) when the anchor is absent |
+| `--edit <old> <new>` | replace one custom anchor; refuses a malformed `<new>` |
+| `--induce <path>` | from a sample spec directory, offer a literal-dir candidate and a `<project>` generalization; refuses a path that is not a directory under the repo |
+| `--preview <pattern>` | list the project(s) a candidate pattern would discover, **without** persisting it; a malformed pattern is refused, a zero-match pattern reports none |
+
+**Curate with preview.** The intended flow: take the user's sample path → `--induce` it → `--preview`
+each candidate to show the matched projects → confirm with the user → `--add` the chosen pattern.
+Never write a pattern the user has not seen the effect of.
+
+## Boundaries
+
+Writes **only** `.agents/sdd/spec-anchors.toml` — never a `spec.md`, `status`, `approval`, or a
+freeze; it is operational config, not spec content (so `manage`'s write-ownership guard holds). It
+does **not** scan or list specs — that is `discover-specs`, which *reads* this config. The
+**read-side** fail-safe (an already-corrupted config never breaks discovery) is `discover-specs`'
+guarantee, not this engine's; this engine validates on the **write** side so a bad pattern is never
+persisted.
+
+When `node` is absent, an agent performs the same edits by hand: read the `anchors` array, apply the
+CRUD, validate a pattern is repo-relative with only literal / `*` / `**` / `<project>` segments, and never
+write a fixed convention.