toolroll 0.9.32 → 0.9.34

package/dist/contracts/contract.js

@@ -0,0 +1,181 @@
+/**
+ * The one way Toolroll describes a contract (docs/plans/zod-revamp.md): one Zod schema, and everything else — the
+ * TypeScript type, the runtime check, the JSON Schema a model gets, the text limits — derived from it.
+ *
+ * The helpers here hold the ground rules every contract shares: limits come from TEXT_LIMITS, persisted payloads are
+ * versioned, refusals name the path, and a model-facing schema is exactly what its JSON Schema says (no refinements or
+ * transforms; those checks run in plain code after parsing, with a named error).
+ */
+import { z } from "zod";
+import { limitRule, TEXT_LIMITS } from "../text-limits.js";
+/**
+ * A string bounded by its TEXT_LIMITS entry, never a literal. The limit rule rides along as the field's description,
+ * so a model reads the bound before it writes. Zod counts UTF-16 code units; for a limit named in bytes this is the
+ * schema's necessary bound (a string within N bytes is within N code units), and the byte count itself is checked in
+ * plain code after parsing.
+ */
+export function limited(field, limitKey) {
+    const limit = TEXT_LIMITS[limitKey];
+    const unit = limitKey.endsWith("Bytes") ? "bytes" : "characters";
+    return z.string().max(limit, { error: `over ${limit.toLocaleString("en-US")} ${unit}` }).describe(limitRule(field, limit, unit));
+}
+/** A versioned payload envelope: a strict object whose `version` is exactly `version`. */
+export function versioned(version, shape) {
+    return z.strictObject({ version: z.literal(version), ...shape });
+}
+/** `["steps", 0, "routes", 0, "goesTo"]` as `steps[0].routes[0].goesTo`. */
+export function pathOf(path) {
+    let out = "";
+    for (const part of path) {
+        if (typeof part === "number")
+            out += `[${part}]`;
+        else
+            out += out === "" ? String(part) : `.${String(part)}`;
+    }
+    return out === "" ? "payload" : out;
+}
+function got(input) {
+    if (input === null)
+        return "null";
+    if (Array.isArray(input))
+        return "an array";
+    return typeof input === "object" ? "an object" : `a ${typeof input}`;
+}
+function issuesOf(issue) {
+    const at = pathOf(issue.path);
+    const one = (kind, what) => ({ path: at, kind, line: `${at}: ${what}` });
+    switch (issue.code) {
+        case "unrecognized_keys":
+            return issue.keys.map(key => ({ path: at, kind: "unknown-key", line: `${at}: unknown key '${key}'` }));
+        case "invalid_type": {
+            const missing = "input" in issue ? issue.input === undefined : / received undefined$/.test(issue.message);
+            if (missing)
+                return [one("required", "required")];
+            return [one("wrong-type", `must be ${issue.expected === "array" ? "an array" : issue.expected === "object" ? "an object" : `a ${issue.expected}`}${"input" in issue ? ` (got ${got(issue.input)})` : ""}`)];
+        }
+        case "too_big":
+            if (issue.origin === "array" || issue.origin === "set")
+                return [one("too-many", `at most ${String(issue.maximum)} items`)];
+            return [one("too-long", issue.origin === "string" && issue.message.startsWith("over ") ? issue.message : `at most ${String(issue.maximum)}${issue.origin === "string" ? " characters" : ""}`)];
+        case "too_small":
+            if (issue.origin === "string" && Number(issue.minimum) === 1)
+                return [one("empty", "must not be empty")];
+            if (issue.origin === "array" || issue.origin === "set")
+                return [one("too-few", `at least ${String(issue.minimum)} item${Number(issue.minimum) === 1 ? "" : "s"}`)];
+            return [one("too-few", `at least ${String(issue.minimum)}`)];
+        case "invalid_value":
+            return [one("bad-value", `must be ${issue.values.length === 1 ? JSON.stringify(issue.values[0]) : `one of ${issue.values.map(value => JSON.stringify(value)).join(", ")}`}`)];
+        case "invalid_union":
+            return [one("invalid", "does not match any allowed shape")];
+        default:
+            return [one("invalid", issue.message)];
+    }
+}
+/** A Zod error as path-named issues, in the error's own order. */
+export function contractIssues(error) {
+    return error.issues.flatMap(issuesOf);
+}
+/** A Zod error as path-named lines: `steps[0].routes[0].goesTo: required`, `routes[0]: unknown key 'to'`. */
+export function contractError(error) {
+    return contractIssues(error).map(issue => issue.line);
+}
+/** Parse with the input reported, so a missing field reads `required` rather than a wrong type. */
+export function parseContract(schema, input) {
+    const parsed = schema.safeParse(input, { reportInput: true });
+    return parsed.success ? { ok: true, value: parsed.data } : { ok: false, issues: contractIssues(parsed.error) };
+}
+/**
+ * Read a versioned payload. The current version parses as itself; an older known version (0 for a payload saved
+ * before it carried `version`) is upgraded by its adapter and then parsed by the same schema; a newer version is
+ * refused plainly; anything else is an unknown version.
+ */
+export function readVersioned(schema, input, upgrades = {}) {
+    const current = schema.shape.version.value;
+    if (typeof input !== "object" || input === null || Array.isArray(input)) {
+        return { ok: false, issues: [{ path: "payload", kind: "wrong-type", line: `payload: must be an object (got ${got(input)})` }] };
+    }
+    const body = input;
+    const version = Object.prototype.hasOwnProperty.call(body, "version") ? body["version"] : 0;
+    if (version === current)
+        return parseContract(schema, body);
+    if (typeof version === "number" && Number.isInteger(version) && version > current) {
+        return { ok: false, issues: [{ path: "version", kind: "newer-version", line: `version: made by a newer Toolroll (version ${version}; this one reads up to ${current})` }] };
+    }
+    const upgrade = typeof version === "number" ? upgrades[version] : undefined;
+    if (upgrade === undefined) {
+        return { ok: false, issues: [{ path: "version", kind: "bad-value", line: `version: unknown version ${JSON.stringify(version)} (this Toolroll reads ${current}${Object.keys(upgrades).length === 0 ? "" : ` and ${Object.keys(upgrades).join(", ")}`})` }] };
+    }
+    return parseContract(schema, upgrade(body));
+}
+/** The Zod node kinds a model-facing schema may use: each says exactly what its JSON Schema says. */
+const MODEL_FACING_TYPES = new Set(["string", "number", "int", "boolean", "null", "literal", "enum", "array", "object", "optional", "nullable", "union", "tuple", "record", "lazy", "readonly", "unknown", "any"]);
+/** Checks that only constrain (never rewrite) and that JSON Schema can state. */
+const MODEL_FACING_CHECKS = new Set(["max_length", "min_length", "length_equals", "greater_than", "less_than", "multiple_of", "number_format", "string_format", "size_equals", "max_size", "min_size"]);
+/** Every node of a schema graph, refusing a refinement, transform, preprocess or unknown node by its schema path. */
+function assertModelFacing(schema, at, seen) {
+    if (seen.has(schema))
+        return;
+    seen.add(schema);
+    const def = schema._zod.def;
+    const where = at === "" ? "the schema" : at;
+    if (def.type === "pipe") {
+        const into = def["in"]?._zod.def.type;
+        const out = def["out"]?._zod.def.type;
+        const what = into === "transform" ? "preprocess" : out === "transform" ? "transform" : "pipe";
+        throw new Error(`toModelSchema: ${where} uses ${what}; a model-facing schema must be JSON-Schema-exact — check it in plain code after parsing`);
+    }
+    if (def.type === "transform")
+        throw new Error(`toModelSchema: ${where} uses transform; a model-facing schema must be JSON-Schema-exact — check it in plain code after parsing`);
+    if (!MODEL_FACING_TYPES.has(def.type))
+        throw new Error(`toModelSchema: ${where} uses a ${def.type} node, which a model-facing schema may not use`);
+    for (const check of def.checks ?? []) {
+        const kind = check._zod.def.check;
+        if (kind === "custom")
+            throw new Error(`toModelSchema: ${where} uses refine or superRefine; a model-facing schema must be JSON-Schema-exact — check it in plain code after parsing`);
+        if (!MODEL_FACING_CHECKS.has(kind))
+            throw new Error(`toModelSchema: ${where} uses a ${kind} check, which rewrites or cannot be stated in JSON Schema`);
+    }
+    const child = (value, path) => assertModelFacing(value, path, seen);
+    const join = (key) => (at === "" ? key : `${at}.${key}`);
+    switch (def.type) {
+        case "object":
+            for (const [key, value] of Object.entries(def["shape"]))
+                child(value, join(key));
+            // A strict object's catchall is `never` (additionalProperties: false); any other catchall is a schema too.
+            if (def["catchall"] !== undefined && def["catchall"]._zod.def.type !== "never")
+                child(def["catchall"], join("*"));
+            break;
+        case "array":
+            child(def["element"], `${at}[]`);
+            break;
+        case "optional":
+        case "nullable":
+        case "readonly":
+            child(def["innerType"], at);
+            break;
+        case "union":
+            def["options"].forEach((option, index) => child(option, `${at}|${index}`));
+            break;
+        case "tuple":
+            def["items"].forEach((item, index) => child(item, `${at}[${index}]`));
+            if (def["rest"] !== undefined && def["rest"] !== null)
+                child(def["rest"], `${at}[]`);
+            break;
+        case "record":
+            child(def["keyType"], `${at}{key}`);
+            child(def["valueType"], `${at}{}`);
+            break;
+        case "lazy":
+            child(def["getter"](), at);
+            break;
+    }
+}
+/**
+ * The JSON Schema a model gets for `schema` (Claude's `--json-schema`). Throws when the schema uses refine,
+ * superRefine, transform or preprocess anywhere: what a model is told must be everything the schema checks.
+ */
+export function toModelSchema(schema) {
+    assertModelFacing(schema, "", new Set());
+    const { $schema: _dialect, ...json } = z.toJSONSchema(schema, { target: "draft-2020-12", unrepresentable: "throw" });
+    return json;
+}

package/dist/contracts/plan.d.ts

@@ -0,0 +1,58 @@
+/**
+ * The planner's handoff: one schema for the file a planner writes, the JSON Schema it is given (`--json-schema`) and
+ * the parser that reads it back (`parsePlan` in plan.ts). The rules JSON Schema cannot state — the plan document's
+ * sections, UTF-8 byte limits, control characters, duplicate criterion ids, the Proof naming every criterion and the
+ * silent-amendment contract check — run in plain code after parsing, each with a named error.
+ */
+import { z } from "zod";
+import { type ContractResult } from "./contract.js";
+/** How many paths a plan may say it touches. */
+export declare const PLAN_TOUCHES = 32;
+/** One acceptance criterion: the scope's own shape (scope.ts `AcceptanceCriterion`), `how` advisory and unsigned. */
+export declare const acceptanceCriterionSchema: z.ZodObject<{
+    id: z.ZodString;
+    statement: z.ZodString;
+    how: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    evidence: z.ZodArray<z.ZodEnum<{
+        "changed-path": "changed-path";
+        check: "check";
+        "manual-review": "manual-review";
+        screenshot: "screenshot";
+    }>>;
+}, z.core.$strict>;
+export declare const PLAN_VERSION = 1;
+export declare const planSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    goal: z.ZodString;
+    outOfScope: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    touches: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    acceptance: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        statement: z.ZodString;
+        how: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        evidence: z.ZodArray<z.ZodEnum<{
+            "changed-path": "changed-path";
+            check: "check";
+            "manual-review": "manual-review";
+            screenshot: "screenshot";
+        }>>;
+    }, z.core.$strict>>;
+    plan: z.ZodString;
+    amendment: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strict>;
+export type PlanPayload = z.infer<typeof planSchema>;
+/** What the planner's `--json-schema` is: the plan schema, exactly. */
+export declare const PLAN_MODEL_SCHEMA: Readonly<Record<string, unknown>>;
+/**
+ * A plan written before plans carried `version` (every plan through 0.9.33), as version 1. The old parser read only
+ * the fields it knew and ignored any others, read a null goal, plan or acceptance as missing and null touches as
+ * none; this keeps exactly that, so every plan that parsed then parses now. Values themselves are never rewritten.
+ */
+export declare function upgradeUnversionedPlan(body: Record<string, unknown>): Record<string, unknown>;
+export declare const PLAN_UPGRADES: {
+    readonly 0: typeof upgradeUnversionedPlan;
+};
+/** The payload as version 1, upgraded when it was saved unversioned; null for anything that is not an object. */
+export declare function planPayloadBody(input: unknown): Record<string, unknown> | null;
+/** Read a plan payload: version 1 as itself, an unversioned one upgraded, a newer one refused plainly. */
+export declare function readPlanPayload(input: unknown): ContractResult<PlanPayload>;

package/dist/contracts/plan.js

@@ -0,0 +1,67 @@
+/**
+ * The planner's handoff: one schema for the file a planner writes, the JSON Schema it is given (`--json-schema`) and
+ * the parser that reads it back (`parsePlan` in plan.ts). The rules JSON Schema cannot state — the plan document's
+ * sections, UTF-8 byte limits, control characters, duplicate criterion ids, the Proof naming every criterion and the
+ * silent-amendment contract check — run in plain code after parsing, each with a named error.
+ */
+import { z } from "zod";
+import { ACCEPTANCE_LIMITS, EVIDENCE_KINDS } from "../scope.js";
+import { limited, readVersioned, toModelSchema, versioned } from "./contract.js";
+/** How many paths a plan may say it touches. */
+export const PLAN_TOUCHES = 32;
+/** One acceptance criterion: the scope's own shape (scope.ts `AcceptanceCriterion`), `how` advisory and unsigned. */
+export const acceptanceCriterionSchema = z.strictObject({
+    id: limited("acceptance id", "acceptanceIdBytes").min(1),
+    statement: limited("acceptance statement", "acceptanceStatementBytes").min(1),
+    how: limited("acceptance how", "acceptanceHowBytes").nullable().optional(),
+    evidence: z.array(z.enum(EVIDENCE_KINDS)).min(1).max(EVIDENCE_KINDS.length),
+});
+export const PLAN_VERSION = 1;
+export const planSchema = versioned(PLAN_VERSION, {
+    goal: limited("goal", "goal").min(1),
+    outOfScope: limited("outOfScope", "goal").nullable().optional(),
+    touches: z.array(limited("touch", "planTouch").min(1)).max(PLAN_TOUCHES).optional(),
+    acceptance: z.array(acceptanceCriterionSchema).min(1).max(ACCEPTANCE_LIMITS.criteria),
+    plan: limited("plan", "planDocumentBytes").min(1),
+    amendment: limited("amendment", "planAmendment").nullable().optional(),
+});
+/** What the planner's `--json-schema` is: the plan schema, exactly. */
+export const PLAN_MODEL_SCHEMA = toModelSchema(planSchema);
+const PLAN_FIELDS = ["goal", "outOfScope", "touches", "acceptance", "plan", "amendment"];
+const CRITERION_FIELDS = ["id", "statement", "how", "evidence"];
+function pick(body, fields) {
+    const out = {};
+    for (const field of fields) {
+        if (Object.prototype.hasOwnProperty.call(body, field) && body[field] !== undefined)
+            out[field] = body[field];
+    }
+    return out;
+}
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/**
+ * A plan written before plans carried `version` (every plan through 0.9.33), as version 1. The old parser read only
+ * the fields it knew and ignored any others, read a null goal, plan or acceptance as missing and null touches as
+ * none; this keeps exactly that, so every plan that parsed then parses now. Values themselves are never rewritten.
+ */
+export function upgradeUnversionedPlan(body) {
+    const out = { version: PLAN_VERSION, ...pick(body, PLAN_FIELDS) };
+    for (const field of ["goal", "plan", "touches", "acceptance"]) {
+        if (out[field] === null)
+            delete out[field];
+    }
+    if (Array.isArray(out["acceptance"])) {
+        out["acceptance"] = out["acceptance"].map(criterion => (isRecord(criterion) ? pick(criterion, CRITERION_FIELDS) : criterion));
+    }
+    return out;
+}
+export const PLAN_UPGRADES = { 0: upgradeUnversionedPlan };
+/** The payload as version 1, upgraded when it was saved unversioned; null for anything that is not an object. */
+export function planPayloadBody(input) {
+    if (!isRecord(input))
+        return null;
+    return Object.prototype.hasOwnProperty.call(input, "version") ? input : upgradeUnversionedPlan(input);
+}
+/** Read a plan payload: version 1 as itself, an unversioned one upgraded, a newer one refused plainly. */
+export function readPlanPayload(input) {
+    return readVersioned(planSchema, input, PLAN_UPGRADES);
+}

package/dist/desktop-update.d.ts

@@ -125,13 +125,13 @@ export declare function prepareDesktopUpdate(stateDir: string, installed: string
 export declare function sqliteLock(file: string, busyTimeoutMs?: number): DatabaseSync | null;
 export declare const installationLock: (j: UpdateJournal) => DatabaseSync | null;
 export declare function desktopUpdateStatus(stateDir: string): {
+    error?: never;
     active: boolean;
     phase: string;
     detail: string;
     running: boolean;
     canResume: boolean;
     canCancel: boolean;
-    error?: never;
     automaticRecovery?: never;
     recoveryAttempts?: never;
     recoveryRepairs?: never;

package/dist/evidence.js

@@ -18,7 +18,7 @@ import { closeSync, existsSync, constants, fstatSync, mkdirSync, openSync, readd
 import { join, sep } from "node:path";
 import { namedPath } from "./names.js";
 import { LIMITS } from "./decision.js";
-import { PLAN_LIMITS } from "./plan.js";
+import { TEXT_LIMITS } from "./text-limits.js";
 import { parseReport, REPORT_LIMITS } from "./scout-report.js";
 import { parseProof, PROOF_LIMITS } from "./proof.js";
 import { encodeBaseTreeSnapshot, parseBaseTreeSnapshot } from "./peek.js";
@@ -84,7 +84,7 @@ export const EVIDENCE_CAPS = {
     diff: 256 * 1024,
     status: 64 * 1024,
     "park-payload": LIMITS.payload,
-    plan: PLAN_LIMITS.document,
+    plan: TEXT_LIMITS.planDocumentBytes,
     "terminal-diff": 256 * 1024,
     "diff-stat": 32 * 1024,
     // The enveloped base snapshot (live peek): 20k entries of path+sha+size.

package/dist/guides.js

@@ -419,6 +419,9 @@ and crew agent reads from it before working:
 - Instructions and references change on the Knowledge page under Settings,
   or through the lead's knowledge cards. Every change keeps a revision you
   can restore.
+- If a project was replaced at the same path, its saved knowledge waits:
+  tasks run without it until an approver applies it on the Knowledge page
+  or with \`toolroll knowledge apply --repo PATH --as <you> --token <t>\`.
 - Agent conclusions are not instructions: a crew agent reports; a person or
   the lead's confirmed card records.
 

package/dist/knowledge-cli.d.ts

@@ -89,7 +89,38 @@ export declare const KNOWLEDGE_DESCRIPTORS: readonly [{
         readonly takesValue: true;
         readonly meaning: 'environment variable containing a scoped coordinator token';
     }];
+}, {
+    readonly action: 'apply';
+    readonly synopsis: "carry this project's saved knowledge from before a change forward as a new revision; an approver's --as/--token";
+    readonly mutation: 'identity-idempotent';
+    readonly takesQuery: false;
+    readonly flags: readonly [{
+        readonly name: 'repo';
+        readonly takesValue: true;
+        readonly meaning: 'admitted project checkout root';
+    }, {
+        readonly name: 'as';
+        readonly takesValue: true;
+        readonly meaning: 'approver account name';
+    }, {
+        readonly name: 'token';
+        readonly takesValue: true;
+        readonly meaning: "the approver's password (never a lead token)";
+    }, {
+        readonly name: 'json';
+        readonly takesValue: false;
+        readonly meaning: 'versioned structured response';
+    }, {
+        readonly name: 'db';
+        readonly takesValue: true;
+        readonly meaning: 'local Toolroll database';
+    }];
+    readonly audience: 'operator';
 }];
+/** `knowledge apply`: the caller has verified `actor` as an approver of `repo` (never the lead). */
+export declare function runKnowledgeApply(options: Map<string, string | true>, context: KnowledgeCliContext & {
+    actor: string | null;
+}): number;
 export type KnowledgeCliContext = {
     store: Store;
     write: (line: string) => void;

package/dist/knowledge-cli.js

@@ -6,6 +6,7 @@ import { authenticateCoordinator } from './coordinator.js';
 import { envelopeJson } from './envelope.js';
 import { repositoryContext } from './repository-context.js';
 import { namedPath } from './names.js';
+import { applySavedKnowledge } from './project-knowledge.js';
 const flags = [
     { name: 'repo', takesValue: true, meaning: 'admitted project checkout root' },
     { name: 'base', takesValue: true, meaning: 'exact committed task base; defaults to current HEAD' },
@@ -14,11 +15,43 @@ const flags = [
     { name: 'token-file', takesValue: true, meaning: 'explicit scoped coordinator credential file' },
     { name: 'token-env', takesValue: true, meaning: 'environment variable containing a scoped coordinator token' },
 ];
+const applyFlags = [
+    { name: 'repo', takesValue: true, meaning: 'admitted project checkout root' },
+    { name: 'as', takesValue: true, meaning: 'approver account name' },
+    { name: 'token', takesValue: true, meaning: "the approver's password (never a lead token)" },
+    { name: 'json', takesValue: false, meaning: 'versioned structured response' },
+    { name: 'db', takesValue: true, meaning: 'local Toolroll database' },
+];
 export const KNOWLEDGE_DESCRIPTORS = [
     { action: 'search', synopsis: 'find bounded source excerpts and relevant code symbols', mutation: 'none', takesQuery: true, flags },
     { action: 'impact', synopsis: 'inspect static imports affected by one file or unambiguous symbol', mutation: 'none', takesQuery: true, flags },
     { action: 'refresh', synopsis: 'refresh the optional local code index; never starts a model or task', mutation: 'identity-idempotent', takesQuery: false, flags },
+    // A person's action: the approver carries saved knowledge from before a project change forward.
+    { action: 'apply', synopsis: "carry this project's saved knowledge from before a change forward as a new revision; an approver's --as/--token", mutation: 'identity-idempotent', takesQuery: false, flags: applyFlags, audience: 'operator' },
 ];
+/** `knowledge apply`: the caller has verified `actor` as an approver of `repo` (never the lead). */
+export function runKnowledgeApply(options, context) {
+    const command = 'knowledge apply';
+    const fail = (reason, message) => { context.write(context.json ? envelopeJson({ ok: false, command, reason, message }) : message); return reason === 'usage' ? 2 : 3; };
+    for (const key of options.keys())
+        if (!applyFlags.some(flag => flag.name === key))
+            return fail('usage', `--${key} is not a knowledge apply option.`);
+    const repo = options.get('repo');
+    if (typeof repo !== 'string' || !repo.trim() || repo.length > 4096 || /[\x00-\x1f]/.test(repo))
+        return fail('usage', 'Use --repo with the project checkout root.');
+    if (context.actor === null)
+        return fail('unauthenticated', 'An approver of this project applies saved knowledge: --as <you> --token <password>.');
+    let revision;
+    try {
+        revision = applySavedKnowledge(context.store, resolve(repo), context.actor, context.now);
+    }
+    catch (error) {
+        return fail('failed', error instanceof Error ? error.message : 'Saved knowledge could not be applied.');
+    }
+    const message = revision === null ? 'Nothing to apply.' : `Applied saved knowledge as version ${revision}.`;
+    context.write(context.json ? envelopeJson({ ok: true, command, result: { revision, message } }) : message);
+    return 0;
+}
 function lines(result) {
     return [
         `Repository context: ${result.index.status}${result.index.engine === 'text-search' ? ' · source search' : ' · code relationships'}`,
@@ -32,8 +65,8 @@ export async function runKnowledgeCommand(positional, options, context) {
     const spec = KNOWLEDGE_DESCRIPTORS.find(s => s.action === positional[0]);
     const command = spec ? `knowledge ${spec.action}` : 'knowledge';
     const fail = (reason, message) => { context.write(context.json ? envelopeJson({ ok: false, command, reason, message }) : message); return reason === 'usage' ? 2 : 3; };
-    if (!spec)
-        return fail('usage', 'Use knowledge search <query>, impact <file-or-symbol>, or refresh with --repo PATH.');
+    if (!spec || spec.action === 'apply')
+        return fail('usage', 'Use knowledge search <query>, impact <file-or-symbol>, refresh or apply with --repo PATH.');
     if (positional.length !== (spec.takesQuery ? 2 : 1))
         return fail('usage', spec.takesQuery ? 'Provide one quoted query or source path.' : 'knowledge refresh takes no query.');
     for (const key of options.keys())

package/dist/knowledge-ui.d.ts

@@ -1,4 +1,4 @@
-import type { KnowledgeDraft, KnowledgeSelection, KnowledgeView } from './project-knowledge.js';
+import { type KnowledgeDraft, type KnowledgeSelection, type KnowledgeView } from './project-knowledge.js';
 export declare const KNOWLEDGE_CSS = ".knowledge{max-width:780px;min-width:0;overflow-wrap:anywhere}.knowledge .card{padding:20px;min-width:0;margin:16px 0}.knowledge h2{margin:0 0 12px}.knowledge form{display:grid;gap:12px;margin:0}.knowledge label{display:grid;gap:6px}.knowledge textarea,.knowledge input,.knowledge select{box-sizing:border-box;width:100%;min-width:0;max-width:100%}.knowledge textarea{resize:vertical;min-height:110px}.knowledge button,.knowledge summary,.knowledge .button-link{min-height:44px}.knowledge button{justify-self:start;white-space:nowrap}.knowledge summary{padding:12px 0;cursor:pointer}.knowledge pre{white-space:pre-wrap;overflow-wrap:anywhere;font:inherit}.knowledge .knowledge-actions{display:flex;gap:12px;flex-wrap:wrap}.knowledge .meta{font-size:.86rem}.knowledge .knowledge-source{display:block}.knowledge details+details{border-top:1px solid var(--so-line)}.memory-stats{display:flex;flex-wrap:wrap;gap:.4rem}.memory-stats span{padding:.15rem .55rem;border-radius:.375rem;background:var(--so-neutral-soft);color:var(--so-neutral-ink)}@media(max-width:600px){.knowledge .card{padding:16px}.knowledge h2{font-size:1.1rem}}";
 export declare function knowledgeHtml(view: KnowledgeView, csrf: string, canManage: boolean, draft?: KnowledgeDraft, error?: string): string;
 export declare function knowledgeContextHtml(snapshot: KnowledgeSelection | null): string;

package/dist/knowledge-ui.js

@@ -1,3 +1,4 @@
+import { STALE_KNOWLEDGE } from './project-knowledge.js';
 const e = (s) => String(s ?? '').replace(/[&<>"']/g, c => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]));
 const fields = (data) => Object.entries(data).map(([k, v]) => `<input type="hidden" name="${e(k)}" value="${e(v)}">`).join('');
 export const KNOWLEDGE_CSS = `.knowledge{max-width:780px;min-width:0;overflow-wrap:anywhere}.knowledge .card{padding:20px;min-width:0;margin:16px 0}.knowledge h2{margin:0 0 12px}.knowledge form{display:grid;gap:12px;margin:0}.knowledge label{display:grid;gap:6px}.knowledge textarea,.knowledge input,.knowledge select{box-sizing:border-box;width:100%;min-width:0;max-width:100%}.knowledge textarea{resize:vertical;min-height:110px}.knowledge button,.knowledge summary,.knowledge .button-link{min-height:44px}.knowledge button{justify-self:start;white-space:nowrap}.knowledge summary{padding:12px 0;cursor:pointer}.knowledge pre{white-space:pre-wrap;overflow-wrap:anywhere;font:inherit}.knowledge .knowledge-actions{display:flex;gap:12px;flex-wrap:wrap}.knowledge .meta{font-size:.86rem}.knowledge .knowledge-source{display:block}.knowledge details+details{border-top:1px solid var(--so-line)}.memory-stats{display:flex;flex-wrap:wrap;gap:.4rem}.memory-stats span{padding:.15rem .55rem;border-radius:.375rem;background:var(--so-neutral-soft);color:var(--so-neutral-ink)}@media(max-width:600px){.knowledge .card{padding:16px}.knowledge h2{font-size:1.1rem}}`;
@@ -8,6 +9,12 @@ export function knowledgeHtml(view, csrf, canManage, draft, error) {
     const referenceFields = (d) => `<label>Name<input name="title" maxlength="120" value="${e(d.title)}" required></label><label>Reference text<textarea name="content" rows="5" maxlength="12000">${e(d.content)}</textarea></label><details${d.path ? ' open' : ''}><summary>Use a project document</summary><label>Committed .md or .txt path<input name="path" value="${e(d.path)}" placeholder="docs/design-guide.md"></label><p class="meta">Uses the committed file instead of the text above. Save again to refresh it.</p></details><button type="submit">Save reference</button>`;
     const refs = view.knowledge.references.map(ref => `<details class="card"${draft?.id === ref.id ? ' open' : ''}><summary><strong>${e(ref.title)}</strong></summary>${ref.path ? `<span class="meta knowledge-source">${e(ref.path)} · ${e(ref.sourceRevision?.slice(0, 7))}</span>` : ''}<pre>${e(ref.content)}</pre>${manage ? `<details${draft?.id === ref.id ? ' open' : ''}><summary>Edit reference</summary>${form('save', referenceFields(draft?.id === ref.id ? draft : { title: ref.title, content: ref.path ? '' : ref.content, path: ref.path ?? '' }), { id: ref.id })}<details><summary>Remove reference</summary>${form('remove', '<p>Remove from future tasks. Previous run context stays available.</p><button>Remove reference</button>', { id: ref.id })}</details></details>` : ''}</details>`).join('');
     const history = view.history.map(h => `<li><a class="button-link" href="/settings/knowledge?repo=${encodeURIComponent(view.repo)}&version=${h.revision}">Version ${h.revision}</a> · ${e(h.actor)} · ${e(h.at.slice(0, 16).replace('T', ' '))} UTC</li>`).join('');
+    if (view.stale) {
+        // One notice, the saved knowledge on demand, one approver action. Editing waits until it is applied.
+        const saved = view.stale.knowledge;
+        const review = `<details><summary>Review saved knowledge</summary><pre class="knowledge-instructions">${e(saved.instructions || 'No project instructions.')}</pre>${saved.references.map(ref => `<details><summary>${e(ref.title)}</summary><pre>${e(ref.content)}</pre></details>`).join('')}</details>`;
+        return `<section class="knowledge knowledge-library">${error ? `<p class="problem" role="alert">${e(error)}</p>` : ''}<section class="card knowledge-stale"><p role="status">${e(STALE_KNOWLEDGE)}.</p>${review}${manage ? form('apply', '<button>Apply saved knowledge</button>') : ''}</section></section>`;
+    }
     const instructions = `<pre class="knowledge-instructions">${e(view.knowledge.instructions || 'No project instructions yet.')}</pre>`;
     const editor = manage ? `<details class="knowledge-editor"${draft?.instructions !== undefined ? ' open' : ''}><summary>${view.knowledge.instructions ? 'Edit instructions' : 'Add instructions'}</summary>${form('instructions', `<textarea aria-label="Project instructions" name="instructions" rows="5" maxlength="4000" placeholder="Goals, preferences, and what good work looks like…">${e(draft?.instructions ?? view.knowledge.instructions)}</textarea><button>Save instructions</button>`)}</details>` : '';
     return `<section class="knowledge knowledge-library">${error ? `<p class="problem" role="alert">${e(error)}</p>` : ''}<section class="knowledge-intro"><h2>Instructions</h2>${instructions}${editor}</section><section><h2>References</h2>${refs || '<p class="meta">Add a spec, design guide, or useful project document.</p>'}${manage ? `<details class="card"${draft?.title && !draft.id ? ' open' : ''}><summary>Add reference</summary>${form('save', referenceFields(draft?.id ? {} : draft ?? {}))}</details>` : ''}</section>${history ? `<details><summary>Change history</summary><ol>${history}</ol></details>` : ''}</section>`;