aiki-cli 0.3.1 → 0.3.2

package/CHANGELOG.md

@@ -1,18 +1,25 @@
 # Changelog
 
-## Unreleased
+## 0.3.2 — 2026-07-17
 
 ### Added
 - Public URL snapshots for idea prompts, including an npm registry adapter, private-network rejection,
-  auditable `FETCHED` / `BLOCKED` / `FAILED` status, and a research-mode gate that stops before model calls
+  auditable `FETCHED` / `BLOCKED` / `FAILED` status, and a full-council gate that stops before model calls
   when a supplied source cannot be read.
 - Requested-output planning: prompts that ask for a feature list or implementation plan now carry that
   requirement through the decision contract, the existing planner call, machine JSON, Markdown, and HTML.
 
 ### Changed
-- Explicit research wording selects research mode deterministically when `--mode` is absent; an explicit
-  mode remains authoritative. Preflight asks zero to four questions and may not repeat facts already present
-  in the user prompt or a fetched source.
+- **Report v4 answer-first decisions** — reports now lead with the requested deliverables and chair reasoning,
+  substitute readable claim labels for internal ids, dedupe and cap claim-named conditions, frame/cap risks,
+  summarize each council seat (including a plain-language `weak_seat` warning), and distinguish FACTUAL
+  claims from JUDGMENT calls so verification priority and coverage describe checkable facts honestly.
+  Deliverable detection now combines model-backed readings with a widened fallback that hears requests for
+  standout or "ultra-level" features.
+- `council` now includes the complete source-investigation path, 8–10-call allowance, 12-call repair budget,
+  and 45-minute deadline. `research` remains accepted as a compatibility alias with identical behavior.
+  Preflight asks zero to four questions and may not repeat facts already present in the user prompt or a
+  fetched source.
 - Reader-facing report sections use human claim text instead of internal graph ids such as `G1`; raw ids
   remain in machine artifacts and the Markdown technical audit.
 

package/README.md

@@ -50,9 +50,8 @@ stop copy-pasting between them by hand.
 - **Evidence-grounded decisions.** Supply local sources with `--evidence`; Aiki records their paths and
   hashes, checks freshness and citations, independently verifies selected load-bearing claims, and shows the
   remaining coverage gaps before the chair.
-- **Three bounded modes.** Use `quick` for one structured analyst, `council` for bounded multi-model
-  deliberation, or `research` for current-fact work. Explicit research wording selects `research`
-  deterministically; `--mode` always overrides it.
+- **Two bounded behaviors.** Use `quick` for one structured analyst or `council` for the full multi-model
+  decision council with source investigation. `research` remains accepted as an alias for `council`.
 - **A decision dossier, not an essay.** Reports lead with the recommendation, verified evidence coverage,
   decisive facts, first action, strongest counter-case, and critical unknowns. Financial and threshold-heavy
   decisions can include graph-anchored numbers, payback, option commitments, and a go/no-go tripwire.
@@ -236,7 +235,7 @@ Plain text is never charged silently — you get a confirm step before any run s
 aiki run idea-refinement "a fridge-photo-to-recipe app for busy parents"
 aiki run idea-refinement "an early idea" --mode quick             # one structured analyst; no council claim
 aiki run idea-refinement ./idea.md
-aiki run idea-refinement ./idea.md --mode research --evidence ./research/  # grounded, source-verifying council
+aiki run idea-refinement ./idea.md --mode council --evidence ./research/   # grounded, source-verifying council
 aiki run code-review --base main             # review this branch vs main
 aiki run code-review --diff ./changes.patch  # review a patch file
 aiki run code-review --cheap                 # Gemini+Codex review, Claude judges only disputes (~⅓ the Opus)
@@ -251,7 +250,7 @@ reads provider credential directories.
 
 Public `http(s)` links in an idea are snapshotted once before model calls and stored in
 `00a-url-sources.json`; every preflight reader and analyst sees that same text. npm package links use the
-registry metadata API. A snapshot records `FETCHED`, `BLOCKED`, or `FAILED` honestly. In research mode,
+registry metadata API. A snapshot records `FETCHED`, `BLOCKED`, or `FAILED` honestly. In full council mode,
 an unreadable supplied link stops before paid calls and asks for pasted text or a public export instead of
 letting the council guess or grill you for facts that should have come from the link.
 
@@ -269,10 +268,9 @@ only the disputes → report.
 complementary analyst lanes → deterministic claim/evidence graph audit → only decision-critical verification
 or rebuttal → evidence-linked chair → validation planner. The report is a graph-backed **decision dossier**,
 not an essay.
-Choose `--mode quick` for one structured analyst, `--mode council` for the full decision council, or
-`--mode research` for source-grounded current-fact work. Without a flag, the default is council unless the
-request explicitly asks to research, browse, look up, or check current sources; that conservative rule is
-deterministic, and an explicit flag wins:
+Choose `--mode quick` for one structured analyst or `--mode council` for the full source-investigating decision
+council. `--mode research` is retained as a compatibility alias and runs the same council. Without a flag, the
+default is the full council:
 
 - a **reader-first decision card** — recommendation, verified evidence coverage, decisive facts, first action,
   strongest counter-case, and critical unknowns before audit detail
@@ -360,8 +358,8 @@ This is the part that makes aiki trustworthy to point at a real repo:
 ## Costs & limits
 
 - **Runs cost real model calls** against your existing CLI subscriptions/quota. Idea refinement is nominally
-  **3 calls in quick**, **6–8 in council**, or **8–10 in research** (schema repairs can add calls within the
-  mode-aware budget); code review is about **5**. `aiki run` shows the mode, range, budget, and reserved
+  **3 calls in quick** or **8–10 in the full council** (`research` is the same behavior; schema repairs can add
+  calls within the mode-aware budget); code review is about **5**. `aiki run` shows the mode, range, budget, and reserved
   chair/planner calls before asking to confirm (skip with `--yes`).
 - **Not a general assistant.** Questions and "explore my whole codebase" requests are redirected, not answered
   — aiki reviews a *diff* and vets a *stated idea*.

package/dist/bench/idea-v3-rating.js

@@ -118,7 +118,7 @@ function blindId(seed) {
     return createHash('sha256').update(seed).digest('hex').slice(0, 12).toUpperCase();
 }
 /** Remove the explicit identifiers forbidden by BENCHMARK-IDEA-V3.md §4 before human rating. §4 bars
- *  provider/model names, run ids, arm labels, AND costs — so the R7 dossier's §9 "Run details" cost
+ *  provider/model names, run ids, arm labels, AND costs — so the dossier's "Run details" cost
  *  block (mode, call counts, categories, per-provider calls, model time, degradation flags) and the
  *  inline `> ⚠ DEGRADED: <flag tokens>` callouts are redacted too; the DEGRADED marker and any prose
  *  note stay, since those are quality self-assessments raters legitimately read. */

package/dist/cli/index.js

@@ -51,7 +51,7 @@ program
     .option('--head <ref>', 'code-review: head git ref to diff to (default HEAD)')
     .option('--diff <file>', 'code-review: review a patch file instead of computing a git diff')
     .option('--evidence <path>', 'idea-refinement: local source file/directory (stores paths + hashes, not copies)')
-    .option('--mode <mode>', 'idea-refinement: quick | council | research (default council; explicit research wording selects research)')
+    .option('--mode <mode>', 'idea-refinement: quick | council (research is an alias for council)')
     .option('--cheap', 'code-review: Gemini+Codex review, Claude judges only disputes (~⅓ the Opus; experimental)')
     .option('--yes', 'skip the run-cost confirmation prompt')
     .action(async (workflow, input, opts) => {

package/dist/cli/run.js

@@ -21,7 +21,7 @@ export function estimateRun(workflow, opts = {}) {
     return {
         calls: plan.maxCalls,
         opus: mode === 'quick' ? 1 : 2,
-        minCalls: mode === 'research' ? 8 : plan.baseCalls,
+        minCalls: plan.maxCalls - plan.reservedCalls,
         reserved: plan.reservedCalls,
     };
 }

package/dist/council/view.js

@@ -3,7 +3,7 @@ import { basename, join } from 'node:path';
 import { DISPLAY_NAME } from '../providers/types.js';
 import { RoleOutput as RoleOutputSchema } from '../schemas/index.js';
 import { deriveAudit, deriveScorecard, mergeOpenQuestions } from '../orchestration/stages/s10-render.js';
-import { readerClaimLabel, readerClaimRefs, renderDecisionDossierMarkdown, stripReaderClaimIds } from '../orchestration/decision-dossier.js';
+import { buildReaderProjection, claimLookup, readerClaimLabel, readerClaimRefs, renderDecisionDossierMarkdown, stripReaderClaimIds } from '../orchestration/decision-dossier.js';
 import { IDEA_RUBRIC } from '../workflows/idea-refinement.js';
 import { listArtifacts, readJsonArtifact } from '../storage/runs-read.js';
 import { adaptIdeaOutput, adaptLegacyDecisionGraph } from '../orchestration/legacy-idea-adapter.js';
@@ -377,12 +377,16 @@ function renderDossierIdeaBody(report) {
     const criticalUnknowns = report.criticalUnknowns?.length ? report.criticalUnknowns : report.openQuestions.slice(0, 3);
     const tone = dossier.recommendation.status === 'ACCEPTED' ? 'good'
         : dossier.recommendation.status === 'REJECTED' ? 'risk' : 'caution';
-    const conditions = dossier.recommendation.conditions.length
-        ? `<details class="decision-details"><summary>Conditions and decision state</summary><div><p><strong>Internal state:</strong> ${escapeHtml(dossier.recommendation.status)}</p><ul>${dossier.recommendation.conditions.map((condition) => `<li>${escapeHtml(condition.text)}</li>`).join('')}</ul></div></details>`
+    const labelFor = claimLookup(report);
+    // Substitute ids then dedupe before escaping, mirroring the markdown renderer: old stored artifacts
+    // may carry duplicate / bare-G# condition strings.
+    const conditionItems = [...new Set(dossier.recommendation.conditions.map((condition) => stripReaderClaimIds(condition.text, labelFor)))];
+    const conditions = conditionItems.length
+        ? `<details class="decision-details"><summary>Conditions and decision state</summary><div><p><strong>Internal state:</strong> ${escapeHtml(dossier.recommendation.status)}</p><ul>${conditionItems.map((item) => `<li>${escapeHtml(item)}</li>`).join('')}</ul></div></details>`
         : '';
     const startHere = dossier.experiments.actions[0]?.action ?? 'No executable next step was produced.';
-    const recommendationLead = stripReaderClaimIds(dossier.recommendation.reason);
-    const recommendationDetail = stripReaderClaimIds(dossier.recommendation.summary);
+    const recommendationLead = stripReaderClaimIds(dossier.recommendation.reason, labelFor);
+    const recommendationDetail = stripReaderClaimIds(dossier.recommendation.summary, labelFor);
     const factLabels = ['Decisive result', 'Consequence', 'Supporting signal'];
     const facts = keyFindings.slice(0, 3).map((finding, index) => `<article class="decision-fact"><span>${factLabels[index]}</span><p>${escapeHtml(finding)}</p></article>`).join('');
     const snapshot = report.decisionSnapshot;
@@ -470,7 +474,10 @@ function renderDossierIdeaBody(report) {
     <span>by provider ${escapeHtml(Object.entries(report.receipt.byProvider).map(([provider, count]) => `${providerName(provider)} ${count}`).join(', ') || 'none')}</span>
     <span>model time ${(report.receipt.modelTimeMs / 1000).toFixed(1)}s</span>
   </div>${report.flags.length ? `<div class="warns">${report.flags.map((flag) => `<span class="warn">⚑ ${escapeHtml(flag)}</span>`).join('')}</div>` : '<p class="muted">No degradation flags.</p>'}`;
-    const risks = dossierTable(['Risk', 'Severity'], report.risks.map((item) => [item.risk, item.severity]));
+    const shownRisks = report.risks.slice(0, 8);
+    const risks = `${dossierTable(['Risk', 'Severity'], shownRisks.map((item) => [item.risk, item.severity]))}${report.risks.length > shownRisks.length
+        ? `<p class="muted">${report.risks.length - shownRisks.length} lower-severity items — more in the technical audit (full list in the stored JSON).</p>`
+        : ''}`;
     const questions = report.openQuestions.length
         ? `<ul class="checks">${report.openQuestions.map((question) => `<li>${escapeHtml(question)}</li>`).join('')}</ul>`
         : '<p class="muted">No verdict-flipping open question was recorded.</p>';
@@ -500,7 +507,37 @@ function renderDossierIdeaBody(report) {
         section('08', 'What the council added', `${shared}${unique}<h3>Verified unique contributions</h3>${contributions}`, 340),
         section('09', 'Run details', runDetails, 380),
     ].join('');
-    return `${stripReaderClaimIds(readerBody)}${section('10', 'Technical audit', technical, 420)}`;
+    return `${stripReaderClaimIds(readerBody, labelFor)}${section('10', 'Technical audit', technical, 420)}`;
+}
+function renderReaderBriefIdeaBody(report) {
+    const dossier = report.dossier;
+    const projection = buildReaderProjection(report);
+    const tone = dossier.recommendation.status === 'ACCEPTED' ? 'good'
+        : dossier.recommendation.status === 'REJECTED' ? 'risk' : 'caution';
+    const hero = `<section class="verdict tone-${tone} reveal" style="animation-delay:60ms">
+    <span class="pill">Recommendation</span>
+    <p class="verdict-text">${escapeHtml(projection.headline)}</p>
+    <p class="verdict-detail">${escapeHtml(projection.bottomLine)}</p>
+  </section>`;
+    const warnings = projection.warnings.length || projection.notices.length
+        ? `<div class="warns">${projection.warnings.map((warning) => `<span class="warn">⚑ ${escapeHtml(warning.message)}</span>`).join('')}${projection.notices.map((notice) => `<span class="warn">ⓘ ${escapeHtml(notice.message)}</span>`).join('')}</div>`
+        : '';
+    const snapshot = projection.snapshot ? section('', 'Decision numbers', `${dossierTable(['Metric', 'Value', 'What it means'], projection.snapshot.decisiveNumbers.map((item) => [item.label, item.value, item.meaning]))}${projection.snapshot.payback ? `<div class="action-callout"><span>Payback · ${escapeHtml(projection.snapshot.payback.status.replaceAll('_', ' '))}</span><p>${escapeHtml(projection.snapshot.payback.result)} — ${escapeHtml(projection.snapshot.payback.basis)}</p></div>` : ''}<h3>Options at a glance</h3>${dossierTable(['Path', 'Commitment', 'Basis', 'Trade-off'], projection.snapshot.options.map((item) => [item.label, item.commitment, item.commitmentKind.replace('_', ' '), item.tradeoff]))}${projection.snapshot.tripwire ? `<div class="action-callout"><span>Go/no-go tripwire</span><p><strong>${escapeHtml(projection.snapshot.tripwire.metric)}: ${escapeHtml(projection.snapshot.tripwire.threshold)}</strong> — ${escapeHtml(projection.snapshot.tripwire.decisionRule)}</p></div>` : ''}`, 80) : '';
+    const editorial = projection.sections.map((item, index) => section(String(index + 1).padStart(2, '0'), item.heading, `<p class="lede">${escapeHtml(item.summary)}</p>${item.bullets.length
+        ? `<ul class="reasons">${item.bullets.map((bullet) => `<li>${escapeHtml(bullet)}</li>`).join('')}</ul>`
+        : ''}`, 100 + index * 40)).join('');
+    const backlog = projection.featureBacklog;
+    const features = backlog ? section('', 'Feature priorities', `<div class="feature-groups">${[
+        ['MUST', 'Build for the first useful release', backlog.must],
+        ['SHOULD', 'Add after the golden path is stable', backlog.should],
+        ['LATER', 'Keep outside the current build', backlog.later],
+    ].filter(([, , items]) => items.length).map(([priority, description, items]) => `<section class="feature-group priority-${priority.toLowerCase()}"><header><div><span>${priority}</span><h4>${description}</h4></div><strong>${items.length}</strong></header><ul>${items.map((item) => `<li><div class="feature-title"><strong>${escapeHtml(item.feature)}</strong><span>${item.effort}</span></div><p>${escapeHtml(item.user_value)}</p><small>${escapeHtml(item.rationale)}</small></li>`).join('')}</ul></section>`).join('')}</div>${backlog.wont.length ? `<h3>Not in this scope</h3><ul class="checks">${backlog.wont.map((item) => `<li><strong>${escapeHtml(item.feature)}</strong> — ${escapeHtml(item.reason)}</li>`).join('')}</ul>` : ''}`, 340) : '';
+    const buildPlan = projection.implementationPlan ? section('', 'Build plan', `<ol class="milestone-list">${projection.implementationPlan.milestones.map((milestone) => `<li><div class="milestone-marker"><span>${String(milestone.order).padStart(2, '0')}</span><small>${escapeHtml(milestone.timebox)}</small></div><article><h4>${escapeHtml(milestone.outcome)}</h4><ul>${milestone.tasks.map((task) => `<li>${escapeHtml(task)}</li>`).join('')}</ul><div class="acceptance"><span>Done when</span><p>${escapeHtml(milestone.acceptance_test)}</p></div></article></li>`).join('')}</ol>`, 380) : '';
+    const caveats = projection.caveats.length ? section('', 'Top caveats', `<ul class="checks">${projection.caveats.map((item) => `<li>${escapeHtml(item)}</li>`).join('')}</ul>`, 420) : '';
+    const sources = projection.sources.length ? section('', 'Sources', `<ul class="agree">${projection.sources.map((source) => `<li><p>${source.url ? `<a href="${escapeHtml(source.url)}" rel="noopener noreferrer">${escapeHtml(source.label)}</a>` : escapeHtml(source.label)}</p>${source.citedFor.length ? `<small>Cited for: ${source.citedFor.map(escapeHtml).join('; ')}</small>` : ''}</li>`).join('')}</ul>`, 460) : '';
+    const nextStep = section('', 'Next step', `<div class="action-callout"><span>Do this now</span><p>${escapeHtml(projection.nextStep)}</p></div>`, 500);
+    const audit = `<details class="fold council-audit"><summary>Council audit — reasoning, evidence, dissent, and run receipt</summary><div class="fold-body">${renderDossierIdeaBody(report)}</div></details>`;
+    return `${hero}${warnings}${snapshot}${editorial}${features}${buildPlan}${caveats}${sources}${nextStep}${audit}`;
 }
 function renderLegacyIdeaBody(view) {
     const risks = view.risks ?? [];
@@ -891,19 +928,22 @@ function renderTechnical(view) {
 export function renderCouncilHtml(view) {
     const isIdea = view.workflow !== 'code-review';
     const quick = isIdea && view.mode === 'quick';
+    const hasReaderBrief = Boolean(view.decisionReport?.dossier.readerBrief);
     const kicker = quick ? 'aiki · quick analysis' : isIdea ? 'aiki · idea refinement' : 'aiki · code review';
     const title = isIdea && view.topic ? cleanTopic(view.topic) : (isIdea ? 'Idea refinement' : 'Code review');
     const panel = view.columns.map((c) => c.title);
-    const metaBits = [
+    const metaBits = hasReaderBrief ? [] : [
         panel.length ? `${quick ? 'Analyst' : 'Panel'}: ${panel.join(' · ')}` : '',
         !quick && view.moderator ? `Chair: ${view.moderator}` : '',
         view.calls,
     ].filter(Boolean);
-    const flags = view.flags.length
+    const flags = !hasReaderBrief && view.flags.length
         ? `<div class="warns">${view.flags.map((f) => `<span class="warn">⚑ ${escapeHtml(f.replaceAll('_', ' '))}</span>`).join('')}</div>`
         : '';
     const body = isIdea && view.decisionReport?.dossier
-        ? renderDossierIdeaBody(view.decisionReport)
+        ? view.decisionReport.dossier.readerBrief
+            ? renderReaderBriefIdeaBody(view.decisionReport)
+            : renderDossierIdeaBody(view.decisionReport)
         : quick ? renderQuickIdeaBody(view) : isIdea ? renderIdeaBody(view) : renderReviewBody(view);
     // Embed the report as Markdown for the Copy button. Escape "<" so a "</script>" in content can't break out.
     const md = JSON.stringify(councilMarkdown(view)).replace(/</g, '\\u003c');
@@ -928,14 +968,14 @@ html{-webkit-text-size-adjust:100%;}
 body{margin:0;background:var(--paper);color:var(--ink);font-family:var(--sans);font-size:16px;line-height:1.6;}
 main{max-width:940px;margin:0 auto;padding:34px 24px 90px;}
 a{color:var(--accent);}
-h1{font-family:var(--serif);font-weight:600;letter-spacing:-.025em;}
+h1{font-family:var(--sans);font-weight:650;letter-spacing:-.01em;}
 h2,h3,h4{font-family:var(--sans);font-weight:650;letter-spacing:-.01em;}
 p{margin:0 0 .6em;}
 
 /* masthead */
 .mast{border-bottom:1px solid var(--ink);padding-bottom:22px;margin-bottom:30px;}
 .kicker{font-family:var(--mono);font-size:11.5px;letter-spacing:.22em;text-transform:uppercase;color:var(--accent);}
-.mast h1{font-size:clamp(32px,5.4vw,50px);line-height:1.05;margin:12px 0 18px;max-width:18ch;}
+.mast h1{font-size:clamp(28px,4.6vw,42px);line-height:1.12;margin:12px 0 16px;}
 .mmeta{display:flex;flex-wrap:wrap;gap:7px;}
 .mmeta span{font-family:var(--mono);font-size:11.5px;color:var(--soft);border:1px solid var(--line);background:var(--panel);border-radius:100px;padding:3px 10px;}
 .warns{margin-top:12px;display:flex;flex-wrap:wrap;gap:8px;}

package/dist/orchestration/context.js

@@ -15,7 +15,7 @@ import { extractJson } from '../providers/adapter-core.js';
 import { detect } from '../providers/detect.js';
 import { probeFlags } from '../providers/probe.js';
 import { replayKey } from '../storage/replay.js';
-import { callCategory, defaultBudgetFor, IDEA_MODE_PLANS, isOptionalStage, LEGACY_DEFAULT_BUDGET } from './modes.js';
+import { callCategory, defaultBudgetFor, defaultDeadlineFor, IDEA_MODE_PLANS, isOptionalStage, LEGACY_DEFAULT_BUDGET } from './modes.js';
 /** Bracket a stage call with the TUI's start/end events (no-op headless). A thrown StageError marks
  *  the row `failed` and re-propagates unchanged — the engine's failure handling is untouched. */
 export async function runStage(ctx, id, fn) {
@@ -100,7 +100,7 @@ export class RunCtx {
         this.budget = { limit: opts.budget ?? defaultBudgetFor(opts.workflow, this.mode), used: 0 };
         this.handles = new Map(opts.handles.map((h) => [h.id, h]));
         this.signal = opts.signal;
-        this.deadlineMs = opts.deadlineMs ?? DEFAULT_DEADLINE_MS;
+        this.deadlineMs = opts.deadlineMs ?? defaultDeadlineFor(opts.workflow, this.mode);
         this.now = opts.now ?? Date.now;
         this.deadlineAt = this.now() + this.deadlineMs;
         this.replay = opts.replay;
@@ -174,7 +174,7 @@ export class RunCtx {
                 timeoutMs: req.timeoutMs ?? DEFAULT_CALL_TIMEOUT_MS,
                 expectJson: req.expectJson,
                 readOnly: true,
-                research: this.mode === 'research' && stage.startsWith('S4'),
+                research: this.workflow === 'idea-refinement' && this.mode !== 'quick' && stage.startsWith('S4'),
                 signal: this.signal, // Ctrl+C kills the in-flight child (T8); undefined headless
             }, handle.flags);
             // Only REAL calls count toward the ledger/budget; a replayed call is free and already recorded in