@llman-sdd/core 0.2.0 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llman-sdd/core",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Pure domain logic for llman-sdd (config, gherkin specs, validation, templates)",
   "license": "MIT",
   "repository": {

package/src/change/lifecycle.ts

@@ -184,6 +184,14 @@ export function finalizeChange(
   if (binding === null) {
     throw new LifecycleError(`change \`${id}\` has no branch binding — run start/attach first`);
   }
+  // r15 (v1 r94): finalize runs on the bound branch — any other branch must
+  // fail before any write (no switch, no merge, no rename).
+  const current = currentBranch(git);
+  if (current !== binding.branch) {
+    throw new LifecycleError(
+      `finalize must run on the bound branch \`${binding.branch}\` (current: ${current ?? 'detached HEAD'})`,
+    );
+  }
   const method = opts.method ?? 'squash';
   const target = opts.into ?? binding.baseBranch ?? defaultBranch(git);
   return mergeRenameCommit(git, io, id, binding.branch, target, method, opts.today, opts.noCommit);

package/src/change/resolve.ts

@@ -0,0 +1,34 @@
+/**
+ * Change-id prefix resolution (peripheral-commands r61, v1 cli spec r112):
+ * exact match > unique prefix > multiple candidates > no match, all
+ * case-sensitive. Candidates are the active change ids discovered via
+ * collectChanges (depth-limited, archive-skipping). Pure — IO is injected.
+ */
+import { collectChanges, type ChangeFsIo } from '../report/collect.ts';
+
+export interface ResolvedChangeId {
+  id: string;
+  viaPrefix: boolean;
+}
+
+export class ChangeIdResolveError extends Error {}
+
+export function resolveChangeId(
+  io: ChangeFsIo,
+  root: string,
+  input: string,
+  opts: { maxScanDepth?: number } = {},
+): ResolvedChangeId {
+  const ids = collectChanges(io, root, new Date(0), opts).map((c) => c.name);
+  if (ids.includes(input)) return { id: input, viaPrefix: false };
+  const matches = ids.filter((id) => id.startsWith(input));
+  if (matches.length === 1) return { id: matches[0] as string, viaPrefix: true };
+  if (matches.length > 1) {
+    throw new ChangeIdResolveError(
+      `change '${input}' matches multiple active changes:\n${matches
+        .map((m) => `  - ${m}`)
+        .join('\n')}\nDid you mean one of these?`,
+    );
+  }
+  throw new ChangeIdResolveError(`change not found: ${input}`);
+}

package/src/context/indexStore.ts

@@ -124,3 +124,44 @@ export function loadTree(io: IndexIo): SerializedTreeIndex | null {
     return null;
   }
 }
+
+export interface AutoRefreshResult {
+  tree: SerializedTreeIndex | null;
+  rebuilt: boolean;
+  error: string | null;
+}
+
+/**
+ * r62: retrieval-side lazy refresh — a missing/corrupted/stale index is
+ * rebuilt once (zero-LLM) before retrieval; a failed rebuild surfaces
+ * `index_rebuild_failed` instead of a missing/stale quality note.
+ */
+export function loadTreeWithAutoRebuild(
+  io: IndexIo,
+  specsDir: string,
+  entries: readonly SpecEntry[],
+  opts: RebuildOpts,
+): AutoRefreshResult {
+  const initial = loadTree(io);
+  if (initial !== null && checkIndexFreshness(io, specsDir).fresh) {
+    return { tree: initial, rebuilt: false, error: null };
+  }
+  try {
+    rebuildIndex(io, specsDir, entries, opts);
+  } catch (error) {
+    return {
+      tree: null,
+      rebuilt: false,
+      error: `auto-rebuild failed: ${(error as Error).message} — run \`llman-sdd index rebuild\``,
+    };
+  }
+  const tree = loadTree(io);
+  if (tree === null) {
+    return {
+      tree: null,
+      rebuilt: true,
+      error: 'auto-rebuild produced an unreadable tree.json — run `llman-sdd index rebuild`',
+    };
+  }
+  return { tree, rebuilt: true, error: null };
+}

package/src/index.ts

@@ -112,6 +112,7 @@ export {
 } from './git/spawnGit.ts';
 export { DRAFT_PROPOSAL_TEMPLATE, deriveChangeId, isLegalChangeId } from './change/id.ts';
 export { extractUniqueNumber, harvestUniqueNumbers } from './change/nextId.ts';
+export { ChangeIdResolveError, resolveChangeId, type ResolvedChangeId } from './change/resolve.ts';
 export {
   CHANGES_DIR,
   LifecycleError,
@@ -184,6 +185,7 @@ export {
 } from './report/specHelpers.ts';
 export {
   collectSpecs,
+  morphologyOfScenarios,
   renderSpecsJson,
   renderSpecsList,
   type SpecMorphology,
@@ -235,8 +237,10 @@ export {
   TREE_JSON_REL,
   checkIndexFreshness,
   loadTree,
+  loadTreeWithAutoRebuild,
   parseLock,
   rebuildIndex,
+  type AutoRefreshResult,
   type FreshnessResult,
   type IndexIo,
   type RebuildOpts,

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`;
@@ -129,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/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

@@ -6,7 +6,7 @@ import { evaluateStaleness, notApplicableStaleness } from '../validation/stalene
  */
 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;
@@ -28,7 +28,7 @@ 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/manual/unbound/stale) to this capability. */
+  /** Restrict per-capability signals (pending/unbound/stale) to this capability. */
   capability?: string;
   /** git + root for real staleness evaluation (v1 parity). */
   git?: GitLike;
@@ -65,12 +65,10 @@ export function buildReview(input: ReviewInput, io: SpecIo): ReviewResult {
     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);
     // 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 (v1 evaluate): real base-ref/scope evaluation.
@@ -131,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/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,

package/src/validation/changeCheck.ts

@@ -1,8 +1,10 @@
+import { readBinding } from '../change/frontmatter.ts';
 /**
  * Change-domain validation (v1 `commands/validate.rs` change path parity):
  * frontmatter/depends_on gates, design/tasks constraints, completeness stage
  * INFO, pattern gate and task gates. IO + git injected (pure).
  */
+import type { GitLike } from '../git/spawnGit.ts';
 
 export type ChangeIssueLevel = 'ERROR' | 'WARNING' | 'INFO';
 
@@ -111,18 +113,21 @@ const COMPLETENESS: Record<string, string> = {
     "Change is in 'designed' stage (next: add tasks.md to reach 'planned', then `llman sdd change start` to enter feature branch and reach 'full')",
   planned:
     "Change is in 'planned' stage (next: `llman sdd change start` to enter feature branch and reach 'full')",
+  full: "Change is bound and stage is 'full' (verify readiness via `llman sdd show <id> --json` readyToImplement)",
 };
 
 /**
  * File-aware change validation with v1 messages/paths (used by the validate
  * command). `strict` escalates WARNING issues to ERROR (v1 build_report).
+ * `git` (optional) enables the r63 completeness WARNINGs — Full-not-ready
+ * with skill guidance, per change.
  */
 export function validateChange(
   io: ChangeFsIoLite,
   root: string,
   id: string,
   config: ChangeValidationConfig,
-  opts: { stage?: StageGate; strict?: boolean } = {},
+  opts: { stage?: StageGate; strict?: boolean; git?: GitLike } = {},
 ): ChangeCheckResult {
   const issues: ChangeIssue[] = [];
   const push = (level: ChangeIssueLevel, path: string, message: string): void => {
@@ -206,7 +211,15 @@ export function validateChange(
 
     const hasDesign = io.exists(`${dir}design.md`);
     const hasTasks = io.exists(`${dir}tasks.md`);
-    const stage = hasDesign && hasTasks ? 'planned' : hasDesign ? 'designed' : 'draft';
+    const binding = readBinding(text);
+    const stage =
+      hasDesign && hasTasks
+        ? binding !== null
+          ? 'full'
+          : 'planned'
+        : hasDesign
+          ? 'designed'
+          : 'draft';
 
     if (hasTasks && !hasDesign) {
       push(
@@ -239,6 +252,24 @@ export function validateChange(
 
     // completeness INFO (v1 surface).
     push('INFO', 'completeness', COMPLETENESS[stage] ?? '');
+
+    // r63: Full-but-not-ready WARNING with skill guidance (v1 r1 surface).
+    if (opts.git !== undefined && binding !== null && stage === 'full') {
+      const needs =
+        text.match(/^needs_specs_change:\s*(true|false)\s*$/mu)?.[1] !== undefined
+          ? text.match(/^needs_specs_change:\s*(true|false)\s*$/mu)?.[1] === 'true'
+          : true;
+      const touched =
+        opts.git.runOpt(['diff', '--name-only', `${binding.baseBranch}...${binding.branch}`]) ?? '';
+      const landed = touched.includes('llmanspec/specs/');
+      if (!landed && needs) {
+        push(
+          'WARNING',
+          'proposal.md',
+          `specs not landed: change bound to \`${binding.branch}\` but no changes under \`llmanspec/specs/\` on its bound branch. Edit live specs there and commit (or set \`needs_specs_change: false\` if this change has no live contract edits). Skill: llman-sdd-propose — do NOT re-run change start when already attached; apply only when \`llman-sdd show <id> --json\` reports readyToImplement=true (llman-sdd-apply).`,
+        );
+      }
+    }
   }
 
   // pattern gate (v1 change-id path).

package/src/validation/validate.ts

@@ -112,8 +112,8 @@ export function validateCapability(
     push('ERROR', `${cap}/feature`, 'Feature line must carry a title');
   }
 
-  // Parser-level structural errors (mutual exclusion, manual orphan, nested
-  // rule scenarios). Header gates and the MUST-word gate are owned here
+  // Parser-level structural errors (mutual exclusion, removed-tag migration,
+  // nested rule scenarios). Header gates and the MUST-word gate are owned here
   // (mapped below), so the parser's duplicate findings are skipped.
   const OWNED_BY_THIS_LAYER = ['missing-header:', 'rule:missing-must-word'];
   for (const err of doc.errors) {
@@ -161,6 +161,14 @@ export function validateCapability(
   // Dangling acceptance @req links (v1 order: acceptance/@req then coverage).
   const ruleReqIds = new Set(human.flatMap((s) => s.reqIds));
   for (const sc of acceptance) {
+    // r65: orphan acceptance scenario — no @req link at all (v1 r132 WARNING).
+    if (sc.reqIds.length === 0) {
+      push(
+        'WARNING',
+        `${cap}/acceptance/${sc.name}`,
+        `orphan acceptance scenario \`${sc.name}\` has no @req:<req_id> link`,
+      );
+    }
     for (const rid of sc.reqIds) {
       if (!ruleReqIds.has(rid)) {
         push(
@@ -180,7 +188,7 @@ export function validateCapability(
         push(
           'INFO',
           coveragePath(cap),
-          `rule ${rid} is pending: no @executable acceptance scenario and no @manual waiver`,
+          `rule ${rid} is pending: no @executable acceptance scenario`,
         );
       }
     }

package/templates/en/units/skills/validation-hints.md

@@ -12,7 +12,7 @@ Every capability `.feature` (`llmanspec/specs/<capability>.feature` or `llmanspe
 2) Tag grammar (`@human constraint scenario must carry an @req:<req_id> tag` / `orphan acceptance scenario`):
 - Rules: `@req:<id> @human` — statement in the scenario description (MUST/SHALL required).
 - Acceptance: `@executable` + at least one `@req:<id>` linking a rule.
-- `@manual` requires `@human`. Never combine `@human` with `@executable`.
+Never combine `@human` with `@executable`. (`@manual` was removed in 0.3.0 — drop it; `@human` already carries the human-judgement semantics.)
 
 3) Legacy `spec.toon` present (`legacy spec.toon found ... run ... toon2features`):
 Run `llman-sdd project migrate --kind toon2features --yes`, review the diff, commit.

package/templates/en/units/spec/feature-contract.md

@@ -25,5 +25,5 @@ It is the only spec artifact — there is no `spec.toon`.
 - Header comments (`# capability:` / `# purpose:` / `# scope:`) are REQUIRED; `scope` drives staleness.
 - `@human` scenarios are human-owned constraints; their description carries the normative statement verbatim. Editing/removing them yields a WARNING only (report-only, never blocks a gate) — compare via git branch diff; the legacy lock-ack metadata `rules_touched` / `agent_acked` / `@agent` is removed with no aliases and no compat layer (locked rules are report-only: a warning, never a block).
 - `@executable` scenarios are runner-bound acceptance; they link rules via `@req:<req_id>`.
-- Coverage tiers: enforced (has acceptance) / manual (`@manual`) / pending. `list --specs` reports all three.
+- Coverage tiers: enforced (has acceptance) / pending. `list --specs` reports both.
 - Scenarios MUST stay top-level: `Rule:` blocks are rejected (the runner skips them silently).

package/templates/zh-Hans/units/skills/validation-hints.md

@@ -12,7 +12,7 @@
 2）tag 语法（`@human constraint scenario must carry an @req:<req_id> tag` / `orphan acceptance scenario`）：
 - 规则：`@req:<id> @human` —— statement 放场景描述（须含 MUST/SHALL）。
 - 验收：`@executable` 且至少一个 `@req:<id>` 挂到规则。
-- `@manual` 须与 `@human` 同用；禁止 `@human` 与 `@executable` 同场景。
+- 禁止 `@human` 与 `@executable` 同场景；`@manual` 已在 0.3.0 移除——残留会被报迁移 ERROR，删掉该 tag 即可（`@human` 本身已承载人工判定语义）。
 
 3）遗留 `spec.toon`（`legacy spec.toon found ... run ... toon2features`）：
 运行 `llman-sdd project migrate --kind toon2features --yes`，审阅 diff 后提交。

package/templates/zh-Hans/units/spec/feature-contract.md

@@ -25,5 +25,5 @@
 - 头注释（`# capability:` / `# purpose:` / `# scope:`）必填；`scope` 驱动 staleness 检查。
 - `@human` 场景是人拥有的约束场景；规则 statement 全文放在场景描述里。改/删它只出 WARNING（报告制，不阻断门禁），用 git 分支对比审视；旧的锁定确认元数据 `rules_touched` / `agent_acked` / `@agent` 已删除，无别名也无兼容层。
 - `@executable` 场景是 runner 绑定的验收场景；用 `@req:<req_id>` 挂回规则。
-- 覆盖三态分级：enforced（有验收）/ manual（`@manual`）/ pending——`list --specs` 逐项输出。
+- 覆盖两态分级：enforced（有验收）/ pending——`list --specs` 逐项输出。
 - 场景 MUST 保持顶层：`Rule:` 块会被拒绝（runner 会静默跳过其中场景）。