@llman-sdd/core 0.1.4 → 0.2.0

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/review/review.ts

@@ -1,3 +1,5 @@
+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.
@@ -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/manual/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,38 @@ 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 +115,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

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/validation/changeCheck.ts

@@ -0,0 +1,310 @@
+/**
+ * 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).
+ */
+
+export type ChangeIssueLevel = 'ERROR' | 'WARNING' | 'INFO';
+
+export interface ChangeIssue {
+  level: ChangeIssueLevel;
+  /** v1-style anchor (issue path), e.g. `proposal.md/frontmatter.depends_on`. */
+  path: string;
+  message: string;
+}
+
+export interface ChangeCheckInput {
+  name: string;
+  stage: 'draft' | 'designed' | 'planned' | 'full';
+  hasBinding: boolean;
+  totalTasks: number;
+  completedTasks: number;
+}
+
+export interface ChangeCheckConfig {
+  strict_defer?: boolean | null;
+  min_completion_ratio?: number | null;
+  change_id_pattern?: string | null;
+}
+
+export interface ChangeFsIoLite {
+  exists(path: string): boolean;
+  readText(path: string): string;
+  listDir(path: string): string[];
+  isDirectory(path: string): boolean;
+}
+
+export const STAGE_ORDER = ['draft', 'designed', 'planned', 'full'] as const;
+
+export type StageGate = (typeof STAGE_ORDER)[number];
+
+export interface ChangeCheckResult {
+  id: string;
+  valid: boolean;
+  issues: ChangeIssue[];
+}
+
+/** Legacy pure gate (r47 surface) — kept for existing callers/tests. */
+export function checkChangeDoc(
+  input: ChangeCheckInput,
+  config: ChangeCheckConfig,
+  opts: { stage?: StageGate } = {},
+): ChangeCheckResult {
+  const issues: ChangeIssue[] = [];
+  if (input.totalTasks > 0 && input.completedTasks < input.totalTasks) {
+    const pending = input.totalTasks - input.completedTasks;
+    issues.push({
+      level: config.strict_defer ? 'ERROR' : 'WARNING',
+      path: 'tasks.md',
+      message: `${pending} unchecked task(s) in tasks.md`,
+    });
+  }
+  if (
+    config.min_completion_ratio !== undefined &&
+    config.min_completion_ratio !== null &&
+    input.totalTasks > 0 &&
+    input.completedTasks / input.totalTasks < config.min_completion_ratio
+  ) {
+    issues.push({
+      level: 'ERROR',
+      path: 'tasks.md',
+      message: `completion ratio below archive.min_completion_ratio (${config.min_completion_ratio})`,
+    });
+  }
+  if (!input.hasBinding) {
+    issues.push({
+      level: 'WARNING',
+      path: 'binding',
+      message: 'change has no branch binding (not started/attached)',
+    });
+  }
+  if (config.change_id_pattern) {
+    const re = new RegExp(config.change_id_pattern, 'u');
+    if (!re.test(input.name)) {
+      issues.push({
+        level: 'ERROR',
+        path: 'change-id',
+        message: `Change id '${input.name}' does not match change_id.pattern '${config.change_id_pattern}' (sdd-workflow r29; scope: active changes only, archive/legacy shapes are not back-checked).`,
+      });
+    }
+  }
+  if (opts.stage !== undefined) {
+    const currentIdx = STAGE_ORDER.indexOf(input.stage);
+    const requiredIdx = STAGE_ORDER.indexOf(opts.stage);
+    if (currentIdx < requiredIdx) {
+      issues.push({
+        level: 'ERROR',
+        path: 'stage',
+        message: `stage \`${input.stage}\` is below the required \`${opts.stage}\``,
+      });
+    }
+  }
+  return { id: input.name, valid: issues.every((i) => i.level !== 'ERROR'), issues };
+}
+
+export type ChangeValidationConfig = ChangeCheckConfig;
+
+const COMPLETENESS: Record<string, string> = {
+  draft:
+    "Change is in 'draft' stage (next: add design.md + tasks.md, then `llman sdd change start <id>` to enter a feature branch)",
+  designed:
+    "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')",
+};
+
+/**
+ * File-aware change validation with v1 messages/paths (used by the validate
+ * command). `strict` escalates WARNING issues to ERROR (v1 build_report).
+ */
+export function validateChange(
+  io: ChangeFsIoLite,
+  root: string,
+  id: string,
+  config: ChangeValidationConfig,
+  opts: { stage?: StageGate; strict?: boolean } = {},
+): ChangeCheckResult {
+  const issues: ChangeIssue[] = [];
+  const push = (level: ChangeIssueLevel, path: string, message: string): void => {
+    issues.push({ level, path, message });
+  };
+
+  const dir = `${root}/llmanspec/changes/${id}/`;
+  const baseDir = `${root}/llmanspec/changes`;
+  const proposal = `${dir}proposal.md`;
+  if (!io.exists(proposal)) {
+    push('ERROR', 'proposal.md', 'Change is missing proposal.md.');
+  } else {
+    const text = io.readText(proposal);
+    const fmMatch = text.match(/^---\n([\s\S]*?)\n---/u);
+    const fm = fmMatch?.[1] ?? '';
+    const fmLines = fm.split('\n').map((l) => l.trim());
+
+    for (const key of ['depends_on', 'blocks'] as const) {
+      const lineIdx = fmLines.findIndex((l) => l.startsWith(`${key}:`));
+      if (lineIdx === -1) continue;
+      const value = (fmLines[lineIdx] ?? '').slice(key.length + 1).trim();
+      let items: string[] = [];
+      if (value === '') {
+        for (const l of fmLines.slice(lineIdx + 1)) {
+          if (l.startsWith('- ')) items.push(l.slice(2).trim());
+          else if (l === '') continue;
+          else break;
+        }
+      } else if (value.startsWith('[')) {
+        items = value
+          .slice(1, -1)
+          .split(',')
+          .map((s) => s.trim())
+          .filter((s) => s !== '');
+      } else {
+        push(
+          'ERROR',
+          `proposal.md/frontmatter.${key}`,
+          `proposal.md ${key} must be a list of change ID strings`,
+        );
+        continue;
+      }
+      for (const item of items) {
+        if (item === '') continue;
+        if (/^\d/u.test(item)) {
+          push(
+            'ERROR',
+            `proposal.md/frontmatter.${key}`,
+            `proposal.md ${key} must be a list of change ID strings`,
+          );
+          continue;
+        }
+        const depDir = `${baseDir}/${item}`;
+        const archived = `${baseDir}/archive`;
+        if (
+          !io.exists(`${depDir}/proposal.md`) &&
+          !io.exists(dir.replace(/\/[^/]+\/$/u, '/archive/')) &&
+          !io.listDir(archived).some((n) => n.endsWith(`-${item}`))
+        ) {
+          push(
+            'ERROR',
+            `proposal.md/frontmatter.${key}`,
+            `proposal.md ${key} references unknown change: ${item}`,
+          );
+        }
+      }
+    }
+
+    // Unknown frontmatter field gate (v1).
+    for (const l of fmLines) {
+      if (l === '' || l.startsWith('-') || l.startsWith('#')) continue;
+      const m = l.match(/^([a-zA-Z_][a-zA-Z0-9_]*)\s*:/u);
+      if (m && m[1] !== undefined && !ALLOWED_FIELDS.includes(m[1])) {
+        push(
+          'ERROR',
+          'proposal.md/frontmatter',
+          `proposal.md frontmatter has unknown field '${m[1]}'; allowed fields are: ${ALLOWED_FIELDS.join(', ')}. Stage is inferred from on-disk artifacts (run \`llman sdd show\` / \`llman sdd list\`); do not store lifecycle state in frontmatter.`,
+        );
+      }
+    }
+
+    const hasDesign = io.exists(`${dir}design.md`);
+    const hasTasks = io.exists(`${dir}tasks.md`);
+    const stage = hasDesign && hasTasks ? 'planned' : hasDesign ? 'designed' : 'draft';
+
+    if (hasTasks && !hasDesign) {
+      push(
+        'ERROR',
+        'proposal.md/frontmatter',
+        'Change has tasks.md but missing design.md. Tasks MUST be generated after design decisions are documented. Create design.md first, then regenerate tasks.md.',
+      );
+    }
+
+    if (hasTasks) {
+      const tasks = io.readText(`${dir}tasks.md`);
+      let total = 0;
+      let completed = 0;
+      for (const line of tasks.split('\n')) {
+        const m = line.match(/^\s*-\s+\[( |x|X)\]/u);
+        if (m) {
+          total += 1;
+          if (m[1] !== ' ') completed += 1;
+        }
+      }
+      if (total > 0 && completed < total) {
+        const n = total - completed;
+        push(
+          config.strict_defer ? 'ERROR' : 'WARNING',
+          'tasks.md',
+          `${n} unchecked task(s) in tasks.md`,
+        );
+      }
+    }
+
+    // completeness INFO (v1 surface).
+    push('INFO', 'completeness', COMPLETENESS[stage] ?? '');
+  }
+
+  // pattern gate (v1 change-id path).
+  if (config.change_id_pattern) {
+    try {
+      const re = new RegExp(config.change_id_pattern, 'u');
+      if (!re.test(id)) {
+        push(
+          'ERROR',
+          'change-id',
+          `Change id '${id}' does not match change_id.pattern '${config.change_id_pattern}' (sdd-workflow r29; scope: active changes only, archive/legacy shapes are not back-checked).`,
+        );
+      }
+    } catch {
+      /* compile already validated at load; ignore */
+    }
+  }
+
+  // stage gate (v1 --stage: artifact presence per gate).
+  if (opts.stage !== undefined) {
+    const hasDesign = io.exists(`${dir}design.md`);
+    const hasTasks = io.exists(`${dir}tasks.md`);
+    if (opts.stage === 'designed' && !hasDesign) {
+      push('ERROR', 'design.md', `Stage forced to 'designed' but design.md is missing`);
+    }
+    if (opts.stage === 'planned') {
+      if (!hasDesign)
+        push('ERROR', 'design.md', `Stage forced to 'planned' but design.md is missing`);
+      if (!hasTasks) push('ERROR', 'tasks.md', `Stage forced to 'planned' but tasks.md is missing`);
+    }
+    if (opts.stage === 'full' && !hasTasks) {
+      push('ERROR', 'tasks.md', `Stage forced to 'full' but tasks.md is missing`);
+    }
+  }
+
+  const effective =
+    opts.strict === true
+      ? issues.map((i) => (i.level === 'WARNING' ? { ...i, level: 'ERROR' as const } : i))
+      : issues;
+  return { id, valid: effective.every((i) => i.level !== 'ERROR'), issues: effective };
+}
+
+const ALLOWED_FIELDS = [
+  'depends_on',
+  'blocks',
+  'branch',
+  'base_branch',
+  'base_sha',
+  'needs_specs_change',
+];
+
+export interface PlaceholderTarget {
+  featureDir: string;
+  featureName: string;
+  featurePath: string;
+}
+
+/** True when run_command carries any r48 placeholder. */
+export function hasPlaceholders(runCommand: string): boolean {
+  return /\{feature_dir\}|\{feature_name\}|\{feature_path\}/u.test(runCommand);
+}
+
+/** Expand {feature_dir}/{feature_name}/{feature_path} for one target (r48). */
+export function expandRunCommand(runCommand: string, target: PlaceholderTarget): string {
+  return runCommand
+    .replaceAll('{feature_dir}', target.featureDir)
+    .replaceAll('{feature_name}', target.featureName)
+    .replaceAll('{feature_path}', target.featurePath);
+}