faf-cli 6.13.0 → 6.15.0

package/dist/core/interview.d.ts

@@ -17,6 +17,7 @@
  * Authoring doctrine baked into the prompts: 6Ws answers are terse LABELS
  * (3-4 words, hard cap <6) — a scannable spec card, not prose.
  */
+import type { SeededContextDetailed } from '../detect/relentless.js';
 /** Bump when questions/options change — consumers can pin or report it. */
 export declare const INTERVIEW_VERSION = "faf-interview/1";
 export interface InterviewOption {
@@ -24,9 +25,9 @@ export interface InterviewOption {
     value: string;
     description: string;
 }
-export interface InterviewQuestion {
+export interface InterviewQuestion<P extends string = string> {
     /** Canonical slot path (core/slots.ts is the spine). */
-    path: string;
+    path: P;
     question: string;
     /** Short chip/header label (max ~12 chars) for option-UI consumers. */
     header: string;
@@ -34,22 +35,37 @@ export interface InterviewQuestion {
     required: boolean;
     options?: InterviewOption[];
 }
+/**
+ * The human/sourced boundary, as TYPES — the load-bearing line in FAF.
+ *
+ *   HumanSlotPath   = the 8 things only a human knows (name + goal + the 6Ws).
+ *   SourcedSlotPath = the slots detection fills (language + the stack).
+ *
+ * They are DISJOINT by construction. Typing the two interviews against these
+ * makes it a COMPILE error to put a sourced slot in the human interview (or
+ * vice-versa) — the "Interview-16" drift becomes unrepresentable at the Truth,
+ * not merely caught by a downstream test. "I'll remember" is not a fix; a type
+ * is. (claude-faf-mcp's wjttc-faf-go-boundary test is the belt; this is the
+ * braces — the source itself can no longer drift.)
+ */
+export type HumanSlotPath = 'project.name' | 'project.goal' | 'human_context.who' | 'human_context.what' | 'human_context.why' | 'human_context.where' | 'human_context.when' | 'human_context.how';
+export type SourcedSlotPath = 'project.main_language' | 'stack.frontend' | 'stack.backend' | 'stack.database' | 'stack.runtime' | 'stack.hosting' | 'stack.build' | 'stack.cicd';
 /**
  * THE 8-Q 6Ws INTERVIEW — the core. Project identity (name + goal) plus the
  * six Ws. Language is deliberately NOT here: detection finds it; humans are
  * only asked what machines cannot derive. The 6Ws are the underivable half.
  */
-export declare const SIX_WS_INTERVIEW: InterviewQuestion[];
+export declare const SIX_WS_INTERVIEW: InterviewQuestion<HumanSlotPath>[];
 /**
  * Stack interview — asked only for slots ACTIVE for the app_type and still
  * empty. Selects where a common vocabulary exists; every select includes
  * Other (specify) and None where absence is legitimate.
  */
-export declare const STACK_INTERVIEW: InterviewQuestion[];
+export declare const STACK_INTERVIEW: InterviewQuestion<SourcedSlotPath>[];
 /** The full ordered registry: the 8-Q core first, then stack. */
 export declare const INTERVIEW: InterviewQuestion[];
 /** Lookup by slot path. */
-export declare const INTERVIEW_BY_PATH: Map<string, InterviewQuestion>;
+export declare const INTERVIEW_BY_PATH: Map<string, InterviewQuestion<string>>;
 /**
  * Plain-object companion to INTERVIEW_BY_PATH. A Map JSON-serializes to `{}`,
  * which reads as "the export shipped empty" to any consumer that crosses a
@@ -90,6 +106,12 @@ export interface TableOf8Row {
     value: string;
     status: BoxStatus;
     seeded: boolean;
+    /** Provenance for a SEEDED row — where the suggestion was sourced from, so the
+     *  human confirms informed: 'project goal' or a README locus ('README:## Why').
+     *  Absent on filled/empty rows. */
+    source?: string;
+    /** 0..1 confidence for a seeded row, by source quality. Absent otherwise. */
+    confidence?: number;
 }
 export interface TableOf8 {
     version: string;
@@ -100,11 +122,16 @@ export interface TableOf8 {
     complete: boolean;
 }
 /**
- * Build the Table-of-8 from a .faf object (any/empty) + an optional goal. The
- * goal seeds WHO/WHAT/WHERE via seedSixWsFromGoal (facts only); WHY/WHEN/HOW are
- * never seeded. Rows the .faf already fills are 'filled'; goal-seeded ones are
- * 'seeded' (suggestions); the rest are 'empty' (ask the human). Pure.
+ * Build the Table-of-8 from a .faf object (any/empty) + an optional goal and an
+ * optional sourced README extraction (relentlessContextDetailed). The goal seeds
+ * WHO/WHAT/WHERE via seedSixWsFromGoal (facts only, source 'project goal'); the
+ * detailed README form covers WHY/WHEN/HOW and any slot the goal didn't reach,
+ * each carrying its own provenance. Rows the .faf already fills are 'filled';
+ * seeded ones carry `source`+`confidence` so the human confirms informed; the
+ * rest are 'empty' (ask the human). Goal wins over README where both have a
+ * fact (the deliberate sentence beats the extraction). Pure.
  */
 export declare function buildTableOf8(faf: Record<string, unknown>, opts?: {
     goal?: string;
+    detailed?: SeededContextDetailed;
 }): TableOf8;

package/dist/core/loop.d.ts

@@ -0,0 +1,91 @@
+/**
+ * The faf_loop decision core — the brain of "100% or ask human".
+ *
+ * A pure, snapshot decision: given a parsed .faf, classify its remaining gaps
+ * as SOURCEABLE (detection can fill — language, stack: no human needed) or
+ * HUMAN (only the human knows — the goal + the 6Ws), and return a verdict:
+ *
+ *   done        — nothing left (or already 100%). Stop, success.
+ *   can-source  — sourceable gaps remain → the loop runs auto and re-scores.
+ *   needs-human — ONLY human gaps remain → the wall; ask (or seed-and-confirm).
+ *
+ * The classification IS the human/sourced boundary at runtime: a slot is human
+ * iff its slot category is 'human' (the 6Ws) or it's the goal sentence. The
+ * loop sources everything it can FIRST (minimise human asks); only when the
+ * sourceable well is dry does it turn to the human. It never invents a human
+ * slot to reach 100% — needs-human is a legitimate, honest terminal, not a
+ * failure.
+ *
+ * This is the deterministic engine the CLI `faf loop` and the agentic
+ * `/faf-loop` skill both decide from. Orchestration (run auto, re-score, the
+ * no-progress + iteration-cap guards) lives in the command on top of this.
+ */
+export type LoopStatus = 'done' | 'can-source' | 'needs-human';
+export interface LoopGaps {
+    /** Empty active slots only the human can give — the goal + the 6Ws. */
+    human: string[];
+    /** Empty active slots detection can fill — language + the stack. */
+    sourceable: string[];
+}
+export interface LoopVerdict {
+    status: LoopStatus;
+    score: number;
+    gaps: LoopGaps;
+    /** The questions to put to the human — populated only when status is
+     *  'needs-human' (sourceable work is done; the human is all that's left). */
+    ask: Array<{
+        path: string;
+        question: string;
+    }>;
+}
+/** Default empty test: null/undefined, blank, or a placeholder token. The
+ *  What-Not (`slotignored`) is handled separately — it is never a gap. */
+export declare function isEmptyValue(value: unknown): boolean;
+/** A path is HUMAN (only the human can give it) iff it is the goal sentence or
+ *  its slot category is 'human' (the 6Ws). Everything else — name, language,
+ *  the stack — is sourceable by detection. */
+export declare function isHumanSlot(path: string): boolean;
+/**
+ * Classify the empty, non-ignored interviewable slots of a .faf into human vs
+ * sourceable. Scope = the interviewable slots (the 6Ws + name + goal + the core
+ * stack); `slotignored` (the What-Not) is never a gap.
+ */
+export declare function classifyGaps(data: Record<string, unknown>, isEmpty?: (value: unknown) => boolean): LoopGaps;
+/**
+ * The loop verdict for a .faf snapshot. `score` is the current AI-readiness
+ * score (the loop's termination test). Precedence is deliberate: source
+ * everything possible BEFORE asking the human — so 'can-source' wins while any
+ * sourceable gap remains, and 'needs-human' fires only once they're exhausted.
+ */
+export declare function loopVerdict(score: number, data: Record<string, unknown>, isEmpty?: (value: unknown) => boolean): LoopVerdict;
+export type LoopRunStatus = 'done' | 'needs-human' | 'stuck' | 'capped' | 'no-faf';
+export interface LoopDeps {
+    /** The current .faf as {data, yaml}, or null when none exists. */
+    read(): {
+        data: Record<string, unknown>;
+        yaml: string;
+    } | null;
+    /** Score raw .faf yaml → 0..100 (the termination test). */
+    score(yaml: string): number;
+    /** Source what detection can (auto): fill the stack and WRITE the .faf. */
+    runAuto(): void;
+}
+export interface LoopRunOptions {
+    /** Hard cap on auto rounds (default 5). */
+    maxRounds?: number;
+    isEmpty?: (value: unknown) => boolean;
+}
+export interface LoopRunResult {
+    status: LoopRunStatus;
+    score: number;
+    /** Auto rounds actually run. */
+    rounds: number;
+    /** Score after each read — the climb, for narration. */
+    history: number[];
+    /** The human questions to put — populated only when status is 'needs-human'. */
+    ask: Array<{
+        path: string;
+        question: string;
+    }>;
+}
+export declare function runLoop(deps: LoopDeps, opts?: LoopRunOptions): LoopRunResult;

package/dist/detect/relentless.d.ts

@@ -19,4 +19,38 @@ export interface SeededContext {
     when?: string;
     how?: string;
 }
+/**
+ * A sourced 6-W value WITH its provenance — where it came from and how much to
+ * trust it. The honesty gate: a fill the human can audit before confirming.
+ *   - `source`: the artifact + locus it was relocated from, e.g.
+ *     'package.json:description' or 'README:## Why'. If we can't name a source,
+ *     we don't emit a value — sourced-or-empty, never invented.
+ *   - `confidence`: 0..1 by source quality (structured field > named section >
+ *     heuristic match). A signal for the seeded/confirm UI, not a score.
+ */
+export interface SourcedValue {
+    value: string;
+    source: string;
+    confidence: number;
+}
+export interface SeededContextDetailed {
+    who?: SourcedValue;
+    what?: SourcedValue;
+    why?: SourcedValue;
+    where?: SourcedValue;
+    when?: SourcedValue;
+    how?: SourcedValue;
+}
+/**
+ * The 6-W extractor WITH provenance — each slot carries {value, source,
+ * confidence}. This is the auditable form: the seeded/confirm UI can show the
+ * human WHERE a value was relocated from before they accept it.
+ */
+export declare function relentlessContextDetailed(dir: string): SeededContextDetailed;
+/**
+ * The bare 6-W extractor — values only, backward-compatible. A pure projection
+ * of `relentlessContextDetailed` (single internal source; identical output to
+ * the pre-provenance version). Existing consumers (claude-faf-mcp's faf_auto)
+ * keep working unchanged; opt into provenance via the Detailed form.
+ */
 export declare function relentlessContext(dir: string): SeededContext;

package/dist/index.d.ts

@@ -8,13 +8,15 @@ export { findFafFile, readFaf, readFafRaw } from './interop/faf.js';
 export { generateProjectHtml, writeProjectHtml } from './interop/projecthtml.js';
 export { generateServerCard, writeServerCard, fafContextBlock, registryMeta, registryName, REGISTRY_PUBLISHER_KEY, } from './interop/servercard.js';
 export type { ServerCardOptions } from './interop/servercard.js';
-export type { InterviewQuestion, InterviewOption, GoalSeed, TableOf8, TableOf8Row, BoxStatus } from './core/interview.js';
+export type { InterviewQuestion, InterviewOption, HumanSlotPath, SourcedSlotPath, GoalSeed, TableOf8, TableOf8Row, BoxStatus } from './core/interview.js';
 export { INTERVIEW, SIX_WS_INTERVIEW, STACK_INTERVIEW, INTERVIEW_BY_PATH, INTERVIEW_PATHS, INTERVIEW_VERSION, questionForSlot, interviewForMissing, seedSixWsFromGoal, buildTableOf8, } from './core/interview.js';
+export type { LoopStatus, LoopGaps, LoopVerdict, LoopRunStatus, LoopDeps, LoopRunOptions, LoopRunResult } from './core/loop.js';
+export { classifyGaps, loopVerdict, isHumanSlot, isEmptyValue, runLoop } from './core/loop.js';
 export { BENCH_VERSION, deriveQuestionSet, publicQuestions, gradeAnswers, buildReceipt, normalizeAnswer, answersMatch, ALIAS_GROUPS, } from './commands/bench.js';
 export type { BenchQuestion, QuestionSet, GradeResult, BenchState, RunRecord } from './commands/bench.js';
 export { turboCatScan, turboCatSlots } from './detect/turbo-cat.js';
 export type { TurboCatResult, DiscoveredFormat } from './detect/turbo-cat.js';
-export { relentlessContext } from './detect/relentless.js';
-export type { SeededContext } from './detect/relentless.js';
+export { relentlessContext, relentlessContextDetailed } from './detect/relentless.js';
+export type { SeededContext, SeededContextDetailed, SourcedValue } from './detect/relentless.js';
 export { assembleFreshFaf } from './detect/assemble.js';
 export * as kernel from './wasm/kernel.js';