@fitlab-ai/agent-infra 0.8.5 → 0.9.0

package/lib/task/commands/cat.ts

@@ -1,11 +1,15 @@
 import fs from 'node:fs';
-import { resolveTaskRef } from '../resolve-ref.ts';
+import { parseTaskScope } from '../command-options.ts';
+import { resolveTaskContext } from '../resolve-ref.ts';
 import { resolveArtifact } from '../artifacts.ts';
 
-const USAGE = `Usage: ai task cat <N | #N | TASK-id> <artifact | N>
+const USAGE = `Usage: ai task cat <artifact | N>
+       ai task cat (--task <ref> | -t <ref>) <artifact | N>
+       ai task cat <ref> <artifact | N>
 
 Prints a task artifact's raw content to stdout.
-  <ref>            Bare numeric / '#N' short id, or a full TASK-YYYYMMDD-HHMMSS id.
+  One positional    Uses current task context and treats the operand as the artifact.
+  <ref>            Bare numeric short id, or a full TASK-YYYYMMDD-HHMMSS id.
   <artifact | N>   Artifact filename (with or without '.md'), or the number from 'ai task files'.
 `;
 
@@ -14,12 +18,21 @@ function cat(args: string[] = []): void {
     process.stdout.write(USAGE);
     return;
   }
-  if (args.length < 2) {
-    process.stdout.write(USAGE);
-    process.exitCode = 1;
-    return;
+  let scope;
+  try { scope = parseTaskScope(args); } catch (error) {
+    process.stderr.write(`ai task cat: ${error instanceof Error ? error.message : String(error)}\n`); process.exitCode = 1; return;
   }
-  const resolved = resolveTaskRef(args[0]!);
+  let taskRef: string | undefined;
+  let artifact: string | undefined;
+  if (scope.explicit) {
+    if (scope.positionals.length !== 1) { process.stdout.write(USAGE); process.exitCode = 1; return; }
+    taskRef = scope.taskRef; artifact = scope.positionals[0];
+  } else if (scope.positionals.length === 1) {
+    artifact = scope.positionals[0];
+  } else if (scope.positionals.length === 2) {
+    [taskRef, artifact] = scope.positionals;
+  } else { process.stdout.write(USAGE); process.exitCode = 1; return; }
+  const resolved = resolveTaskContext(taskRef);
   if (!resolved.ok) {
     process.stderr.write(`ai task cat: ${resolved.message}\n`);
     process.exitCode = 1;
@@ -27,7 +40,7 @@ function cat(args: string[] = []): void {
   }
   let artifactPath: string;
   try {
-    artifactPath = resolveArtifact(resolved.taskDir, args[1]!);
+    artifactPath = resolveArtifact(resolved.taskDir, artifact!);
   } catch (e) {
     process.stderr.write(`ai task cat: ${(e as Error).message}\n`);
     process.exitCode = 1;

package/lib/task/commands/decisions.ts

@@ -1,19 +1,24 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { formatTable } from '../../table.ts';
-import { resolveTaskRef } from '../resolve-ref.ts';
-import { parseLedger, HUMAN_DECISION_STATUSES, type LedgerRow } from '../ledger.ts';
+import { parseTaskScope } from '../command-options.ts';
+import { resolveTaskContext } from '../resolve-ref.ts';
+import { isReviewStage, parseLedger, type LedgerRow, type ReviewStage } from '../ledger.ts';
+import { listDecisionItems, selectDecisionItem } from '../decision-items.ts';
 import { extractSubSection } from '../sections.ts';
 
-const USAGE = `Usage: ai task decisions <N | #N | TASK-id> [selector] [options]
+const USAGE = `Usage: ai task decisions [--task <ref> | -t <ref>] [--item <selector> | -i <selector>] [options]
+       ai task decisions <ref> [selector] [options]
 
-Lists the human-decision (HD-) items recorded in a task's review disagreement
+Lists decision items recorded in a task's review disagreement
 ledger, or prints the full detail block for a single item. Read-only.
 
-  <ref>          Bare numeric / '#N' short id, or a full TASK-YYYYMMDD-HHMMSS id.
-  [selector]     Ordinal (1-based) or HD id (e.g. 'HD-3') to show one item's detail.
+  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.
 
 Options:
+  -i, --item <s>    Select an item when task scope is implicit or flag-based.
   --all              Include already-decided (human-decided) items, not just pending.
   --stage <s>        Filter to one stage: analysis | plan | code.
   --format <fmt>     Output format: text (default) | markdown.
@@ -22,9 +27,7 @@ Options:
 Aliased as 'ai task d'.
 `;
 
-const STAGES = new Set(['analysis', 'plan', 'code']);
 const FORMATS = new Set(['text', 'markdown']);
-const HD_ID_RE = /^HD-\d+$/;
 
 function fail(message: string): void {
   process.stderr.write(`ai task decisions: ${message}\n`);
@@ -33,6 +36,7 @@ function fail(message: string): void {
 
 type ParsedArgs = {
   positionals: string[];
+  item?: string;
   all: boolean;
   stage?: string;
   format: string;
@@ -45,6 +49,15 @@ function parseArgs(args: string[]): ParsedArgs | null {
     const a = args[i]!;
     if (a === '--all') {
       out.all = true;
+    } else if (a === '--item' || a === '-i') {
+      const v = args[i + 1];
+      if (v === undefined) { fail(`${a} requires a value`); return 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; }
     } else if (a === '--stage') {
       const v = args[i + 1];
       if (v === undefined) {
@@ -86,7 +99,7 @@ function roundOf(file: string): number {
   return m ? Number.parseInt(m[1]!, 10) : 1;
 }
 
-// Locate the `### HD-N` detail block for a row. Prefer the artifact named by the
+// 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).
@@ -118,12 +131,12 @@ function findDetailBlock(row: LedgerRow, taskDir: string): string {
   return best;
 }
 
-// Pull the `## 人工裁决` record lines that mention this HD id, so a decided item
+// Pull the `## 人工裁决` record lines that mention this ledger id, so a decided item
 // shows the human's recorded ruling alongside its detail block.
 function findDecisionRecord(id: string, content: string): string[] {
   const lines = content.split('\n');
   let i = 0;
-  while (i < lines.length && !/^##\s+(人工裁决|Human Decisions?)\s*$/.test(lines[i]!)) i += 1;
+  while (i < lines.length && !/^##\s+(人工裁决|Human Rulings|Human Decisions?)\s*$/.test(lines[i]!)) i += 1;
   if (i >= lines.length) return [];
   const idRe = new RegExp(`(^|[^\\w-])${id}(?![\\w-])`);
   const out: string[] = [];
@@ -181,29 +194,12 @@ function renderDetail(
   taskDir: string,
   content: string
 ): void {
-  let row: LedgerRow | undefined;
-  if (/^\d+$/.test(selector)) {
-    const idx = Number.parseInt(selector, 10) - 1;
-    if (idx < 0 || idx >= rows.length) {
-      fail(`ordinal '${selector}' out of range (1..${rows.length})`);
-      return;
-    }
-    row = rows[idx];
-  } else {
-    const want = selector.toUpperCase();
-    const matches = rows.filter((r) => r.id.toUpperCase() === want);
-    if (matches.length === 0) {
-      fail(`no decision item matches '${selector}'`);
-      return;
-    }
-    if (matches.length > 1) {
-      fail(`duplicate id '${selector}' in ledger; select by ordinal instead`);
-      return;
-    }
-    row = matches[0];
+  const selected = selectDecisionItem(rows, selector);
+  if (!selected.ok) {
+    fail(selected.message);
+    return;
   }
-
-  const r = row!;
+  const r = selected.row;
   const block = findDetailBlock(r, taskDir);
   const lines: string[] = [];
   if (format === 'markdown') {
@@ -232,14 +228,11 @@ function decisions(args: string[] = []): void {
     process.stdout.write(USAGE);
     return;
   }
-  const parsed = parseArgs(args);
+  let scope;
+  try { scope = parseTaskScope(args); } catch (error) { fail(error instanceof Error ? error.message : String(error)); return; }
+  const parsed = parseArgs(scope.positionals);
   if (!parsed) return;
-  if (parsed.positionals.length === 0) {
-    process.stdout.write(USAGE);
-    process.exitCode = 1;
-    return;
-  }
-  if (parsed.stage !== undefined && !STAGES.has(parsed.stage)) {
+  if (parsed.stage !== undefined && !isReviewStage(parsed.stage)) {
     fail(`invalid --stage '${parsed.stage}' (expected analysis|plan|code)`);
     return;
   }
@@ -248,20 +241,29 @@ function decisions(args: string[] = []): void {
     return;
   }
 
-  const resolved = resolveTaskRef(parsed.positionals[0]!);
+  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 resolved = resolveTaskContext(taskRef);
   if (!resolved.ok) {
     fail(resolved.message);
     return;
   }
 
   const content = fs.readFileSync(resolved.taskMdPath, 'utf8');
-  let rows = parseLedger(content).filter((r) => HD_ID_RE.test(r.id));
-  rows = rows.filter((r) =>
-    parsed.all ? HUMAN_DECISION_STATUSES.has(r.status) : r.status === 'needs-human-decision'
-  );
-  if (parsed.stage !== undefined) rows = rows.filter((r) => r.stage === parsed.stage);
+  const rows = listDecisionItems(parseLedger(content), {
+    includeDecided: parsed.all,
+    stage: parsed.stage as ReviewStage | undefined
+  });
 
-  const selector = parsed.positionals[1];
   if (selector === undefined) {
     renderList(rows, parsed.format, resolved.taskDir);
   } else {

package/lib/task/commands/files.ts

@@ -1,11 +1,13 @@
 import { formatTable } from '../../table.ts';
-import { resolveTaskRef } from '../resolve-ref.ts';
+import { parseTaskScope } from '../command-options.ts';
+import { resolveTaskContext } from '../resolve-ref.ts';
 import { enumerateArtifacts } from '../artifacts.ts';
 
-const USAGE = `Usage: ai task files <N | #N | TASK-id>
+const USAGE = `Usage: ai task files [<N | TASK-id> | --task <ref> | -t <ref>]
 
 Lists the artifacts in a task directory with stable numbers.
-  <ref>   Bare numeric / '#N' short id, or a full TASK-YYYYMMDD-HHMMSS id.
+  Omit <ref>   Resolve the unique active task for the current branch.
+  <ref>   Bare numeric short id, or a full TASK-YYYYMMDD-HHMMSS id.
 
 Columns: # (artifact number, usable with 'ai task cat') / NAME / SIZE (bytes) / MTIME
 `;
@@ -25,12 +27,18 @@ function formatMtime(mtimeMs: number): string {
 }
 
 function files(args: string[] = []): void {
-  if (args.length === 0 || args[0] === '--help' || args[0] === '-h') {
+  if (args[0] === '--help' || args[0] === '-h') {
     process.stdout.write(USAGE);
-    if (args.length === 0) process.exitCode = 1;
     return;
   }
-  const resolved = resolveTaskRef(args[0]!);
+  let scope;
+  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;
+  }
+  const resolved = resolveTaskContext(scope.taskRef ?? scope.positionals[0]);
   if (!resolved.ok) {
     process.stderr.write(`ai task files: ${resolved.message}\n`);
     process.exitCode = 1;

package/lib/task/commands/grep.ts

@@ -1,14 +1,15 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { resolveTaskRef, detectRepoRoot, enumerateTaskDirs } from '../resolve-ref.ts';
+import { resolveTaskContext, resolveTaskRef, detectRepoRoot, enumerateTaskDirs } 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]
 
 Literal (non-regex) line search across task artifacts.
   <pattern>          Literal substring to match (NOT a regex). Case-sensitive by default.
-  [ref]              Bare numeric / '#N' short id, or a full TASK-YYYYMMDD-HHMMSS id.
+  [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).
@@ -17,6 +18,8 @@ Literal (non-regex) line search across task artifacts.
 
 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).
@@ -62,14 +65,31 @@ function scanArtifact(
 function grep(args: string[] = []): void {
   const positional: string[] = [];
   let ignoreCase = false;
+  let current = false;
+  let taskRef: string | undefined;
   let optsEnded = false;
-  for (const a of args) {
+  for (let index = 0; index < args.length; index += 1) {
+    const a = args[index]!;
     if (!optsEnded && a === '--') { optsEnded = true; continue; }
     if (!optsEnded && (a === '-h' || a === '--help')) {
       process.stdout.write(USAGE);
       return;
     }
     if (!optsEnded && (a === '-i' || a === '--ignore-case')) { ignoreCase = true; continue; }
+    if (!optsEnded && a === '--current') { current = true; continue; }
+    if (!optsEnded && (a === '--task' || a === '-t')) {
+      if (taskRef !== undefined) { process.stderr.write("ai task grep: duplicate option '--task'\n"); process.exitCode = 1; return; }
+      const value = args[++index];
+      if (!value || value.startsWith('-')) { process.stderr.write(`ai task grep: ${a} requires a value\n`); process.exitCode = 1; return; }
+      taskRef = value;
+      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; }
+      continue;
+    }
     if (!optsEnded && a.startsWith('-') && a !== '-') {
       process.stderr.write(`ai task grep: unknown flag: ${a}\n`);
       process.exitCode = 1;
@@ -83,19 +103,26 @@ function grep(args: string[] = []): void {
     process.exitCode = 1;
     return;
   }
-  if (positional.length > 3) {
+  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)) {
     process.stderr.write('ai task grep: too many arguments\n');
     process.exitCode = 1;
     return;
   }
 
-  const [pattern, ref, artifactOrN] = positional;
+  let [pattern, ref, artifactOrN] = positional;
+  if (current || taskRef !== undefined) {
+    artifactOrN = ref;
+    ref = taskRef;
+  }
   const matcher = makeMatcher(pattern!, ignoreCase);
   const chunks: string[] = [];
   const emit = (line: string) => chunks.push(line);
   let total = 0;
 
-  if (ref === undefined) {
+  if (ref === undefined && !current) {
     // No ref: full scan across active / blocked / completed (no archive).
     let repoRoot: string;
     try {
@@ -113,7 +140,7 @@ function grep(args: string[] = []): void {
       }
     }
   } else {
-    const resolved = resolveTaskRef(ref);
+    const resolved = current ? resolveTaskContext() : resolveTaskRef(ref!);
     if (!resolved.ok) {
       process.stderr.write(`ai task grep: ${resolved.message}\n`);
       process.exitCode = 1;

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

@@ -1,14 +1,16 @@
 import fs from 'node:fs';
-import { resolveTaskRef } from '../resolve-ref.ts';
+import { parseTaskScope } from '../command-options.ts';
+import { resolveTaskContext } from '../resolve-ref.ts';
 import { extractTitle } from '../frontmatter.ts';
 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 <N | #N | TASK-id> [--template <path>]
+const USAGE = `Usage: ai task issue-body [<ref> | --task <ref> | -t <ref>] [--template <path>]
 
 Print a deterministic Issue body extracted from a task's task.md.
-  <ref>               Bare numeric / '#N' short id, or a full TASK-YYYYMMDD-HHMMSS id.
+  Omit <ref>           Resolve the unique active task for the current branch.
+  <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).
 
@@ -40,28 +42,19 @@ function readTaskFields(content: string): TaskFields {
 }
 
 function issueBody(args: string[] = []): void {
-  if (args.length === 0 || args[0] === '--help' || args[0] === '-h') {
+  if (args[0] === '--help' || args[0] === '-h') {
     process.stdout.write(USAGE);
-    if (args.length === 0) process.exitCode = 1;
     return;
   }
 
-  let ref: string | undefined;
   let templatePath: string | undefined;
+  const scopeArgs: string[] = [];
   for (let i = 0; i < args.length; i += 1) {
     const arg = args[i]!;
     if (arg === '--template') {
       templatePath = args[i + 1];
       i += 1;
-    } else if (ref === undefined) {
-      ref = arg;
-    }
-  }
-
-  if (!ref) {
-    process.stderr.write('ai task issue-body: missing task ref\n');
-    process.exitCode = 1;
-    return;
+    } else { scopeArgs.push(arg); }
   }
   if (templatePath === undefined && args.includes('--template')) {
     process.stderr.write('ai task issue-body: --template requires a path\n');
@@ -69,7 +62,14 @@ function issueBody(args: string[] = []): void {
     return;
   }
 
-  const resolved = resolveTaskRef(ref);
+  let scope;
+  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;
+  }
+  const resolved = resolveTaskContext(scope.taskRef ?? scope.positionals[0]);
   if (!resolved.ok) {
     process.stderr.write(`ai task issue-body: ${resolved.message}\n`);
     process.exitCode = 1;

package/lib/task/commands/log.ts

@@ -1,14 +1,17 @@
 import fs from 'node:fs';
 import { formatTable } from '../../table.ts';
-import { resolveTaskRef } from '../resolve-ref.ts';
-import { parseLedger, type LedgerRow } from '../ledger.ts';
+import { parseTaskScope } from '../command-options.ts';
+import { resolveTaskContext } from '../resolve-ref.ts';
+import { isReviewStage, parseLedger, type LedgerRow, type ReviewStage } from '../ledger.ts';
+import { parseActivityLog, pairEntries } from '../activity-log.ts';
 
-const USAGE = `Usage: ai task log <N | #N | TASK-id>
+const USAGE = `Usage: ai task log [<N | TASK-id> | --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).
-  <ref>   Bare numeric / '#N' short id, or a full TASK-YYYYMMDD-HHMMSS id.
+  Omit <ref>   Resolve the unique active task for the current branch.
+  <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,
@@ -20,27 +23,17 @@ Columns: # (row) / STEP / AGENT / STARTED / DONE / NOTE
 const TABLE_HEADERS = ['#', 'STEP', 'AGENT', 'STARTED', 'DONE', 'NOTE'] as const;
 
 // The activity-log H2 heading is language-dependent (zh template / en template).
-const HEADING_RE = /^##\s+(活动日志|Activity Log)\s*$/;
-const NEXT_H2_RE = /^##\s/;
 // `- {time} — **{step}** by {agent} — {note}` ; the separator is an em-dash
 // (U+2014). STEP/AGENT are non-greedy so a note that itself contains ' — ' or
 // '→' is not mis-split; NOTE greedily takes the rest of the line.
-const ENTRY_RE =
-  /^- (\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}[+-]\d{2}:\d{2}) — \*\*(.+?)\*\* by (.+?) — (.*)$/;
-
-type LogEntry = { time: string; step: string; agent: string; note: string };
-type ReviewStage = 'analysis' | 'plan' | 'code';
-
 // One rendered row = one step instance. `started`/`done` are timestamps; an empty
 // `done` with a non-empty `started` means the step is still in flight, while an
 // empty `started` is a historical done-only entry (no start marker was written).
-type StepRow = { step: string; agent: string; started: string; done: string; note: string };
 
 // A start marker reuses the normal entry grammar and only suffixes its action
 // with ` [started]`; the matching done entry carries the identical base action
 // without the suffix. Pairing therefore keys on the base action (including any
 // `(Round N)`), so every round and every repeated execution pairs on its own.
-const STARTED_SUFFIX_RE = /\s*\[started\]\s*$/;
 // Short agent tokens that actually appear in activity logs for AI executors
 // (workflow recommended_agents claude/codex/gemini/cursor + enabled TUI opencode;
 // note these differ from the `.airc.json` long names claude-code/gemini-cli).
@@ -52,59 +45,11 @@ const REVIEW_STAGE_PREFIXES: { prefix: string; stage: ReviewStage }[] = [
   { prefix: 'Review Code', stage: 'code' }
 ];
 
-function parseActivityLog(content: string): { sectionFound: boolean; entries: LogEntry[] } {
-  const lines = content.split('\n');
-  let i = 0;
-  while (i < lines.length && !HEADING_RE.test(lines[i]!)) i += 1;
-  if (i >= lines.length) return { sectionFound: false, entries: [] };
-  const parsed: { entry: LogEntry; epoch: number; order: number }[] = [];
-  for (let j = i + 1; j < lines.length; j += 1) {
-    if (NEXT_H2_RE.test(lines[j]!)) break;
-    const m = ENTRY_RE.exec(lines[j]!);
-    if (!m) continue; // skip blank / non-entry / malformed lines
-    parsed.push({
-      entry: { time: m[1]!, step: m[2]!, agent: m[3]!, note: m[4]! },
-      epoch: Date.parse(m[1]!.replace(' ', 'T')),
-      order: parsed.length
-    });
-  }
-  // Ascending by time; stable tie-break on original order for equal timestamps.
-  parsed.sort((a, b) => a.epoch - b.epoch || a.order - b.order);
-  return { sectionFound: true, entries: parsed.map((p) => p.entry) };
-}
-
 // Collapse a chronological entry list into per-step rows: a `[started]` marker
 // opens a row, the next matching done entry fills it in place (FIFO per base
 // action). Started-only rows stay in flight; done-only entries (legacy logs with
 // no start marker) render as standalone rows. Result order = first-seen order,
 // which is already ascending because `entries` is sorted ascending.
-function pairEntries(entries: LogEntry[]): StepRow[] {
-  const rows: StepRow[] = [];
-  const open = new Map<string, StepRow[]>();
-  for (const e of entries) {
-    const isStarted = STARTED_SUFFIX_RE.test(e.step);
-    const base = e.step.replace(STARTED_SUFFIX_RE, '');
-    if (isStarted) {
-      const row: StepRow = { step: base, agent: e.agent, started: e.time, done: '', note: e.note };
-      rows.push(row);
-      const queue = open.get(base);
-      if (queue) queue.push(row);
-      else open.set(base, [row]);
-    } else {
-      const pending = open.get(base)?.shift();
-      if (pending) {
-        // Done fills the open row; the done entry carries the meaningful note.
-        pending.done = e.time;
-        pending.agent = e.agent;
-        pending.note = e.note;
-      } else {
-        rows.push({ step: base, agent: e.agent, started: '', done: e.time, note: e.note });
-      }
-    }
-  }
-  return rows;
-}
-
 function countHumanDecisionsByStage(rows: LedgerRow[]): Map<ReviewStage, number> {
   const counts = new Map<ReviewStage, number>();
   for (const row of rows) {
@@ -114,10 +59,6 @@ function countHumanDecisionsByStage(rows: LedgerRow[]): Map<ReviewStage, number>
   return counts;
 }
 
-function isReviewStage(stage: string): stage is ReviewStage {
-  return stage === 'analysis' || stage === 'plan' || stage === 'code';
-}
-
 function reviewStageForStep(step: string): ReviewStage | undefined {
   return REVIEW_STAGE_PREFIXES.find(({ prefix }) => step.startsWith(prefix))?.stage;
 }
@@ -173,12 +114,18 @@ function foldHumanCounts(note: string, decisions: number, manualValidation: numb
 }
 
 function log(args: string[] = []): void {
-  if (args.length === 0 || args[0] === '--help' || args[0] === '-h') {
+  if (args[0] === '--help' || args[0] === '-h') {
     process.stdout.write(USAGE);
-    if (args.length === 0) process.exitCode = 1;
     return;
   }
-  const resolved = resolveTaskRef(args[0]!);
+  let scope;
+  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;
+  }
+  const resolved = resolveTaskContext(scope.taskRef ?? scope.positionals[0]);
   if (!resolved.ok) {
     process.stderr.write(`ai task log: ${resolved.message}\n`);
     process.exitCode = 1;
@@ -216,4 +163,4 @@ function log(args: string[] = []): void {
   process.stdout.write(`Total: ${steps.length} steps\n`);
 }
 
-export { log, parseActivityLog, pairEntries, isHumanAgent };
+export { log, isHumanAgent };

package/lib/task/commands/show.ts

@@ -1,21 +1,29 @@
 import fs from 'node:fs';
-import { resolveTaskRef } from '../resolve-ref.ts';
+import { parseTaskScope } from '../command-options.ts';
+import { resolveTaskContext } from '../resolve-ref.ts';
 
-const USAGE = `Usage: ai task show <N | #N | TASK-id>
+const USAGE = `Usage: ai task show [<N | TASK-id> | --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.
-  '#N'               Compatibility form for old commands.
   TASK-YYYYMMDD-HHMMSS  Locates a task in active / blocked / completed / archive.
 `;
 
 function show(args: string[] = []): void {
-  if (args.length === 0 || args[0] === '--help' || args[0] === '-h') {
+  if (args[0] === '--help' || args[0] === '-h') {
     process.stdout.write(USAGE);
-    if (args.length === 0) process.exitCode = 1;
     return;
   }
-  const resolved = resolveTaskRef(args[0]!);
+  let scope;
+  try { scope = parseTaskScope(args); } catch (error) {
+    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;
+  }
+  const resolved = resolveTaskContext(scope.taskRef ?? scope.positionals[0]);
   if (!resolved.ok) {
     process.stderr.write(`ai task show: ${resolved.message}\n`);
     process.exitCode = 1;