@fitlab-ai/agent-infra 0.9.10 → 0.9.12

package/lib/task/commands/decisions.ts

@@ -3,20 +3,19 @@ import path from 'node:path';
 import { formatTable } from '../../table.ts';
 import { parseTaskScope } from '../command-options.ts';
 import { resolveTaskContext } from '../resolve-ref.ts';
-import { isReviewStage, parseLedger, type LedgerRow, type ReviewStage } from '../ledger.ts';
+import { isReviewStage, parseLedgerDocument, type LedgerRow, type ReviewStage } from '../ledger.ts';
 import { listDecisionItems, selectDecisionItem } from '../decision-items.ts';
-import { extractSubSection } from '../sections.ts';
+import { normalizeDecisionDetailForDisplay, parseDecisionEvidence, resolveDecisionDetail } from '../decision-details.ts';
 
 const USAGE = `Usage: ai task decisions [--task <ref> | -t <ref>] [--item <selector> | -i <selector>] [options]
-       ai task decisions <ref> [selector] [options]
 
 Shows what still needs a maintainer's decision. Without a selector, it lists
 the choices. With a selector, it shows the explanation and how to respond.
 Read-only.
 
-  Omit <ref>     Resolve the unique active task for the current branch.
-  <ref>          Legacy positional task ref.
-  [selector]     Ordinal (1-based) or ledger id (e.g. 'PL-3') to show one item's detail.
+  Omit the scope  Resolve the unique active task for the current branch.
+  --task/-t <ref> Select a task explicitly.
+  --item/-i <s>   Ordinal (1-based) or ledger id (e.g. 'PL-3') to show one item's detail.
 
 Options:
   -i, --item <s>    Select an item when task scope is implicit or flag-based.
@@ -56,9 +55,8 @@ function parseArgs(args: string[]): ParsedArgs | null {
       if (out.item !== undefined) { fail("duplicate option '--item'"); return null; }
       out.item = v; i += 1;
     } else if (a.startsWith('--item=')) {
-      if (out.item !== undefined) { fail("duplicate option '--item'"); return null; }
-      out.item = a.slice('--item='.length);
-      if (out.item === '') { fail('--item requires a value'); return null; }
+      fail("--item=... is not supported; use --item <selector> or -i <selector>");
+      return null;
     } else if (a === '--stage') {
       const v = args[i + 1];
       if (v === undefined) {
@@ -89,47 +87,30 @@ function parseArgs(args: string[]): ParsedArgs | null {
   return out;
 }
 
-// Parse `<file>.md#anchor` evidence into its filename, when present.
-function evidenceFile(evidence: string): string | null {
-  const m = /([\w.-]+\.md)#/.exec(evidence);
-  return m ? m[1]! : null;
-}
-
-function roundOf(file: string): number {
-  const m = /-r(\d+)\.md$/.exec(file);
-  return m ? Number.parseInt(m[1]!, 10) : 1;
-}
+// Locate the canonical detail block named by the row's current evidence. Historical
+// artifacts are intentionally not searched: an evidence reference is a precise
+// provenance pointer, not a best-effort hint.
+type DetailLookup =
+  | { status: 'found'; content: string }
+  | { status: 'missing'; reason: string }
+  | { status: 'ambiguous'; reason: string }
+  | { status: 'invalid'; reason: string };
 
-// Locate the `### {ledger-id}` detail block for a row. Prefer the artifact named by the
-// row's evidence anchor; otherwise scan analysis/plan/code artifacts and return
-// the block from the highest-round file that contains it. Returns '' when none
-// is found (caller degrades gracefully — plan B3).
-function findDetailBlock(row: LedgerRow, taskDir: string): string {
-  const hinted = evidenceFile(row.evidence);
-  if (hinted) {
-    const p = path.join(taskDir, hinted);
-    if (fs.existsSync(p)) {
-      const block = extractSubSection(fs.readFileSync(p, 'utf8'), row.id);
-      if (block) return block;
-    }
-  }
-  let best = '';
-  let bestRound = -1;
-  let entries: string[];
+function findDetailBlock(row: LedgerRow, taskDir: string): DetailLookup {
+  const evidence = parseDecisionEvidence(row.evidence);
+  if (!evidence.ok) return { status: 'invalid', reason: `invalid evidence '${row.evidence}'` };
+  const artifactPath = path.join(taskDir, evidence.artifact);
+  if (!fs.existsSync(artifactPath)) return { status: 'missing', reason: `artifact '${evidence.artifact}' is missing` };
+  let artifactContent: string;
   try {
-    entries = fs.readdirSync(taskDir);
+    artifactContent = fs.readFileSync(artifactPath, 'utf8');
   } catch {
-    return '';
-  }
-  for (const file of entries) {
-    if (!/^(analysis|plan|code)(-r\d+)?\.md$/.test(file)) continue;
-    const block = extractSubSection(fs.readFileSync(path.join(taskDir, file), 'utf8'), row.id);
-    if (block && roundOf(file) > bestRound) {
-      best = block;
-      bestRound = roundOf(file);
-    }
+    return { status: 'missing', reason: `artifact '${evidence.artifact}' cannot be read` };
   }
-  return best;
+  const resolved = resolveDecisionDetail(artifactContent, row.id, evidence.anchor);
+  if (resolved.status === 'found') return { status: 'found', content: normalizeDecisionDetailForDisplay(resolved.block) };
+  if (resolved.status === 'ambiguous') return { status: 'ambiguous', reason: resolved.reason };
+  return { status: 'missing', reason: resolved.reason };
 }
 
 // Pull the `## 人工裁决` record lines that mention this ledger id, so a decided item
@@ -149,9 +130,9 @@ function findDecisionRecord(id: string, content: string): string[] {
 }
 
 function titleOf(row: LedgerRow, taskDir: string): string {
-  const block = findDetailBlock(row, taskDir);
-  if (block) {
-    const title = block
+  const detail = findDetailBlock(row, taskDir);
+  if (detail.status === 'found') {
+    const title = detail.content
       .split('\n')[0]!
       .replace(/^###\s+/, '')
       .replace(/\s*\[needs-human-decision\]\s*$/, '')
@@ -165,7 +146,7 @@ function trackingOf(row: LedgerRow): string {
   return `stage=${row.stage} · severity=${row.severity} · status=${row.status} · evidence=${row.evidence}`;
 }
 
-function renderList(rows: LedgerRow[], format: string, taskDir: string): void {
+function renderList(rows: LedgerRow[], format: string, taskDir: string, taskId: string): void {
   if (rows.length === 0) {
     process.stdout.write('No pending decisions.\n');
     return;
@@ -184,10 +165,10 @@ function renderList(rows: LedgerRow[], format: string, taskDir: string): void {
       `| ${sep.join(' | ')} |`,
       ...data.map((row) => `| ${row.join(' | ')} |`)
     ];
-    process.stdout.write(`${md.join('\n')}\n\nView one item: ai task decisions <task-ref> <ordinal|ledger-id>\n`);
+    process.stdout.write(`${md.join('\n')}\n\nView one item: ai task decisions --task ${taskId} --item <ordinal|ledger-id>\n`);
     return;
   }
-  process.stdout.write(`${formatTable(headers, data).join('\n')}\n\nView one item: ai task decisions <task-ref> <ordinal|ledger-id>\n`);
+  process.stdout.write(`${formatTable(headers, data).join('\n')}\n\nView one item: ai task decisions --task ${taskId} --item <ordinal|ledger-id>\n`);
 }
 
 function renderTracking(row: LedgerRow, format: string): string[] {
@@ -214,7 +195,8 @@ function renderDetail(
   selector: string,
   format: string,
   taskDir: string,
-  content: string
+  content: string,
+  taskId: string
 ): void {
   const selected = selectDecisionItem(rows, selector);
   if (!selected.ok) {
@@ -222,21 +204,23 @@ function renderDetail(
     return;
   }
   const r = selected.row;
-  const block = findDetailBlock(r, taskDir);
-  const title = titleOf(r, taskDir);
+  const detail = findDetailBlock(r, taskDir);
+  if (detail.status === 'invalid' || detail.status === 'ambiguous') {
+    fail(`cannot resolve ${r.id}: ${detail.reason}`);
+    return;
+  }
+  const block = detail.status === 'found' ? detail.content : '';
+  const title = block
+    ? block.split('\n')[0]!.replace(/^###\s+/, '').replace(/\s*\[needs-human-decision\]\s*$/, '').trim()
+      .replace(new RegExp(`^${r.id}\\s*[:：]\\s*`, 'i'), '').trim()
+    : '(explanation unavailable)';
   const lines: string[] = [];
   const decided = r.status === 'human-decided';
   if (format === 'markdown') {
     lines.push(`## ${decided ? 'Decision already recorded' : 'Decision needed'}: ${title}`, '');
-    if (!decided) {
-      lines.push('**How to record your choice**', `\`ai decide <task-ref> ${r.id} <your choice and rationale>\``, '');
-    }
     lines.push('**Original context**', '');
   } else {
     lines.push(`${decided ? 'Decision already recorded' : 'Decision needed'}: ${title}`, '');
-    if (!decided) {
-      lines.push('How to record your choice:', `ai decide <task-ref> ${r.id} <your choice and rationale>`, '');
-    }
     lines.push('Original context:');
   }
   if (block) {
@@ -252,6 +236,14 @@ function renderDetail(
     lines.push('', format === 'markdown' ? '**Recorded choice**' : 'Recorded choice:');
     lines.push(...(record.length ? record : ['No separate ruling record was found.']));
   }
+  if (!decided) {
+    lines.push('');
+    if (format === 'markdown') {
+      lines.push('**How to record your choice**', `\`ai decide --task ${taskId} --item ${r.id} <your choice and rationale>\``);
+    } else {
+      lines.push('How to record your choice:', `ai decide --task ${taskId} --item ${r.id} <your choice and rationale>`);
+    }
+  }
   lines.push('', ...renderTracking(r, format));
   process.stdout.write(`${lines.join('\n')}\n`);
 }
@@ -274,16 +266,11 @@ function decisions(args: string[] = []): void {
     return;
   }
 
-  let taskRef = scope.taskRef;
-  let selector = parsed.item;
-  if (parsed.item !== undefined) {
-    if (parsed.positionals.length > 0) { fail('positional task ref/selector cannot be combined with --item'); return; }
-  } else if (scope.explicit) {
-    if (parsed.positionals.length > 0) { fail('positional task ref/selector cannot be combined with --task'); return; }
-  } else {
-    if (parsed.positionals.length > 2) { fail('too many positional arguments'); return; }
-    taskRef = parsed.positionals[0];
-    selector = parsed.positionals[1];
+  const taskRef = scope.taskRef;
+  const selector = parsed.item;
+  if (parsed.positionals.length > 0) {
+    fail('positional task ref/selector is not supported; use --task <ref> or -t <ref>, and --item <selector> or -i <selector>');
+    return;
   }
   const resolved = resolveTaskContext(taskRef);
   if (!resolved.ok) {
@@ -291,16 +278,34 @@ function decisions(args: string[] = []): void {
     return;
   }
 
-  const content = fs.readFileSync(resolved.taskMdPath, 'utf8');
-  const rows = listDecisionItems(parseLedger(content), {
+  let content: string;
+  let ledger;
+  try {
+    content = fs.readFileSync(resolved.taskMdPath, 'utf8');
+    ledger = parseLedgerDocument(content);
+  } catch (error) {
+    fail(`ledger unavailable [LEDGER_DOCUMENT_INVALID]: ${error instanceof Error ? error.message : String(error)}`);
+    return;
+  }
+  if (!ledger.present) {
+    fail('ledger unavailable [LEDGER_SECTION_MISSING]: review disagreement ledger section is missing');
+    return;
+  }
+  const rows = listDecisionItems(ledger.rows as LedgerRow[], {
     includeDecided: parsed.all,
     stage: parsed.stage as ReviewStage | undefined
   });
 
   if (selector === undefined) {
-    renderList(rows, parsed.format, resolved.taskDir);
+    renderList(rows, parsed.format, resolved.taskDir, resolved.taskId);
   } else {
-    renderDetail(rows, selector, parsed.format, resolved.taskDir, content);
+    const selectionRows = /^[A-Za-z]+-\d+$/.test(selector)
+      ? listDecisionItems(ledger.rows as LedgerRow[], {
+        includeDecided: true,
+        stage: parsed.stage as ReviewStage | undefined
+      })
+      : rows;
+    renderDetail(selectionRows, selector, parsed.format, resolved.taskDir, content, resolved.taskId);
   }
 }
 

package/lib/task/commands/files.ts

@@ -3,11 +3,11 @@ import { parseTaskScope } from '../command-options.ts';
 import { resolveTaskContext } from '../resolve-ref.ts';
 import { enumerateArtifacts } from '../artifacts.ts';
 
-const USAGE = `Usage: ai task files [<N | TASK-id> | --task <ref> | -t <ref>]
+const USAGE = `Usage: ai task files [--task <ref> | -t <ref>]
 
 Lists the artifacts in a task directory with stable numbers.
-  Omit <ref>   Resolve the unique active task for the current branch.
-  <ref>   Bare numeric short id, or a full TASK-YYYYMMDD-HHMMSS id.
+  Omit the scope   Resolve the unique active task for the current branch.
+  --task/-t <ref> Bare numeric short id, or a full TASK-YYYYMMDD-HHMMSS id.
 
 Columns: # (artifact number, usable with 'ai task cat') / NAME / SIZE (bytes) / MTIME
 `;
@@ -35,10 +35,10 @@ function files(args: string[] = []): void {
   try { scope = parseTaskScope(args); } catch (error) {
     process.stderr.write(`ai task files: ${error instanceof Error ? error.message : String(error)}\n`); process.exitCode = 1; return;
   }
-  if (scope.positionals.length > 1 || (scope.explicit && scope.positionals.length > 0)) {
-    process.stderr.write('ai task files: task ref must be provided once\n'); process.exitCode = 1; return;
+  if (scope.positionals.length > 0) {
+    process.stderr.write('ai task files: positional task ref is not supported; use --task <ref> or -t <ref>\n'); process.exitCode = 1; return;
   }
-  const resolved = resolveTaskContext(scope.taskRef ?? scope.positionals[0]);
+  const resolved = resolveTaskContext(scope.taskRef);
   if (!resolved.ok) {
     process.stderr.write(`ai task files: ${resolved.message}\n`);
     process.exitCode = 1;

package/lib/task/commands/grep.ts

@@ -1,25 +1,20 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { resolveTaskContext, resolveTaskRef, detectRepoRoot, enumerateTaskDirs } from '../resolve-ref.ts';
+import { resolveTaskContext, resolveTaskRef } from '../resolve-ref.ts';
 import { enumerateArtifacts, resolveArtifact } from '../artifacts.ts';
 import { loadShortIdByTaskId } from '../short-id.ts';
 
-const USAGE = `Usage: ai task grep <pattern> [ref] [artifact | N]
-       ai task grep <pattern> (--current | --task <ref> | -t <ref>) [artifact | N]
+const USAGE = `Usage: ai task grep [--current | --task <ref> | -t <ref>] <pattern> [artifact | N]
 
 Literal (non-regex) line search across task artifacts.
   <pattern>          Literal substring to match (NOT a regex). Case-sensitive by default.
-  [ref]              Bare numeric short id, or a full TASK-YYYYMMDD-HHMMSS id.
-                     Omit to scan every task under active / blocked / completed
-                     (archive is skipped). With a ref, narrows to that single task
-                     (a TASK-id ref can also resolve an archived task).
-  [artifact | N]     Only valid with <ref>. Artifact filename (with or without '.md')
+  --current          Limit search to the unique active task for the current branch.
+  -t, --task <ref>   Limit search to an explicit task (bare short id or TASK-id).
+  [artifact | N]     Artifact filename (with or without '.md')
                      or the number from 'ai task files'. Narrows to a single artifact.
 
 Options:
   -i, --ignore-case  Case-insensitive matching.
-  --current          Limit search to the current task context.
-  -t, --task <ref>   Limit search to an explicit task.
   --                 Treat the rest as positional (use for patterns starting with '-').
 
 Output: '{taskId} [#short] {fileStem}:{line}: {matched-line}' (short id only for active tasks).
@@ -85,9 +80,7 @@ function grep(args: string[] = []): void {
       continue;
     }
     if (!optsEnded && a.startsWith('--task=')) {
-      if (taskRef !== undefined) { process.stderr.write("ai task grep: duplicate option '--task'\n"); process.exitCode = 1; return; }
-      taskRef = a.slice('--task='.length);
-      if (taskRef === '') { process.stderr.write('ai task grep: --task requires a value\n'); process.exitCode = 1; return; }
+      process.stderr.write('ai task grep: --task=... is not supported; use --task <ref> or -t <ref>\n'); process.exitCode = 1; return;
       continue;
     }
     if (!optsEnded && a.startsWith('-') && a !== '-') {
@@ -106,61 +99,40 @@ function grep(args: string[] = []): void {
   if (current && taskRef !== undefined) {
     process.stderr.write('ai task grep: --current and --task are mutually exclusive\n'); process.exitCode = 1; return;
   }
-  if (positional.length > 3 || ((current || taskRef !== undefined) && positional.length > 2)) {
+  if (positional.length > 2) {
     process.stderr.write('ai task grep: too many arguments\n');
     process.exitCode = 1;
     return;
   }
 
-  let [pattern, ref, artifactOrN] = positional;
-  if (current || taskRef !== undefined) {
-    artifactOrN = ref;
-    ref = taskRef;
-  }
+  const [pattern, artifactOrN] = positional;
   const matcher = makeMatcher(pattern!, ignoreCase);
   const chunks: string[] = [];
   const emit = (line: string) => chunks.push(line);
   let total = 0;
 
-  if (ref === undefined && !current) {
-    // No ref: full scan across active / blocked / completed (no archive).
-    let repoRoot: string;
+  const resolved = current || taskRef === undefined
+    ? resolveTaskContext()
+    : resolveTaskRef(taskRef);
+  if (!resolved.ok) {
+    process.stderr.write(`ai task grep: ${resolved.message}\n`);
+    process.exitCode = 1;
+    return;
+  }
+  const shortToken = loadShortIdByTaskId(resolved.repoRoot).get(resolved.taskId);
+  if (artifactOrN !== undefined) {
+    let artifactPath: string;
     try {
-      repoRoot = detectRepoRoot();
+      artifactPath = resolveArtifact(resolved.taskDir, artifactOrN);
     } catch (e) {
       process.stderr.write(`ai task grep: ${(e as Error).message}\n`);
       process.exitCode = 1;
       return;
     }
-    const shortMap = loadShortIdByTaskId(repoRoot);
-    for (const { taskId, taskDir } of enumerateTaskDirs(repoRoot)) {
-      const shortToken = shortMap.get(taskId);
-      for (const a of enumerateArtifacts(taskDir)) {
-        total += scanArtifact(taskId, shortToken, a.path, matcher, emit);
-      }
-    }
+    total += scanArtifact(resolved.taskId, shortToken, artifactPath, matcher, emit);
   } else {
-    const resolved = current ? resolveTaskContext() : resolveTaskRef(ref!);
-    if (!resolved.ok) {
-      process.stderr.write(`ai task grep: ${resolved.message}\n`);
-      process.exitCode = 1;
-      return;
-    }
-    const shortToken = loadShortIdByTaskId(resolved.repoRoot).get(resolved.taskId);
-    if (artifactOrN !== undefined) {
-      let artifactPath: string;
-      try {
-        artifactPath = resolveArtifact(resolved.taskDir, artifactOrN);
-      } catch (e) {
-        process.stderr.write(`ai task grep: ${(e as Error).message}\n`);
-        process.exitCode = 1;
-        return;
-      }
-      total += scanArtifact(resolved.taskId, shortToken, artifactPath, matcher, emit);
-    } else {
-      for (const a of enumerateArtifacts(resolved.taskDir)) {
-        total += scanArtifact(resolved.taskId, shortToken, a.path, matcher, emit);
-      }
+    for (const a of enumerateArtifacts(resolved.taskDir)) {
+      total += scanArtifact(resolved.taskId, shortToken, a.path, matcher, emit);
     }
   }
 

package/lib/task/commands/issue-body.ts

@@ -6,11 +6,11 @@ import { extractSection, findSectionHeading } from '../sections.ts';
 import { renderTemplateBody, PLACEHOLDER } from '../issue-form.ts';
 import type { TaskFields } from '../issue-form.ts';
 
-const USAGE = `Usage: ai task issue-body [<ref> | --task <ref> | -t <ref>] [--template <path>]
+const USAGE = `Usage: ai task issue-body [--task <ref> | -t <ref>] [--template <path>]
 
 Print a deterministic Issue body extracted from a task's task.md.
-  Omit <ref>           Resolve the unique active task for the current branch.
-  <ref>               Bare numeric short id, or a full TASK-YYYYMMDD-HHMMSS id.
+  Omit the scope        Resolve the unique active task for the current branch.
+  --task/-t <ref>       Bare numeric short id, or a full TASK-YYYYMMDD-HHMMSS id.
   --template <path>   Render the final body for the given GitHub Issue Form (scenario A);
                       without it, print the default '任务输入 + 描述 + 需求' body (scenario B).
 
@@ -71,10 +71,10 @@ function issueBody(args: string[] = []): void {
   try { scope = parseTaskScope(scopeArgs); } catch (error) {
     process.stderr.write(`ai task issue-body: ${error instanceof Error ? error.message : String(error)}\n`); process.exitCode = 1; return;
   }
-  if (scope.positionals.length > 1 || (scope.explicit && scope.positionals.length > 0)) {
-    process.stderr.write('ai task issue-body: task ref must be provided once\n'); process.exitCode = 1; return;
+  if (scope.positionals.length > 0) {
+    process.stderr.write('ai task issue-body: positional task ref is not supported; use --task <ref> or -t <ref>\n'); process.exitCode = 1; return;
   }
-  const resolved = resolveTaskContext(scope.taskRef ?? scope.positionals[0]);
+  const resolved = resolveTaskContext(scope.taskRef);
   if (!resolved.ok) {
     process.stderr.write(`ai task issue-body: ${resolved.message}\n`);
     process.exitCode = 1;

package/lib/task/commands/log.ts

@@ -3,16 +3,16 @@ import { classifyAgent } from '../../agent-clients/tokens.ts';
 import { formatTable } from '../../table.ts';
 import { parseTaskScope } from '../command-options.ts';
 import { resolveTaskContext } from '../resolve-ref.ts';
-import { isReviewStage, parseLedger, type LedgerRow, type ReviewStage } from '../ledger.ts';
+import { LEDGER_SECTION_MISSING_CODE, LEDGER_SECTION_MISSING_MESSAGE, isReviewStage, parseLedgerDocument, type LedgerRow, type ReviewStage } from '../ledger.ts';
 import { parseActivityLog, pairEntries } from '../activity-log.ts';
 
-const USAGE = `Usage: ai task log [<N | TASK-id> | --task <ref> | -t <ref>]
+const USAGE = `Usage: ai task log [--task <ref> | -t <ref>]
 
 Renders a task's activity log as a per-step status table. A step's start and
 completion are paired onto one row: STARTED holds the start time, DONE the
 completion time (or '(in progress)' while still running).
-  Omit <ref>   Resolve the unique active task for the current branch.
-  <ref>   Bare numeric short id, or a full TASK-YYYYMMDD-HHMMSS id.
+  Omit the scope   Resolve the unique active task for the current branch.
+  --task/-t <ref> Bare numeric short id, or a full TASK-YYYYMMDD-HHMMSS id.
 
 Columns: # (row) / STEP / AGENT / STARTED / DONE / NOTE
   A human-executed step shows AGENT as 'human' and, when it has no start marker,
@@ -92,8 +92,8 @@ function isHumanCountField(field: string): boolean {
 }
 
 // A step is human-executed when its agent token is not a known AI token.
-// Known long names (claude-code -> claude, gemini-cli -> gemini) classify as
-// AI; empty or unknown tokens classify as non-AI (human).
+// Known long names classify as AI; empty or unknown tokens classify as non-AI
+// (human).
 export function isHumanAgent(agent: string): boolean {
   return classifyAgent(agent).status !== 'ai';
 }
@@ -122,10 +122,10 @@ function log(args: string[] = []): void {
   try { scope = parseTaskScope(args); } catch (error) {
     process.stderr.write(`ai task log: ${error instanceof Error ? error.message : String(error)}\n`); process.exitCode = 1; return;
   }
-  if (scope.positionals.length > 1 || (scope.explicit && scope.positionals.length > 0)) {
-    process.stderr.write('ai task log: task ref must be provided once\n'); process.exitCode = 1; return;
+  if (scope.positionals.length > 0) {
+    process.stderr.write('ai task log: positional task ref is not supported; use --task <ref> or -t <ref>\n'); process.exitCode = 1; return;
   }
-  const resolved = resolveTaskContext(scope.taskRef ?? scope.positionals[0]);
+  const resolved = resolveTaskContext(scope.taskRef);
   if (!resolved.ok) {
     process.stderr.write(`ai task log: ${resolved.message}\n`);
     process.exitCode = 1;
@@ -146,7 +146,15 @@ function log(args: string[] = []): void {
     return;
   }
   const steps = pairEntries(entries);
-  const humanDecisionCounts = countHumanDecisionsByStage(parseLedger(content));
+  let humanDecisionCounts = new Map<ReviewStage, number>();
+  let ledgerDiagnostic: string | null = null;
+  try {
+    const ledger = parseLedgerDocument(content);
+    if (ledger.present) humanDecisionCounts = countHumanDecisionsByStage(ledger.rows as LedgerRow[]);
+    else ledgerDiagnostic = `${LEDGER_SECTION_MISSING_CODE}: ${LEDGER_SECTION_MISSING_MESSAGE}`;
+  } catch (error) {
+    ledgerDiagnostic = `LEDGER_DOCUMENT_INVALID: ${error instanceof Error ? error.message : String(error)}`;
+  }
   const rows = steps.map((s, idx) => {
     const stage = reviewStageForStep(s.step);
     const note = stage
@@ -161,6 +169,10 @@ function log(args: string[] = []): void {
   for (const line of formatTable(TABLE_HEADERS, rows, { zebra: Boolean(process.stdout.isTTY) })) {
     process.stdout.write(`${line}\n`);
   }
+  if (ledgerDiagnostic) {
+    process.stdout.write(`Ledger: unavailable [${ledgerDiagnostic}]\n`);
+    process.exitCode = 1;
+  }
   process.stdout.write(`Total: ${steps.length} steps\n`);
 }
 

package/lib/task/commands/show.ts

@@ -2,12 +2,11 @@ import fs from 'node:fs';
 import { parseTaskScope } from '../command-options.ts';
 import { resolveTaskContext } from '../resolve-ref.ts';
 
-const USAGE = `Usage: ai task show [<N | TASK-id> | --task <ref> | -t <ref>]
+const USAGE = `Usage: ai task show [--task <ref> | -t <ref>]
 
 Prints the task.md content for the matching task.
   Omit the ref       Resolve the unique active task for the current branch.
-  N (bare numeric)   Recommended; resolves the active short id via the registry.
-  TASK-YYYYMMDD-HHMMSS  Locates a task in active / blocked / completed / archive.
+  --task/-t <ref>    Bare numeric short id, or a full TASK-YYYYMMDD-HHMMSS id.
 `;
 
 function show(args: string[] = []): void {
@@ -20,10 +19,10 @@ function show(args: string[] = []): void {
     process.stderr.write(`ai task show: ${error instanceof Error ? error.message : String(error)}\n`);
     process.exitCode = 1; return;
   }
-  if (scope.positionals.length > 1 || (scope.explicit && scope.positionals.length > 0)) {
-    process.stderr.write('ai task show: task ref must be provided once\n'); process.exitCode = 1; return;
+  if (scope.positionals.length > 0) {
+    process.stderr.write('ai task show: positional task ref is not supported; use --task <ref> or -t <ref>\n'); process.exitCode = 1; return;
   }
-  const resolved = resolveTaskContext(scope.taskRef ?? scope.positionals[0]);
+  const resolved = resolveTaskContext(scope.taskRef);
   if (!resolved.ok) {
     process.stderr.write(`ai task show: ${resolved.message}\n`);
     process.exitCode = 1;

package/lib/task/commands/status.ts

@@ -8,17 +8,17 @@ import { enumerateArtifacts, type Artifact } from '../artifacts.ts';
 import { parseTaskFrontmatter, extractTitle, type Frontmatter } from '../frontmatter.ts';
 import { loadShortIdByTaskId } from '../short-id.ts';
 import { getOpenWorkflowWarnings, formatWorkflowWarningSummary, type WorkflowWarning } from '../workflow-warnings.ts';
-import { parseActivityLog, pairEntries } from '../activity-log.ts';
+import { parseActivityLog, pairEntries, startedBackedRows } from '../activity-log.ts';
 import { readRun, type OrchestrationRun } from '../orchestration.ts';
 import type { DelegationReceipt } from '../delegation-receipts.ts';
 import { statusCard, type DisplayMessage } from '../../server/display.ts';
 
-const USAGE = `Usage: ai task status [<N | TASK-id> | --task <ref> | -t <ref>]
+const USAGE = `Usage: ai task status [--task <ref> | -t <ref>]
 
 Prints an aggregated "health check" view for a task: header, metadata,
 artifacts, workflow/runtime execution state, and git branch state.
-  Omit <ref>   Resolve the unique active task for the current branch.
-  <ref>   Bare numeric short id, or a full TASK-YYYYMMDD-HHMMSS id.
+  Omit the scope   Resolve the unique active task for the current branch.
+  --task/-t <ref> Bare numeric short id, or a full TASK-YYYYMMDD-HHMMSS id.
 
 Git rows are best-effort: a failed git call degrades that row to '-' without
 failing the command.
@@ -186,7 +186,7 @@ function collectWorkflow(content: string, now: Date = new Date()): WorkflowInfo
     return { state: 'unknown', step: DASH, agent: DASH, startedAt: DASH, doneAt: DASH, stale: DASH };
   }
 
-  const rows = pairEntries(parsed.entries);
+  const rows = startedBackedRows(pairEntries(parsed.entries));
   const latest = rows.at(-1);
   if (!latest) {
     return { state: 'unknown', step: DASH, agent: DASH, startedAt: DASH, doneAt: DASH, stale: DASH };
@@ -577,10 +577,10 @@ function status(args: string[] = []): void {
   let model: StatusModel;
   try {
     const scope = parseTaskScope(args);
-    if (scope.positionals.length > 1 || (scope.explicit && scope.positionals.length > 0)) {
-      throw new Error('task ref must be provided once');
+    if (scope.positionals.length > 0) {
+      throw new Error('positional task ref is not supported; use --task <ref> or -t <ref>');
     }
-    const resolved = resolveTaskContext(scope.taskRef ?? scope.positionals[0]);
+    const resolved = resolveTaskContext(scope.taskRef);
     if (!resolved.ok) throw new Error(resolved.message);
     model = buildFromResolved({
       taskId: resolved.taskId, taskDir: resolved.taskDir, taskMdPath: resolved.taskMdPath,