@yagni-app/code-staging 0.3.0-staging.1096.1 → 0.3.0-staging.1098.1

package/dist/extension/askYagniTool.d.ts

@@ -1,11 +1,20 @@
 import type { ToolDefinition } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
+import { type FlywheelState } from "./flywheel.js";
 import { type RepoDocSnippet } from "./repoDocs.js";
 /** A single source citation returned by the YAGNI `ask` endpoint. */
 export interface Citation {
     title: string;
     url: string;
 }
+/**
+ * How hard the answer may be leaned on (mirror of `@yagni/shared`'s
+ * AskStanding — mirrored locally by this extension's no-workspace-imports
+ * convention, see costHud.ts).
+ */
+export type AskStanding = "confirmed" | "asserted" | "inferred" | "no_position";
+/** One line the TUI shows above the answer, per standing. */
+export declare const STANDING_LINES: Record<AskStanding, string>;
 /** Options for {@link makeAskYagniTool}. */
 export interface MakeAskYagniToolOptions {
     baseUrl: string;
@@ -19,6 +28,19 @@ export interface MakeAskYagniToolOptions {
      * checkout's own era, since the docs are read from the tree being edited.
      */
     collectDocs?: (cwd: string, query: string) => RepoDocSnippet[];
+    /**
+     * Shared flywheel session state (Run 7): caps how many no-position
+     * recordSuggestions reach the model per session and attributes the
+     * follow-up record_decision for dedupe. Absent → suggestions always
+     * surface, nothing is attributed (tests, older wiring).
+     */
+    flywheel?: FlywheelState;
+    /**
+     * The session repo (`owner/name`), for the backend's soft-scoped decision
+     * read (workspace-level decisions plus this repo's own — never another
+     * repo's conventions). Absent keeps the workspace-wide read.
+     */
+    getRepo?: () => string | undefined;
 }
 declare const parameters: Type.TObject<{
     question: Type.TString;
@@ -34,6 +56,7 @@ declare const parameters: Type.TObject<{
  */
 export declare function makeAskYagniTool(opts: MakeAskYagniToolOptions): ToolDefinition<typeof parameters, {
     citations: Citation[];
+    standing?: AskStanding;
 }>;
 export {};
 //# sourceMappingURL=askYagniTool.d.ts.map

package/dist/extension/askYagniTool.js

@@ -1,8 +1,21 @@
 import { Container, Spacer, Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
+import { canSurfaceSuggestion, noteSuggestionSurfaced } from "./flywheel.js";
 import { collectRepoDocs } from "./repoDocs.js";
 import { friendlyFetchError, METERED_POST_FETCH_POLICY, resilientFetch } from "./resilientFetch.js";
 import { markdownOrPlain } from "./subagentRender.js";
+/** One line the TUI shows above the answer, per standing. */
+export const STANDING_LINES = {
+    confirmed: "Grounded in a confirmed decision",
+    asserted: "Grounded in a recorded assumption, not yet verified",
+    inferred: "Inferred from workspace context, not a recorded decision",
+    no_position: "No recorded position in this workspace",
+};
+function standingLine(value) {
+    return typeof value === "string" && value in STANDING_LINES
+        ? STANDING_LINES[value]
+        : undefined;
+}
 const parameters = Type.Object({
     question: Type.String(),
     context: Type.Optional(Type.String()),
@@ -40,6 +53,7 @@ export function makeAskYagniTool(opts) {
             "Call ask_yagni BEFORE guessing about anything organization- or codebase-specific (conventions, policies, architecture, ownership, product decisions).",
             "Pass the user's actual question; add relevant local context (file paths, snippets) in the optional `context` field.",
             "When you use an answer, quote or reference its citations so the user can verify the source.",
+            "Answers carry a standing: treat a confirmed decision as settled; when you lean on an unverified assumption or an inference, say so where the work is reviewed; when there is no recorded position, follow the answer's instruction to record the assumption you proceed on.",
         ],
         parameters,
         renderCall(args, theme) {
@@ -55,8 +69,11 @@ export function makeAskYagniTool(opts) {
             const citations = result.details?.citations ?? [];
             if (isPartial)
                 return new Text(t.fg("muted", answer || "Asking YAGNI…"), 0, 0);
+            const standing = standingLine(result.details?.standing);
             if (expanded) {
                 const container = new Container();
+                if (standing)
+                    container.addChild(new Text(t.fg("muted", standing), 0, 0));
                 container.addChild(markdownOrPlain(answer || "(no answer)", t));
                 if (citations.length > 0) {
                     container.addChild(new Spacer(1));
@@ -69,6 +86,8 @@ export function makeAskYagniTool(opts) {
             const lines = answer.trim().split("\n");
             const out = lines.slice(0, ANSWER_PREVIEW_LINES).map((l) => t.fg("toolOutput", l));
             const meta = [];
+            if (standing)
+                meta.push(standing);
             if (citations.length > 0)
                 meta.push(citationCount(citations.length));
             if (lines.length > ANSWER_PREVIEW_LINES || citations.length > 0)
@@ -95,6 +114,7 @@ export function makeAskYagniTool(opts) {
                     question: params.question,
                     context: params.context,
                     cwd: ctx?.cwd,
+                    ...(opts.getRepo?.() ? { repo: opts.getRepo() } : {}),
                     ...(repoDocs.length > 0 ? { repoDocs } : {}),
                 }),
             }, { fetchImpl: opts.fetchImpl, signal, policy: METERED_POST_FETCH_POLICY });
@@ -102,9 +122,29 @@ export function makeAskYagniTool(opts) {
                 throw new Error(await friendlyFetchError("ask_yagni", res));
             }
             const data = (await res.json());
+            // Run 7 flywheel: a no-position answer carries the record-the-assumption
+            // instruction. It reaches the model VERBATIM inside the tool result, but
+            // only up to the per-session cap — past it a busy run stops being told
+            // to bank more asserted rows.
+            let text = data.answer;
+            const suggestion = data.recordSuggestion?.instruction;
+            if (suggestion && data.standing === "no_position") {
+                const state = opts.flywheel;
+                if (!state || canSurfaceSuggestion(state)) {
+                    // Attribution correlates to the QUESTION the suggestion asked
+                    // about, so only the record_decision that answers it inherits the
+                    // dedupe flag.
+                    if (state)
+                        noteSuggestionSurfaced(state, data.recordSuggestion?.question ?? params.question);
+                    text = `${text}\n\n${suggestion}`;
+                }
+            }
             return {
-                content: [{ type: "text", text: data.answer }],
-                details: { citations: data.citations ?? [] },
+                content: [{ type: "text", text }],
+                details: {
+                    citations: data.citations ?? [],
+                    ...(data.standing ? { standing: data.standing } : {}),
+                },
             };
         },
     };

package/dist/extension/config.d.ts

@@ -113,6 +113,12 @@ export interface ContextBrief {
         decisions: number;
         corrections: number;
     };
+    /**
+     * Active decisions scoped to the repo named on the request (additive, Run
+     * 7; absent without `?repo=`, on older backends, and on a count failure).
+     * The opt-in mining beat fires ONLY on an explicit 0.
+     */
+    repoDecisionCount?: number;
 }
 /**
  * Attribution headers for the model proxy (YAG-471). On the SERVER side these
@@ -192,6 +198,12 @@ export interface FetchContextBriefOptions {
     fetchImpl?: typeof fetch;
     /** Env seam for the telemetry headers; defaults to process.env. */
     env?: NodeJS.ProcessEnv;
+    /**
+     * The session repo (`owner/name`), when resolvable. Rides as `?repo=` so
+     * the response can carry `repoDecisionCount` for the mining beat — no
+     * second round-trip at boot.
+     */
+    repo?: string;
 }
 /**
  * Fetch the workspace company brief at startup.

package/dist/extension/config.js

@@ -208,7 +208,8 @@ export function sessionTelemetryHeaders(env = process.env) {
  */
 export async function fetchContextBrief(opts) {
     try {
-        const res = await resilientFetch(`${opts.baseUrl}/api/yagni-code/context`, {
+        const query = opts.repo ? `?repo=${encodeURIComponent(opts.repo)}` : "";
+        const res = await resilientFetch(`${opts.baseUrl}/api/yagni-code/context${query}`, {
             method: "GET",
             headers: {
                 authorization: `Bearer ${opts.getToken() ?? ""}`,

package/dist/extension/flywheel.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Session state for the miss-to-record flywheel (org plane, Run 7).
+ *
+ * When `ask_yagni` answers `no_position`, the server attaches a
+ * `recordSuggestion` telling the agent to bank the assumption it proceeds on.
+ * The extension owns two client-side guards the server cannot:
+ *
+ *  - **The per-run cap.** At most {@link FLYWHEEL_RUN_CAP} suggestions are
+ *    surfaced per session; past it the suggestion is suppressed so a busy
+ *    session cannot flood the ledger with asserted rows.
+ *  - **Dedupe attribution.** A `record_decision` call that answers the
+ *    QUESTION a surfaced suggestion asked about is a mid-run agent with no
+ *    human to adjudicate a near-duplicate, so it sends `dedupe: true` (the
+ *    backend then returns the existing row instead of inserting). The
+ *    attribution is correlated to the suggested question — an unrelated
+ *    record_decision (a different judgment the agent banks mid-run, or a
+ *    human `/decide`) never inherits the flag.
+ */
+/** Most flywheel suggestions surfaced per session. */
+export declare const FLYWHEEL_RUN_CAP = 3;
+export interface FlywheelState {
+    /** Suggestions surfaced so far this session. */
+    suggestionsShown: number;
+    /**
+     * The question of the most recent surfaced suggestion, until a matching
+     * record_decision consumes it. Only a record answering THIS question is
+     * flywheel-attributed (sends `dedupe: true`).
+     */
+    pendingQuestion: string | null;
+}
+export declare function makeFlywheelState(): FlywheelState;
+/** May another suggestion be surfaced? */
+export declare function canSurfaceSuggestion(state: FlywheelState): boolean;
+/** Record that a suggestion (asking about `question`) reached the model. */
+export declare function noteSuggestionSurfaced(state: FlywheelState, question: string): void;
+/**
+ * Consume the flywheel attribution for a record_decision call. Returns true
+ * (and clears the pending question) only when the recorded question matches
+ * the surfaced suggestion's; a mismatch leaves the attribution pending — the
+ * agent may record other judgments before circling back, and a fail-safe
+ * mismatch simply means a normal insert (no dedupe), never a swallowed write.
+ */
+export declare function consumeFlywheelAttribution(state: FlywheelState, recordedQuestion: string): boolean;
+//# sourceMappingURL=flywheel.d.ts.map

package/dist/extension/flywheel.js

@@ -0,0 +1,53 @@
+/**
+ * Session state for the miss-to-record flywheel (org plane, Run 7).
+ *
+ * When `ask_yagni` answers `no_position`, the server attaches a
+ * `recordSuggestion` telling the agent to bank the assumption it proceeds on.
+ * The extension owns two client-side guards the server cannot:
+ *
+ *  - **The per-run cap.** At most {@link FLYWHEEL_RUN_CAP} suggestions are
+ *    surfaced per session; past it the suggestion is suppressed so a busy
+ *    session cannot flood the ledger with asserted rows.
+ *  - **Dedupe attribution.** A `record_decision` call that answers the
+ *    QUESTION a surfaced suggestion asked about is a mid-run agent with no
+ *    human to adjudicate a near-duplicate, so it sends `dedupe: true` (the
+ *    backend then returns the existing row instead of inserting). The
+ *    attribution is correlated to the suggested question — an unrelated
+ *    record_decision (a different judgment the agent banks mid-run, or a
+ *    human `/decide`) never inherits the flag.
+ */
+/** Most flywheel suggestions surfaced per session. */
+export const FLYWHEEL_RUN_CAP = 3;
+export function makeFlywheelState() {
+    return { suggestionsShown: 0, pendingQuestion: null };
+}
+/** May another suggestion be surfaced? */
+export function canSurfaceSuggestion(state) {
+    return state.suggestionsShown < FLYWHEEL_RUN_CAP;
+}
+/** Loose textual identity: case- and whitespace-insensitive, terminal punctuation ignored. */
+function normalizeQuestion(question) {
+    return question.toLowerCase().replace(/\s+/g, " ").replace(/[.?!\s]+$/g, "").trim();
+}
+/** Record that a suggestion (asking about `question`) reached the model. */
+export function noteSuggestionSurfaced(state, question) {
+    state.suggestionsShown += 1;
+    state.pendingQuestion = question;
+}
+/**
+ * Consume the flywheel attribution for a record_decision call. Returns true
+ * (and clears the pending question) only when the recorded question matches
+ * the surfaced suggestion's; a mismatch leaves the attribution pending — the
+ * agent may record other judgments before circling back, and a fail-safe
+ * mismatch simply means a normal insert (no dedupe), never a swallowed write.
+ */
+export function consumeFlywheelAttribution(state, recordedQuestion) {
+    if (state.pendingQuestion === null)
+        return false;
+    if (normalizeQuestion(state.pendingQuestion) !== normalizeQuestion(recordedQuestion)) {
+        return false;
+    }
+    state.pendingQuestion = null;
+    return true;
+}
+//# sourceMappingURL=flywheel.js.map

package/dist/extension/index.d.ts

@@ -5,6 +5,7 @@ import { fetchMcpServers as defaultFetchMcpServers } from "./mcpTools.js";
 import { type FlushOutcome, type SpoolClientOpts } from "./spool.js";
 import { type TokenProvider } from "./tokenProvider.js";
 import { type CatalogResult, type ContextBrief } from "./config.js";
+import { maybeOfferMiningBeat as defaultMaybeOfferMiningBeat, type MineBeatMarkers } from "./mineBeat.js";
 /**
  * YAGNI Code extension entry point.
  *
@@ -36,7 +37,21 @@ export interface RegisterYagniDeps {
         baseUrl: string;
         getToken: () => string | undefined;
         fetchImpl?: typeof fetch;
+        repo?: string;
     }) => Promise<ContextBrief | null>;
+    /**
+     * The session repo (`owner/name`), resolved from the origin remote before
+     * the boot brief fetch so `/context` can carry `repoDecisionCount` for the
+     * mining beat. Injectable (no git in tests); undefined outside a repo.
+     */
+    resolveRepoFullName?: (cwd: string) => string | undefined;
+    /**
+     * The opt-in seeding beat itself (Run 7). Injectable so tests assert it
+     * fires only on a startup with an explicitly-zero repo ledger.
+     */
+    offerMiningBeat?: typeof defaultMaybeOfferMiningBeat;
+    /** The beat's once-per-repo marker store. Injectable (no disk in tests). */
+    mineBeatMarkers?: MineBeatMarkers;
     /**
      * Workspace MCP server list seam (YAG-446). The default hits
      * `/api/yagni-code/mcp/servers` and is fail-soft: older backends and

package/dist/extension/index.js

@@ -41,6 +41,8 @@ import { makeAuthedFetch, makeTokenProvider } from "./tokenProvider.js";
 import { attributionHeaders, fetchCatalog as defaultFetchCatalog, fetchContextBrief as defaultFetchContextBrief, getToken, getTokenExpiresAt as defaultGetTokenExpiresAt, getWorkspaceId as defaultGetWorkspaceId, isDriverCaller, resolveBaseUrl, tokenExpiryNotice, } from "./config.js";
 import { buildYagniProvider } from "./provider.js";
 import { registerChipEditor } from "./chipEditor.js";
+import { defaultMineBeatGit, fileMineBeatMarkers, maybeOfferMiningBeat as defaultMaybeOfferMiningBeat, } from "./mineBeat.js";
+import { makeFlywheelState } from "./flywheel.js";
 function isEvalMode(env = process.env) {
     return env.YAGNI_CODE_EVAL_MODE === "1";
 }
@@ -144,7 +146,11 @@ export async function registerYagni(pi, deps = {}) {
     // child, a subagent, or an advisor consult).
     pi.registerProvider("yagni", buildYagniProvider(catalog, baseUrl, attributionHeaders(deps.env)));
     const toolOpts = { baseUrl, getToken: getTokenFn, fetchImpl: authedFetch };
-    pi.registerTool(makeAskYagniTool(toolOpts));
+    // One flywheel state per session, shared by ask_yagni (caps how many
+    // no-position record suggestions reach the model) and record_decision
+    // (flywheel-attributed records send dedupe: true). Run 7.
+    const flywheelState = makeFlywheelState();
+    pi.registerTool(makeAskYagniTool({ ...toolOpts, flywheel: flywheelState, getRepo: () => sessionRepo }));
     // Ticket write-back (spec 2026-08-09): explicit user-intent writes to the
     // workspace tracker, attributed to the developer via per-user credentials.
     if (!evalMode) {
@@ -172,7 +178,7 @@ export async function registerYagni(pi, deps = {}) {
         pi.registerTool(makeRecordEngineeringContextTool(toolOpts));
         // The capture half of the judgment loop: bank a product-intent decision so
         // ask_yagni answers the same question next time instead of interrupting a human.
-        pi.registerTool(makeRecordDecisionTool(toolOpts));
+        pi.registerTool(makeRecordDecisionTool({ ...toolOpts, flywheel: flywheelState }));
     }
     // The visible checklist for multi-step work: the todo_write tool, its
     // above-editor widget, and /todos. Branch-replayed, so forks and resumes
@@ -460,11 +466,27 @@ export async function registerYagni(pi, deps = {}) {
     // must never block the agent), then inject it into the system prompt so the
     // very first turn already knows how this company and codebase work.
     const fetchBrief = deps.fetchContextBrief ?? defaultFetchContextBrief;
+    // Resolved BEFORE the brief fetch so /context can answer repoDecisionCount
+    // in the same round-trip (the mining beat's signal). Best-effort: undefined
+    // outside a git repo or without an origin remote.
+    const resolveRepoFn = deps.resolveRepoFullName ?? ((cwd) => defaultMineBeatGit.repoFullName(cwd));
+    let sessionRepo;
+    try {
+        sessionRepo = evalMode ? undefined : resolveRepoFn(process.cwd());
+    }
+    catch {
+        sessionRepo = undefined;
+    }
     let contextBrief;
     let briefResult = null;
     if (!evalMode) {
         try {
-            briefResult = await fetchBrief({ baseUrl, getToken: getTokenFn, fetchImpl: authedFetch });
+            briefResult = await fetchBrief({
+                baseUrl,
+                getToken: getTokenFn,
+                fetchImpl: authedFetch,
+                repo: sessionRepo,
+            });
             contextBrief = briefResult?.brief?.trim() ? briefResult.brief : undefined;
         }
         catch {
@@ -769,6 +791,28 @@ export async function registerYagni(pi, deps = {}) {
                 // The init pass is best-effort; a failure never blocks the session.
             }
         }
+        // Run 7: the opt-in repo seeding beat. Fires only on a genuine startup
+        // when /context reported an explicitly-empty repo-scoped ledger, once per
+        // repo (marker store). Fully fail-soft — a beat failure never blocks the
+        // session.
+        if (event.reason === "startup" && !evalMode) {
+            try {
+                const offerBeat = deps.offerMiningBeat ?? defaultMaybeOfferMiningBeat;
+                const markers = deps.mineBeatMarkers ?? fileMineBeatMarkers(codeStateHome(null, env));
+                await offerBeat(ctx, {
+                    repoFullName: sessionRepo,
+                    repoDecisionCount: briefResult?.repoDecisionCount,
+                    cwd: process.cwd(),
+                    baseUrl,
+                    getToken: getTokenFn,
+                    fetchImpl: authedFetch,
+                    markers,
+                });
+            }
+            catch {
+                // Seeding is best-effort; a failure never blocks the session.
+            }
+        }
     });
 }
 export default async function (pi) {

package/dist/extension/mineBeat.d.ts

@@ -0,0 +1,95 @@
+/**
+ * The opt-in repo seeding beat (org plane, Run 7).
+ *
+ * On the first interactive session in a repo whose repo-scoped decision
+ * ledger is empty (`/context?repo=` reports `repoDecisionCount: 0`), YAGNI
+ * Code offers — once — to read the repo's own decision record and seed the
+ * ledger: "Read this repo's ADRs and docs and seed the decision ledger?".
+ * One keystroke, then the backend extracts, dedupes, and banks at most 12
+ * `repo_mined` asserted rows, and the beat prints the banked count plus the
+ * Library review deep link.
+ *
+ * Never automatic, never a nag: a decline writes a per-repo marker so the
+ * beat does not recur; an accepted pass marks the repo only after the server
+ * confirms (a transport failure leaves the offer available next session).
+ * The corpus is collected at git HEAD (same echo-chamber guard as
+ * repoDocs.ts) — ADR directories, agent-instruction root docs, top-level
+ * docs/*.md, and recent merge subjects — bounded client-side to the same
+ * limits the backend enforces.
+ */
+/**
+ * Client-side bounds on the mining corpus — mirror of the backend's
+ * MINE_INPUT_LIMITS so nothing is silently truncated server-side.
+ */
+export declare const MINE_BEAT_LIMITS: {
+    readonly maxDocs: 40;
+    readonly maxPathChars: 300;
+    readonly maxExcerptChars: 8000;
+    readonly maxCommitSubjects: 200;
+    readonly maxSubjectChars: 200;
+};
+/** One document offered to the mining pass. */
+export interface MineBeatDoc {
+    path: string;
+    excerpt: string;
+}
+/** Injectable git seam (default: execFileSync; every call fail-soft). */
+export interface MineBeatGit {
+    /** `owner/name` from the origin remote, or undefined outside a repo. */
+    repoFullName: (cwd: string) => string | undefined;
+    /** Tracked paths at HEAD, or null when cwd is not a usable git tree. */
+    listAtHead: (cwd: string) => string[] | null;
+    /** One file's HEAD content, or null when unreadable. */
+    readAtHead: (cwd: string, rel: string) => string | null;
+    /** Recent merge-commit subjects (fallback: plain subjects on squash repos). */
+    mergeSubjects: (cwd: string, max: number) => string[];
+}
+/** Parse `owner/name` from an origin remote URL (ssh or https). */
+export declare function parseRepoFullName(remote: string | null | undefined): string | undefined;
+export declare const defaultMineBeatGit: MineBeatGit;
+/** Is this HEAD-tracked path part of the repo's decision record? */
+export declare function isMineCandidate(rel: string): boolean;
+/** Collect the HEAD-era mining corpus, bounded to MINE_BEAT_LIMITS. */
+export declare function collectMineCorpus(cwd: string, gitImpl?: MineBeatGit): {
+    docs: MineBeatDoc[];
+    commitSubjects: string[];
+};
+/** Injectable marker-store seam (default: a JSON file per repo on disk). */
+export interface MineBeatMarkers {
+    has: (repoFullName: string) => boolean;
+    write: (repoFullName: string, status: "declined" | "seeded") => void;
+}
+/** Filesystem path of one repo's beat marker under the state home. */
+export declare function mineMarkerPath(stateHome: string, repoFullName: string): string;
+export declare function fileMineBeatMarkers(stateHome: string): MineBeatMarkers;
+/** The subset of the session-start ctx the beat needs. */
+export interface MineBeatUi {
+    hasUI: boolean;
+    ui: {
+        confirm?: (title: string, message: string) => Promise<boolean>;
+        notify: (message: string, level: "info" | "error") => void;
+    };
+}
+export interface OfferMiningBeatOptions {
+    repoFullName: string | undefined;
+    /** From `/context?repo=`; the beat fires ONLY on an explicit 0. */
+    repoDecisionCount: number | undefined;
+    cwd: string;
+    baseUrl: string;
+    getToken: () => string | undefined;
+    fetchImpl?: typeof fetch;
+    markers: MineBeatMarkers;
+    gitImpl?: MineBeatGit;
+    collect?: typeof collectMineCorpus;
+}
+export interface MiningBeatOutcome {
+    offered: boolean;
+    accepted?: boolean;
+    banked?: number;
+}
+/**
+ * Offer (once per repo) and, on yes, run the seeding pass. Fail-soft
+ * throughout: any error surfaces as a notify at most, never a broken session.
+ */
+export declare function maybeOfferMiningBeat(ctx: MineBeatUi, opts: OfferMiningBeatOptions): Promise<MiningBeatOutcome>;
+//# sourceMappingURL=mineBeat.d.ts.map

package/dist/extension/mineBeat.js

@@ -0,0 +1,193 @@
+/**
+ * The opt-in repo seeding beat (org plane, Run 7).
+ *
+ * On the first interactive session in a repo whose repo-scoped decision
+ * ledger is empty (`/context?repo=` reports `repoDecisionCount: 0`), YAGNI
+ * Code offers — once — to read the repo's own decision record and seed the
+ * ledger: "Read this repo's ADRs and docs and seed the decision ledger?".
+ * One keystroke, then the backend extracts, dedupes, and banks at most 12
+ * `repo_mined` asserted rows, and the beat prints the banked count plus the
+ * Library review deep link.
+ *
+ * Never automatic, never a nag: a decline writes a per-repo marker so the
+ * beat does not recur; an accepted pass marks the repo only after the server
+ * confirms (a transport failure leaves the offer available next session).
+ * The corpus is collected at git HEAD (same echo-chamber guard as
+ * repoDocs.ts) — ADR directories, agent-instruction root docs, top-level
+ * docs/*.md, and recent merge subjects — bounded client-side to the same
+ * limits the backend enforces.
+ */
+import { execFileSync } from "node:child_process";
+import * as fs from "node:fs";
+import { dirname, join } from "node:path";
+import { METERED_POST_FETCH_POLICY, resilientFetch } from "./resilientFetch.js";
+/**
+ * Client-side bounds on the mining corpus — mirror of the backend's
+ * MINE_INPUT_LIMITS so nothing is silently truncated server-side.
+ */
+export const MINE_BEAT_LIMITS = {
+    maxDocs: 40,
+    maxPathChars: 300,
+    maxExcerptChars: 8_000,
+    maxCommitSubjects: 200,
+    maxSubjectChars: 200,
+};
+const GIT_OPTS = {
+    encoding: "utf8",
+    maxBuffer: 16 * 1024 * 1024,
+    stdio: ["ignore", "pipe", "ignore"],
+};
+function git(cwd, args) {
+    try {
+        return execFileSync("git", args, { cwd, ...GIT_OPTS });
+    }
+    catch {
+        return null;
+    }
+}
+/** Parse `owner/name` from an origin remote URL (ssh or https). */
+export function parseRepoFullName(remote) {
+    if (!remote)
+        return undefined;
+    const m = remote.trim().match(/[:/]([^/:]+\/[^/]+?)(?:\.git)?$/);
+    return m ? m[1] : undefined;
+}
+export const defaultMineBeatGit = {
+    repoFullName: (cwd) => parseRepoFullName(git(cwd, ["config", "--get", "remote.origin.url"])),
+    listAtHead: (cwd) => {
+        const out = git(cwd, ["ls-tree", "-r", "--name-only", "HEAD"]);
+        return out === null ? null : out.split("\n").filter(Boolean);
+    },
+    readAtHead: (cwd, rel) => git(cwd, ["show", `HEAD:${rel}`]),
+    mergeSubjects: (cwd, max) => {
+        const merges = git(cwd, ["log", "--merges", `-n`, String(max), "--pretty=%s"]);
+        const chosen = merges && merges.trim().length > 0
+            ? merges
+            : // Squash-merge repos have no merge commits; plain subjects still
+                // carry the shipped-work trail. No further heuristics (spec flag).
+                git(cwd, ["log", `-n`, String(max), "--pretty=%s"]);
+        return (chosen ?? "").split("\n").map((s) => s.trim()).filter(Boolean).slice(0, max);
+    },
+};
+/** Is this HEAD-tracked path part of the repo's decision record? */
+export function isMineCandidate(rel) {
+    if (/^(?:docs\/)?adrs?\/[^/]+\.md$/i.test(rel))
+        return true;
+    if (/^(?:AGENTS|CLAUDE|CONTRIBUTING|CONTEXT|ARCHITECTURE)\.md$/i.test(rel))
+        return true;
+    if (/^docs\/[^/]+\.md$/i.test(rel))
+        return true;
+    return false;
+}
+/** Collect the HEAD-era mining corpus, bounded to MINE_BEAT_LIMITS. */
+export function collectMineCorpus(cwd, gitImpl = defaultMineBeatGit) {
+    const tracked = gitImpl.listAtHead(cwd);
+    if (tracked === null)
+        return { docs: [], commitSubjects: [] };
+    const docs = [];
+    for (const rel of tracked) {
+        if (docs.length >= MINE_BEAT_LIMITS.maxDocs)
+            break;
+        if (rel.length > MINE_BEAT_LIMITS.maxPathChars)
+            continue;
+        if (!isMineCandidate(rel))
+            continue;
+        const body = gitImpl.readAtHead(cwd, rel);
+        if (body === null || body.trim().length === 0)
+            continue;
+        docs.push({ path: rel, excerpt: body.trim().slice(0, MINE_BEAT_LIMITS.maxExcerptChars) });
+    }
+    const commitSubjects = gitImpl
+        .mergeSubjects(cwd, MINE_BEAT_LIMITS.maxCommitSubjects)
+        .map((s) => s.slice(0, MINE_BEAT_LIMITS.maxSubjectChars));
+    return { docs, commitSubjects };
+}
+/** Filesystem path of one repo's beat marker under the state home. */
+export function mineMarkerPath(stateHome, repoFullName) {
+    return join(stateHome, "mine-beat", `${repoFullName.replace(/[/\\]/g, "__")}.json`);
+}
+export function fileMineBeatMarkers(stateHome) {
+    return {
+        has: (repo) => {
+            try {
+                return fs.existsSync(mineMarkerPath(stateHome, repo));
+            }
+            catch {
+                return false;
+            }
+        },
+        write: (repo, status) => {
+            try {
+                const p = mineMarkerPath(stateHome, repo);
+                fs.mkdirSync(dirname(p), { recursive: true });
+                fs.writeFileSync(p, JSON.stringify({ status, at: new Date().toISOString() }), "utf8");
+            }
+            catch {
+                // A marker failure must never break the session; worst case the beat
+                // asks once more next launch.
+            }
+        },
+    };
+}
+/**
+ * Offer (once per repo) and, on yes, run the seeding pass. Fail-soft
+ * throughout: any error surfaces as a notify at most, never a broken session.
+ */
+export async function maybeOfferMiningBeat(ctx, opts) {
+    const { repoFullName } = opts;
+    // Only an EXPLICIT zero fires the beat: an absent count means an older
+    // backend or a count failure, and a nag on either would be wrong.
+    if (!repoFullName || opts.repoDecisionCount !== 0)
+        return { offered: false };
+    if (opts.markers.has(repoFullName))
+        return { offered: false };
+    if (!ctx.hasUI || typeof ctx.ui.confirm !== "function")
+        return { offered: false };
+    const collect = opts.collect ?? collectMineCorpus;
+    const corpus = collect(opts.cwd, opts.gitImpl ?? defaultMineBeatGit);
+    // Nothing to mine yet: skip WITHOUT a marker, so a later checkout that
+    // gains docs still gets its one offer.
+    if (corpus.docs.length === 0 && corpus.commitSubjects.length === 0) {
+        return { offered: false };
+    }
+    const accepted = await ctx.ui.confirm("Seed the decision ledger?", `Read this repo's ADRs and docs and bank up to 12 candidate decisions for ${repoFullName}? You review every one in the Library before it counts as confirmed.`);
+    if (!accepted) {
+        opts.markers.write(repoFullName, "declined");
+        return { offered: true, accepted: false };
+    }
+    try {
+        const res = await resilientFetch(`${opts.baseUrl}/api/yagni-code/decisions/mine`, {
+            method: "POST",
+            headers: {
+                authorization: `Bearer ${opts.getToken() ?? ""}`,
+                "content-type": "application/json",
+            },
+            body: JSON.stringify({
+                repo: repoFullName,
+                docs: corpus.docs,
+                commitSubjects: corpus.commitSubjects,
+                // Stable per repo: the write-spool replay contract makes a retry of
+                // the same pass idempotent server-side.
+                idempotencyKey: `mine:${repoFullName}`,
+            }),
+        }, { fetchImpl: opts.fetchImpl, policy: METERED_POST_FETCH_POLICY });
+        if (!res.ok) {
+            // No marker: the offer stays available next session.
+            ctx.ui.notify("Seeding the decision ledger failed; YAGNI Code will offer again next session.", "error");
+            return { offered: true, accepted: true };
+        }
+        const body = (await res.json());
+        opts.markers.write(repoFullName, "seeded");
+        if (body.alreadyMined)
+            return { offered: true, accepted: true, banked: 0 };
+        const banked = typeof body.banked === "number" ? body.banked : 0;
+        const noun = banked === 1 ? "decision" : "decisions";
+        ctx.ui.notify(`Banked ${banked} ${noun} read from this repo's docs. Review them: ${opts.baseUrl}/knowledge/decisions`, "info");
+        return { offered: true, accepted: true, banked };
+    }
+    catch {
+        ctx.ui.notify("Seeding the decision ledger failed; YAGNI Code will offer again next session.", "error");
+        return { offered: true, accepted: true };
+    }
+}
+//# sourceMappingURL=mineBeat.js.map

package/dist/extension/pipeline/personas.js

@@ -57,7 +57,7 @@ Budget discipline: you have a hard output budget, and a plan that gets cut off m
 Keep it concrete; the worker executes it verbatim.`;
 const WORKER_BODY = `You are a worker with full capabilities, operating in an isolated context to implement a plan. Work autonomously and use the tools as needed.
 
-You are grounded. Call ask_yagni before guessing about anything organization- or codebase-specific. Critically: for ANY product-intent call you are forced to make that the plan did not settle — a behavior choice, a tradeoff, an interpretation of intent — call record_decision so the company's decision corpus captures it and the next agent inherits the call instead of re-litigating it.
+You are grounded. Call ask_yagni before guessing about anything organization- or codebase-specific. Treat a confirmed answer as settled; when an answer is an unverified assumption or an inference and your change leans on it, say so in your Notes so the reviewer knows what to check. Critically: for ANY product-intent call you are forced to make that the plan did not settle — a behavior choice, a tradeoff, an interpretation of intent — call record_decision so the company's decision corpus captures it and the next agent inherits the call instead of re-litigating it. When ask_yagni reports no recorded position, follow its instruction and record the assumption you proceed on.
 
 You MUST make the change. If the plan is missing, partial, or appears cut off, do not stop at exploring: implement the ticket directly from the ticket text and the code, calling record_decision for any intent you infer. Ending your turn with no write/edit is a failure.
 

package/dist/extension/recordDecisionTool.d.ts

@@ -1,5 +1,6 @@
 import type { ToolDefinition } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
+import { type FlywheelState } from "./flywheel.js";
 /** Options for {@link makeRecordDecisionTool}. */
 export interface MakeRecordDecisionToolOptions {
     baseUrl: string;
@@ -7,6 +8,13 @@ export interface MakeRecordDecisionToolOptions {
     fetchImpl?: typeof fetch;
     /** Idempotency-key source (default: crypto.randomUUID); injected in tests. */
     makeIdempotencyKey?: () => string;
+    /**
+     * Shared flywheel session state (Run 7). A record_decision that follows a
+     * surfaced no-position suggestion sends `dedupe: true` — a mid-run agent
+     * has no human to adjudicate a near-duplicate. A human `/decide` never
+     * rides this state.
+     */
+    flywheel?: FlywheelState;
 }
 /** The durable fields of a recorded product-intent decision. */
 export interface RecordDecisionParams {

package/dist/extension/recordDecisionTool.js

@@ -1,5 +1,6 @@
 import { randomUUID } from "node:crypto";
 import { Type } from "typebox";
+import { consumeFlywheelAttribution } from "./flywheel.js";
 import { sendOrSpool } from "./spool.js";
 /**
  * POST a single decision to the token-scoped grounding endpoint and return its
@@ -67,12 +68,20 @@ export function makeRecordDecisionTool(opts) {
             // never bank the same decision twice. Transport failures and 5xx are
             // spooled durably instead of lost (R4 write half).
             const idempotencyKey = (opts.makeIdempotencyKey ?? randomUUID)();
+            // Run 7 flywheel attribution: a record answering the QUESTION a
+            // surfaced no-position suggestion asked about asks the backend to
+            // dedupe against active decisions first (decisive, not advisory — no
+            // human is present). An unrelated record never inherits the flag.
+            const flywheelAttributed = opts.flywheel
+                ? consumeFlywheelAttribution(opts.flywheel, params.question)
+                : false;
             const outcome = await sendOrSpool(opts, "record_decision", "/api/yagni-code/decisions", {
                 question: params.question,
                 decision: params.decision,
                 rationale: params.rationale,
                 repo: params.repo,
                 workItemId: params.workItemId,
+                ...(flywheelAttributed ? { dedupe: true } : {}),
             }, idempotencyKey, signal);
             if (outcome.kind === "rejected") {
                 throw new Error(outcome.message);
@@ -92,6 +101,21 @@ export function makeRecordDecisionTool(opts) {
                 };
             }
             const data = outcome.json;
+            if (data?.deduped) {
+                // The backend matched an existing active decision and inserted
+                // nothing; surface it so the agent leans on the recorded judgment.
+                const existing = data.existing;
+                const summary = existing?.decision ? ` ${existing.decision}` : "";
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `An equivalent decision is already recorded; nothing new was banked.${summary}`,
+                        },
+                    ],
+                    details: { id: existing?.id ?? null, spooled: false },
+                };
+            }
             return {
                 content: [{ type: "text", text: "Recorded the decision in YAGNI." }],
                 details: { id: data?.id ?? null, spooled: false },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yagni-app/code-staging",
-  "version": "0.3.0-staging.1096.1",
+  "version": "0.3.0-staging.1098.1",
   "description": "YAGNI Code: a terminal coding agent that already knows your company. One YAGNI login routes the model and grounds the agent in your team's context.",
   "license": "SEE LICENSE IN LICENSE.md",
   "author": "YAGNI, Inc. <jack@yagni.app> (https://yagni.app)",
@@ -39,5 +39,5 @@
     "smol-toml": "^1.8.0",
     "typebox": "^1.3.11"
   },
-  "yagniSourceSha": "04ba3799e7c6310f337b80067ba44ee257d69df3"
+  "yagniSourceSha": "41fc21aacfab499d38635d4dad5bace90249b438"
 }