@llman-sdd/core 0.1.4 → 0.3.0

package/src/report/show.ts

@@ -22,7 +22,11 @@ export interface ShowDeps {
   specsDir: string;
 }
 
-export function showChangeJson(deps: ShowDeps, id: string): Record<string, unknown> {
+export function showChangeJson(
+  deps: ShowDeps,
+  id: string,
+  opts: { matchedViaPrefix?: boolean } = {},
+): Record<string, unknown> {
   const { io, git, root } = deps;
   const dir = `${root}/${CHANGES_DIR}/${id}`;
   const proposalPath = `${dir}/proposal.md`;
@@ -41,8 +45,16 @@ export function showChangeJson(deps: ShowDeps, id: string): Record<string, unkno
     ? countTasks(io.readText(`${dir}/tasks.md`))
     : { completed: 0, total: 0 };
 
-  const cleanTree = isCleanTree(git);
-  const onBoundBranch = binding !== null && currentBranch(git) === binding.branch;
+  // v1 parity: show works (gracefully degraded gates) outside a git repo.
+  let cleanTree = false;
+  let current = null;
+  try {
+    cleanTree = isCleanTree(git);
+    current = currentBranch(git);
+  } catch {
+    current = null;
+  }
+  const onBoundBranch = binding !== null && current === binding.branch;
 
   // specs landing: bound changes must have touched llmanspec/specs/ since base
   let specsLanded = false;
@@ -60,7 +72,17 @@ export function showChangeJson(deps: ShowDeps, id: string): Record<string, unkno
   const specReport = validateAllSpecs(discoverSpecs(deps.specsDir, io), io);
   const validateOk = !specReport.failed && (total === 0 || tasksDone);
 
-  const stageComplete = stage === 'full';
+  const stageHint = !hasDesign
+    ? 'add design.md (current: draft → designed)'
+    : !hasTasks
+      ? 'add tasks.md (current: designed → planned)'
+      : stage === 'planned'
+        ? 'bind via `llman sdd change start <id>` (planned → full)'
+        : '';
+  const tasksHint =
+    total > 0 && completed < total
+      ? `${total - completed} unchecked tasks`
+      : 'complete or check off remaining tasks';
 
   const gateChecks = [
     {
@@ -71,29 +93,30 @@ export function showChangeJson(deps: ShowDeps, id: string): Record<string, unkno
     {
       name: 'on-bound-branch',
       pass: onBoundBranch,
-      hint: onBoundBranch ? '' : 'change is not attached; run `llman-sdd change start <id>`',
+      hint: onBoundBranch ? '' : 'change is not attached; run `llman sdd change start <id>`',
     },
     {
       name: 'stage-complete',
-      pass: stageComplete,
-      hint: stageComplete ? '' : `add ${!hasDesign ? 'design.md' : 'tasks.md'} (current: ${stage})`,
+      pass: hasDesign && hasTasks,
+      hint: hasDesign && hasTasks ? '' : (stageHint as string),
     },
     {
       name: 'specs-landed',
-      pass: specsLanded,
-      hint: specsLanded
-        ? ''
-        : 'edit live specs on the bound branch and commit (or needs_specs_change: false)',
+      pass: specsLanded || !needsSpecsChange,
+      hint:
+        specsLanded || !needsSpecsChange
+          ? ''
+          : 'edit live specs on the bound branch and commit (or needs_specs_change: false)',
     },
     {
       name: 'tasks-done',
-      pass: tasksDone,
-      hint: tasksDone ? '' : `${total - completed} unchecked tasks`,
+      pass: tasksDone && total > 0,
+      hint: tasksDone && total > 0 ? '' : tasksHint,
     },
     {
       name: 'validate',
       pass: validateOk,
-      hint: validateOk ? '' : 'fix issues reported by `llman-sdd validate <id> --strict`',
+      hint: validateOk ? '' : 'fix issues reported by `llman sdd validate <id> --strict`',
     },
   ];
 
@@ -110,6 +133,6 @@ export function showChangeJson(deps: ShowDeps, id: string): Record<string, unkno
     deltaCount: 0,
     deltas: [] as string[],
     gateChecks,
-    matchedViaPrefix: false,
+    matchedViaPrefix: opts.matchedViaPrefix === true,
   };
 }

package/src/report/specHelpers.ts

@@ -14,9 +14,12 @@ export interface SpecHelperIo {
   listDir(path: string): string[];
 }
 
-/** Scan all specs under `specsDir` for @req:rN TAGS (not step text) and return the next free id. */
+/**
+ * v1 parity (`req_registry.rs::next_req_id_from_index`): smallest free rN over
+ * the RULE (@human) req ids only; acceptance-only req tags do not occupy ids.
+ */
 export function nextReqId(io: SpecHelperIo, specsDir: string): string {
-  let max = 0;
+  const used = new Set<number>();
   const walk = (dir: string): void => {
     if (!io.exists(dir)) return;
     for (const name of io.listDir(dir)) {
@@ -24,8 +27,10 @@ export function nextReqId(io: SpecHelperIo, specsDir: string): string {
       if (name.endsWith('.feature')) {
         const doc = parseCapability(io.readText(full), full);
         for (const scenario of doc.scenarios) {
+          if (scenario.classification !== 'human') continue;
           for (const reqId of scenario.reqIds) {
-            max = Math.max(max, Math.trunc(Number(reqId.replace(/^r/u, ''))));
+            const n = Math.trunc(Number(reqId.replace(/^r/u, '')));
+            if (Number.isFinite(n)) used.add(n);
           }
         }
       } else if (io.isDirectory(full)) {
@@ -34,7 +39,9 @@ export function nextReqId(io: SpecHelperIo, specsDir: string): string {
     }
   };
   walk(specsDir);
-  return `r${max + 1}`;
+  let n = 1;
+  while (used.has(n)) n += 1;
+  return `r${n}`;
 }
 
 export function skeletonContent(capability: string, reqId: string, locale: string): string {
@@ -53,10 +60,11 @@ export function scaffoldSpec(
   specsDir: string,
   capability: string,
   locale: string,
+  opts: { force?: boolean } = {},
 ): string {
   const reqId = nextReqId(io, specsDir);
   const path = `${specsDir}/${capability}.feature`;
-  if (io.exists(path)) throw new Error(`spec already exists: ${path}`);
+  if (!opts.force && io.exists(path)) throw new Error(`spec already exists: ${path}`);
   io.mkdirp('src/');
   io.writeText(path, skeletonContent(capability, reqId, locale));
   return path;

package/src/report/specs.ts

@@ -10,7 +10,6 @@ import { pad } from './collect.ts';
 export interface SpecMorphology {
   ruleCount: number;
   ruleEnforcedCount: number;
-  ruleManualCount: number;
   rulePendingCount: number;
   acceptanceCount: number;
   orphanAcceptanceCount: number;
@@ -27,22 +26,30 @@ export interface SpecSummary {
   morphology: SpecMorphology;
 }
 
-function morphologyOf(doc: CapabilityDoc): SpecMorphology {
-  const rules = doc.scenarios.filter((s) => s.classification === 'human');
-  const acceptance = doc.scenarios.filter((s) => s.classification === 'executable');
-  const acceptanceReqIds = new Set(acceptance.flatMap((s) => s.reqIds));
+/** Morphology counts shared by `list --specs`, `show <spec> --json`, and the
+ * CLI text render — the single source of the enforced/pending two-state rule
+ * (rules = @human; enforced = @req-linked acceptance coverage; pending = rest). */
+export function morphologyOfScenarios(
+  scenarios: readonly { classification: string; reqIds: readonly string[] }[],
+): SpecMorphology {
+  const rules = scenarios.filter((s) => s.classification === 'human');
+  const acceptance = scenarios.filter((s) => s.classification === 'executable');
+  const acceptanceReqIds = new Set(acceptance.flatMap((s) => [...s.reqIds]));
   const enforced = rules.filter((r) => r.reqIds.some((id) => acceptanceReqIds.has(id)));
   const orphan = acceptance.filter((s) => s.reqIds.length === 0);
   return {
     ruleCount: rules.length,
     ruleEnforcedCount: enforced.length,
-    ruleManualCount: rules.filter((r) => r.manual).length,
     rulePendingCount: rules.length - enforced.length,
     acceptanceCount: acceptance.length,
     orphanAcceptanceCount: orphan.length,
   };
 }
 
+function morphologyOf(doc: CapabilityDoc): SpecMorphology {
+  return morphologyOfScenarios(doc.scenarios);
+}
+
 export function collectSpecs(entries: readonly SpecEntry[]): SpecSummary[] {
   return entries.map((e) => {
     const morphology = morphologyOf(e.doc);
@@ -68,7 +75,7 @@ export function renderSpecsList(summaries: readonly SpecSummary[]): string[] {
   for (const s of summaries) {
     const m = s.morphology;
     lines.push(
-      `  ${pad(s.id, idWidth)}rules ${m.ruleCount}  enforced ${m.ruleEnforcedCount}  manual ${m.ruleManualCount}  pending ${m.rulePendingCount}  acceptance ${m.acceptanceCount}`,
+      `  ${pad(s.id, idWidth)}rules ${m.ruleCount}  enforced ${m.ruleEnforcedCount}  pending ${m.rulePendingCount}  acceptance ${m.acceptanceCount}`,
     );
   }
   return lines;

package/src/review/review.ts

@@ -1,10 +1,12 @@
+import type { GitLike } from '../git/spawnGit.ts';
+import { evaluateStaleness, notApplicableStaleness } from '../validation/staleness.ts';
 /**
  * Review aggregation (review-freeze capability, r23): five-signal review over
  * spec IR + validate sweep. Port of v1 sdd/review.rs observable contract.
  */
 import { validateAllSpecs, type SpecEntry, type SpecIo } from '../validation/validate.ts';
 
-export type ReviewKind = 'pending' | 'manual' | 'unbound' | 'stale' | 'locked' | 'validate';
+export type ReviewKind = 'pending' | 'unbound' | 'stale' | 'locked' | 'validate';
 
 export interface ReviewSignal {
   kind: ReviewKind;
@@ -26,6 +28,12 @@ export interface ReviewInput {
   boundChangeCount: number;
   /** Active change summaries for the strict sweep (pending tasks → FAIL). */
   activeChanges?: readonly { name: string; completedTasks: number; totalTasks: number }[];
+  /** Restrict per-capability signals (pending/unbound/stale) to this capability. */
+  capability?: string;
+  /** git + root for real staleness evaluation (v1 parity). */
+  git?: GitLike;
+  root?: string;
+  specsDir?: string;
 }
 
 export interface ReviewResult {
@@ -35,17 +43,8 @@ export interface ReviewResult {
   exitCode: number;
 }
 
-function executableBound(
-  scenarioTags: readonly string[],
-  bindings: readonly TagBinding[] | null,
-): boolean {
-  if (!bindings || bindings.length === 0) return false;
-  const has = (t: string): boolean => scenarioTags.includes(t);
-  return bindings.some((b) => (b.kind === 'tags' ? b.tags.every((t) => has(t)) : false));
-}
-
 export function buildReview(input: ReviewInput, io: SpecIo): ReviewResult {
-  const { entries, bindings, boundChangeCount } = input;
+  const { entries, boundChangeCount } = input;
   const strictChangeFails = (input.activeChanges ?? []).filter(
     (c) => c.totalTasks > 0 && c.completedTasks < c.totalTasks,
   );
@@ -59,18 +58,36 @@ export function buildReview(input: ReviewInput, io: SpecIo): ReviewResult {
 
   for (const entry of sorted) {
     const cap = entry.doc.header.capability ?? entry.fileName;
+    // r33: per-capability signals honor the --capability filter; locked and
+    // validate stay global regardless.
+    if (input.capability !== undefined && cap !== input.capability) continue;
     const rules = entry.doc.scenarios.filter((s) => s.classification === 'human');
     const acceptance = entry.doc.scenarios.filter((s) => s.classification === 'executable');
     const acceptanceReqIds = new Set(acceptance.flatMap((s) => s.reqIds));
     const pending = rules.filter((r) => !r.reqIds.some((id) => acceptanceReqIds.has(id)));
-    const manual = rules.filter((r) => r.manual);
-    const unbound = acceptance.filter((s) => !executableBound(s.tags, bindings));
+    // v1 r5: unbound = orphan acceptance scenarios (no @req link).
+    const unbound = acceptance.filter((s) => s.reqIds.length === 0);
 
     push('pending', cap, pending.length);
-    push('manual', cap, manual.length);
     push('unbound', cap, unbound.length);
-    // staleness is deferred in v2 — placeholder signal (golden normalizes it)
-    push('stale', cap, 0, 'DEFERRED');
+
+    // staleness (v1 evaluate): real base-ref/scope evaluation.
+    let staleInfo = notApplicableStaleness();
+    let staleCount = 0;
+    if (input.git !== undefined && input.root !== undefined) {
+      const specRel =
+        (entry.fileName.startsWith('llmanspec/') ? '' : 'llmanspec/specs/') + entry.fileName;
+      const evalResult = evaluateStaleness({
+        git: input.git,
+        root: input.root,
+        specRel,
+        scope: entry.doc.header.scope?.split(',').map((x) => x.trim()) ?? [],
+        baseRefEnv: process.env.LLMANSPEC_BASE_REF,
+      });
+      staleInfo = evalResult.info;
+      staleCount = staleInfo.status === 'OK' || staleInfo.status === 'NOTAPPLICABLE' ? 0 : 1;
+    }
+    push('stale', cap, staleCount, staleInfo.status === 'NOTAPPLICABLE' ? '' : staleInfo.status);
   }
 
   const failed = sweep.verdicts.filter((v) => !v.ok);
@@ -96,13 +113,13 @@ export function buildReview(input: ReviewInput, io: SpecIo): ReviewResult {
     'locked',
     '-',
     0,
-    `${boundChangeCount} bound change(s); inspect with \`llman-sdd change diff <id>\``,
+    `${boundChangeCount} bound change(s); inspect with \`llman sdd change diff <id>\``,
   );
   push(
     'validate',
     '-',
     failed.length,
-    failed.length > 0 ? 'validate --all failed; run `llman-sdd validate --all` for details' : 'ok',
+    failed.length > 0 ? 'validate --all failed; run `llman sdd validate --all` for details' : 'ok',
   );
 
   const warningCount = signals
@@ -112,7 +129,7 @@ export function buildReview(input: ReviewInput, io: SpecIo): ReviewResult {
 
   const lines: string[] = [`Review: critical=${criticalCount} warning=${warningCount}`];
   for (const cap of sorted.map((e) => e.doc.header.capability ?? e.fileName)) {
-    for (const kind of ['pending', 'manual', 'unbound', 'stale'] as const) {
+    for (const kind of ['pending', 'unbound', 'stale'] as const) {
       const s = signals.find((x) => x.kind === kind && x.capability === cap);
       if (!s) continue;
       lines.push(`${kind}: ${cap} (${s.count})`);

package/src/spec/authoring.ts

@@ -0,0 +1,206 @@
+/**
+ * Programming-style spec authoring helpers (r41-r43, v1 parity):
+ * append rules / acceptance scenarios, resolve req ids, dedupe conflicts.
+ * Appends are text-level so existing file content (formatting, comments)
+ * stays untouched.
+ */
+
+import type { CapabilityDoc } from './ir.ts';
+
+const RULE_KEYWORDS = ['MUST', 'SHALL', '必须', '不得', '禁止'] as const;
+
+export class AuthoringError extends Error {}
+
+export interface SpecEntryLike {
+  fileName: string;
+  doc: CapabilityDoc;
+}
+
+export interface WriteIo {
+  exists(path: string): boolean;
+  readText(path: string): string;
+  writeText(path: string, content: string): void;
+}
+
+function keywordsOf(content: string): {
+  scenario: string;
+  given: string;
+  when: string;
+  thenText: string;
+} {
+  return content.includes('功能:')
+    ? { scenario: '场景', given: '假如', when: '当', thenText: '那么' }
+    : { scenario: 'Scenario', given: 'Given', when: 'When', thenText: 'Then' };
+}
+
+function assertRuleWording(statement: string): void {
+  if (!RULE_KEYWORDS.some((k) => statement.includes(k))) {
+    throw new AuthoringError(
+      `statement must contain a rule keyword (${RULE_KEYWORDS.join('/')}): ${statement}`,
+    );
+  }
+}
+
+function findReq(
+  entries: readonly SpecEntryLike[],
+  reqId: string,
+): { entry: SpecEntryLike; scenarioName: string; statement: string } | null {
+  for (const entry of entries) {
+    for (const scenario of entry.doc.scenarios) {
+      if (scenario.reqIds.includes(reqId) && scenario.classification === 'human') {
+        return { entry, scenarioName: scenario.name, statement: scenario.statement };
+      }
+    }
+  }
+  return null;
+}
+
+/** v1 parity: only @human (rule) req ids participate in the dedupe registry. */
+export function ruleReqIds(entries: readonly SpecEntryLike[]): Set<string> {
+  const ids = new Set<string>();
+  for (const entry of entries) {
+    for (const scenario of entry.doc.scenarios) {
+      if (scenario.classification === 'human') {
+        for (const id of scenario.reqIds) ids.add(id);
+      }
+    }
+  }
+  return ids;
+}
+
+export function allReqIds(entries: readonly SpecEntryLike[]): Set<string> {
+  const ids = new Set<string>();
+  for (const entry of entries) {
+    for (const scenario of entry.doc.scenarios) {
+      for (const id of scenario.reqIds) ids.add(id);
+    }
+  }
+  return ids;
+}
+
+export interface AddReqOpts {
+  capability: string;
+  reqId: string;
+  title: string;
+  statement: string;
+}
+
+/** Append `@req:<id> @human` rule scenario to `<capability>.feature` (r41). */
+export function addReq(
+  io: WriteIo,
+  specsRoot: string,
+  entries: readonly SpecEntryLike[],
+  opts: AddReqOpts,
+): string {
+  const path = `${specsRoot}/${opts.capability}.feature`;
+  if (!io.exists(path)) throw new AuthoringError(`spec not found: ${path}`);
+  if (allReqIds(entries).has(opts.reqId)) {
+    throw new AuthoringError(`req id already in use: ${opts.reqId}`);
+  }
+  assertRuleWording(opts.statement);
+  const kw = keywordsOf(io.readText(path));
+  const block = `\n  @req:${opts.reqId} @human\n  ${kw.scenario}: ${opts.title}\n    ${opts.statement}\n`;
+  io.writeText(path, `${io.readText(path).replace(/\n+$/u, '')}${block}`);
+  return path;
+}
+
+export interface AddScenarioOpts {
+  capability: string;
+  reqId: string;
+  scenarioId: string;
+  given?: string;
+  when: string;
+  thenText: string;
+}
+
+/** Append `@req:<id> @executable` acceptance scenario (r42). */
+export function addScenario(
+  io: WriteIo,
+  specsRoot: string,
+  entries: readonly SpecEntryLike[],
+  opts: AddScenarioOpts,
+): string {
+  const path = `${specsRoot}/${opts.capability}.feature`;
+  if (!io.exists(path)) throw new AuthoringError(`spec not found: ${path}`);
+  if (findReq(entries, opts.reqId) === null) {
+    throw new AuthoringError(`req id not found: ${opts.reqId}`);
+  }
+  const kw = keywordsOf(io.readText(path));
+  const givenLine =
+    opts.given !== undefined && opts.given !== '' ? `    ${kw.given} ${opts.given}\n` : '';
+  const block =
+    `\n  @req:${opts.reqId} @executable\n  ${kw.scenario}: ${opts.scenarioId}\n` +
+    `${givenLine}    ${kw.when} ${opts.when}\n    ${kw.thenText} ${opts.thenText}\n`;
+  io.writeText(path, `${io.readText(path).replace(/\n+$/u, '')}${block}`);
+  return path;
+}
+
+export interface ResolvedReq {
+  reqId: string;
+  capability: string;
+  title: string;
+  statement: string;
+  harness: string[];
+}
+
+/** Resolve an rN to capability/statement plus bound harness scenarios (r43). */
+export function resolveReq(entries: readonly SpecEntryLike[], reqId: string): ResolvedReq | null {
+  const rule = findReq(entries, reqId);
+  if (rule === null) return null;
+  const capability =
+    rule.entry.doc.header.capability ?? rule.entry.fileName.replace(/\.feature$/u, '');
+  const harness: string[] = [];
+  for (const entry of entries) {
+    for (const scenario of entry.doc.scenarios) {
+      if (scenario.classification === 'executable' && scenario.reqIds.includes(reqId)) {
+        harness.push(`${entry.fileName}:${scenario.name}`);
+      }
+    }
+  }
+  return { reqId, capability, title: rule.scenarioName, statement: rule.statement, harness };
+}
+
+export interface DedupePlanItem {
+  reqId: string;
+  keepFile: string;
+  remapFile: string;
+  newReqId: string;
+}
+
+/**
+ * Plan (and optionally apply) a re-map of globally duplicated rN ids: the
+ * first file keeps the id, later files get the next free id (r43).
+ */
+export function planDedupe(
+  entries: readonly SpecEntryLike[],
+  io: WriteIo,
+  specsRoot: string,
+  duplicates: readonly { reqId: string; files: string[] }[],
+): DedupePlanItem[] {
+  const used = ruleReqIds(entries);
+  let next = 1;
+  const fresh = (): string => {
+    while (used.has(`r${String(next)}`)) next += 1;
+    used.add(`r${String(next)}`);
+    return `r${String(next)}`;
+  };
+  const plan: DedupePlanItem[] = [];
+  for (const dup of duplicates) {
+    const [keep, ...rest] = dup.files;
+    for (const remapFile of rest) {
+      const newReqId = fresh();
+      if (keep !== undefined) {
+        plan.push({ reqId: dup.reqId, keepFile: keep, remapFile, newReqId });
+      }
+    }
+  }
+  for (const item of plan) {
+    // registry duplicates carry bare file names; accept already-rooted paths too
+    const path = item.remapFile.startsWith(`${specsRoot}/`)
+      ? item.remapFile
+      : `${specsRoot}/${item.remapFile}`;
+    const content = io.readText(path);
+    io.writeText(path, content.replaceAll(`@req:${item.reqId}`, `@req:${item.newReqId}`));
+  }
+  return plan;
+}

package/src/spec/ir.ts

@@ -19,7 +19,6 @@ export interface ScenarioIR {
   /** `@req:rN` links, normalized to `rN`. */
   reqIds: string[];
   classification: ScenarioClassification;
-  manual: boolean;
   /** Rule statement (description lines, trimmed) + step texts for executables. */
   statement: string;
   stepCount: number;

package/src/spec/parser.ts

@@ -77,20 +77,18 @@ function extractHeader(source: string): CapabilityHeader {
 
 function classify(tags: string[]): {
   classification: ScenarioIR['classification'];
-  manual: boolean;
   errors: SpecStructuralError[];
 } {
   const errors: SpecStructuralError[] = [];
   const has = (t: string): boolean => tags.includes(t);
   const human = has('human');
   const executable = has('executable');
-  const manual = has('manual');
   const label = tags.join(',');
 
-  if (manual && !human) {
+  if (has('manual')) {
     errors.push({
-      code: 'tag:manual-orphan',
-      message: `@manual 必须与 @human 同用(tags: ${label})`,
+      code: 'tag:manual-removed',
+      message: `@manual was removed in 0.3.0 — drop the tag (@human already carries the human-judgement semantics) (tags: ${label})`,
     });
   }
   if (human && executable) {
@@ -104,7 +102,7 @@ function classify(tags: string[]): {
     : executable
       ? 'executable'
       : 'unclassified';
-  return { classification, manual, errors };
+  return { classification, errors };
 }
 
 /** Parse one capability .feature source into the single-track IR. */
@@ -165,7 +163,6 @@ export function parseCapability(source: string, fileName = '<inline>'): Capabili
       tags,
       reqIds,
       classification: kind.classification,
-      manual: kind.manual,
       statement,
       stepCount: stepTexts.length,
       steps,