@llman-sdd/core 0.1.4 → 0.3.0

package/src/validation/validate.ts

@@ -1,7 +1,8 @@
 /**
  * Validation engine (validation capability): aggregates Phase-2 parse errors
- * plus the verdict-equivalent gates probed from v1 (r11/r12). Pure —
- * filesystem access is injected via SpecIo.
+ * plus the verdict-equivalent gates (r11/r12, ordered to match v1
+ * `spec/validation.rs` observable issue order). Pure — filesystem access is
+ * injected via SpecIo.
  */
 import type { CapabilityDoc } from '../spec/ir.ts';
 import { MUST_WORD_RE } from '../spec/ir.ts';
@@ -11,7 +12,7 @@ export type ValidationLevel = 'ERROR' | 'WARNING' | 'INFO';
 
 export interface ValidationItem {
   level: ValidationLevel;
-  /** Gate anchor, e.g. `t/rule/ok` or `t/valid_scope` (v1-style). */
+  /** Gate anchor, e.g. `t/rule/ok` or `t/valid_scope` (v1-style `path`). */
   id: string;
   message: string;
 }
@@ -39,79 +40,156 @@ export interface ValidationReport {
   failed: boolean;
 }
 
+const rulesPath = (cap: string): string => `${cap}/rules`;
+const acceptanceReqPath = (cap: string, name: string): string => `${cap}/acceptance/${name}/@req`;
+const coveragePath = (cap: string): string => `${cap}/coverage`;
+
 export function validateCapability(
   entry: SpecEntry,
   duplicatesFor: (reqId: string) => boolean,
   io: SpecIo,
+  opts: { strict?: boolean } = {},
 ): SpecVerdict {
   const { doc } = entry;
   const cap = doc.header.capability ?? entry.fileName;
+  const strict = opts.strict === true;
   const items: ValidationItem[] = [];
 
-  // Header gates (r12): capability header is an ERROR (v1 parity); missing
-  // purpose/scope degrade to WARNING.
+  const push = (level: ValidationLevel, id: string, message: string): void => {
+    items.push({ level, id, message });
+  };
+
+  // Header gates (r12 / v1 spec_meta). v1 treats a missing `# capability:`
+  // header as a parse-level failure: only `file` + registry-scan issues are
+  // emitted and all single-track gates are skipped.
   if (doc.header.capability === null) {
-    items.push({
-      level: 'ERROR',
-      id: 'file',
-      message: 'missing `# capability:` header comment',
-    });
+    const msg = `spec \`${cap}\`: missing \`# capability:\` header comment (spec-format r133)`;
+    push('ERROR', 'file', msg);
+    push('ERROR', 'llmanspec/specs', `Failed to scan req_id index: ${msg}`);
+    return { fileName: entry.fileName, capability: cap, ok: false, items };
   }
-  if (doc.header.purpose === null) {
-    items.push({ level: 'WARNING', id: 'file', message: 'missing `# purpose:` header comment' });
+  if (doc.header.purpose === null || doc.header.purpose.trim() === '') {
+    push(
+      'ERROR',
+      `${cap}/purpose`,
+      '`# purpose:` header comment must not be empty (spec-format r133)',
+    );
   }
   if (doc.header.scope === null) {
-    items.push({ level: 'WARNING', id: 'file', message: 'missing `# scope:` header comment' });
+    push(
+      'ERROR',
+      `${cap}/valid_scope`,
+      'Spec valid_scope must not be empty (add it inside the .toon document).',
+    );
   } else {
-    for (const p of doc.header.scope
+    // r42: missing valid_scope paths are independent failures —
+    // ERROR (nonzero exit) under --strict, WARNING otherwise.
+    const missing = doc.header.scope
       .split(',')
       .map((s) => s.trim())
-      .filter((s) => s !== '')) {
-      if (!io.exists(p)) {
-        items.push({
-          level: 'ERROR',
-          id: `${cap}/valid_scope`,
-          message: `valid_scope path(s) do not exist on disk: ${p}`,
-        });
-      }
+      .filter((s) => s !== '')
+      .filter((s) => !io.exists(s));
+    if (missing.length > 0) {
+      push(
+        strict ? 'ERROR' : 'WARNING',
+        `${cap}/valid_scope`,
+        `valid_scope path(s) do not exist on disk: ${missing.join(', ')}`,
+      );
     }
   }
 
-  // Structural errors from parsing (mutual exclusion, manual orphan, nested
-  // rule scenarios) — all ERROR level (v1 verdict parity). Header gates and
-  // the MUST-word gate are owned by this layer (mapped below), so the
-  // parser's duplicate findings are skipped here.
+  // Spec name must match the capability id (flat stem).
+  if (doc.header.capability !== null && doc.header.capability.trim() !== cap) {
+    push(
+      'WARNING',
+      `${cap}/meta.name`,
+      `Spec \`# capability:\` header must match spec id (flat file stem or directory name): \`${doc.header.capability.trim()}\` != \`${cap}\``,
+    );
+  }
+
+  // Feature title must be non-empty.
+  if ((doc.featureName ?? '').trim() === '') {
+    push('ERROR', `${cap}/feature`, 'Feature line must carry a title');
+  }
+
+  // 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) {
     if (OWNED_BY_THIS_LAYER.some((prefix) => err.code.startsWith(prefix))) continue;
-    items.push({ level: 'ERROR', id: `${cap}/${err.code}`, message: err.message });
+    push('ERROR', err.code.startsWith('file') ? 'file' : `${cap}/${err.code}`, err.message);
+  }
+
+  // Single-track gates (v1 validate_single_track order).
+  const human = doc.scenarios.filter((s) => s.classification === 'human');
+  const acceptance = doc.scenarios.filter((s) => s.classification === 'executable');
+
+  if (human.length === 0) {
+    push('ERROR', rulesPath(cap), 'spec must define at least one @human constraint scenario');
   }
 
   for (const scenario of doc.scenarios) {
     const anchor = `${cap}/rule/${scenario.name}`;
     if (scenario.classification === 'human') {
       if (scenario.reqIds.length === 0) {
-        items.push({
-          level: 'ERROR',
-          id: anchor,
-          message: '@human constraint scenario must carry an @req:<req_id> tag',
-        });
+        push('ERROR', anchor, '@human constraint scenario must carry an @req:<req_id> tag');
       }
       if (!MUST_WORD_RE.test(scenario.statement)) {
-        items.push({
-          level: 'ERROR',
-          id: anchor,
-          message: 'constraint statement must contain MUST/SHALL (or 必须/不得/禁止)',
-        });
+        push('ERROR', anchor, 'constraint statement must contain MUST/SHALL (or 必须/不得/禁止)');
       }
+    } else if (scenario.classification === 'executable') {
+      // (pairing handled below, after all rule req ids are known)
+    } else {
+      push(
+        'WARNING',
+        `${cap}/scenario/${scenario.name}`,
+        `scenario \`${scenario.name}\` carries neither @human nor @executable; tag it or drop it`,
+      );
     }
     for (const reqId of scenario.reqIds) {
       if (duplicatesFor(reqId)) {
-        items.push({
-          level: 'ERROR',
-          id: `${cap}/registry/${reqId}`,
-          message: `global duplicate req_id \`${reqId}\` used by multiple capabilities`,
-        });
+        push(
+          'ERROR',
+          `${cap}/registry/${reqId}`,
+          `global duplicate req_id \`${reqId}\` used by multiple capabilities`,
+        );
+      }
+    }
+  }
+
+  // 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(
+          'ERROR',
+          acceptanceReqPath(cap, sc.name),
+          `@req:${rid} on acceptance scenario \`${sc.name}\` has no matching @human constraint`,
+        );
+      }
+    }
+  }
+
+  // Rule coverage INFO (r134 pending rules).
+  for (const sc of human) {
+    for (const rid of sc.reqIds) {
+      const covered = acceptance.some((a) => a.reqIds.includes(rid));
+      if (!covered) {
+        push(
+          'INFO',
+          coveragePath(cap),
+          `rule ${rid} is pending: no @executable acceptance scenario`,
+        );
       }
     }
   }
@@ -149,3 +227,8 @@ export function validateAllSpecs(entries: readonly SpecEntry[], io: SpecIo): Val
 
   return { verdicts, lines, failed };
 }
+
+/** v1 `apply_strict`: WARNING issues escalate to ERROR when --strict. */
+export function applyStrict<T extends { level: ValidationLevel }>(items: readonly T[]): T[] {
+  return items.map((i) => (i.level === 'WARNING' ? { ...i, level: 'ERROR' as const } : i));
+}

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 会静默跳过其中场景）。