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

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/dist/token.d.ts

@@ -0,0 +1,25 @@
+/**
+ * `yagni token` — print the active environment's API token to stdout.
+ *
+ * This is the credential feed for `yagni connect claude-code`: Claude Code's
+ * `apiKeyHelper` runs this command (re-running on 401 and on a TTL), so the
+ * contract is strict — stdout carries the TOKEN AND NOTHING ELSE (Claude Code
+ * v2.1.227+ rejects helpers that print banners), and every notice goes to
+ * stderr. Riding the same refresh-at-launch client as the launcher means a
+ * token that enters the 7-day rotation window is rotated and persisted here
+ * too, so a Claude Code session keeps working without the user ever running
+ * `yagni` itself.
+ */
+import { maybeRefreshAtLaunch } from "./refresh.js";
+import type { Credentials } from "./credentials.js";
+import { type Profile } from "./profiles.js";
+export interface TokenCommandDeps {
+    readProfile?: () => Promise<Profile>;
+    refresh?: typeof maybeRefreshAtLaunch;
+    persist?: (name: string, creds: Credentials) => Promise<void>;
+    now?: () => number;
+    stdout?: (text: string) => void;
+    stderr?: (text: string) => void;
+}
+export declare function tokenCommand(deps?: TokenCommandDeps): Promise<number>;
+//# sourceMappingURL=token.d.ts.map

package/dist/token.js

@@ -0,0 +1,45 @@
+/**
+ * `yagni token` — print the active environment's API token to stdout.
+ *
+ * This is the credential feed for `yagni connect claude-code`: Claude Code's
+ * `apiKeyHelper` runs this command (re-running on 401 and on a TTL), so the
+ * contract is strict — stdout carries the TOKEN AND NOTHING ELSE (Claude Code
+ * v2.1.227+ rejects helpers that print banners), and every notice goes to
+ * stderr. Riding the same refresh-at-launch client as the launcher means a
+ * token that enters the 7-day rotation window is rotated and persisted here
+ * too, so a Claude Code session keeps working without the user ever running
+ * `yagni` itself.
+ */
+import { classifyTokenExpiry } from "./launch.js";
+import { maybeRefreshAtLaunch } from "./refresh.js";
+import { credentialsFromProfile, persistProfileTokenRotation, readActiveProfile, } from "./profiles.js";
+export async function tokenCommand(deps = {}) {
+    const readProfile = deps.readProfile ?? readActiveProfile;
+    const refresh = deps.refresh ?? maybeRefreshAtLaunch;
+    const persist = deps.persist ?? persistProfileTokenRotation;
+    const stdout = deps.stdout ?? ((t) => process.stdout.write(t));
+    const stderr = deps.stderr ?? ((t) => process.stderr.write(t));
+    const profile = await readProfile();
+    let creds = credentialsFromProfile(profile);
+    if (!creds?.token) {
+        stderr(`Not logged in to environment "${profile.name}" (${profile.baseUrl}). Run \`yagni login\` first.\n`);
+        return 1;
+    }
+    const outcome = await refresh(creds, {
+        persist: (c) => persist(profile.name, c),
+        ...(deps.now ? { now: deps.now } : {}),
+    });
+    for (const warning of outcome.warnings)
+        stderr(`${warning}\n`);
+    creds = outcome.creds;
+    // An expired token would send the consumer into a silent 401 loop — fail
+    // loudly instead so Claude Code surfaces a helper error the user can act on.
+    const nowMs = deps.now ? deps.now() : Date.now();
+    if (classifyTokenExpiry(creds.expiresAt, nowMs).kind === "expired") {
+        stderr("Your YAGNI Code session has expired. Run `yagni login` to re-authenticate.\n");
+        return 1;
+    }
+    stdout(`${creds.token}\n`);
+    return 0;
+}
+//# sourceMappingURL=token.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yagni-app/code-staging",
-  "version": "0.3.0-staging.1093.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)",
@@ -36,7 +36,8 @@
   "dependencies": {
     "@earendil-works/pi-coding-agent": "0.84.1",
     "@earendil-works/pi-tui": "0.84.1",
+    "smol-toml": "^1.8.0",
     "typebox": "^1.3.11"
   },
-  "yagniSourceSha": "189159f08a0b5f7ab5cf10221f8238782ff7d1f7"
+  "yagniSourceSha": "41fc21aacfab499d38635d4dad5bace90249b438"
 }