@selvakumaresra/specship 0.9.0 → 0.10.0

package/commands/ss-domain.md

@@ -0,0 +1,98 @@
+---
+description: Capture a human-confirmed domain fact (a term, rule, decision, or constraint) for an undocumented entity or spec. Grounds in the real gap-seed, interviews per-type, and writes only on explicit confirmation.
+argument-hint: [entity-or-spec name | --type rule]
+allowed-tools: mcp__specship__specship_explore, mcp__specship__specship_spec, Bash, Write
+---
+
+# SpecShip Domain Capture
+
+Capture a **domain fact** — a piece of the project's ubiquitous language or a
+stated business rule — and persist it under `specs/domain/` as a `domain` spec.
+Domain facts attach at the **spec tier** (linked to a requirement spec) and
+inherit code links + drift through that spec.
+
+**Governing principle — propose, never auto-apply.** A fact reaches disk ONLY on
+explicit human confirmation. If the human does not confirm, you write **nothing**.
+
+## 1. Find what is undocumented (ground in the real gap-seed)
+
+Run the gap-seed pass and read its output. This lists the **real** code entities
+and specs that no domain fact yet covers — never invent a generic prompt.
+
+```bash
+specship domain-gaps --json
+```
+
+The JSON has `entities` (undocumented `class`/`struct`/`interface`/`route`/`component`
+nodes, each with `qualifiedName`, `kind`, `filePath`), `specs` (undocumented
+non-domain specs, each with `id`, `title`, `kind`), and a `coverage` rollup of
+`{documented, gaps}`.
+
+- If `$ARGUMENTS` names a specific entity or spec, target that one.
+- Otherwise pick the most central few gaps to offer the human.
+- If `coverage.gaps` is `0`, tell the human the domain layer is fully covered and stop.
+
+## 2. Understand the candidate before asking
+
+For the entity or spec you are about to ask about, ground yourself in the code so
+your questions are specific, not generic:
+
+- `mcp__specship__specship_explore` naming the gap entity (and neighbours) to read its real source.
+- `mcp__specship__specship_spec` on the spec you intend to link the fact to, to see its requirements and current code links.
+
+## 3. Interview — per-type, targeted, citing the gap
+
+Ask about **the named gap**, not "describe your domain". Frame the questions by
+the fact `type` you are capturing:
+
+- **term** — "What does `<EntityName>` mean in this product's language? What's the one-sentence definition a new teammate needs?"
+- **rule** — "What invariant must always hold for `<EntityName>` / the `<SpecTitle>` flow? State it as MUST/NEVER."
+- **decision** — "What was decided about `<EntityName>` and why was the alternative rejected?"
+- **constraint** — "What external limit (regulatory, performance, contractual) bounds `<EntityName>`?"
+
+Confirm with the human:
+- the **type** (`term` | `rule` | `decision` | `constraint`),
+- the **statement** (the fact body),
+- the **spec to link** (a requirement `id` from the gap-seed / `specship_spec`),
+- a `DOM-<AREA>-NNN` **id** (AREA = a short uppercase domain tag, NNN zero-padded; pick the next free number for that AREA).
+
+## 4. Confirm, then write (and ONLY then)
+
+Show the human the exact fact you are about to write and ask for explicit
+confirmation (e.g. "Write this fact? (yes/no)"). **If they do not clearly
+confirm, stop and write nothing — the command is a no-op.**
+
+On confirmation, `Write` the file to `specs/domain/<area>.md` (one fact per file
+is simplest; append to an existing area file only if the human asks):
+
+```markdown
+---
+id: DOM-PAY-001
+title: Settlement currency
+type: rule
+depends_on: REQ-PAY-004
+---
+# Settlement currency
+
+All payments settle in the merchant's account currency, never the buyer's.
+```
+
+Frontmatter rules:
+- `id` — `DOM-<AREA>-NNN`, distinct from `REQ-` ids.
+- `type` — exactly one of `term`, `rule`, `decision`, `constraint`.
+- Link with `depends_on: <REQ-ID>` (comma-separate multiple) and/or `parent_id: <REQ-ID>`. A fact with no link is allowed — it indexes as an unlinked gap, never an error.
+
+## 5. Index it
+
+```bash
+specship sync
+```
+
+The fact now projects as a `spec:DOM-…` node, is returned by `specship_explore`
+and `specship_spec`, and inherits the linked requirement's code links + drift.
+
+## Manual authoring is equivalent
+
+This command is a convenience, not a gate. A human can hand-create the same
+`specs/domain/<area>.md` file with the frontmatter above and run `specship sync`
+to get the **identical** indexed fact — no command required.

package/commands/ss-triage.md

@@ -0,0 +1,177 @@
+---
+description: Route a small change (a bug, an error log, or a one-line enhancement) to the existing spec it belongs to and append to it — a new requirement or acceptance criterion — only on your explicit confirmation. Falls back to authoring a new spec when nothing fits.
+argument-hint: <bug | error log | one-line enhancement>
+allowed-tools: Read, Edit, Write, Bash, mcp__specship__specship_spec, mcp__specship__specship_explore, mcp__specship__specship_search, mcp__specship__specship_node
+---
+
+# SpecShip Triage: `$ARGUMENTS`
+
+A **front door** for small changes. Take the prompt, find the **existing** spec
+it belongs to, and **add to it** — a new requirement or a new acceptance
+criterion — rather than spawning a fresh spec. Only fall back to authoring a new
+spec when nothing fits.
+
+You match and author; SpecShip retrieves and ranks; **the human gates the
+write**. This is distinct from `/ss-fix` (which repairs a drifted/broken link
+for a *known* spec) and `/ss-brainstorm` + `/ss-spec-author` (which author a
+*new* spec from scratch).
+
+**Governing principle — propose, never auto-apply.** A spec file is edited ONLY
+on explicit human confirmation. If the human does not confirm, you write
+**nothing** — the command is a no-op. Never auto-create a spec.
+
+If `$ARGUMENTS` is empty, ask the human for the bug / error / enhancement.
+
+## 1. Classify the input
+
+Decide which of three classes the prompt is, and say so out loud before any
+retrieval or write (REQ-TRIAGE-002.A3):
+
+- **error log** — contains a stack trace, an exception, a `file:line`, or a
+  symbol/function name from a crash. Route via the code→spec path (step 2b).
+- **bug** — prose describing wrong behaviour, possibly naming a symbol.
+- **enhancement** — prose proposing a new/changed capability.
+
+## 2. Retrieve candidate specs
+
+### 2a. Prose (bug / enhancement) → spec query
+
+Call `specship_spec` with a free-text **`query`** built from the salient terms
+of the prompt. It returns scored, ranked candidate specs (id, title, kind,
+relevance **score**, snippet) over the spec index — enough to act on without a
+follow-up fetch (REQ-TRIAGE-002.A1).
+
+```
+specship_spec  { "query": "<key terms from the prompt>" }
+```
+
+For a bug that names a symbol, you may *also* run step 2b and blend the results
+(a spec reached by both the prose query and the code→spec path is the strongest
+candidate).
+
+### 2b. Error log → code → spec
+
+Parse the `file:line` / symbol out of the trace, then walk code → owning spec:
+
+- `mcp__specship__specship_explore` (or `specship_search`) naming the symbol(s)
+  from the trace to locate the implicated code.
+- `mcp__specship__specship_node` on the implicated symbol — its response renders
+  the **linked specs** for that node. The owning requirement is the spec the
+  crashing code already implements (REQ-TRIAGE-002.A2).
+
+## 3. Present the ranked match + recommended target
+
+Before proposing any change, show the human (REQ-TRIAGE-002.A3):
+
+- the **detected input class** (bug / error log / enhancement),
+- the **ranked candidates** with their scores, and
+- the **recommended target** — which document (for a new requirement) or which
+  requirement (for a new criterion), and why.
+
+**Ambiguity:** when several candidates score closely, present the **top N** and
+ask the human to choose — never auto-select among them (REQ-TRIAGE-002.A4).
+
+## 4. No confident match → offer a new spec, don't create one
+
+If the top candidate's score is **below the match floor** (no candidate is
+clearly the right home), do NOT extend a spec on your own (REQ-TRIAGE-004):
+
+1. State **"no confident match"** and show the weak candidates **with their
+   scores** (A1).
+2. Offer the human a choice (A2): route to **`/ss-spec-author`** (or
+   `/ss-brainstorm`) to author a new spec; **append anyway** to the top weak
+   candidate; or **cancel**.
+3. Never create a new spec without an explicit human choice (A3).
+
+Use judgment for the floor — a top score that's roughly on par with unrelated
+specs, or a snippet that doesn't actually concern the change, is "no confident
+match" even if the number isn't zero. SpecShip ranks; you and the human decide.
+
+## 5. Choose the granularity (requirement vs criterion)
+
+On a confident match, pick what to append by intent (REQ-TRIAGE-003.A2):
+
+- **A distinct new concern** → a **new requirement** under the matched document.
+- **A bug / regression an existing requirement should already have covered** →
+  a **new acceptance criterion** on that requirement. This leaves the
+  requirement's existing code links intact — you are extending its contract,
+  not rewriting it. Error logs and most bugs land here as a regression guard.
+
+## 6. Auto-derive the id (next in series, collision-checked)
+
+Inspect the index / target file to find the next free id (REQ-TRIAGE-003.A3):
+
+- **New requirement** → next `REQ-<AREA>-<NNN>` for that document's AREA
+  (zero-padded NNN; one past the current max for that AREA).
+- **New criterion** → next `REQ-<ID>.A<N>` on the owning requirement (one past
+  its current max `A<N>`).
+
+Confirm the id collides with nothing already in the index — read the target spec
+file (or `specship_spec` on the document/requirement to list its children /
+acceptance bullets) before settling on the number.
+
+## 7. Preview the exact diff → confirm (and ONLY then write)
+
+Show the human the **exact change** (REQ-TRIAGE-003.A1): the target spec file
+and the precise block to be inserted, with its `<!-- id: -->` marker. Then ask
+for explicit confirmation and offer the alternatives:
+
+> `confirm` · `edit` (adjust the wording first) · `new spec instead` (hand off
+> to `/ss-spec-author`) · `cancel`
+
+**If the human does not clearly confirm, stop and write nothing.**
+
+A new **requirement** block:
+
+```markdown
+<!-- id: REQ-<AREA>-<NNN> -->
+## <Title with a MUST / SHOULD / MAY keyword>
+
+<one-concern normative description>
+
+## Acceptance
+<!-- id: REQ-<AREA>-<NNN>.A1 -->
+- <testable happy-path bullet>
+<!-- id: REQ-<AREA>-<NNN>.A2 -->
+- <testable failure-path bullet>
+```
+
+A new **acceptance criterion** appended to the owning requirement's
+`## Acceptance` list:
+
+```markdown
+<!-- id: REQ-<ID>.A<N> -->
+- <testable bullet covering the bug / regression>
+```
+
+On confirmation, append it with `Edit` (or `Write`) into the matched spec file —
+a new requirement after the document's existing requirements; a new criterion at
+the end of the owning requirement's `## Acceptance` block. Mirror the file's
+existing marker style exactly.
+
+## 8. Index and hand off
+
+```bash
+specship sync
+```
+
+The appended requirement / criterion must index **cleanly** — `specship sync`
+reports no spec error and the new `<!-- id: -->` is unique (REQ-TRIAGE-003.A4).
+If sync flags a duplicate or malformed id, fix it before reporting done; a
+duplicate-looking append should be flagged, not silently doubled.
+
+Then point the human at:
+- `/ss-spec-review <ID>` to review the change, and
+- `/ss-implement <ID>` (then `specship_link_assert`) when ready to build.
+
+## Anti-patterns
+
+- **Writing before confirmation** — the single most important rule (step 7).
+- **Auto-creating a new spec** on a weak match instead of offering the choice
+  (step 4).
+- **Rewriting a requirement's existing normative prose** in place — append a
+  criterion or a new requirement; don't mutate the contract that code links to.
+- **Auto-fixing the bug** — that's `/ss-implement`. Triage routes and records;
+  it does not change code.
+- **Spawning a new doc for a change that belongs on an existing spec** — the
+  whole point is to *add to* the right spec.

package/dist/bin/specship.js

@@ -1186,6 +1186,197 @@ function main() {
             process.exit(1);
         }
     });
+    /**
+     * specship maintainability
+     *
+     * Report graph-derived maintainability signals (REQ-MAINT-003) — coupling, size
+     * hotspots, dependency cycles, dead-code candidates. Advisory (exit 0); the
+     * `--strict` flag is the gating-ready shape consumed later by enforcement mode.
+     */
+    program
+        .command('maintainability [path]')
+        .alias('maint')
+        .description('Report graph-derived maintainability signals (coupling, size, cycles, dead code)')
+        .option('-j, --json', 'Output as JSON')
+        .option('--strict', 'Exit non-zero if any signal has findings (gating-ready; default advisory)')
+        .action(async (pathArg, options) => {
+        const projectPath = resolveProjectPath(pathArg);
+        try {
+            if (!(0, directory_1.isInitialized)(projectPath)) {
+                error(`SpecShip not initialized in ${projectPath}`);
+                process.exit(1);
+            }
+            const { default: SpecShip } = await loadSpecShip();
+            const cg = await SpecShip.open(projectPath);
+            const r = cg.getMaintainability();
+            if (options.json) {
+                console.log(JSON.stringify(r, null, 2));
+                cg.destroy();
+                if (options.strict && !r.clean)
+                    process.exit(1);
+                return;
+            }
+            if (r.clean) {
+                success('Maintainability: clean — nothing past threshold.');
+                cg.destroy();
+                return;
+            }
+            const CAP = 10;
+            const section = (title, count) => console.log(chalk.bold(`\n${title} (${count})`));
+            if (r.coupling.length) {
+                section('Coupling hotspots', r.coupling.length);
+                for (const c of r.coupling.slice(0, CAP))
+                    console.log(chalk.dim('  ') + `${c.name} ${chalk.dim(`(${c.reason}) — ${c.filePath}`)}`);
+            }
+            if (r.oversized.length) {
+                section('Oversized symbols', r.oversized.length);
+                for (const o of r.oversized.slice(0, CAP))
+                    console.log(chalk.dim('  ') + `${o.name} ${chalk.dim(`(${o.reason}) — ${o.filePath}`)}`);
+            }
+            if (r.godFiles.length) {
+                section('God files', r.godFiles.length);
+                for (const f of r.godFiles.slice(0, CAP))
+                    console.log(chalk.dim('  ') + `${f.filePath} ${chalk.dim(`(${f.reason})`)}`);
+            }
+            if (r.cycles.length) {
+                section('Dependency cycles', r.cycles.length);
+                for (const c of r.cycles.slice(0, CAP))
+                    console.log(chalk.dim('  ') + c.files.join(' → '));
+            }
+            if (r.deadCode.length) {
+                section('Dead-code candidates', r.deadCode.length);
+                for (const d of r.deadCode.slice(0, CAP))
+                    console.log(chalk.dim('  ') + `${d.name} ${chalk.dim(`— ${d.filePath}:${d.startLine}`)}`);
+                if (r.deadCode.length > CAP)
+                    console.log(chalk.dim(`  …and ${r.deadCode.length - CAP} more (dead-code is heuristic; tune in ${'specship.config.json'})`));
+            }
+            console.log();
+            info(`Thresholds: highDegree=${r.thresholds.highDegree} largeSymbolLines=${r.thresholds.largeSymbolLines} godFileSymbols=${r.thresholds.godFileSymbols} — override in specship.config.json`);
+            cg.destroy();
+            if (options.strict)
+                process.exit(1);
+        }
+        catch (err) {
+            error(`maintainability failed: ${err instanceof Error ? err.message : String(err)}`);
+            process.exit(1);
+        }
+    });
+    /**
+     * specship fitness
+     *
+     * Evaluate the project's architecture-fitness rules (specship.config.json
+     * `fitness.rules`) against the graph (REQ-FITNESS-003). Headless CI gate: exits
+     * non-zero on any violation OR config error (a no-match rule is a config error,
+     * never a silent pass).
+     */
+    program
+        .command('fitness [path]')
+        .description('Check architecture-fitness rules against the code graph (CI gate; exits non-zero on violation)')
+        .option('-j, --json', 'Output as JSON')
+        .action(async (pathArg, options) => {
+        const projectPath = resolveProjectPath(pathArg);
+        try {
+            if (!(0, directory_1.isInitialized)(projectPath)) {
+                error(`SpecShip not initialized in ${projectPath}`);
+                process.exit(1);
+            }
+            const { default: SpecShip } = await loadSpecShip();
+            const cg = await SpecShip.open(projectPath);
+            const r = cg.getFitness();
+            const fail = r.violations.length > 0 || r.configErrors.length > 0;
+            if (options.json) {
+                console.log(JSON.stringify(r, null, 2));
+                cg.destroy();
+                process.exit(fail ? 1 : 0);
+            }
+            if (r.ruleCount === 0) {
+                info('No architecture-fitness rules declared. Add a `fitness.rules` array to specship.config.json.');
+                cg.destroy();
+                return;
+            }
+            if (r.clean) {
+                success(`Architecture fitness: all ${r.ruleCount} rule(s) pass.`);
+                cg.destroy();
+                return;
+            }
+            if (r.configErrors.length) {
+                console.log(chalk.bold(chalk.red(`\nConfig errors (${r.configErrors.length}):`)));
+                for (const e of r.configErrors)
+                    console.log(chalk.red(`  ✗ ${e.rule}: ${e.message}`));
+            }
+            if (r.violations.length) {
+                console.log(chalk.bold(chalk.red(`\nViolations (${r.violations.length}):`)));
+                for (const v of r.violations.slice(0, 50)) {
+                    console.log(`  ${chalk.red('✗')} [${v.rule}] ${v.source} → ${v.target}`);
+                    console.log(chalk.dim(`      ${v.detail} — ${v.location}`));
+                }
+                if (r.violations.length > 50)
+                    console.log(chalk.dim(`  …and ${r.violations.length - 50} more`));
+            }
+            cg.destroy();
+            process.exit(1);
+        }
+        catch (err) {
+            error(`fitness failed: ${err instanceof Error ? err.message : String(err)}`);
+            process.exit(1);
+        }
+    });
+    /**
+     * specship check
+     *
+     * The enforcement gate (REQ-ENFORCE-001/002/003): runs the harness checks
+     * (drift + fitness + maintainability + behaviour) and exits non-zero if any
+     * GATING check fails. Which checks gate vs advise is configured in
+     * specship.config.json `enforce.gate`; with no config every check is advisory
+     * and the command exits 0 (opt-in — never breaks an existing repo).
+     */
+    program
+        .command('check [path]')
+        .description('Run the enforcement gate (drift + fitness + maintainability + behaviour); exits non-zero on a gating failure')
+        .option('-j, --json', 'Output as JSON')
+        .action(async (pathArg, options) => {
+        const projectPath = resolveProjectPath(pathArg);
+        try {
+            if (!(0, directory_1.isInitialized)(projectPath)) {
+                error(`SpecShip not initialized in ${projectPath}`);
+                process.exit(1);
+            }
+            const { default: SpecShip } = await loadSpecShip();
+            const cg = await SpecShip.open(projectPath);
+            const r = cg.getEnforce();
+            if (options.json) {
+                console.log(JSON.stringify(r, null, 2));
+                cg.destroy();
+                process.exit(r.passed ? 0 : 1);
+            }
+            console.log(chalk.bold('\nEnforcement gate\n'));
+            for (const c of r.checks) {
+                const tag = c.gating ? chalk.dim('[gating]') : chalk.dim('[advisory]');
+                const mark = c.passed ? chalk.green('✓') : (c.gating ? chalk.red('✗') : chalk.yellow('•'));
+                console.log(`  ${mark} ${c.check.padEnd(16)} ${tag} ${c.passed ? 'pass' : `${c.findings.length} finding(s)`}`);
+                if (!c.passed)
+                    for (const f of c.findings.slice(0, 8))
+                        console.log(chalk.dim(`        ${f}`));
+                if (!c.passed && c.findings.length > 8)
+                    console.log(chalk.dim(`        …and ${c.findings.length - 8} more`));
+            }
+            console.log();
+            if (r.passed) {
+                success(r.gatedFailures.length === 0 && r.checks.some((c) => c.gating)
+                    ? 'All gating checks pass.'
+                    : 'Pass (no gating checks failed).');
+                cg.destroy();
+                return;
+            }
+            error(`Gating checks failed: ${r.gatedFailures.join(', ')}`);
+            cg.destroy();
+            process.exit(1);
+        }
+        catch (err) {
+            error(`check failed: ${err instanceof Error ? err.message : String(err)}`);
+            process.exit(1);
+        }
+    });
     /**
      * specship serve
      */
@@ -1920,6 +2111,64 @@ function main() {
             cg.close();
         }
     });
+    // @implements REQ-DOMAIN-003
+    // Thin surface over the read-only gap-seed pass (SpecShip.getDomainGapSeed,
+    // REQ-DOMAIN-003) so the `/ss-domain` capture command can cite the SAME real
+    // undocumented entities/specs the library computes (REQ-DOMAIN-004.A4) without a
+    // new MCP tool (REQ-DOMAIN-005) or a runtime package import. Writes nothing.
+    program
+        .command('domain-gaps [path]')
+        .description('List code entities and specs not yet covered by a domain fact (the domain gap-seed). Feeds the /ss-domain capture interview.')
+        .option('-l, --limit <n>', 'max entities and specs to print in text mode (default: 50)')
+        .option('--json', 'emit JSON')
+        .action(async (pathArg, options) => {
+        const projectRoot = path.resolve(pathArg ?? process.cwd());
+        if (!(0, directory_1.isInitialized)(projectRoot)) {
+            error(`SpecShip not initialized in ${projectRoot}. Run \`specship init -i\` first.`);
+            process.exit(1);
+        }
+        const { default: SpecShip } = await loadSpecShip();
+        const cg = await SpecShip.open(projectRoot);
+        try {
+            const seed = cg.getDomainGapSeed();
+            if (options.json) {
+                // eslint-disable-next-line no-console
+                console.log(JSON.stringify(seed, null, 2));
+                return;
+            }
+            const limit = options.limit ? Math.max(1, parseInt(options.limit, 10) || 50) : 50;
+            const { documented, gaps } = seed.coverage;
+            const total = documented + gaps;
+            /* eslint-disable no-console */
+            console.log(`Domain coverage: ${documented}/${total} documented · ${gaps} gap${gaps === 1 ? '' : 's'}`);
+            if (gaps === 0) {
+                console.log('✨ Every in-scope entity and spec is covered by a domain fact.');
+            }
+            else {
+                if (seed.entities.length > 0) {
+                    console.log(`\nUndocumented entities (${seed.entities.length}):`);
+                    for (const e of seed.entities.slice(0, limit)) {
+                        console.log(`  [${e.kind}] ${e.qualifiedName} — ${e.filePath}`);
+                    }
+                    if (seed.entities.length > limit)
+                        console.log(`  … and ${seed.entities.length - limit} more`);
+                }
+                if (seed.specs.length > 0) {
+                    console.log(`\nUndocumented specs (${seed.specs.length}):`);
+                    for (const s of seed.specs.slice(0, limit)) {
+                        console.log(`  [${s.kind}] ${s.id} — ${s.title}`);
+                    }
+                    if (seed.specs.length > limit)
+                        console.log(`  … and ${seed.specs.length - limit} more`);
+                }
+                console.log(`\nCapture a fact for any of these with \`/ss-domain\`.`);
+            }
+            /* eslint-enable no-console */
+        }
+        finally {
+            cg.close();
+        }
+    });
     // @implements REQ-FUNNEL-004
     program
         .command('spec [id]')