aiki-cli 0.2.0

package/dist/schemas/index.js

@@ -0,0 +1,374 @@
+// Core shared zod schemas (§14). Single source of truth for every stage-boundary payload.
+//
+// Design rules honored here:
+// - Keep small; every optional field justifies itself (§14).
+// - Model-facing outputs are `.strict()`: unknown keys = validation failure → §14 repair retry.
+//   This is an anti-slop mechanic (§11): prose/extra fields cannot leak across a stage boundary.
+// - Hard list caps come straight from the plan (§12/§13); verbosity cannot impersonate rigor (§11).
+// - Internal composites we build ourselves (DisagreementMap, RunMeta) are NOT strict — we own them.
+//
+// NOT done here (deferred, out of T4 scope): §14's "export zod → skills/*/output.schema.json"
+// JSON-Schema generation. It needs a new dep and belongs with the skills system (T5+).
+import { z } from 'zod';
+// ── Enums shared across schemas ─────────────────────────────────────────────
+/** Provider ids (mirrors providers/types.ts PROVIDER_IDS; `agy` = Antigravity/Gemini 3.1 Pro). */
+export const ProviderIdSchema = z.enum(['claude', 'codex', 'agy']);
+/** What S1 classifies the request as. `other` is a valid contract but not a runnable workflow. */
+export const TaskTypeSchema = z.enum(['idea-refinement', 'code-review', 'other']);
+/** The two runnable v1 workflows (§12). Discriminates RoleOutput and tags RunMeta. */
+export const WorkflowIdSchema = z.enum(['idea-refinement', 'code-review']);
+// ── S1: IntentContract (§13) ────────────────────────────────────────────────
+export const IntentContract = z
+    .object({
+    task: z.string().min(1), // one-paragraph normalized restatement
+    task_type: TaskTypeSchema,
+    constraints: z.array(z.string()), // explicit constraints the user stated (may be empty)
+    unknowns: z.array(z.string()), // things the request leaves unspecified
+    success_criteria: z.array(z.string()), // what a good final output must contain
+})
+    .strict();
+// ── S2: Interpretation — per provider (§13) ─────────────────────────────────
+export const Interpretation = z
+    .object({
+    my_interpretation: z.string().min(1), // one sentence: what the model believes the user wants
+    plausible_misreadings: z.array(z.string()).max(2), // "top-2" (§13); empty is degenerate but legal
+})
+    .strict();
+// ── S0: RunBrief / contextual grill ─────────────────────────────────────────
+export const GrillQuestionAxis = z.enum([
+    'decision_frame',
+    'evaluation_lens',
+    'target_user',
+    'success_bar',
+    'non_negotiables',
+    'risk_context',
+    'evidence',
+    'alternatives',
+    'scope',
+]);
+export const RunBriefQuestion = z
+    .object({
+    id: z.string().min(1),
+    axis: GrillQuestionAxis,
+    question: z.string().min(1),
+    why_it_matters: z.string().min(1),
+    suggested_answers: z.array(z.string().min(1)).min(2).max(5),
+})
+    .strict();
+const RunBriefDraftBase = z
+    .object({
+    subject: z.string().min(1),
+    decision_frame: z.string().min(1).nullable(),
+    evaluation_lens: z.string().min(1).nullable(),
+    target_user: z.string().min(1).nullable(),
+    constraints: z.array(z.string().min(1)).max(10),
+    claims_to_test: z.array(z.string().min(1)).max(8),
+    evidence_supplied: z.array(z.string().min(1)).max(8),
+    missing_axes: z.array(z.string().min(1)).max(8),
+    questions: z.array(RunBriefQuestion).min(3).max(4),
+})
+    .strict();
+function checkQuestionIds(questions, ctx) {
+    const seen = new Set();
+    for (const q of questions) {
+        if (seen.has(q.id)) {
+            ctx.addIssue({ code: z.ZodIssueCode.custom, path: ['questions'], message: `duplicate question id: ${q.id}` });
+        }
+        seen.add(q.id);
+    }
+}
+export const RunBriefDraft = RunBriefDraftBase.superRefine((brief, ctx) => checkQuestionIds(brief.questions, ctx));
+export const GrillAnswer = z
+    .object({
+    question_id: z.string().min(1),
+    answer: z.string().min(1),
+    source: z.enum(['user', 'suggested', 'default']),
+})
+    .strict();
+export const RunBrief = RunBriefDraftBase.extend({
+    answers: z.array(GrillAnswer).min(3).max(4),
+}).superRefine((brief, ctx) => {
+    checkQuestionIds(brief.questions, ctx);
+    const questionIds = new Set(brief.questions.map((q) => q.id));
+    const answerIds = new Set();
+    for (const answer of brief.answers) {
+        if (!questionIds.has(answer.question_id)) {
+            ctx.addIssue({ code: z.ZodIssueCode.custom, path: ['answers'], message: `answer for unknown question id: ${answer.question_id}` });
+        }
+        if (answerIds.has(answer.question_id)) {
+            ctx.addIssue({ code: z.ZodIssueCode.custom, path: ['answers'], message: `duplicate answer for question id: ${answer.question_id}` });
+        }
+        answerIds.add(answer.question_id);
+    }
+    for (const q of brief.questions) {
+        if (!answerIds.has(q.id)) {
+            ctx.addIssue({ code: z.ZodIssueCode.custom, path: ['answers'], message: `missing answer for question id: ${q.id}` });
+        }
+    }
+});
+// ── S4: RoleOutput — workflow-discriminated union (§12, §13) ─────────────────
+//
+// The model output (§13) does NOT carry a `workflow` field; the engine injects the discriminator
+// before `.parse()` (S4, T5): `RoleOutput.parse({ workflow, ...modelJson })`.
+const Assumption = z
+    .object({
+    id: z.string().min(1), // "A1", "A2", ...
+    statement: z.string().min(1),
+    type: z.enum(['VERIFIABLE', 'JUDGMENT']),
+    load_bearing: z.boolean(),
+})
+    .strict();
+const Attack = z
+    .object({
+    id: z.string().min(1), // "X1", ...
+    target_assumption: z.string().min(1), // MUST reference an assumption id (validator enforces at T7)
+    argument: z.string().min(1),
+    severity: z.enum(['HIGH', 'MED', 'LOW']),
+})
+    .strict();
+export const IdeaRoleOutput = z
+    .object({
+    workflow: z.literal('idea-refinement'),
+    task_echo: z.string().min(1), // ≤2 sentence restatement (drift check, S5)
+    strongest_version: z.string().min(1), // ≤150 words
+    assumptions: z.array(Assumption).max(8),
+    attacks: z.array(Attack).max(6),
+    open_questions: z.array(z.string()).max(5),
+})
+    .strict();
+/** Defect categories a finding (and a seeded bug, T11) can carry. BENCHMARK.md's "defect class" match
+ *  is equality on this enum (off-by-one→CORRECTNESS, race→CONCURRENCY, unhandled-rejection→ERROR_HANDLING,
+ *  auth-gap→SECURITY, N+1→PERF). */
+export const FindingCategory = z.enum(['CORRECTNESS', 'SECURITY', 'CONCURRENCY', 'ERROR_HANDLING', 'PERF', 'MAINTAINABILITY']);
+export const Finding = z
+    .object({
+    id: z.string().min(1), // "F1", ...
+    file: z.string().min(1),
+    line_start: z.number().int().nonnegative(),
+    line_end: z.number().int().nonnegative(),
+    severity: z.enum(['P0', 'P1', 'P2', 'P3']),
+    category: FindingCategory,
+    claim: z.string().min(1),
+    evidence: z.string().min(1), // the code/behavior that proves it
+    suggested_fix: z.string().min(1),
+    self_confidence: z.number().min(0).max(1),
+})
+    .strict();
+export const CodeReviewRoleOutput = z
+    .object({
+    workflow: z.literal('code-review'),
+    task_echo: z.string().min(1),
+    findings: z.array(Finding).max(12),
+})
+    .strict();
+export const RoleOutput = z.discriminatedUnion('workflow', [IdeaRoleOutput, CodeReviewRoleOutput]);
+/** The exact JSON a code-review S4 reviewer returns: `CodeReviewRoleOutput` WITHOUT the `workflow`
+ *  discriminator (§13 — model output carries no `workflow`). Mirrors `IdeaRoleOutputModel` (T6); S4
+ *  validates the raw call against this, injects `workflow`, then persists as `RoleOutput` (T10). */
+export const CodeReviewRoleOutputModel = CodeReviewRoleOutput.omit({ workflow: true });
+/** The exact JSON the model returns for an idea-refinement S4 seat: `IdeaRoleOutput` WITHOUT the
+ *  `workflow` discriminator (§13 — model output carries no `workflow`). S4 validates the raw call
+ *  against this, then injects `workflow` and re-validates as `RoleOutput` before persisting.
+ *  `.omit` preserves the object's strict mode, so extra keys still trigger the §14 repair retry. */
+export const IdeaRoleOutputModel = IdeaRoleOutput.omit({ workflow: true });
+// ── S3: StagePrompts (§9, §13) ──────────────────────────────────────────────
+//
+// S3 output: the role-specific S4 prompts with every {{SLOT}} filled. Deterministic validator
+// (S3) additionally rejects any prompt still containing an unresolved `{{...}}` (§9 S3 row).
+export const StagePrompts = z
+    .object({
+    prompts: z.record(z.string(), z.string()), // role name → filled prompt (non-empty map)
+})
+    .strict();
+// ── S7: ClaimGroups — semantic grouping call output (T7, decision B refined) ──
+//
+// The one constrained model call inside S7 (run on the judge role). It receives claim IDs +
+// statements with attribution WITHHELD and returns ONLY groupings of existing IDs that mean the
+// same thing. Strict + IDs-only is the anti-blending guard: the model groups by reference, never
+// rewrites a claim. Empty `groups` = nothing merged (legal). Each group needs ≥2 IDs to be a merge.
+export const ClaimGroups = z
+    .object({
+    groups: z.array(z.array(z.string().min(1)).min(2)),
+})
+    .strict();
+// ── S8: Verification (§13) ──────────────────────────────────────────────────
+//
+// `Verification` is the per-item verdict (§9 "per-item Verification"). `VerificationSet` is the
+// actual S8 stage output: the array plus the mandatory justification when zero REFUTEs (§13).
+export const Verification = z
+    .object({
+    target_id: z.string().min(1),
+    verdict: z.enum(['CONFIRM', 'REFUTE', 'UNCERTAIN']),
+    evidence: z.string().min(1), // the verifier's own independent evidence
+    note: z.string(), // ≤2 sentences
+})
+    .strict();
+export const VerificationSet = z
+    .object({
+    verifications: z.array(Verification),
+    // Required by the S8 prompt only when the verifier issued zero REFUTEs (§13).
+    all_confirmed_justification: z.string().optional(),
+})
+    .strict();
+// ── S7: DisagreementMap (§7, §9) ────────────────────────────────────────────
+//
+// The plan (§7/§9) names only the four arrays. `Claim` shape is from §6. NOTE two under-specified
+// points resolved here as documented T4 choices, to be firmed when S6/S7 are built (T6/T7):
+//   1. §6's snippet shows singular `provider`, but its prose says merged claims carry
+//      "multi-provider attribution" → we use `providers: []` (array) to hold that attribution.
+//   2. The plan gives no element shape for `contradictions` → minimal {claim_ids, note?}.
+// These are internal (engine-built), so this schema is not `.strict()`.
+export const Claim = z.object({
+    id: z.string().min(1),
+    statement: z.string().min(1),
+    type: z.enum(['VERIFIABLE', 'JUDGMENT']),
+    providers: z.array(ProviderIdSchema).min(1), // attribution; ≥2 after an S6 merge
+    evidence: z.string().optional(),
+});
+// A dispute over a claim. For idea-refinement (T6) a contradiction is a contested assumption: one
+// or more analysts asserted the claim, and ≥1 analyst attacked it. The `attacks` ARE the dispute
+// content — they are exactly the "disputed items + evidence" the S8 verifier loop consumes (§9 S8),
+// so a contradiction without attacks would be meaningless. `id` is the stable target S8/S9 reference.
+// (Shape firmed at T6, as the T4 note anticipated: the old `claim_ids ≥2` assumed contradictions
+//  linked two claims, but the deterministic idea-refinement signal centers on one contested claim.)
+export const Contradiction = z.object({
+    id: z.string().min(1), // "D1", ...
+    claim_ids: z.array(z.string()).min(1), // the contested claim id(s)
+    attacks: z
+        .array(z.object({
+        provider: ProviderIdSchema,
+        argument: z.string().min(1),
+        severity: z.enum(['HIGH', 'MED', 'LOW']),
+    }))
+        .min(1),
+    note: z.string().optional(),
+});
+export const DisagreementMap = z.object({
+    consensus: z.array(Claim), // agreed by ≥2 providers
+    contradictions: z.array(Contradiction), // direct conflicts; empty is legal (→ low_diversity flag)
+    unique: z.array(Claim), // raised by exactly one provider
+    blind_spots: z.array(z.string()), // rubric checklist items no provider addressed
+});
+// ── code-review: ReviewMap (§12.2, T10) ─────────────────────────────────────
+//
+// The code-review analog of DisagreementMap. Findings are line-anchored, so unlike idea's prose
+// claims we CAN deterministically detect when both reviewers independently flagged the same bug
+// (the §487 matcher: same file + overlapping lines + same category). Built pre-S9 from {reviewer
+// findings, mutual cross-exam}; the judge then adjudicates only `disputed`. Final HIGH/MED/LOW
+// confidence + false-positive exclusion are DERIVED at S10 (not stored here) — one source of truth.
+// Internal (engine-built) → not strict.
+/** The other reviewer's cross-exam verdict on a finding. `NONE` = both reviewers raised it
+ *  independently (§487-matched), so no cross-exam was needed to confirm it. */
+export const CrossVerdict = z.enum(['CONFIRM', 'REFUTE', 'UNCERTAIN', 'NONE']);
+/** A finding tagged with who raised it, the other reviewer's cross-exam verdict, and (if disputed)
+ *  the refuting argument. `reviewers` has 2 entries only when both independently found the same bug. */
+export const AnnotatedFinding = z.object({
+    finding: Finding,
+    reviewers: z.array(ProviderIdSchema).min(1),
+    cross_verdict: CrossVerdict,
+    refutation: z.string().optional(),
+});
+export const ReviewMap = z.object({
+    consensus: z.array(AnnotatedFinding), // both-independent or CONFIRMed → HIGH
+    disputed: z.array(AnnotatedFinding), // REFUTEd → adjudicated by S9
+    single_reviewer: z.array(AnnotatedFinding), // one reviewer, UNCERTAIN/unexamined → MEDIUM
+    per_reviewer: z.array(z.object({ provider: ProviderIdSchema, raised: z.number().int().nonnegative(), kept: z.number().int().nonnegative(), dropped: z.number().int().nonnegative() })),
+});
+// ── S9: JudgeReport (§13) ───────────────────────────────────────────────────
+const Adjudication = z
+    .object({
+    id: z.string().min(1), // disputed item id
+    ruling: z.enum(['UPHOLD', 'REJECT', 'UNRESOLVED']),
+    reasoning: z.string().min(1), // ≤3 sentences
+    evidence_cited: z.string().min(1),
+})
+    .strict();
+export const Recommendation = z.enum(['PROCEED', 'PROCEED_WITH_CONDITIONS', 'PIVOT', 'STOP']);
+const JudgeReportBase = z
+    .object({
+    adjudications: z.array(Adjudication),
+    verdict: z.string().min(1), // the recommendation + core reason (idea: 2-5 sentences; grounded in adjudicated + consensus claims)
+    recommendation: Recommendation.optional(), // idea workflow; code-review omits it
+    conditions: z.array(z.string().min(1)).max(6).optional(), // present only for PROCEED_WITH_CONDITIONS
+    key_points: z.array(z.string()).max(10).optional(), // chairman's bulleted reasoning (idea workflow); code-review omits it
+    dissent: z.array(z.string()).min(1), // ≥1 — empty dissent is invalid (§9); strongest counter-argument
+    confidence_notes: z.string().min(1), // which conclusions are HIGH/MEDIUM/LOW and why
+})
+    .strict();
+export const JudgeReport = JudgeReportBase.superRefine((r, ctx) => {
+    const hasConditions = (r.conditions?.length ?? 0) > 0;
+    if (r.recommendation === 'PROCEED_WITH_CONDITIONS' && !hasConditions) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['conditions'],
+            message: 'conditions are required when recommendation is PROCEED_WITH_CONDITIONS',
+        });
+    }
+    if (hasConditions && r.recommendation !== 'PROCEED_WITH_CONDITIONS') {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['conditions'],
+            message: 'conditions are only valid for PROCEED_WITH_CONDITIONS',
+        });
+    }
+});
+/** S9 call-time variant: `dissent` relaxed to min-0 so an empty dissent does NOT auto-throw inside
+ *  jsonCall. S9 enforces the non-empty rule itself (one re-ask → else flag `synthesis_suspect` +
+ *  inject a placeholder) so it can salvage the rest of the report instead of failing the run (§260).
+ *  Recommendation/condition consistency is also enforced inside idea S9, not by this relaxed schema. */
+export const JudgeReportModel = JudgeReportBase.extend({
+    dissent: z.array(z.string()),
+});
+// ── S9b: ActionPlan (idea-refinement report v3) ─────────────────────────────
+export const ActionPlan = z
+    .object({
+    actions: z
+        .array(z
+        .object({
+        order: z.number().int().min(1),
+        action: z.string().min(1),
+        why: z.string().min(1),
+        validates: z.string().min(1),
+        effort: z.enum(['S', 'M', 'L']),
+        kill_signal: z.string().min(1),
+    })
+        .strict())
+        .min(1)
+        .max(7),
+    sequencing_note: z.string().min(1),
+})
+    .strict();
+// ── RunMeta (§15, §16) ──────────────────────────────────────────────────────
+//
+// Written by the artifact writer; assembled by the engine's RunCtx (T5). Internal → not strict.
+/** One provider call's accounting entry (§15 "per-call timings"). */
+export const CallRecord = z.object({
+    provider: ProviderIdSchema,
+    stage: z.string(), // e.g. "S4", "S1"
+    durationMs: z.number().nonnegative(),
+    error: z.enum(['NOT_FOUND', 'AUTH', 'QUOTA', 'TIMEOUT', 'BAD_OUTPUT', 'CRASH']).optional(),
+});
+/** How read-only was actually enforced per provider (§15, §19). Mirrors providers ReadOnlyFlag. */
+const ReadOnlyFlagSchema = z.enum(['plan', 'sandbox', 'none']);
+/** Resolved flag profile as recorded in meta (mirrors providers/types.ts FlagProfile). */
+const FlagProfileSchema = z.object({
+    id: ProviderIdSchema,
+    jsonOutput: z.boolean(),
+    readOnlyFlag: ReadOnlyFlagSchema,
+    model: z.string().optional(),
+});
+export const RunMeta = z.object({
+    run_id: z.string().min(1), // encodes the timestamp (e.g. 20260702-1412-idea-refinement-a3f9)
+    workflow: WorkflowIdSchema,
+    provider_versions: z.record(ProviderIdSchema, z.string()), // detected `--version` strings
+    flag_profiles: z.record(ProviderIdSchema, FlagProfileSchema),
+    roles: z.record(z.string(), ProviderIdSchema), // role name → assigned provider
+    read_only: z.record(ProviderIdSchema, ReadOnlyFlagSchema), // enforcement level per provider
+    calls: z.array(CallRecord),
+    call_count: z.number().int().nonnegative(),
+    budget: z.object({ limit: z.number().int().positive(), used: z.number().int().nonnegative() }),
+    exit_status: z.enum(['ok', 'failed', 'aborted', 'partial']),
+    aborted: z.boolean(), // §16: Ctrl+C finalizes meta with aborted:true
+    // §16 report-header flags; absent = none.
+    flags: z.array(z.enum(['synthesis_suspect', 'low_diversity', 'plan_skipped', 'plan_fallback'])).optional(),
+});

package/dist/skills/code-review/judge.md

@@ -0,0 +1,23 @@
+# Judge playbook — adjudicate disputed findings
+
+You rule on findings two reviewers disagreed on, from the evidence and refutation text ALONE — you
+cannot open the repo. Rule on what is proven, not on who sounds confident.
+
+## How to weigh each dispute
+- Prefer the side backed by concrete, checkable evidence (a specific line, input, or behavior) over
+  the side that only asserts. A refutation with no mechanism is weak.
+- UPHOLD when the evidence names a real trigger and the refutation does not actually neutralize it.
+- REJECT when the refutation shows the finding misreads the code, the trigger cannot occur, or the
+  path is already guarded.
+- UNRESOLVED only when both sides are genuinely balanced and the text cannot settle it. Do not use
+  UNRESOLVED to avoid deciding — it is the rare case, not the safe default.
+
+## Severity discipline
+- An upheld P0/P1 (correctness / security / data-loss) needs a demonstrated failure, not a worry.
+- If the defect is real but its severity is inflated, uphold it and say the severity is lower in your
+  reasoning — do not reject a real bug over its label.
+
+## Verdict and dissent
+- The verdict states roughly how many real defects survive and the worst severity — no hedging.
+- Your dissent must be the strongest honest argument against your OWN verdict, not a throwaway. If you
+  cannot argue against yourself, you have not stress-tested the ruling.

package/dist/skills/code-review/reviewer.md

@@ -0,0 +1,38 @@
+# Reviewer playbook — hunt for real defects
+
+You are hunting for bugs a single reviewer would miss. Depth over breadth: a few well-evidenced
+defects beat a long list of guesses.
+
+## Hunt order (chase behavior, not style)
+1. CORRECTNESS — off-by-one, inverted condition, wrong operator/variable, missing return,
+   unhandled null/undefined, broken control flow, wrong default.
+2. SECURITY — unvalidated input, injection (SQL/shell/path), authz/authn gaps, secret or PII
+   exposure, unsafe deserialization, missing access checks.
+3. CONCURRENCY — races, unawaited promises, shared mutable state, lost updates, ordering
+   assumptions, deadlock.
+4. ERROR_HANDLING — swallowed errors, wrong error type, partial failure leaving bad state,
+   missing cleanup on the failure path.
+5. PERF — accidental O(n^2), work inside a loop that belongs outside, N+1 calls, unbounded
+   growth. Only when the impact is real, not theoretical.
+
+## Trace the change, don't just read it
+- For each changed function: who calls it, with what values, and what happens on the failure
+  path? Read the surrounding code before judging.
+- Ask "what input breaks this?" Name that concrete input in your evidence.
+- Check the boundaries: empty, zero, negative, very large, null, and concurrent access.
+
+## Evidence bar (a finding without this is noise)
+- `evidence` must quote the exact code or describe the exact behavior that proves the defect —
+  not a restatement of the claim.
+- Give the concrete trigger, e.g. "when `items` is empty, line 42 divides by zero".
+- If you cannot point to the line that fails, do not report it.
+
+## Confidence, honestly
+- 0.9+  : you can name the input and the wrong result it produces.
+- 0.6-0.8 : likely defect, but rests on an assumption about callers or runtime.
+- <0.5  : a smell worth flagging, not a claim — say so in the `claim`.
+
+## Do not
+- No style, naming, or formatting nits (nothing below P2).
+- No speculative "could be a problem" without a concrete trigger.
+- No findings on files or lines outside the diff.

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

@@ -0,0 +1,45 @@
+# Analyst playbook — pressure-test the idea
+
+You are an adversarial analyst on a decision panel. Your job is not to like the idea — it is to find
+where it breaks. Steelman it once, then attack it honestly.
+
+## Strongest version first
+- Before attacking, state the best honest version of the idea: who it is for and why it would win.
+- Attack THAT version, not a weak strawman. If the steelman is thin, that itself is a finding.
+
+## Assumptions — surface the load-bearing ones
+- Name the assumptions the idea silently depends on. Mark each VERIFIABLE (checkable with data or a
+  test) or JUDGMENT (a bet on taste, market, or behavior).
+- Flag which are load-bearing: the ones where, if false, the whole idea collapses. Spend effort
+  there, not on cosmetic assumptions.
+
+## Attacks — anchored and severe
+- Every attack must target a specific assumption id. An attack that floats free of an assumption is
+  noise — discard it yourself.
+- Rank by severity: HIGH = kills or reshapes the idea; MED = forces a costly change; LOW = a caveat.
+- Prefer the attack a smart skeptic would actually make: no strawmen, no nitpicks dressed as risks.
+
+## MANDATORY coverage — address every dimension below
+Do not leave a dimension unexamined; an unaddressed dimension is a hole in your analysis, not a
+neutral omission. For each, either raise an assumption/attack or state plainly why it is not a
+concern for THIS idea:
+1. Target user / who this is actually for.
+2. Existing alternatives — including "do nothing" and the status quo.
+3. Differentiation — why this wins over those alternatives.
+4. Feasibility — can it actually be built, under real constraints.
+5. Cost / effort / resources to build and run it.
+6. Policy / legal / compliance / privacy risk.
+7. Kill criteria — what evidence would make you abandon it.
+8. Business model / how it makes money (or why it needn't).
+9. Distribution / go-to-market — how anyone even finds it.
+10. Timing — why now, and what makes the market ready or not.
+11. Scalability — what breaks as it grows.
+12. Key risks / assumptions that must be validated first.
+
+## Open questions that move the verdict
+- List only questions whose ANSWER would change the decision. "Nice to know" is not one of them.
+- Phrase each so that a yes/no or a single number would actually flip your assessment.
+
+## Do not
+- No motivational framing, no pitch language, no summarizing your own output.
+- No attack without an assumption to anchor it. No assumption you cannot tie to the idea.

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

@@ -0,0 +1,25 @@
+# Planner playbook — decisive validation
+
+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.
+
+## 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.
+
+## 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`.
+
+## 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.
+
+## 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.

package/dist/storage/feedback.js

@@ -0,0 +1,111 @@
+// `.aiki/feedback.jsonl` — the human review gate (`aiki resolve`, §127/§444/§618). Append-only.
+// This is the PURE core (schema + build + append); the interactive readline shell lives in cli/resolve.ts.
+// Keeping the writes pure is what lets §604/§606 ("resolve appends valid JSONL") be tested without a TTY.
+//
+// Workflow-aware (T11): idea-refinement annotates the judge's adjudicated contradictions with
+// correct/incorrect/unsure; code-review annotates the report's kept findings with fixed/wontfix/
+// false-positive (the false-positive labels feed the bench PRECISION metric, BENCHMARK.md §2). Each line
+// snapshots the item's `ruling` (a free string: idea = UPHOLD/REJECT/UNRESOLVED; code-review = severity/
+// category/confidence) so it's self-describing for the bench scorer without rejoining to the run.
+import { appendFile, mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { z } from 'zod';
+import { WorkflowIdSchema } from '../schemas/index.js';
+/** All human verdicts across workflows. `parseVerdictFlags`/`resolve` restrict to the per-workflow vocab. */
+export const VerdictSchema = z.enum(['correct', 'incorrect', 'unsure', 'fixed', 'wontfix', 'false-positive']);
+export const VERDICT_VOCAB = {
+    'idea-refinement': ['correct', 'incorrect', 'unsure'],
+    'code-review': ['fixed', 'wontfix', 'false-positive'],
+};
+/** One appended feedback line. `item_type` distinguishes an idea adjudication from a code-review finding. */
+export const FeedbackEntry = z
+    .object({
+    run_id: z.string().min(1),
+    workflow: WorkflowIdSchema,
+    item_type: z.enum(['adjudication', 'finding']),
+    item_id: z.string().min(1),
+    verdict: VerdictSchema,
+    ruling: z.string().min(1), // snapshot of what the human reacted to (workflow-specific)
+    at: z.string().min(1), // ISO-8601
+    note: z.string().optional(),
+})
+    .strict();
+export class FeedbackError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'FeedbackError';
+    }
+}
+/**
+ * Build validated feedback entries from a verdict map, in `items` order. A verdict referencing an
+ * unknown item id is a hard error (typo guard — mirrors the config hard-fail rule).
+ */
+export function buildFeedbackEntries(runId, workflow, items, verdicts, at = new Date(), itemType = 'adjudication') {
+    const known = new Set(items.map((i) => i.id));
+    for (const id of verdicts.keys()) {
+        if (!known.has(id))
+            throw new FeedbackError(`no ${itemType} "${id}" in this run (have: ${[...known].join(', ') || 'none'})`);
+    }
+    const iso = at.toISOString();
+    const entries = [];
+    for (const item of items) {
+        const v = verdicts.get(item.id);
+        if (!v)
+            continue;
+        entries.push(FeedbackEntry.parse({
+            run_id: runId,
+            workflow,
+            item_type: itemType,
+            item_id: item.id,
+            verdict: v.verdict,
+            ruling: item.ruling,
+            at: iso,
+            ...(v.note ? { note: v.note } : {}),
+        }));
+    }
+    return entries;
+}
+const VERDICT_ALIAS = {
+    c: 'correct',
+    correct: 'correct',
+    i: 'incorrect',
+    incorrect: 'incorrect',
+    u: 'unsure',
+    unsure: 'unsure',
+    f: 'fixed',
+    fixed: 'fixed',
+    w: 'wontfix',
+    wontfix: 'wontfix',
+    fp: 'false-positive',
+    'false-positive': 'false-positive',
+};
+/**
+ * Parse repeatable `--verdict <id>=<verdict>` flags → a verdict map. `allowed` restricts to a workflow's
+ * vocab (default: all). Malformed flag or out-of-vocab verdict throws FeedbackError (hard-fail).
+ */
+export function parseVerdictFlags(flags, allowed = VerdictSchema.options) {
+    const ok = new Set(allowed);
+    const m = new Map();
+    for (const f of flags) {
+        const eq = f.indexOf('=');
+        if (eq < 1)
+            throw new FeedbackError(`bad --verdict "${f}" — use <id>=<${allowed.join('|')}>`);
+        const id = f.slice(0, eq).trim();
+        const verdict = VERDICT_ALIAS[f.slice(eq + 1).trim().toLowerCase()];
+        if (!id)
+            throw new FeedbackError(`bad --verdict "${f}" — missing item id`);
+        if (!verdict || !ok.has(verdict))
+            throw new FeedbackError(`bad verdict for "${id}" — use ${allowed.join('|')}`);
+        m.set(id, { verdict });
+    }
+    return m;
+}
+/** Append entries to `<root>/feedback.jsonl` (one JSON object per line). No-op on empty input. */
+export async function appendFeedback(entries, root = '.aiki') {
+    const path = join(root, 'feedback.jsonl');
+    if (entries.length === 0)
+        return path;
+    await mkdir(root, { recursive: true });
+    await appendFile(path, entries.map((e) => JSON.stringify(e)).join('\n') + '\n', 'utf8');
+    return path;
+}

package/dist/storage/paths.js

@@ -0,0 +1,20 @@
+// Where aiki keeps its files when launched from anywhere (hybrid model, user decision 2026-07-06).
+//
+//   runs  → the project's `.aiki/` when you are inside a git repo, else the global `~/.aiki/`.
+//           So project work stays co-located with its project, but running from home still has a home.
+//   home  → `~/.aiki/` holds the global session registry (+ later: global config).
+//
+// Library defaults elsewhere stay `.aiki` (cwd-relative) for tests/back-compat; only the CLI entry
+// points resolve the hybrid root and inject it. Kept tiny + pure-ish (one git probe) on purpose.
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { repoToplevel } from '../orchestration/git.js';
+/** Global aiki home — `$AIKI_HOME` if set, else `~/.aiki`. Holds the cross-location session registry. */
+export function homeAikiRoot() {
+    return process.env.AIKI_HOME ?? join(homedir(), '.aiki');
+}
+/** Hybrid runs root for `cwd`: `<repoRoot>/.aiki` inside a git repo, else `~/.aiki`. */
+export async function resolveRunsRoot(cwd = process.cwd()) {
+    const repo = await repoToplevel(cwd);
+    return repo ? join(repo, '.aiki') : homeAikiRoot();
+}