aiki-cli 0.3.1 → 0.3.2

package/dist/skills/idea-refinement/planner.md

@@ -1,25 +1,31 @@
-# Planner playbook — decisive validation
+# Answer editor playbook — useful first, honest throughout
 
-You write the next tests after the council has already judged the idea. Do not plan the build.
-Plan only the cheapest validation work that can change the decision.
+You turn the council's work into the answer the user actually asked for. Lead with a clear product
+recommendation, select the strongest ideas from both seats, and make the result practical enough to act on.
 
-## Order
-- Start with upheld HIGH risks. If one fails, the idea should stop or change shape before any other work.
-- Then cover blind spots that could hide a blocker.
-- Then answer open questions that would flip the verdict.
+## Reader answer
+- Answer the original task directly. Do not narrate the council process.
+- Prefer specific product language: what to build, why users care, what makes it memorable, and what to do first.
+- Combine complementary proposals; remove duplicates and cautious filler.
+- Explain the user value or demo payoff of each standout idea, not merely its feature name.
+- Keep facts inside supported findings and sources. Present unevidenced product choices as recommendations,
+  never as established market facts.
+- Chair output is decision reasoning, not evidence. Reframe its unsupported certainty as a recommendation,
+  risk, or hypothesis unless the proposition also appears in supported findings.
+- Use plain-language caveats only when they could change the recommendation.
 
-## Action quality
-- Every action must be concrete enough that a person can run it this week.
-- Prefer interviews, landing-page smoke tests, pricing tests, manual concierge trials, prototype probes,
-  competitor checks, and policy checks over implementation work.
-- Tie every action to exactly one anchor in `validates`.
+## Requested deliverables
+- When a feature backlog is requested, make MUST the smallest compelling golden path. Use SHOULD and LATER
+  for real prioritization; WONT protects the concept from scope creep.
+- When an implementation plan is requested, give an outcome-driven build sequence with observable acceptance tests.
+- The reader brief should summarize these deliverables rather than repeat every field verbatim.
 
-## Kill signals
-- A kill signal is not "learn more". It is the result that stops, pivots, or narrows the idea.
-- Make the signal observable: a count, threshold, refusal pattern, legal blocker, cost ceiling, or
-  behavior that contradicts the assumption.
+## Validation actions
+- Keep 1–4 actions. Start with the cheapest unresolved risk that could stop or reshape the recommendation.
+- Every action must be concrete enough to run this week and tie to exactly one supplied anchor.
+- A kill signal must be observable: a threshold, refusal pattern, blocker, cost ceiling, or failed behavior.
 
 ## Do not
-- No product roadmap, scaffolding plan, architecture plan, or feature list.
-- No action for a claim the chair already settled.
-- No vague market research. No unanchored action.
+- No graph ids, verification labels, confidence formulas, audit vocabulary, or model-process commentary in reader_brief.
+- No generic "do more research" action.
+- No invented source or unsupported hype.

package/dist/skills/idea-refinement/rebuttal.md

@@ -0,0 +1,15 @@
+# Rebuttal playbook — answer the strongest opposition
+
+Add to your base instructions; the schema and caps are unchanged and always win.
+
+## Review in this order
+1. Steelman the opposing position in one line before answering it.
+2. Name its biggest blind spot: the assumption it never checks. Attack that assumption with supplied
+   evidence IDs.
+3. Name what both sides missed. Use NARROW or UNRESOLVED instead of pretending it was covered.
+
+## Stance discipline
+- CONCEDE when the evidence beats your position. An early concession on a lost point preserves
+  credibility for the decision-critical dispute.
+- Never change a stance word without a supplied evidence ID.
+- Prefer a precise unresolved boundary over a broad defensive counterclaim.

package/dist/skills/idea-refinement/verifier.md

@@ -0,0 +1,17 @@
+# Verifier playbook — try to disprove the claim
+
+Add to your base instructions; the schema and caps are unchanged and always win.
+
+## Refute first
+- Assume each claim is wrong. Hunt for the disconfirming reading of the same supplied evidence.
+- Confirm only after a serious refutation attempt fails.
+- Agreement without attempted refutation is analytically NOT_CHECKED, not SUPPORTED; express that
+  uncertainty with the closest allowed schema status rather than returning VERIFIED.
+- Judge the evidence, never its author.
+
+## Evidence discipline
+- Treat CONFLICTED as a finding, not an output enum: use the allowed status and record the exact two
+  clashing readings in the reasoning.
+- Never verify a value judgment as fact. Numbers, deadlines, and rule text can be checked; taste and
+  strategy remain positions for the chair.
+- Include one concise sentence describing the method used for each verification.

package/dist/workflows/idea-refinement.js

@@ -42,7 +42,7 @@ export function buildIdeaRubric(domainDimensions = []) {
 }
 /** Idea S4 analyst template. R6 fills every slot deterministically before the parallel scout calls. */
 export const IDEA_S4_ANALYST_TEMPLATE = `ROLE: Independent analyst on a decision panel. You work ALONE; you will not see
-other analysts' output. Be adversarial toward the idea, not polite.
+other analysts' output. Improve the strongest version and pressure-test it honestly within your assigned lane.
 
 TASK CONTRACT: {{INTENT_CONTRACT_JSON}}
 INPUT DOCUMENT: read the file at {{INPUT_PATH}}{{SKILL}}
@@ -54,7 +54,10 @@ Produce ONLY JSON matching {{S4_SCHEMA_REF}} with:
 - task_echo: restate the task in ≤2 sentences (drift check).
 - strongest_version: the best honest version of this idea in ≤150 words.
 - positions: explicit claim positions with local_id, proposition, rubric dimension_id, stance
-  SUPPORT|OPPOSE|MIXED|UNKNOWN, basis EVIDENCE|INFERENCE|ASSUMPTION, load_bearing, if_false
+  SUPPORT|OPPOSE|MIXED|UNKNOWN, basis EVIDENCE|INFERENCE|ASSUMPTION, nature FACTUAL when the position
+  asserts something independently checkable about the world (rules, deadlines, prices, observed CLI
+  behavior, published numbers) or JUDGMENT for a design choice, recommendation, prioritization, or
+  prediction (when unsure use JUDGMENT), load_bearing, if_false
   STOP|PIVOT|CONDITION|MINOR, concise reasoning, evidence_ids, and depends_on position ids.
 - evidence: evidence cards {id, claim_supported, source_kind USER|PRIMARY|SECONDARY|MODEL_KNOWLEDGE,
   support SUPPORTS|CONTRADICTS|CONTEXT_ONLY (exact token, no extra words), freshness CURRENT|DATED|UNKNOWN,
@@ -66,8 +69,11 @@ Produce ONLY JSON matching {{S4_SCHEMA_REF}} with:
 - coverage: one entry per rubric dimension {dimension_id, status COVERED|NOT_APPLICABLE,
   position_ids ([] when none), rationale (required for NOT_APPLICABLE)}.
 - decision_questions: questions {question, claim_ids} whose answers could change the verdict.
-Caps: at most 12 positions, 20 evidence cards, 8 calculations, 8 decision_questions.
-Rules: no motivation, no summaries of your own output, no markdown, JSON only.`;
+- deliverable_proposals: when requested_outputs includes FEATURE_BACKLOG or IMPLEMENTATION_PLAN, propose
+  concrete user-facing work as {output,title,detail,user_value,why_distinctive,evidence_ids}; otherwise [].
+  Proposals are recommendations, not factual claims. Use evidence_ids only when evidence directly supports them.
+Caps: at most 12 positions, 20 evidence cards, 8 calculations, 8 decision_questions, 8 deliverable_proposals.
+Rules: no unsupported hype, no summaries of your own output, no markdown, JSON only.`;
 /**
  * Resolve the {{SKILL}} slot before deterministic structural fill. An empty skill collapses the slot
  * to the pre-skill baseline.
@@ -77,11 +83,11 @@ export function buildAnalystTemplate(skill) {
 }
 /** R6 deterministic S4 prompt fill. No model-authored prompt generation remains. */
 export function buildAnalystPrompt(contract, inputPath, evidencePack, mode, skill) {
-    const modeRules = mode === 'research'
-        ? `\n\nMODE: research. Use provider-native read-only source investigation when available. Every current
+    const modeRules = mode !== 'quick'
+        ? `\n\nMODE: full council. Use provider-native read-only source investigation when available. Every current
 fact must have an independently checkable locator and access date. If investigation is unavailable,
 leave the claim unverified; never invent a source.`
-        : `\n\nMODE: council. Analyze independently; do not assume another seat will cover your lane.`;
+        : `\n\nMODE: quick. Analyze independently and keep unsupported claims visibly unverified.`;
     const prompt = buildAnalystTemplate(skill)
         .replace('{{INTENT_CONTRACT_JSON}}', JSON.stringify(contract))
         .replace('{{INPUT_PATH}}', inputPath)
@@ -107,6 +113,26 @@ export const IDEA_STAGES = [
     { id: 'S9b', label: 'Validation plan', role: 'judge' },
     { id: 'S10', label: 'Report', role: null },
 ];
+/** Record guarantees observed at the surviving typed S4 boundary; never infer them from prompts. */
+export function recordIdeaOutcomeFlags(ctx, contract, seats) {
+    if (ctx.mode === 'quick')
+        return;
+    const requested = (contract.requested_outputs ?? [])
+        .filter((output) => output === 'FEATURE_BACKLOG' || output === 'IMPLEMENTATION_PLAN');
+    if (requested.some((output) => seats.some((seat) => !seat.output.deliverable_proposals.some((proposal) => proposal.output === output)))) {
+        ctx.addFlag('deliverable_gap');
+    }
+    const grounded = seats.some((seat) => {
+        const cited = new Set(seat.output.positions.flatMap((position) => position.evidence_ids));
+        return seat.output.evidence.some((card) => cited.has(card.id)
+            && (card.source_kind === 'PRIMARY' || card.source_kind === 'SECONDARY')
+            && card.freshness === 'CURRENT'
+            && Boolean(card.accessed_at && (card.url || card.locator))
+            && card.support !== 'CONTEXT_ONLY');
+    });
+    if (!grounded)
+        ctx.addFlag('research_ungrounded');
+}
 /** Runs the full idea-refinement pipeline S0–S10. Throws on any fatal condition; the engine's
  *  `executeRun` wrapper turns that into a graceful failure + meta. Each stage is wrapped in
  *  `runStage` so the TUI timeline (T8) gets start/end events; headless, that's a no-op. */
@@ -116,9 +142,13 @@ export async function runIdeaRefinement(ctx, input) {
     const urlSources = await snapshotUrlSources(input);
     await ctx.writer.writeJson('url-sources', urlSources);
     const unreadableSources = urlSources.sources.filter((source) => source.status !== 'FETCHED');
-    if (ctx.mode === 'research' && unreadableSources.length > 0) {
+    const needsSourceFallback = ctx.mode !== 'quick' && unreadableSources.length > 0;
+    const hasReadableResearch = Boolean(ctx.evidencePack?.files.length)
+        || urlSources.sources.some((source) => source.status === 'FETCHED');
+    const canSearch = ctx.roles.s4.includes('codex');
+    if (needsSourceFallback && !canSearch && !hasReadableResearch) {
         const details = unreadableSources.map((source) => `${source.url} (${source.status}: ${source.error})`).join('; ');
-        throw new StageError('S0', 'SOURCE_UNREADABLE', `research stopped before model calls because a supplied source could not be read: ${details}. Paste the relevant text or provide a public export, then rerun.`);
+        throw new StageError('S0', 'SOURCE_UNREADABLE', `source investigation stopped before model calls because no source was readable and Codex search is unavailable${details ? `: ${details}` : ''}. Paste the relevant text, provide a public export, or enable Codex, then rerun.`);
     }
     const { contract, brief } = await runStage(ctx, 'S0', () => preflight(ctx, input, IDEA_RUBRIC.map((item) => item.label), urlSources));
     const grilledInput = renderDecisionInput(input, brief, urlSources);
@@ -159,19 +189,17 @@ export async function runIdeaRefinement(ctx, input) {
         await runStage(ctx, 'S10', () => s10Render(ctx, { contract, seats: kept, graph, verifications, rebuttals, judgeReport, actionPlan, rubric, original: input }));
         return;
     }
-    if (ctx.mode === 'research' && !ctx.evidencePack && !ctx.available().includes('codex')) {
-        ctx.addFlag('research_ungrounded');
-    }
     const analystPrompt = buildAnalystPrompt(contract, inputPath, ctx.evidencePack, ctx.mode, analystSkill);
     await ctx.writer.writePrompt('analyst.md', analystPrompt);
     const lanePrompts = buildLanePrompts(analystPrompt, rubric);
-    const seats = await runStage(ctx, 'S4', () => s4Analyze(ctx, lanePrompts));
+    const seats = await runStage(ctx, 'S4', () => s4Analyze(ctx, lanePrompts, needsSourceFallback));
     const { kept } = await runStage(ctx, 'S5', () => s5Drift(ctx, contract, seats));
+    recordIdeaOutcomeFlags(ctx, contract, kept);
     const positions = await runStage(ctx, 'S6', () => s6Positions(ctx, kept));
     const graph = await runStage(ctx, 'S7', () => s7DecisionGraph(ctx, positions, rubric, contract.task));
     const verifications = await runStage(ctx, 'S8', () => s8Verify(ctx, graph));
     const rebuttals = await runStage(ctx, 'S8b', () => s8bRebuttal(ctx, graph, verifications, ctx.mode));
     const judgeReport = await runStage(ctx, 'S9', () => s9Judge(ctx, contract, graph, verifications, rubric, rebuttals));
-    const actionPlan = await runStage(ctx, 'S9b', () => s9bPlan(ctx, contract, kept, graph, judgeReport));
+    const actionPlan = await runStage(ctx, 'S9b', () => s9bPlan(ctx, contract, kept, graph, judgeReport, input));
     await runStage(ctx, 'S10', () => s10Render(ctx, { contract, seats: kept, graph, verifications, rebuttals, judgeReport, actionPlan, rubric, original: input }));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aiki-cli",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "Local-first AI model council for code review and idea stress-testing using Claude Code, Codex, and Gemini/Antigravity CLIs. No API keys.",
   "type": "module",
   "license": "MIT",