@sentropic/track 0.86.0 → 0.88.0

package/dist/cli/bin.js

@@ -5,6 +5,17 @@
 // bin/ — so the installed `track` silently did nothing. A separate entry that just runs is the
 // same posture as track-mcp's cli.ts and cannot regress that way. `index.ts` stays import-only.
 import { runCli } from './index.js';
+// Keep the natural drain that preserves large reports, while treating a downstream closed pipe (for
+// example `track report | head`) as normal CLI termination rather than an uncaught stream error.
+for (const stream of [process.stdout, process.stderr]) {
+    stream.on('error', (error) => {
+        if (error.code === 'EPIPE') {
+            process.exitCode ??= 0;
+            return;
+        }
+        throw error;
+    });
+}
 // `runCli` returns `number | Promise<number>` — the `focus` command is async (it dynamically imports the
 // integrated focus); every other command stays sync and returns a plain number. `Promise.resolve`
 // normalizes both into one exit path, so a sync command still exits with no added microtask churn beyond a
@@ -13,5 +24,7 @@ Promise.resolve(runCli(process.argv.slice(2), {
     cwd: process.cwd(),
     out: (s) => process.stdout.write(s),
     err: (s) => process.stderr.write(s),
-})).then((rc) => process.exit(rc));
+})).then((rc) => {
+    process.exitCode = rc;
+});
 //# sourceMappingURL=bin.js.map

package/dist/cli/bin.js.map

@@ -1 +1 @@
-{"version":3,"file":"bin.js","sourceRoot":"","sources":["../../src/cli/bin.ts"],"names":[],"mappings":";AACA,yFAAyF;AACzF,8FAA8F;AAC9F,+FAA+F;AAC/F,+FAA+F;AAC/F,gGAAgG;AAChG,OAAO,EAAE,MAAM,EAAE,MAAM,YAAY,CAAA;AAEnC,yGAAyG;AACzG,kGAAkG;AAClG,2GAA2G;AAC3G,yBAAyB;AACzB,OAAO,CAAC,OAAO,CACb,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE;IAC5B,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE;IAClB,GAAG,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;IACnC,GAAG,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;CACpC,CAAC,CACH,CAAC,IAAI,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAA"}
+{"version":3,"file":"bin.js","sourceRoot":"","sources":["../../src/cli/bin.ts"],"names":[],"mappings":";AACA,yFAAyF;AACzF,8FAA8F;AAC9F,+FAA+F;AAC/F,+FAA+F;AAC/F,gGAAgG;AAChG,OAAO,EAAE,MAAM,EAAE,MAAM,YAAY,CAAA;AAEnC,oGAAoG;AACpG,iGAAiG;AACjG,KAAK,MAAM,MAAM,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;IACtD,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,KAA4B,EAAE,EAAE;QAClD,IAAI,KAAK,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC;YAC3B,OAAO,CAAC,QAAQ,KAAK,CAAC,CAAA;YACtB,OAAM;QACR,CAAC;QACD,MAAM,KAAK,CAAA;IACb,CAAC,CAAC,CAAA;AACJ,CAAC;AAED,yGAAyG;AACzG,kGAAkG;AAClG,2GAA2G;AAC3G,yBAAyB;AACzB,OAAO,CAAC,OAAO,CACb,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE;IAC5B,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE;IAClB,GAAG,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;IACnC,GAAG,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;CACpC,CAAC,CAIH,CAAC,IAAI,CAAC,CAAC,EAAE,EAAE,EAAE;IACZ,OAAO,CAAC,QAAQ,GAAG,EAAE,CAAA;AACvB,CAAC,CAAC,CAAA"}

package/dist/cli/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"AA+CA,MAAM,WAAW,KAAK;IACpB,GAAG,EAAE,MAAM,CAAA;IACX,GAAG,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,IAAI,CAAA;IACxB,GAAG,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,IAAI,CAAA;IACxB,kGAAkG;IAClG,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAA;CACxB;AAuRD,wBAAgB,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,EAAE,KAAK,GAAG,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAuI7E"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"AA6CA,MAAM,WAAW,KAAK;IACpB,GAAG,EAAE,MAAM,CAAA;IACX,GAAG,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,IAAI,CAAA;IACxB,GAAG,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,IAAI,CAAA;IACxB,kGAAkG;IAClG,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAA;CACxB;AAqTD,wBAAgB,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,EAAE,KAAK,GAAG,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CA8J7E"}

package/dist/cli/index.js

@@ -9,20 +9,22 @@ import { cmdEventsContains } from './events-contains.js';
 import { cmdInstallSkills } from './install-skills.js';
 import { initTrackDir, resolveTrackDir, resolveTrackDirOrNull } from './resolve.js';
 import { DomainError } from '../model/item.js';
-import { formatRows } from '../report/format.js';
+import { displayText, formatRows } from '../report/format.js';
 import { Track } from '../track.js';
-import { BLOCKER_KINDS, BLOCKER_SCOPES, DECISION_KINDS, DISPOSITIONS, EVIDENCE_KINDS, GATES, ITEM_KINDS, ITEM_ROLES, OUTCOMES, REALIZE_TARGETS, RESOLUTION_RULES, RESULTS, ROLE_CHANGE_TARGETS, SPEC_TARGETS, } from '../ingest/contract.js';
+import { BLOCKER_KINDS, BLOCKER_SCOPES, DECISION_KINDS, DISPOSITIONS, EVIDENCE_KINDS, GATES, ITEM_KINDS, ITEM_ROLES, REALIZE_TARGETS, RESOLUTION_RULES, RESULTS, ROLE_CHANGE_TARGETS, SPEC_TARGETS, } from '../ingest/contract.js';
 import { ingest } from '../ingest/ingest.js';
 import { applyRestructurePlan } from './restructure-apply.js';
 import { TrackReader } from '../read/contract.js';
-import { queryText, reportText, statusText } from '../read/commands.js';
+import { queryText, reportHtml, reportInline, reportText, resolveHandle, statusText } from '../read/commands.js';
 import { STATUS_LEVELS } from '../report/status-by-level.js';
 import { renderSnapshot } from '../report/snapshot.js';
-import { generateAiReport } from '../report/ai-report.js';
 import { VERSION } from '../version.js';
 import { durableWorkspaceId } from '../workspace-id.js';
 import { desyncFindings } from './desync.js';
 const USAGE = `usage: track <command>
+  --help | help
+  global read/store override: --track-dir <directory-containing-events.jsonl> (or TRACK_DIR)
+    may appear before or after the command; it redirects reads AND writes to that directory
   --version | -v
   init
   item new --kind <feature|bug|chore> --title <t> --workspace <w> [--body <b>] [--parent <id>] [--role <workpackage|spec-phase|stream>] [--accountable <a>] [--responsible <a,a>] [--engagement-ref <e>]
@@ -35,9 +37,11 @@ const USAGE = `usage: track <command>
   item assign-code <itemId> --code <c> [--client-token <t>]
   item show <itemId>
   item ls [--workspace <w>] [--kind <feature|bug|chore>] [--format json|text|md]
-  decision new --kind <orientation|commitment> --title <t> --workspace <w> --targets <id,id> [--context <c>] [--accountable <a>] [--engagement-ref <e>]
-  decision outcome <decisionId> <go|no-go|deferred>
-  decision dossier <decisionId> --context <c>
+  decision new --kind <orientation|commitment> --title <t> --workspace <w> --targets <id,id> --context <c> --options-json <json> --recommendation <optionId> --rationale <r> [--accountable <a>] [--engagement-ref <e>]
+  decision ls [--workspace <w>] [--outcome <pending|go|no-go|deferred>] [--format json|text|md] [--commit <sha>]
+  decision outcome <decisionId> deferred
+  decision select <decisionId> <optionId> [--outcome <go|no-go>]
+  decision dossier <decisionId> [--context <c>] [--options-json <json> --recommendation <optionId> --rationale <r>]
   decision disposition <itemId> <orientation|commitment> <required|skipped|not-applicable>
   decision add-artifact <decisionId> --kind <h2a-decision-dossier|rendered-view|mockup> [--negotiation-ref <n>] [--dossier-hash <h>] [--view-ref <v>] [--source-dossier-hash <h>] [--label <l>] [--client-token <t>]
   blocker raise --target <id> --kind <decision|dependency> [--ref <id>] [--reason <r>] [--rule <linked-done|linked-accepted|manual>] [--scope <intra|extra>] [--engagement-ref <e>]
@@ -50,7 +54,7 @@ const USAGE = `usage: track <command>
   accept waive <criterionId> --reason <r>
   consolidate --items <id,id> --commit <mergeCommit> [--client-token <t>]
   priority assess <itemId> --ubv <n> --tc <n> --rr <n> --js <n>
-  report [--decisions] [--require-accepted] [--active-roster] [--wp|--flat] [--inline] [--width <n>] [--level <spec|plan|wp|lot|task>] [--raw] [--format json|text|md|html] [--commit <sha>]
+  report [--decisions] [--require-accepted] [--active-roster] [--wp|--flat] [--inline] [--width <n>] [--level <spec|plan|wp|lot|task>] [--raw] [--resolve <handle>] [--sub-wp] [--format json|text|md|html] [--commit <sha>] [--now <iso>]
   snapshot [--require-accepted] [--format json|text|md] [--commit <sha>]
   export-graph [--repo-key <repo:key>] [--source-id <id>] [--observed-at <iso>]
   query [--kind <k>] [--role <workpackage|spec-phase|stream>] [--workspace <w>] [--bucket <AWAITED|DROPPED|DONE|TO-DO>] [--realization <r>] [--acceptance <a>] [--format json|text|md] [--commit <sha>]
@@ -66,7 +70,7 @@ const USAGE = `usage: track <command>
   install-skills --host <claude|codex|gemini|agy|all> [--scope user|project] [--force]
   workspace-id [--cwd <path>]
 `;
-// Write enums (ITEM_KINDS, SPEC_TARGETS, REALIZE_TARGETS, DECISION_KINDS, OUTCOMES, GATES, DISPOSITIONS,
+// Write enums (ITEM_KINDS, SPEC_TARGETS, REALIZE_TARGETS, DECISION_KINDS, GATES, DISPOSITIONS,
 // BLOCKER_KINDS, RESOLUTION_RULES, EVIDENCE_KINDS, RESULTS) are sourced from the ingest contract — the
 // SINGLE source, so the CLI's `oneOf` checks and the WorkEvent mapper cannot diverge on accepted values.
 // (`linked-accepted` openness is DERIVED at report/query time vs `--commit`, v2.2a hybrid-A; see
@@ -74,6 +78,7 @@ const USAGE = `usage: track <command>
 const REALIZATIONS = ['to-do', 'in-progress', 'done', 'cancelled', 'rejected'];
 const FROM_FORMATS = ['junit', 'json'];
 const BUCKETS_ARG = ['AWAITED', 'DROPPED', 'DONE', 'TO-DO'];
+const DECISION_OUTCOMES = ['pending', 'go', 'no-go', 'deferred'];
 // `n/a` is decision-only; `query` projects non-decision rows, so it would never match.
 const ACCEPTANCES = ['fail', 'waived', 'unknown', 'stale', 'pass'];
 // The DossierArtifact discriminator (M5 §3.1). CLI-local: the union SHAPE is validated fail-closed in the
@@ -241,6 +246,19 @@ function num(flags, key) {
         throw new DomainError(`--${key} must be a number`);
     return n;
 }
+function dossierOptions(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new DomainError('--options-json must be a JSON array of existing Option objects');
+    }
+    if (!Array.isArray(parsed)) {
+        throw new DomainError('--options-json must be a JSON array of existing Option objects');
+    }
+    return parsed;
+}
 /** Validate a positional/flag against an allowed enum (CLI-boundary input validation). */
 function oneOf(value, allowed, name) {
     if (value === undefined || !allowed.includes(value)) {
@@ -290,10 +308,28 @@ function extractTrackDirFlag(argv) {
     }
     return trackDirFlag !== undefined ? { trackDirFlag, rest } : { rest };
 }
+const REPORT_USAGE = `usage: track report [--raw] [--wp] [--flat] [--inline|--width <40..240>] [--decisions] [--active-roster] [--require-accepted] [--resolve <handle>] [--commit <sha>] [--now <iso>] [--sub-wp] [--format json|text|md|html] [--track-dir <directory-containing-events.jsonl>]
+
+--resolve <handle> resolves a report handle (a positional [n.m] row handle, or a D#/Q# dossier number) back to its item id. It is the one command the report documents for acting on a row without printing a ULID in a column. Handles are positional and per-report: resolve them against the same log and baseline the report was rendered from.
+
+--sub-wp lists sub-WP rows beside their parent. Without it, sub-levels are aggregated into their parent on a long window (>= 14 days) and listed on a short one — the WP is the reading unit of a long report.
+
+--now <iso> pins the window's upper bound (default: the wall clock). The report's period always runs from the first recorded event to that bound; pin it to reproduce a committed fixture byte for byte.
+
+--track-dir is a global override and may appear before or after the command. It selects the directory that contains events.jsonl; it is especially useful for a read-only fixture. TRACK_DIR is the environment equivalent.
+`;
 export function runCli(rawArgv, io) {
     const { trackDirFlag, rest: argv } = extractTrackDirFlag(rawArgv);
     const cmd = argv[0];
     const rest = argv.slice(1);
+    if (cmd === '--help' || cmd === 'help' || cmd === undefined) {
+        io.out(USAGE);
+        return 0;
+    }
+    if (cmd === 'report' && rest.length === 1 && rest[0] === '--help') {
+        io.out(REPORT_USAGE);
+        return 0;
+    }
     const trackDirEnv = process.env['TRACK_DIR'];
     const resolveOpts = {
         cwd: io.cwd,
@@ -301,6 +337,19 @@ export function runCli(rawArgv, io) {
         ...(trackDirEnv !== undefined ? { env: trackDirEnv } : {}),
     };
     try {
+        // `decision ls` is an inspection surface, not a write verb. Route it through the same serve-empty
+        // read path as report/query so it never creates a sidecar and can be used by a fresh reporting agent.
+        if (cmd === 'decision' && rest[0] === 'ls') {
+            const trackDir = resolveTrackDirOrNull(resolveOpts);
+            if (trackDir === null) {
+                io.err(`track: no .track resolved from ${io.cwd}. Run \`track init\` to create one ` +
+                    `(the ONLY command that does), or pass --track-dir / TRACK_DIR. Serving an empty view.\n`);
+            }
+            return cmdDecisionLs(rest, {
+                io,
+                eventsPath: trackDir !== null ? eventsPathOf(trackDir) : eventsPathOf(join(resolve(io.cwd), '.track')),
+            });
+        }
         switch (cmd) {
             case '--version':
             case '-v':
@@ -659,7 +708,12 @@ function cmdDecision(args, ctx) {
             title: req(flags, 'title'),
             workspace: req(flags, 'workspace'),
             targets: req(flags, 'targets').split(',').map((s) => s.trim()).filter(Boolean),
-            dossier: { context: opt(flags, 'context') ?? '', options: [], qa: [] },
+            dossier: {
+                context: req(flags, 'context'),
+                options: dossierOptions(req(flags, 'options-json')),
+                qa: [],
+                recommendation: { optionId: req(flags, 'recommendation'), rationale: req(flags, 'rationale') },
+            },
             ...(opt(flags, 'accountable') !== undefined ? { accountable: req(flags, 'accountable') } : {}),
             ...(opt(flags, 'engagement-ref') !== undefined ? { engagementRef: req(flags, 'engagement-ref') } : {}),
         });
@@ -667,16 +721,37 @@ function cmdDecision(args, ctx) {
         return 0;
     }
     if (sub === 'outcome') {
-        track.setOutcome(positional[0], oneOf(positional[1], OUTCOMES, 'outcome'));
+        track.setOutcome(positional[0], oneOf(positional[1], ['deferred'], 'outcome'));
         io.out('ok\n');
         return 0;
     }
     if (sub === 'dossier') {
-        // merge: a context-only edit must not erase existing options/qa/recommendation
+        // Merge: a context-only edit preserves a structured dossier. A legacy dossier must provide the
+        // full options/recommendation triplet here; the facade validates it fail-closed.
         const current = track.state().decisions.get(positional[0])?.dossier;
         if (current === undefined)
             throw new DomainError(`unknown decision ${positional[0]}`);
-        track.reviseDossier(positional[0], { ...current, context: opt(flags, 'context') ?? current.context });
+        const optionJson = opt(flags, 'options-json');
+        const recommendation = opt(flags, 'recommendation');
+        const rationale = opt(flags, 'rationale');
+        if ((recommendation === undefined) !== (rationale === undefined)) {
+            throw new DomainError('--recommendation and --rationale must be supplied together');
+        }
+        if (optionJson !== undefined && recommendation === undefined && current.recommendation === undefined) {
+            throw new DomainError('migrating a legacy dossier requires --recommendation and --rationale');
+        }
+        track.reviseDossier(positional[0], {
+            ...current,
+            context: opt(flags, 'context') ?? current.context,
+            ...(optionJson !== undefined ? { options: dossierOptions(optionJson) } : {}),
+            ...(recommendation !== undefined ? { recommendation: { optionId: recommendation, rationale: rationale } } : {}),
+        });
+        io.out('ok\n');
+        return 0;
+    }
+    if (sub === 'select') {
+        const outcome = opt(flags, 'outcome');
+        track.selectDecisionOption(positional[0], positional[1], outcome === undefined ? 'go' : oneOf(outcome, ['go', 'no-go'], '--outcome'));
         io.out('ok\n');
         return 0;
     }
@@ -719,7 +794,7 @@ function cmdDecision(args, ctx) {
         io.out('ok\n');
         return 0;
     }
-    io.err('usage: track decision <new|outcome|dossier|disposition|add-artifact>\n');
+    io.err('usage: track decision <new|outcome|select|dossier|disposition|add-artifact>\n');
     return 2;
 }
 function cmdBlocker(args, ctx) {
@@ -857,61 +932,58 @@ function cmdReport(args, ctx) {
     const { positional, flags } = parseFlags(args);
     if (positional.length > 0)
         throw new DomainError(`unexpected report argument(s): ${positional.join(' ')}`);
-    for (const name of ['commit', 'format', 'level', 'width'])
+    for (const name of ['commit', 'format', 'level', 'width', 'resolve', 'now'])
         assertValueFlag(flags, name);
+    // Criterion 10b — the one documented command that turns a short report handle back into an item.
+    if (opt(flags, 'resolve') !== undefined) {
+        assertOnlyFlags(flags, ['resolve', 'commit', 'require-accepted']);
+        io.out(resolveHandle(new TrackReader(ctx.eventsPath), {
+            baselineCommit: resolveCommit(io.cwd, opt(flags, 'commit')),
+            requireAccepted: assertBooleanFlag(flags, 'require-accepted'),
+        }, req(flags, 'resolve')));
+        return 0;
+    }
     const raw = assertBooleanFlag(flags, 'raw');
     if (raw) {
         assertOnlyFlags(flags, ['raw', 'commit', 'require-accepted', 'format']);
         return emitSnapshot(flags, ctx, true);
     }
-    // Reads go through the shared TrackReader command layer (same path the MCP server uses).
-    const reader = new TrackReader(ctx.eventsPath);
     // Scope §A/§B — `--level <spec|plan|wp|lot|task>` switches to the status(level) projection.
-    // Otherwise 0.19.1 prefers the WP/table conductor view; `--flat` is the deprecated legacy opt-out.
+    // Otherwise the WP/table conductor is the default; `--flat` is the legacy opt-out.
     if (opt(flags, 'level') !== undefined) {
         assertOnlyFlags(flags, ['level', 'commit', 'require-accepted', 'format']);
         assertBooleanFlag(flags, 'require-accepted');
-        io.out(statusText(reader, oneOf(req(flags, 'level'), STATUS_LEVELS, '--level'), {
+        io.out(statusText(new TrackReader(ctx.eventsPath), oneOf(req(flags, 'level'), STATUS_LEVELS, '--level'), {
             baselineCommit: resolveCommit(io.cwd, opt(flags, 'commit')),
             requireAccepted: assertBooleanFlag(flags, 'require-accepted'),
         }, fmt(flags)));
         return 0;
     }
+    assertOnlyFlags(flags, [
+        'commit', 'require-accepted', 'decisions', 'active-roster', 'wp', 'flat', 'inline', 'width', 'format', 'now',
+        'sub-wp',
+    ]);
     const rawFormat = opt(flags, 'format');
+    if (rawFormat !== undefined && !['json', 'text', 'md', 'html'].includes(rawFormat)) {
+        throw new DomainError('--format must be one of: json|text|md|html');
+    }
     const widthArg = opt(flags, 'width');
     const inlineFlag = assertBooleanFlag(flags, 'inline');
     const inline = inlineFlag || widthArg !== undefined;
-    if (inline && rawFormat !== undefined && rawFormat !== 'text') {
+    const format = oneOf(rawFormat ?? 'text', ['json', 'text', 'md', 'html'], '--format');
+    if (inline && format !== 'text')
         throw new DomainError('--inline/--width accepts no --format, or --format text');
-    }
-    if (rawFormat === 'html' && inline)
-        throw new DomainError('--format html rejects --inline/--width');
-    // Frozen legacy path. Keep this call and option derivation byte-for-byte equivalent to the former JSON
-    // branch: it never enters context collection or the adapter.
-    if (rawFormat === 'json') {
-        assertOnlyFlags(flags, ['commit', 'require-accepted', 'decisions', 'active-roster', 'wp', 'flat', 'format']);
-        io.out(reportText(reader, {
-            baselineCommit: resolveCommit(io.cwd, opt(flags, 'commit')),
-            requireAccepted: flags['require-accepted'] === true,
-            decisions: flags['decisions'] === true,
-            wpTree: flags['wp'] === true,
-            activeRoster: flags['active-roster'] === true,
-        }, 'json'));
-        return 0;
-    }
-    assertOnlyFlags(flags, [
-        'commit', 'require-accepted', 'decisions', 'active-roster', 'wp', 'flat', 'inline', 'width', 'format',
-    ]);
-    if (rawFormat !== undefined && !['text', 'md', 'html'].includes(rawFormat)) {
-        throw new DomainError('--format must be one of: json|text|md|html');
-    }
     const requireAccepted = assertBooleanFlag(flags, 'require-accepted');
-    const decisions = assertBooleanFlag(flags, 'decisions');
+    const requestedDecisions = assertBooleanFlag(flags, 'decisions');
     const activeRoster = assertBooleanFlag(flags, 'active-roster');
     const wp = assertBooleanFlag(flags, 'wp');
     const flat = assertBooleanFlag(flags, 'flat');
     if (wp && flat)
         throw new DomainError('--wp and --flat are mutually exclusive');
+    if (format === 'json' && flat)
+        throw new DomainError('--flat is only meaningful for text or md reports');
+    if (format === 'html' && flat)
+        throw new DomainError('--format html is always the deterministic conductor and rejects --flat');
     let width;
     if (widthArg !== undefined) {
         if (!/^\d+$/u.test(widthArg))
@@ -920,28 +992,41 @@ function cmdReport(args, ctx) {
         if (width < 40 || width > 240)
             throw new DomainError('--width must be an integer in [40,240]');
     }
-    const baselineInput = opt(flags, 'commit') ?? 'HEAD';
-    const baselineCommit = resolveCommit(io.cwd, baselineInput);
-    const format = inline
-        ? 'inline'
-        : rawFormat === 'md' || rawFormat === 'html'
-            ? rawFormat
-            : 'text';
-    io.out(generateAiReport({
-        reader,
-        cwd: io.cwd,
-        request: {
-            baselineInput,
-            baselineCommit,
-            format,
-            emphasis: wp ? 'workpackages' : flat ? 'flat' : 'default',
-            requireAccepted,
-            decisionEmphasis: decisions ? 'all' : 'open-only',
-            activeRoster,
-        },
-        ...(width !== undefined ? { width } : {}),
-        ...(io.env !== undefined ? { env: io.env } : {}),
-    }).output);
+    // Every format is a deterministic read over the folded log. The default human view is
+    // the conductor; --flat explicitly requests the legacy bucket projection. JSON preserves
+    // its established flat machine contract unless --wp is explicit, so --flat is rejected there
+    // instead of being silently accepted as a no-op. Contextual prose remains advisory agent work;
+    // no report format invokes an adapter, gateway, subprocess, or model.
+    const options = {
+        baselineCommit: resolveCommit(io.cwd, opt(flags, 'commit')),
+        requireAccepted,
+        // The owner-facing conductor always classifies decision dossiers. JSON keeps its
+        // established opt-in decision payload, while --flat retains the legacy opt-in.
+        decisions: requestedDecisions || (!flat && format !== 'json'),
+        wpTree: wp || (!flat && format !== 'json'),
+        activeRoster,
+    };
+    // Criterion 21 — the report's window runs from the first recorded event to NOW. The clock is injected
+    // HERE (the same boundary pattern as `workspace-activity --now`) so the library stays clockless and a
+    // committed fixture stays byte-reproducible by pinning `--now`.
+    const nowArg = opt(flags, 'now');
+    if (nowArg !== undefined && Number.isNaN(new Date(nowArg).getTime())) {
+        throw new DomainError('--now must be an ISO timestamp');
+    }
+    const now = nowArg ?? new Date().toISOString();
+    // Criterion 25 — the EXPLICIT owner request for sub-WP rows. Without it the reading unit follows the
+    // window: the WP on a long one, the sub-level on a short one.
+    const subWp = assertBooleanFlag(flags, 'sub-wp');
+    const reader = new TrackReader(ctx.eventsPath);
+    if (inline) {
+        io.out(reportInline(reader, options, width === undefined ? {} : { width }));
+    }
+    else if (format === 'html') {
+        io.out(reportHtml(reader, options, now, subWp));
+    }
+    else {
+        io.out(reportText(reader, options, format, now, subWp));
+    }
     return 0;
 }
 function emitSnapshot(flags, ctx, allowRaw) {
@@ -996,6 +1081,43 @@ function cmdQuery(args, ctx) {
     }, { baselineCommit: resolveCommit(io.cwd, opt(flags, 'commit')) }, fmt(flags)));
     return 0;
 }
+/**
+ * List decision dossiers without a renderer cap. `structure` makes the prose-only migration state explicit;
+ * only a structured dossier has durable alternatives + a durable recommendation to render as a choice.
+ */
+function cmdDecisionLs(args, ctx) {
+    const { io } = ctx;
+    const { positional, flags } = parseFlags(args.slice(1));
+    if (positional.length > 0)
+        throw new DomainError(`unexpected decision ls argument(s): ${positional.join(' ')}`);
+    assertOnlyFlags(flags, ['workspace', 'outcome', 'format', 'commit']);
+    for (const name of ['workspace', 'outcome', 'format', 'commit'])
+        assertValueFlag(flags, name);
+    const format = fmt(flags);
+    const baselineCommit = resolveCommit(io.cwd, opt(flags, 'commit'));
+    const reader = new TrackReader(ctx.eventsPath);
+    const workspace = opt(flags, 'workspace');
+    const outcome = opt(flags, 'outcome') !== undefined ? oneOf(req(flags, 'outcome'), DECISION_OUTCOMES, '--outcome') : undefined;
+    const rows = reader.decisionDossiers({ baselineCommit })
+        .filter((decision) => (workspace === undefined || decision.workspace === workspace) && (outcome === undefined || decision.outcome === outcome))
+        .map(({ dossier, ...decision }) => ({
+        ...decision,
+        options: dossier.options,
+        ...(dossier.recommendation !== undefined ? { recommendation: dossier.recommendation } : {}),
+    }));
+    if (format === 'json') {
+        io.out(`${JSON.stringify(rows, null, 2)}\n`);
+        return 0;
+    }
+    const lines = rows.map((decision) => {
+        const safe = (value) => displayText(value, format);
+        const recommendation = safe(decision.recommendation?.optionId ?? '-');
+        const line = `${safe(decision.id)} · ${safe(decision.workspace)} · ${safe(decision.outcome)} · ${safe(decision.structure ?? 'unstructured')} · options:${decision.options.length} · recommendation:${recommendation} — ${safe(decision.title)}`;
+        return format === 'md' ? `- ${line}` : line;
+    });
+    io.out(lines.length > 0 ? `${lines.join('\n')}\n` : '');
+    return 0;
+}
 /**
  * `track workspace-activity --workspace <id> [--baseline-commit <sha>] [--now <iso>] [--idle-ms <ms>]
  * [--format json|text]` — a poll surface over the shipped, CLOCKLESS `TrackReader.workspaceActivity`
@@ -1079,6 +1201,15 @@ async function cmdFocus(args, ctx, _noStore) {
     const { io } = ctx;
     const FOCUS_USAGE = 'usage: track focus <decision-id> --workspace <w> [--format terminal|md|html] [--baseline-commit <sha>]\n';
     const { positional, flags } = parseFlags(args);
+    try {
+        assertOnlyFlags(flags, ['workspace', 'format', 'baseline-commit']);
+        for (const name of ['workspace', 'format', 'baseline-commit'])
+            assertValueFlag(flags, name);
+    }
+    catch (error) {
+        io.err(`error: ${error instanceof Error ? error.message : String(error)}\n`);
+        return 2;
+    }
     // decision-id is positional + REQUIRED; --workspace is a REQUIRED flag (both gate at the CLI boundary
     // with rc=2 + usage, never reaching focus). Validate BEFORE the dynamic import so a usage error is
     // independent of whether focus is installed.
@@ -1098,6 +1229,15 @@ async function cmdFocus(args, ctx, _noStore) {
         io.err(`error: ${error instanceof Error ? error.message : String(error)}\n`);
         return 2;
     }
+    const baselineCommit = resolveCommit(io.cwd, opt(flags, 'baseline-commit'));
+    const decision = new TrackReader(ctx.eventsPath)
+        .report({ baselineCommit, decisions: true })
+        .decisions
+        ?.find((candidate) => candidate.id === decisionId);
+    if (decision !== undefined && decision.workspace !== workspace) {
+        io.err(`error: decision ${decisionId} belongs to workspace ${decision.workspace}, not ${workspace}\n`);
+        return 3;
+    }
     // Load the focus render binding + core. focus is an integrated dependency → a MODULE_NOT_FOUND means the
     // integrated focus renderer is unavailable: map it to rc=1 + a helpful hint (NOT a stack trace).
     let focusTrack;
@@ -1118,7 +1258,7 @@ async function cmdFocus(args, ctx, _noStore) {
     try {
         // PURE / read-only / clockless: `readAt` is supplied at the CLI boundary (track holds no clock), the
         // baseline commit resolves HEAD/refs/short-SHA → 40-char, and `ctx.eventsPath` is the single store.
-        const doc = focusTrack.readDecisionDossier(ctx.eventsPath, { workspace, baselineCommit: resolveCommit(io.cwd, opt(flags, 'baseline-commit')), decisionId }, new Date().toISOString());
+        const doc = focusTrack.readDecisionDossier(ctx.eventsPath, { workspace, baselineCommit, decisionId }, new Date().toISOString());
         const rendered = format === 'md' ? core.renderMd(doc) : format === 'html' ? core.renderHtml(doc, HTML_HOOKS) : core.renderTerminal(doc);
         io.out(rendered.endsWith('\n') ? rendered : `${rendered}\n`);
         return 0;