@llman-sdd/core 0.1.4 → 0.2.0

package/src/index.ts

@@ -33,6 +33,18 @@ export {
   type SddConfigInput,
 } from './config/schema.ts';
 export { ConfigValidationError, MAX_REPORTED_ISSUES, loadConfig } from './config/load.ts';
+export {
+  ChangeIdError,
+  compileChangeIdPattern,
+  nextUniqueNumber,
+  renderChangeIdTemplate,
+} from './config/changeId.ts';
+export {
+  ExtraSkillsError,
+  renderConfigOverview,
+  setExtraSkills,
+  skillsJson,
+} from './config/surface.ts';
 
 export type {
   CapabilityDoc,
@@ -48,6 +60,16 @@ export {
   parseFeatureSource,
 } from './spec/parser.ts';
 export { buildReqRegistry, type ReqRegistry, type RegistryDuplicate } from './spec/reqRegistry.ts';
+export {
+  addReq,
+  addScenario,
+  allReqIds,
+  AuthoringError,
+  planDedupe,
+  resolveReq,
+  type DedupePlanItem,
+  type ResolvedReq,
+} from './spec/authoring.ts';
 export type {
   SpecEntry,
   SpecIo,
@@ -56,7 +78,26 @@ export type {
   ValidationLevel,
   ValidationReport,
 } from './validation/validate.ts';
-export { validateAllSpecs, validateCapability } from './validation/validate.ts';
+export { validateAllSpecs, validateCapability, applyStrict } from './validation/validate.ts';
+export { splitVerb } from './config/changeId.ts';
+export {
+  evaluateStaleness,
+  notApplicableStaleness,
+  type StalenessInfo,
+} from './validation/staleness.ts';
+export {
+  checkChangeDoc,
+  validateChange,
+  expandRunCommand,
+  hasPlaceholders,
+  STAGE_ORDER,
+  type ChangeCheckConfig,
+  type ChangeCheckInput,
+  type ChangeCheckResult,
+  type ChangeIssue,
+  type ChangeFsIoLite,
+  type StageGate,
+} from './validation/changeCheck.ts';
 export { discoverSpecs, type DiscoveryIo } from './validation/discover.ts';
 export type { ChangeBinding } from './change/frontmatter.ts';
 export { readBinding, writeBinding } from './change/frontmatter.ts';
@@ -70,6 +111,7 @@ export {
   type GitLike,
 } from './git/spawnGit.ts';
 export { DRAFT_PROPOSAL_TEMPLATE, deriveChangeId, isLegalChangeId } from './change/id.ts';
+export { extractUniqueNumber, harvestUniqueNumbers } from './change/nextId.ts';
 export {
   CHANGES_DIR,
   LifecycleError,
@@ -80,6 +122,9 @@ export {
   startChange,
   type FinalizeResult,
   type FsIo,
+  archiveChange,
+  archiveTaskGate,
+  changeDiffInfo,
 } from './change/lifecycle.ts';
 export { normalizeLocale, localeFallbacks } from './templates/locale.ts';
 export {

package/src/report/collect.ts

@@ -37,8 +37,10 @@ export function stageFor(
   hasTasks: boolean,
   hasBinding: boolean,
 ): ChangeSummary['stage'] {
-  if (hasBinding) return 'full';
-  if (hasTasks) return 'planned';
+  // Monotonic v1 parity (r34): design.md gates designed, tasks.md only
+  // upgrades on top of design, binding only upgrades the complete set.
+  if (hasDesign && hasTasks && hasBinding) return 'full';
+  if (hasDesign && hasTasks) return 'planned';
   if (hasDesign) return 'designed';
   return 'draft';
 }
@@ -64,17 +66,32 @@ export function firstH1(md: string): string {
   return '';
 }
 
-export function collectChanges(io: ChangeFsIo, root: string, now: Date): ChangeSummary[] {
+export function collectChanges(
+  io: ChangeFsIo,
+  root: string,
+  now: Date,
+  opts: { maxScanDepth?: number } = {},
+): ChangeSummary[] {
   const changesDir = `${root}/${CHANGES_DIR}`;
   if (!io.exists(changesDir) || !io.isDirectory(changesDir)) return [];
+  const maxDepth = opts.maxScanDepth ?? 8;
   const out: ChangeSummary[] = [];
-  for (const name of io.listDir(changesDir).toSorted()) {
-    if (name === 'archive') continue;
-    const dir = `${changesDir}/${name}`;
-    if (!io.isDirectory(dir)) continue;
+  // r58: recursive, depth-limited proposal discovery (v1 --max-scan-depth parity)
+  const visit = (dir: string, depth: number): void => {
+    if (depth > maxDepth) return;
+    for (const name of io.listDir(dir).toSorted()) {
+      if (name === 'archive' || name.startsWith('.')) continue;
+      const child = `${dir}/${name}`;
+      if (!io.isDirectory(child)) continue;
+      if (io.exists(`${child}/proposal.md`)) {
+        readChangeDir(child, name);
+      } else {
+        visit(child, depth + 1);
+      }
+    }
+  };
+  const readChangeDir = (dir: string, name: string): void => {
     const proposal = `${dir}/proposal.md`;
-    if (!io.exists(proposal)) continue;
-
     const hasDesign = io.exists(`${dir}/design.md`);
     const hasTasks = io.exists(`${dir}/tasks.md`);
     const hasBinding = readBinding(io.readText(proposal)) !== null;
@@ -101,7 +118,8 @@ export function collectChanges(io: ChangeFsIo, root: string, now: Date): ChangeS
       lastModified,
       idleDays,
     });
-  }
+  };
+  visit(changesDir, 1);
   // v1 lists newest-first
   return out.toSorted((a, b) => b.lastModified.getTime() - a.lastModified.getTime());
 }
@@ -130,12 +148,10 @@ export function pad(s: string, width: number): string {
 export function renderChangesList(changes: readonly ChangeSummary[], now: Date): string[] {
   const lines = ['Active changes:'];
   if (changes.length === 0) return lines;
-  const nameWidth = Math.max(...changes.map((c) => c.name.length)) + 2;
-  const stageWidth = Math.max(...changes.map((c) => c.stage.length)) + 7;
-  const statusWidth = Math.max(...changes.map((c) => statusHuman(c).length)) + 5;
+  const nameWidth = Math.max(...changes.map((c) => c.name.length));
   for (const c of changes) {
     lines.push(
-      `  ${pad(c.name, nameWidth)}${pad(c.stage, stageWidth)}${pad(statusHuman(c), statusWidth)}${relativeTime(
+      `  ${pad(c.name, nameWidth)}  ${pad(c.stage, 10)}  ${pad(statusHuman(c), 12)}  ${relativeTime(
         c.lastModified,
         now,
       )}${statusFor(c.totalTasks, c.completedTasks) === 'no-tasks' ? ` (idle ${c.idleDays}d)` : ''}`,

package/src/report/graph.ts

@@ -1,8 +1,10 @@
 /**
- * Change dependency graph (peripheral-commands capability, r21):
- * mermaid output with v1 conventions — node ids dash→underscore, archived
- * changes annotated "✓ done" with the archived class, depends_on edges.
+ * Change dependency graph (peripheral-commands capability, r21/r30/r54):
+ * v1 `commands/graph.rs` observable contract — scope parsing, connected
+ * component subgraphs, conditional classDef, empty placeholder, bidirectional
+ * seed BFS, error paths. Pure: IO injected.
  */
+
 import { CHANGES_DIR } from '../change/lifecycle.ts';
 
 export interface GraphFsIo {
@@ -15,77 +17,371 @@ export interface GraphFsIo {
 interface GraphNode {
   id: string;
   archived: boolean;
-  dependsOn: string[];
+  /** true = directory on disk; false = phantom (frozen/removed dependency). */
+  present: boolean;
+}
+
+interface DepEdge {
+  from: string;
+  to: string;
 }
 
-/** Extract depends_on entries from a proposal's YAML frontmatter. */
-function parseDeps(proposal: string): string[] {
+export class GraphError extends Error {}
+
+function extractArchivedId(name: string): string | null {
+  const m = name.match(/^\d{4}-\d{2}-\d{2}-(.+)$/u);
+  return m ? (m[1] ?? null) : null;
+}
+
+/** Extract depends_on entries (flow + block styles, r30). */
+export function parseDeps(proposal: string): string[] {
   const fm = proposal.match(/^---\n([\s\S]*?)\n---/u);
   const deps: string[] = [];
   if (!fm?.[1]) return deps;
   let inDeps = false;
   for (const line of fm[1].split('\n')) {
+    const flow = line.match(/^depends_on:\s*\[([^\]]*)\]\s*$/u);
+    if (flow) {
+      for (const item of flow[1]?.split(',') ?? []) {
+        const dep = item.trim().replaceAll(/^['"]|['"]$/gu, '');
+        if (dep !== '' && !/^[0-9]+$/u.test(dep)) deps.push(dep);
+      }
+      inDeps = false;
+      continue;
+    }
     if (/^depends_on:\s*$/u.test(line)) {
       inDeps = true;
       continue;
     }
     if (inDeps) {
       const m = line.match(/^\s*-\s+(\S+)/u);
-      if (m?.[1]) deps.push(m[1]);
+      if (m?.[1] && !/^[0-9]+$/u.test(m[1])) deps.push(m[1]);
       else if (line.trim() !== '') inDeps = false;
     }
   }
   return deps;
 }
 
-function collectNodes(io: GraphFsIo, root: string): GraphNode[] {
-  const nodes: GraphNode[] = [];
-  const scan = (dir: string, archived: boolean, stripDatePrefix: boolean): void => {
-    if (!io.exists(dir) || !io.isDirectory(dir)) return;
+type ScopeKind = 'active' | 'archived';
+
+function parseScope(scope: string): ScopeKind[] {
+  if (scope === 'all') return ['active', 'archived'];
+  const kinds: ScopeKind[] = [];
+  for (const part of scope.split(',')) {
+    const t = part.trim();
+    if (t === 'active') kinds.push('active');
+    else if (t === 'archived') kinds.push('archived');
+    else {
+      throw new GraphError(
+        `Unknown scope: '${flagClean(t)}'. Supported: active, archived, all (or comma-separated like active,archived)`,
+      );
+    }
+  }
+  if (kinds.length === 0) throw new GraphError('Scope cannot be empty');
+  return kinds;
+}
+
+function flagClean(v: string): string {
+  return v;
+}
+
+/** Active nodes: dirs (recursively) with a proposal.md (v1 discovery). */
+function collectActiveNodes(io: GraphFsIo, root: string): GraphNode[] {
+  const out: GraphNode[] = [];
+  const changesDir = `${root}/${CHANGES_DIR}`;
+  if (!io.exists(changesDir) || !io.isDirectory(changesDir)) return out;
+  const visit = (dir: string): void => {
     for (const name of io.listDir(dir).toSorted()) {
-      if (name === 'archive') continue;
-      const full = `${dir}/${name}`;
-      if (!io.isDirectory(full)) continue;
-      const proposal = `${full}/proposal.md`;
-      if (!io.exists(proposal)) continue;
-      const id = archived && stripDatePrefix ? name.replace(/^\d{4}-\d{2}-\d{2}-/u, '') : name;
-      nodes.push({ id, archived, dependsOn: parseDeps(io.readText(proposal)) });
+      if (name === 'archive' || name.startsWith('.')) continue;
+      const child = `${dir}/${name}`;
+      if (!io.isDirectory(child)) continue;
+      if (io.exists(`${child}/proposal.md`)) {
+        out.push({ id: name, archived: false, present: true });
+      } else {
+        visit(child);
+      }
     }
   };
-  scan(`${root}/${CHANGES_DIR}`, false, false);
-  // archived nodes appear only when referenced by an active depends_on
-  const referenced = new Set(nodes.flatMap((n) => n.dependsOn));
+  visit(changesDir);
+  return out;
+}
+
+function collectArchivedNodes(io: GraphFsIo, root: string): GraphNode[] {
   const archiveDir = `${root}/${CHANGES_DIR}/archive`;
-  if (io.exists(archiveDir) && io.isDirectory(archiveDir)) {
-    for (const name of io.listDir(archiveDir).toSorted()) {
-      if (!/\d{4}-\d{2}-\d{2}-/u.test(name)) continue;
-      const id = name.replace(/^\d{4}-\d{2}-\d{2}-/u, '');
-      if (!referenced.has(id)) continue;
-      // archived nodes keep their real depends_on — v1 emits their edges too
-      const proposal = `${archiveDir}/${name}/proposal.md`;
-      const deps = io.exists(proposal) ? parseDeps(io.readText(proposal)) : [];
-      nodes.push({ id, archived: true, dependsOn: deps });
+  if (!io.exists(archiveDir) || !io.isDirectory(archiveDir)) return [];
+  const out: GraphNode[] = [];
+  const seen = new Set<string>();
+  for (const name of io.listDir(archiveDir)) {
+    const child = `${archiveDir}/${name}`;
+    if (!io.isDirectory(child)) continue;
+    const id = extractArchivedId(name);
+    if (id !== null && !seen.has(id)) {
+      seen.add(id);
+      out.push({ id, archived: true, present: true });
     }
   }
-  return nodes;
+  return out;
 }
 
-export function graphMermaid(io: GraphFsIo, root: string): string[] {
-  const nodes = collectNodes(io, root);
-  const lines: string[] = ['flowchart TD'];
+function collectNodes(io: GraphFsIo, root: string, kinds: ScopeKind[]): GraphNode[] {
+  const combined: GraphNode[] = [];
+  const seen = new Set<string>();
+  for (const kind of kinds) {
+    const nodes = kind === 'active' ? collectActiveNodes(io, root) : collectArchivedNodes(io, root);
+    for (const node of nodes) {
+      if (!seen.has(node.id)) {
+        seen.add(node.id);
+        combined.push(node);
+      }
+    }
+  }
+  return combined;
+}
+
+function proposalFor(io: GraphFsIo, root: string, node: GraphNode): string {
+  if (node.archived) {
+    const archiveDir = `${root}/${CHANGES_DIR}/archive`;
+    // latest matching dirtategy: pick the newest date-prefixed dir
+    let best = '';
+    let bestDate = '';
+    for (const name of io.listDir(archiveDir)) {
+      const id = extractArchivedId(name);
+      if (id !== node.id) continue;
+      const date = name.slice(0, 10);
+      if (best === '' || date > bestDate) {
+        best = name;
+        bestDate = date;
+      }
+    }
+    const p = `${archiveDir}/${best}/proposal.md`;
+    return io.exists(p) ? io.readText(p) : '';
+  }
+  const changesDir = `${root}/${CHANGES_DIR}`;
+  const found: string[] = [];
+  const visit = (dir: string): void => {
+    for (const name of io.listDir(dir).toSorted()) {
+      if (name === 'archive' || name.startsWith('.')) continue;
+      const child = `${dir}/${name}`;
+      if (!io.isDirectory(child)) continue;
+      if (io.exists(`${child}/proposal.md`)) {
+        if (name === node.id) found.push(`${child}/proposal.md`);
+        continue;
+        // ^ leaf change dir — do not descend further
+      }
+      visit(child);
+    }
+  };
+  visit(changesDir);
+  if (found.length === 0) return '';
+  return io.readText(found[0] ?? '');
+}
+
+interface RelationMaps {
+  depends: Map<string, string[]>;
+  reverse: Map<string, string[]>;
+  nodeSet: Set<string>;
+}
+
+function buildMaps(io: GraphFsIo, root: string, nodes: GraphNode[]): RelationMaps {
+  const depends = new Map<string, string[]>();
+  const reverse = new Map<string, string[]>();
+  const nodeSet = new Set<string>();
   for (const node of nodes) {
-    const nid = node.id.replaceAll('-', '_');
-    const label = node.archived ? `${node.id} ✓ done` : node.id;
-    lines.push(`    ${nid}["${label}"]${node.archived ? ':::archived' : ''}`);
+    nodeSet.add(node.id);
+    if (!node.present) continue;
+    for (const dep of parseDeps(proposalFor(io, root, node))) {
+      depends.set(node.id, [...(depends.get(node.id) ?? []), dep]);
+      reverse.set(dep, [...(reverse.get(dep) ?? []), node.id]);
+    }
+  }
+  return { depends, reverse, nodeSet };
+}
+
+function buildDefaultNodes(io: GraphFsIo, root: string, kinds: ScopeKind[]): GraphNode[] {
+  const nodes = collectNodes(io, root, kinds);
+  const nodeIds = new Set(nodes.map((n) => n.id));
+  const all = collectNodes(io, root, ['active', 'archived']);
+  const allMap = new Map(all.map((n) => [n.id, n]));
+
+  const missing: string[] = [];
+  for (const node of all) {
+    if (!nodeIds.has(node.id) || !node.present) continue;
+    for (const dep of parseDeps(proposalFor(io, root, node))) {
+      if (!nodeIds.has(dep)) missing.push(dep);
+    }
+  }
+  const seenMissing = new Set<string>();
+  for (const dep of missing) {
+    if (seenMissing.has(dep)) continue;
+    seenMissing.add(dep);
+    const existing = allMap.get(dep);
+    if (existing !== undefined) nodes.push(existing);
+    else nodes.push({ id: dep, archived: false, present: false });
   }
-  const byId = new Set(nodes.map((n) => n.id));
+  return nodes;
+}
+
+function collectEdges(io: GraphFsIo, root: string, nodes: GraphNode[]): DepEdge[] {
+  const nodeIds = new Set(nodes.map((n) => n.id));
+  const edges: DepEdge[] = [];
   for (const node of nodes) {
-    for (const dep of node.dependsOn) {
-      // edges render only when both endpoints are shown nodes
-      if (!byId.has(dep)) continue;
-      lines.push(`    ${node.id.replaceAll('-', '_')} -->|depends on| ${dep.replaceAll('-', '_')}`);
+    if (!node.present) continue;
+    for (const dep of parseDeps(proposalFor(io, root, node))) {
+      if (nodeIds.has(dep)) edges.push({ from: node.id, to: dep });
     }
   }
-  lines.push('    classDef archived fill:#d4edda,stroke:#28a745,color:#333');
+  return edges;
+}
+
+function connectedComponents(nodeIds: string[], edges: DepEdge[]): string[][] {
+  if (nodeIds.length === 0) return [];
+  const parent = new Map<string, string>(nodeIds.map((id) => [id, id]));
+  const find = (x: string): string => {
+    let root = parent.get(x) ?? x;
+    while (parent.get(root) !== root) root = parent.get(root) ?? root;
+    return root;
+  };
+  const union = (a: string, b: string): void => {
+    const ra = find(a);
+    const rb = find(b);
+    if (ra !== rb) parent.set(ra, rb);
+  };
+  for (const edge of edges) union(edge.from, edge.to);
+  const groups = new Map<string, string[]>();
+  for (const id of nodeIds) {
+    const root = find(id);
+    groups.set(root, [...(groups.get(root) ?? []), id]);
+  }
+  return [...groups.values()].toSorted((a, b) => b.length - a.length);
+}
+
+function componentLabel(nodes: GraphNode[], ids: Set<string>): string {
+  const comp = nodes.filter((n) => ids.has(n.id));
+  const allActive = comp.every((n) => !n.archived && n.present);
+  const allArchived = comp.every((n) => n.archived);
+  if (allActive) return 'Active';
+  if (allArchived) return 'Done';
+  return 'Mixed';
+}
+
+const sanitize = (id: string): string => id.replaceAll('-', '_');
+
+export interface GraphOptions {
+  scope?: string;
+  depth?: number;
+  seed?: string;
+}
+
+export function graphMermaid(io: GraphFsIo, root: string, opts: GraphOptions = {}): string[] {
+  const scope = opts.scope ?? 'active';
+  const kinds = parseScope(scope);
+
+  let nodes: GraphNode[];
+  if (opts.seed !== undefined) {
+    nodes = buildSeedNeighborhood(io, root, opts.seed, opts.depth ?? 1, kinds);
+  } else {
+    nodes = buildDefaultNodes(io, root, kinds);
+  }
+
+  if (nodes.length === 0) {
+    return [
+      'flowchart TD',
+      opts.seed !== undefined
+        ? `    empty["Change '${opts.seed}' not found or has no relationships"]`
+        : `    empty["No changes in scope '${scope}'"]`,
+    ];
+  }
+
+  const edges = collectEdges(io, root, nodes);
+  const nodeIds = nodes.map((n) => n.id);
+  const components = connectedComponents(nodeIds, edges);
+  const hasArchived = nodes.some((n) => n.archived);
+  const hasMissing = nodes.some((n) => !n.present);
+
+  const lines = ['flowchart TD'];
+  if (components.length > 1) {
+    components.forEach((comp, idx) => {
+      const ids = new Set(comp);
+      const label = componentLabel(nodes, ids);
+      lines.push(`    subgraph sg${idx + 1}["${label}"]`);
+      renderNodesAndEdges(nodes, edges, ids, lines, true);
+      lines.push('    end');
+    });
+  } else {
+    renderNodesAndEdges(nodes, edges, new Set(nodeIds), lines, false);
+  }
+  if (hasArchived) lines.push('    classDef archived fill:#d4edda,stroke:#28a745,color:#333');
+  if (hasMissing) lines.push('    classDef missing fill:#f8d7da,stroke:#dc3545,color:#333');
   return lines;
 }
+
+function renderNodesAndEdges(
+  nodes: GraphNode[],
+  edges: DepEdge[],
+  ids: Set<string>,
+  lines: string[],
+  indented: boolean,
+): void {
+  const pad = indented ? '        ' : '    ';
+  for (const node of nodes) {
+    if (!ids.has(node.id)) continue;
+    if (!node.present) lines.push(`${pad}${sanitize(node.id)}["${node.id} ⚠ missing"]:::missing`);
+    else if (node.archived)
+      lines.push(`${pad}${sanitize(node.id)}["${node.id} ✓ done"]:::archived`);
+    else lines.push(`${pad}${sanitize(node.id)}["${node.id}"]`);
+  }
+  for (const edge of edges) {
+    if (!ids.has(edge.from)) continue;
+    lines.push(`${pad}${sanitize(edge.from)} -->|depends on| ${sanitize(edge.to)}`);
+  }
+}
+
+/** Seed neighborhood: bidirectional BFS (depends_on + reverse) over both sets. */
+function buildSeedNeighborhood(
+  io: GraphFsIo,
+  root: string,
+  seedId: string,
+  maxDepth: number,
+  _kinds: ScopeKind[],
+): GraphNode[] {
+  const resolved = resolveSeedId(io, root, seedId);
+  const allNodes = collectNodes(io, root, ['active', 'archived']);
+  const nodeMap = new Map(allNodes.map((n) => [n.id, n]));
+  if (!nodeMap.has(resolved)) {
+    const prefix = resolved.split('-')[0] ?? '';
+    const suggestions = [...nodeMap.keys()].filter((k) => k.startsWith(prefix));
+    const hint = suggestions.length > 0 ? ` Did you mean: ${suggestions.join(', ')}?` : '';
+    throw new GraphError(`change '${seedId}' not found.${hint}`);
+  }
+  const maps = buildMaps(io, root, allNodes);
+  const visited = new Set<string>([resolved]);
+  const queue: [string, number][] = [[resolved, 0]];
+  while (queue.length > 0) {
+    const [current, depth] = queue.shift() as [string, number];
+    if (depth >= maxDepth) continue;
+    const neighbors = [...(maps.depends.get(current) ?? []), ...(maps.reverse.get(current) ?? [])];
+    for (const neighbor of neighbors) {
+      if (maps.nodeSet.has(neighbor) && !visited.has(neighbor)) {
+        visited.add(neighbor);
+        queue.push([neighbor, depth + 1]);
+      }
+    }
+  }
+  const result = [...visited]
+    .filter((id) => nodeMap.has(id))
+    .map((id) => nodeMap.get(id) as GraphNode);
+  result.sort((a, b) => a.id.localeCompare(b.id));
+  return result;
+}
+
+function resolveSeedId(io: GraphFsIo, root: string, seedId: string): string {
+  const active = collectActiveNodes(io, root);
+  const archived = collectArchivedNodes(io, root);
+  const all = [...active.map((n) => n.id), ...archived.map((n) => n.id)];
+  if (all.includes(seedId)) return seedId;
+  const viaPrefix = all.filter((id) => id.startsWith(seedId));
+  if (viaPrefix.length === 1) return viaPrefix[0] ?? seedId;
+  const viaArchivedPrefix = archived.map((n) => n.id).filter((id) => id.startsWith(seedId));
+  if (viaArchivedPrefix.length === 1) return viaArchivedPrefix[0] ?? seedId;
+  return seedId;
+}

package/src/report/show.ts

@@ -41,8 +41,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 +68,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 +89,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`',
     },
   ];