productfoo 0.0.0-stage → 1.0.1

package/dist-public/src/outlookNango.js

@@ -0,0 +1,327 @@
+// Outlook through Nango (outlook-discovery-connector-v0, local worker mode).
+//
+// Nango is the credential broker (R-001, the email-class shape Gmail's worker
+// established): productfoo asks Nango for the verified user's Outlook credential and
+// then talks to the Microsoft Graph API directly, so message bodies never
+// transit Nango. The connection is per-user (D-002) — a mailbox is personal
+// even at work — so unlike Gong there is no administrator-issued direct-key
+// fallback: a personal OAuth grant through Nango is the only path, and
+// readiness reports that broker truthfully. Credentials are held in process
+// memory for one command, the Nango connection id is never printed (an opaque
+// `connection_ref` stands in for it), and errors carry a typed code plus a
+// bounded message that never embeds a provider response.
+//
+// Microsoft Graph shapes below are beliefs owned by the packet's feasibility
+// task (T-001) and pinned by fixtures in test/discoveryOutlookRuntime.test.ts;
+// nothing here is verified-live, and support stays contract_only.
+import { createHash } from "node:crypto";
+import { refuseSourceWrite } from "./sourceIngress.js";
+export class OutlookRuntimeError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "OutlookRuntimeError";
+    }
+}
+// Versioned policy (R-007): hard ceilings the worker enforces and reports, so
+// a later change is explicit rather than silent. quiet_period_hours is the
+// email class's pinned quiet period (D-001, T-005): a conversation is settled
+// evidence once its last message predates the scope window's end by this
+// much, unless an explicit done category (OUTLOOK_DONE_CATEGORIES) marks it
+// sooner.
+export const OUTLOOK_POLICY = {
+    policy_version: "outlook-local-worker-0.1",
+    max_response_bytes: 8 * 1024 * 1024,
+    fetch_timeout_ms: 90_000,
+    max_model_input_tokens: 100_000,
+    max_list_pages: 5,
+    min_request_interval_ms: 350,
+    quiet_period_hours: 48,
+};
+// Least-privilege delegated read scopes (R-003). Graph needs one read scope
+// for both bounded metadata listing and reading a selected conversation's
+// message bodies: Mail.Read. Never Mail.ReadWrite, never the full mail grant
+// — there is no write path in this client at all (R-009). A connection
+// without the body scope stays useful for metadata and reports
+// needs_provider_access for reads (R-008).
+const OUTLOOK_BODY_SCOPE = "Mail.Read";
+const DEFAULT_NANGO_HOST = "https://api.nango.dev";
+const DEFAULT_GRAPH_BASE = "https://graph.microsoft.com/v1.0";
+function nangoConfigured(env) {
+    return Boolean(env.NANGO_SECRET_KEY?.trim() && env.FOO_OUTLOOK_NANGO_CONNECTION?.trim());
+}
+export function outlookConnectionConfigured(env) {
+    return nangoConfigured(env);
+}
+export function outlookCredentialBroker(_env) {
+    // Per-user ownership (D-002): Nango is the only broker. The parameter keeps
+    // the shared broker signature so callers stay parallel.
+    return "nango";
+}
+function opaqueConnectionRef(integration, connectionId) {
+    return `outlook:${createHash("sha256").update(`${integration}\n${connectionId}`).digest("hex").slice(0, 16)}`;
+}
+async function fetchWithTimeout(fetchImpl, url, init, timeoutMs) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        return await fetchImpl(url, { ...init, signal: controller.signal });
+    }
+    catch (error) {
+        if (controller.signal.aborted)
+            throw new OutlookRuntimeError("provider_timeout", "the provider did not answer within the fetch ceiling");
+        throw new OutlookRuntimeError("network", `network failure reaching ${new URL(url).hostname}`);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+// Reads a response body while counting toward the byte ceiling, so an
+// oversized conversation is dropped before it is ever materialized in full.
+async function readBounded(response, maxBytes) {
+    const declared = Number(response.headers.get("content-length") ?? "0");
+    if (Number.isFinite(declared) && declared > maxBytes)
+        throw new OutlookRuntimeError("conversation_too_large", "the provider response exceeds the byte ceiling");
+    if (!response.body) {
+        const buffer = await response.arrayBuffer();
+        if (buffer.byteLength > maxBytes)
+            throw new OutlookRuntimeError("conversation_too_large", "the provider response exceeds the byte ceiling");
+        return new TextDecoder().decode(buffer);
+    }
+    const reader = response.body.getReader();
+    const chunks = [];
+    let total = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        total += value.byteLength;
+        if (total > maxBytes) {
+            await reader.cancel().catch(() => undefined);
+            chunks.length = 0;
+            throw new OutlookRuntimeError("conversation_too_large", "the provider response exceeds the byte ceiling");
+        }
+        chunks.push(value);
+    }
+    return new TextDecoder().decode(Buffer.concat(chunks));
+}
+function parseJson(text, label) {
+    try {
+        const parsed = JSON.parse(text);
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+            throw new Error("not an object");
+        return parsed;
+    }
+    catch {
+        throw new OutlookRuntimeError("provider_failure", `${label} returned a response productfoo could not read`);
+    }
+}
+/**
+ * Resolve the verified user's Outlook credential through Nango. There is no
+ * direct fallback (D-002): the mailbox belongs to one person, so the OAuth
+ * grant is always brokered, refreshable, and revocable centrally. productfoo receives
+ * the token for one command and never persists or prints it.
+ */
+export async function resolveOutlookConnection(input) {
+    if (!nangoConfigured(input.env)) {
+        throw new OutlookRuntimeError("not_connected", "Outlook is not connected: connect the mailbox through Nango and set NANGO_SECRET_KEY and FOO_OUTLOOK_NANGO_CONNECTION (plus NANGO_HOST / FOO_OUTLOOK_NANGO_INTEGRATION when they differ from the defaults)");
+    }
+    const secret = input.env.NANGO_SECRET_KEY.trim();
+    const connectionId = input.env.FOO_OUTLOOK_NANGO_CONNECTION.trim();
+    const integration = input.env.FOO_OUTLOOK_NANGO_INTEGRATION?.trim() || "microsoft-outlook";
+    const host = (input.env.NANGO_HOST?.trim() || DEFAULT_NANGO_HOST).replace(/\/+$/, "");
+    const url = `${host}/connection/${encodeURIComponent(connectionId)}?provider_config_key=${encodeURIComponent(integration)}`;
+    const response = await fetchWithTimeout(input.fetchImpl, url, { method: "GET", headers: { authorization: `Bearer ${secret}`, accept: "application/json" } }, OUTLOOK_POLICY.fetch_timeout_ms);
+    if (response.status === 401 || response.status === 403)
+        throw new OutlookRuntimeError("not_connected", "Nango refused the secret key; reconnect Outlook");
+    if (response.status === 404)
+        throw new OutlookRuntimeError("not_connected", "Nango has no Outlook connection with that reference; connect Outlook first");
+    if (!response.ok)
+        throw new OutlookRuntimeError("provider_failure", `Nango answered ${response.status} while resolving the connection`);
+    const body = parseJson(await readBounded(response, 256 * 1024), "Nango");
+    const credentials = (body.credentials ?? {});
+    const type = String(credentials.type ?? "").toUpperCase();
+    if (type !== "OAUTH2")
+        throw new OutlookRuntimeError("not_connected", "the Nango connection uses a credential type productfoo does not support for Outlook");
+    const token = String(credentials.access_token ?? "");
+    if (!token)
+        throw new OutlookRuntimeError("auth_expired", "the Nango connection carries no usable Outlook access token; refresh or reconnect");
+    const raw = (credentials.raw ?? {});
+    const scopeValue = typeof raw.scope === "string" ? raw.scope : typeof credentials.scope === "string" ? credentials.scope : "";
+    const scopes = scopeValue.split(/[\s,]+/).filter(Boolean);
+    const bodyScope = scopes.length === 0 ? "unknown" : scopes.some((scope) => scope.toLowerCase() === OUTLOOK_BODY_SCOPE.toLowerCase() || scope.toLowerCase().startsWith(`${OUTLOOK_BODY_SCOPE.toLowerCase()}.`)) ? "granted" : "missing";
+    return { connection_ref: opaqueConnectionRef(integration, connectionId), broker: "nango", credential: { type: "oauth2", access_token: token }, credential_type: "oauth2", body_scope: bodyScope };
+}
+// The metadata $select: every field the adapter and matcher consume, and
+// nothing else — bodies are only ever selected by conversation() (R-004).
+const MESSAGE_METADATA_SELECT = "id,conversationId,subject,receivedDateTime,categories,from,toRecipients,ccRecipients";
+// The full-read select adds the body — and nothing else — over the metadata
+// select (R-004/R-007).
+const MESSAGE_SELECT_WITH_BODY = `${MESSAGE_METADATA_SELECT},body`;
+// OData timestamps are ISO 8601; the approved window's ISO instants pass
+// through unchanged after validation.
+function odataInstant(value, label) {
+    const parsed = Date.parse(value);
+    if (!Number.isFinite(parsed))
+        throw new OutlookRuntimeError("provider_failure", `the approved window is not a valid time range (${label})`);
+    return new Date(parsed).toISOString().replace(/\.\d{3}Z$/, "Z");
+}
+/**
+ * Minimal read-only Microsoft Graph client. Only documented read operations
+ * are reachable — every request method is GET and anything else routes
+ * through the single write-refusal choke point (R-009), so the refusal is
+ * testable rather than scattered. There is no attachment fetch method at all
+ * (D-003): Graph models attachments as separate resources, and this client
+ * never asks for them.
+ */
+export class OutlookClient {
+    credential;
+    options;
+    requests = { profile: 0, list: 0, metadata: 0, conversation: 0 };
+    lastRequestAt = 0;
+    baseUrl;
+    fetchTimeoutMs;
+    sleep;
+    now;
+    constructor(credential, options) {
+        this.credential = credential;
+        this.options = options;
+        this.baseUrl = (options.baseUrl ?? DEFAULT_GRAPH_BASE).replace(/\/+$/, "");
+        this.fetchTimeoutMs = options.fetchTimeoutMs ?? OUTLOOK_POLICY.fetch_timeout_ms;
+        this.sleep = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+        this.now = options.now ?? (() => Date.now());
+    }
+    async request(method, pathname, maxBytes = OUTLOOK_POLICY.max_response_bytes, headers = {}) {
+        // R-009: the client is GET-shaped by construction; a future caller that
+        // tries a write lands here, at the one choke point — the same gate the
+        // Gmail client applies to its non-read methods.
+        if (method !== "GET")
+            refuseSourceWrite(`outlook ${method} ${pathname}`);
+        const wait = this.lastRequestAt + OUTLOOK_POLICY.min_request_interval_ms - this.now();
+        if (wait > 0)
+            await this.sleep(wait);
+        this.lastRequestAt = this.now();
+        const response = await fetchWithTimeout(this.options.fetchImpl, `${this.baseUrl}${pathname}`, { method: "GET", headers: { authorization: `Bearer ${this.credential.access_token}`, accept: "application/json", ...headers } }, this.fetchTimeoutMs);
+        if (response.status === 401)
+            throw new OutlookRuntimeError("auth_expired", "Microsoft Graph rejected the credential; refresh or reconnect");
+        if (response.status === 403)
+            throw new OutlookRuntimeError("access_denied", "Microsoft Graph denied this read; the connection lacks the required scope");
+        if (response.status === 429)
+            throw new OutlookRuntimeError("budget_exhausted", "Microsoft Graph rate limit reached; no retry was attempted");
+        if (response.status === 404)
+            throw new OutlookRuntimeError("provider_failure", "Microsoft Graph reported the requested record does not exist");
+        if (!response.ok)
+            throw new OutlookRuntimeError("provider_failure", `Microsoft Graph answered ${response.status}`);
+        return parseJson(await readBounded(response, maxBytes), "Microsoft Graph");
+    }
+    /** The mailbox owner's address (metadata only) — defines "internal" for a per-user mailbox (R-004). */
+    async profile() {
+        this.requests.profile += 1;
+        const body = await this.request("GET", "/me?$select=mail,userPrincipalName", 16 * 1024);
+        const mail = typeof body.mail === "string" && body.mail ? body.mail : typeof body.userPrincipalName === "string" ? body.userPrincipalName : undefined;
+        return mail ? { email: mail } : {};
+    }
+    /**
+     * Bounded metadata listing inside ONE explicit approved folder (R-004): a
+     * time window expressed as Graph's receivedDateTime range filter, a page
+     * ceiling, no message bodies. Pagination re-issues the SAME pinned filter
+     * with the next page's skiptoken — the approved window and folder are
+     * byte-identical on every page and a listing that exceeds the ceiling
+     * returns `truncated` and the run stops; it never widens.
+     */
+    async listFolderMessages(scope) {
+        const from = odataInstant(scope.from, "start");
+        const to = odataInstant(scope.to, "end");
+        const filter = `receivedDateTime ge ${from} and receivedDateTime le ${to}`;
+        const messages = [];
+        let skiptoken;
+        let pages = 0;
+        for (;;) {
+            if (pages >= OUTLOOK_POLICY.max_list_pages)
+                return { messages, pages, truncated: true };
+            const params = new URLSearchParams({ $select: MESSAGE_METADATA_SELECT, $filter: filter, $orderby: "receivedDateTime asc", $top: "100" });
+            if (skiptoken)
+                params.set("$skiptoken", skiptoken);
+            this.requests.list += 1;
+            const body = await this.request("GET", `/me/mailFolders/${encodeURIComponent(scope.folder)}/messages?${params.toString()}`, 4 * 1024 * 1024);
+            pages += 1;
+            for (const entry of Array.isArray(body.value) ? body.value : []) {
+                messages.push(this.parseMessage(entry));
+            }
+            // Follow only Graph's own paging token, never its absolute nextLink —
+            // the next page must carry THIS pinned filter, and re-issuing from the
+            // approved folder path keeps that true by construction.
+            const nextLink = typeof body["@odata.nextLink"] === "string" ? body["@odata.nextLink"] : undefined;
+            const token = nextLink ? new URL(nextLink).searchParams.get("$skiptoken") : null;
+            skiptoken = token ?? undefined;
+            if (!skiptoken)
+                return { messages, pages, truncated: false };
+        }
+    }
+    /**
+     * One conversation's headers only — the bounded listing read (R-004):
+     * participants and dates without any message body. Bodies are fetched
+     * solely by `conversation()` under the minted proof (R-007).
+     */
+    async conversationMetadata(conversationId) {
+        if (!conversationId || /\s/.test(conversationId))
+            throw new OutlookRuntimeError("provider_failure", "a single well-formed conversation identifier is required");
+        this.requests.metadata += 1;
+        const params = new URLSearchParams({ $select: MESSAGE_METADATA_SELECT, $filter: `conversationId eq '${conversationId}'`, $orderby: "receivedDateTime asc", $top: "100" });
+        const body = await this.request("GET", `/me/messages?${params.toString()}`);
+        const messages = (Array.isArray(body.value) ? body.value : []).map((message) => this.parseMessage(message));
+        if (messages.length === 0)
+            throw new OutlookRuntimeError("access_denied", "Microsoft Graph returned no messages for the selected conversation");
+        return messages;
+    }
+    /**
+     * Exactly one conversation's messages (R-007). This method refuses to ask
+     * for more than one identifier — a fixture observes that no request ever
+     * carries one. Bodies arrive as text (the Prefer header asks Graph for the
+     * text twin); an HTML body is dropped, never stored. Attachment resources
+     * are never fetched — there is no method for them (D-003).
+     */
+    async conversation(conversationId) {
+        if (!conversationId || /\s/.test(conversationId))
+            throw new OutlookRuntimeError("provider_failure", "a single well-formed conversation identifier is required");
+        this.requests.conversation += 1;
+        const params = new URLSearchParams({ $select: MESSAGE_SELECT_WITH_BODY, $filter: `conversationId eq '${conversationId}'`, $orderby: "receivedDateTime asc", $top: "100" });
+        const body = await this.request("GET", `/me/messages?${params.toString()}`, OUTLOOK_POLICY.max_response_bytes, { prefer: 'outlook.body-content-type="Text"' });
+        const messages = (Array.isArray(body.value) ? body.value : []).map((message) => this.parseMessage(message));
+        if (messages.length === 0)
+            throw new OutlookRuntimeError("access_denied", "Microsoft Graph returned no messages for the selected conversation");
+        return messages;
+    }
+    parseMessage(message) {
+        const from = parseGraphAddress((message.from ?? {}));
+        const to = [
+            ...(Array.isArray(message.toRecipients) ? message.toRecipients : []),
+            ...(Array.isArray(message.ccRecipients) ? message.ccRecipients : []),
+        ].map((entry) => parseGraphAddress(entry)).filter((entry) => Boolean(entry));
+        const body = (message.body ?? {});
+        // The HTML twin is refused even when Graph ignores the Prefer header: a
+        // non-text body content type is dropped, never stored (the Gmail class's
+        // html-twin exclusion).
+        const bodyText = body.contentType === "text" && typeof body.content === "string" && body.content.trim() ? body.content : undefined;
+        return {
+            id: typeof message.id === "string" ? message.id : "",
+            conversation_id: typeof message.conversationId === "string" ? message.conversationId : undefined,
+            received_at: typeof message.receivedDateTime === "string" ? message.receivedDateTime : undefined,
+            categories: Array.isArray(message.categories) ? message.categories.filter((category) => typeof category === "string") : undefined,
+            ...(from ? { from } : {}),
+            to: to.length ? to : undefined,
+            subject: typeof message.subject === "string" ? message.subject : undefined,
+            body_text: bodyText,
+        };
+    }
+}
+// Parses Graph's structured { emailAddress: { name, address } } into the
+// adapter's participant shape. Unparseable values are dropped — never guessed.
+function parseGraphAddress(value) {
+    const address = (value.emailAddress ?? {});
+    const smtp = typeof address.address === "string" ? address.address.trim().toLowerCase() : "";
+    if (!smtp || !/^[^\s<>]+@[^\s<>]+$/.test(smtp))
+        return undefined;
+    return { ...(typeof address.name === "string" && address.name.trim() ? { display_name: address.name.trim().replace(/^"|"$/g, "") } : {}), smtp };
+}

package/dist-public/src/packetCorrections.d.ts

@@ -0,0 +1,40 @@
+import { type GlossaryTerm } from "./packetGlossary.js";
+export interface CorrectionLink {
+    kind: "requirement" | "open_question";
+    id: string;
+    title: string;
+}
+export declare function linkCorrection(packetDir: string, correction: string): CorrectionLink | null;
+export interface DecisionRecord {
+    summary: string;
+    by: string;
+    linked: CorrectionLink | null;
+    vocabulary: GlossaryTerm[];
+}
+export interface PendingUserCorrection {
+    eventId: string;
+    summary: string;
+    time?: string;
+}
+export declare function findUnrepresentedUserCorrections(packetDir: string): PendingUserCorrection[];
+export declare function recordDecision(packetDir: string, opts: {
+    summary: string;
+    by: string;
+    now?: Date;
+}): DecisionRecord;
+export interface PatchProposal {
+    schema_version: "0.1";
+    packet: string;
+    correction: string;
+    confidence: "low" | "medium";
+    requires_approval: true;
+    linked: CorrectionLink | null;
+    vocabulary: string[];
+    patches: Array<{
+        file: string;
+        anchor: string;
+        insert: string;
+    }>;
+}
+export declare function proposeSpecPatch(packetDir: string, correction: string): PatchProposal;
+export declare function renderPatchProposal(proposal: PatchProposal): string;

package/dist-public/src/packetCorrections.js

@@ -0,0 +1,172 @@
+// default-agent-routing-v0 T-005 (R-005): capture user corrections as packet
+// contract updates instead of losing them to the chat scrollback. Two moves:
+//
+// - `foo decision add` appends an attributed, append-only decision event,
+//   best-effort linked to the requirement or open question it corrects.
+// - `foo spec patch` turns a correction into an INSPECTABLE patch proposal for
+//   spec.md / tasks.yaml — exact insertions, a confidence grade, and an
+//   explicit approval requirement. It never writes; a human applies.
+//
+// Raw private context stays out: only the correction text the user explicitly
+// provided lands in the packet, and the event writer's safety guard screens it.
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { appendEvent } from "./packetWrite.js";
+import { UsageError } from "./errorTaxonomy.js";
+import { matchGlossaryTerms, readPacketGlossary } from "./packetGlossary.js";
+import { parseOpenQuestions, parseRequirementHeadings } from "./specSections.js";
+const STOP = new Set(["the", "a", "an", "and", "or", "to", "of", "in", "for", "is", "are", "should", "must", "not", "with", "that", "this", "it", "on", "be"]);
+function keywords(text) {
+    return new Set(text
+        .toLowerCase()
+        .split(/[^a-z0-9_-]+/)
+        .filter((w) => w.length > 2 && !STOP.has(w)));
+}
+function overlapScore(a, b) {
+    let n = 0;
+    for (const w of a)
+        if (b.has(w))
+            n += 1;
+    return n;
+}
+// Best-effort: link the correction to the requirement heading or open-question
+// bullet it most plausibly corrects (keyword overlap; ties go to nothing —
+// a wrong link is worse than no link).
+export function linkCorrection(packetDir, correction) {
+    const specPath = path.join(packetDir, "spec.md");
+    if (!existsSync(specPath))
+        return null;
+    const text = readFileSync(specPath, "utf8");
+    const correctionWords = keywords(correction);
+    const candidates = [];
+    for (const r of parseRequirementHeadings(text)) {
+        candidates.push({ kind: "requirement", id: r.id, title: r.title, score: overlapScore(correctionWords, keywords(r.title)) });
+    }
+    // Most packets write open questions as plain bullets with no OQ id; a
+    // positional id keeps the link addressable (the title is the real anchor).
+    parseOpenQuestions(text).forEach((q, i) => {
+        candidates.push({ kind: "open_question", id: q.id ?? `OQ-${i + 1}`, title: q.title, score: overlapScore(correctionWords, keywords(q.text)) });
+    });
+    candidates.sort((a, b) => b.score - a.score);
+    const best = candidates[0];
+    if (!best || best.score === 0)
+        return null;
+    if (candidates[1] && candidates[1].score === best.score)
+        return null;
+    const { score: _score, ...link } = best;
+    return link;
+}
+function normalizeRepresentation(text) {
+    return text.replace(/\s+/g, " ").trim();
+}
+// Preview trusts only productfoo's explicit correction marker. Historical human and
+// agent decisions are too heterogeneous to infer as pending packet patches
+// without false positives. A correction is represented when the exact summary
+// inserted by `foo spec patch` appears after whitespace normalization.
+export function findUnrepresentedUserCorrections(packetDir) {
+    const eventsPath = path.join(packetDir, "events.jsonl");
+    if (!existsSync(eventsPath))
+        return [];
+    const represented = normalizeRepresentation(["spec.md", "tasks.yaml"]
+        .map((file) => path.join(packetDir, file))
+        .map((file) => (existsSync(file) ? readFileSync(file, "utf8") : ""))
+        .join("\n"));
+    const pending = [];
+    for (const line of readFileSync(eventsPath, "utf8").split(/\r?\n/)) {
+        if (!line.trim())
+            continue;
+        try {
+            const event = JSON.parse(line);
+            if (event.type !== "com.adaptivespec.decision.recorded" || !event.data || typeof event.data !== "object")
+                continue;
+            const data = event.data;
+            if (data.source !== "user-correction" || typeof data.summary !== "string" || !data.summary.trim())
+                continue;
+            const summary = data.summary.trim();
+            if (represented.includes(normalizeRepresentation(summary)))
+                continue;
+            pending.push({
+                eventId: typeof event.id === "string" ? event.id : "(unknown event)",
+                summary,
+                ...(typeof event.time === "string" ? { time: event.time } : {}),
+            });
+        }
+        catch {
+            // Packet validation owns malformed ledger structure. Preview's preflight
+            // stays defensive so a bad line does not become an unexpected crash.
+        }
+    }
+    return pending;
+}
+export function recordDecision(packetDir, opts) {
+    // A missing correction is the caller's typo, not productfoo's bug — UsageError keeps it
+    // out of the page-worthy command_error bucket and files no Bug Capsule (#778).
+    if (!opts.summary.trim())
+        throw new UsageError("foo decision add needs --summary <correction>", "E_BAD_FLAG");
+    const linked = linkCorrection(packetDir, opts.summary);
+    const vocabulary = matchGlossaryTerms(readPacketGlossary(packetDir), opts.summary);
+    appendEvent({
+        packetDir,
+        type: "com.adaptivespec.decision.recorded",
+        actor: { type: "human", id: opts.by },
+        data: {
+            summary: opts.summary,
+            linked: linked ? { kind: linked.kind, id: linked.id } : null,
+            vocabulary: vocabulary.map((t) => t.term),
+            source: "user-correction",
+        },
+        now: opts.now,
+    });
+    return { summary: opts.summary, by: opts.by, linked, vocabulary };
+}
+export function proposeSpecPatch(packetDir, correction) {
+    if (!correction.trim())
+        throw new Error("foo spec patch needs --correction <text>");
+    const linked = linkCorrection(packetDir, correction);
+    const vocabulary = matchGlossaryTerms(readPacketGlossary(packetDir), correction).map((t) => t.term);
+    const date = new Date().toISOString().slice(0, 10);
+    const patches = [];
+    // spec.md: record the correction as a dated Decision entry, anchored to the
+    // linked item when one exists.
+    patches.push({
+        file: "spec.md",
+        anchor: "## Decisions",
+        insert: `- ${date} (user correction${linked ? `, ${linked.id}` : ""}): ${correction}`,
+    });
+    // tasks.yaml: when the correction names a task, propose an explicit review
+    // note on it rather than a silent status flip.
+    const taskRef = correction.match(/\bT-\d{3}\b/);
+    if (taskRef) {
+        patches.push({
+            file: "tasks.yaml",
+            anchor: `id: ${taskRef[0]}`,
+            insert: `# user correction (${date}): ${correction} — re-verify done_when before trusting status`,
+        });
+    }
+    return {
+        schema_version: "0.1",
+        packet: path.basename(packetDir),
+        correction,
+        // Linked corrections read as targeted (medium); unlinked ones are broad (low).
+        confidence: linked ? "medium" : "low",
+        requires_approval: true,
+        linked,
+        vocabulary,
+        patches,
+    };
+}
+export function renderPatchProposal(proposal) {
+    const lines = [
+        `Spec patch proposal — ${proposal.packet} (confidence: ${proposal.confidence}; requires human approval, nothing written)`,
+        `  correction: ${proposal.correction}`,
+        proposal.linked ? `  linked: ${proposal.linked.kind} ${proposal.linked.id} — ${proposal.linked.title}` : "  linked: none confidently matched",
+        ...(proposal.vocabulary.length ? [`  packet vocabulary used: ${proposal.vocabulary.join(", ")}`] : []),
+        "",
+    ];
+    for (const patch of proposal.patches) {
+        lines.push(`  ${patch.file} @ ${patch.anchor}:`);
+        lines.push(`  + ${patch.insert}`);
+    }
+    lines.push("", "Apply by editing the file(s) above, then: foo asp validate <packet-dir>");
+    return `${lines.join("\n")}\n`;
+}

package/dist-public/src/packetGlossary.d.ts

@@ -0,0 +1,6 @@
+export interface GlossaryTerm {
+    term: string;
+    definition: string;
+}
+export declare function readPacketGlossary(packetDir: string): GlossaryTerm[];
+export declare function matchGlossaryTerms(terms: GlossaryTerm[], text: string): GlossaryTerm[];

package/dist-public/src/packetGlossary.js

@@ -0,0 +1,42 @@
+// default-agent-routing-v0 T-006 (R-006): packet-local vocabulary. The final
+// `## Glossary` section of a packet's spec.md is the V0 vocabulary source —
+// accepted domain terms that packet-reading flows (shaping, patching,
+// validating, planning handoffs) may use. Vocabulary is strictly packet-local:
+// nothing here feeds global productfoo command semantics, and a term in one packet
+// never leaks into another.
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+export function readPacketGlossary(packetDir) {
+    const specPath = path.join(packetDir, "spec.md");
+    if (!existsSync(specPath))
+        return [];
+    const text = readFileSync(specPath, "utf8");
+    // The FINAL ## Glossary section wins (the spec contract places it last).
+    const idx = text.lastIndexOf("\n## Glossary");
+    if (idx === -1)
+        return [];
+    const section = text.slice(idx + 1);
+    const body = section.slice(section.indexOf("\n") + 1);
+    const end = body.search(/\n## /);
+    const content = end === -1 ? body : body.slice(0, end);
+    const terms = [];
+    for (const line of content.split("\n")) {
+        // Accepted bullet shapes: `- term: definition`, `- **term** — definition`,
+        // `- term — definition`.
+        const match = line.match(/^-\s+(?:\*\*(.+?)\*\*|([^:—]+?))\s*(?:[:—]|--)\s+(.+)$/);
+        if (match) {
+            const term = (match[1] ?? match[2] ?? "").trim();
+            const definition = match[3].trim();
+            if (term && definition)
+                terms.push({ term, definition });
+        }
+    }
+    return terms;
+}
+// Which packet-local terms appear in a piece of text (case-insensitive, whole
+// word). Used to carry vocabulary context into decisions and patch proposals.
+export function matchGlossaryTerms(terms, text) {
+    // Whole-word, case-insensitive, tolerating a simple plural on the last word
+    // ("saved filter" matches "Saved filters").
+    return terms.filter((t) => new RegExp(`\\b${t.term.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}(?:e?s)?\\b`, "i").test(text));
+}

package/dist-public/src/packetIndex.d.ts

@@ -0,0 +1,54 @@
+import { type SpecDecisionSignals } from "./specDecisionSignals.js";
+import type { PacketStatus } from "./packetStatus.js";
+export declare const PACKET_INDEX_SCHEMA_VERSION = "1.2";
+export interface PacketIndexEntry extends PacketStatus {
+    updated: string | null;
+    intent: string | null;
+    decision_signals: SpecDecisionSignals;
+    bucket: "proven" | "progress" | "open" | "retired";
+    error?: string;
+}
+export declare function listPackets(root: string): string[];
+export declare function derivePacketIndex(root: string): PacketIndexEntry[];
+export type TriageLane = "needs_you" | "in_flight" | "ready" | "blocked";
+export interface TriageRow {
+    packet: string;
+    task: string;
+    title: string;
+    lane: TriageLane;
+    prio: string | null;
+    unlocks: number;
+    unmet: string[];
+    owner: string | null;
+    agreement: string;
+    updated: string | null;
+}
+export declare function deriveTriage(index: PacketIndexEntry[]): TriageRow[];
+export declare const MISPRICED_UNLOCK_THRESHOLD = 7;
+export interface PortfolioRow {
+    packet: string;
+    spec_id: string;
+    open_tasks: number;
+    total_tasks: number;
+    lanes: TriageLane[];
+    priority: string | null;
+    unlocks_sum: number;
+    unlocks_max: number;
+    mispriced: boolean;
+    lifecycle_drift: boolean;
+    updated: string | null;
+}
+export declare function derivePacketPortfolio(index: PacketIndexEntry[]): PortfolioRow[];
+export declare function taskGlyph(t: {
+    status: string;
+    checksDone: number;
+    checksTotal: number;
+}): "p" | "d" | "w" | "o" | "b";
+export declare function renderIndexHtml(index: PacketIndexEntry[]): string;
+export interface IndexOptions {
+    json?: boolean;
+    html?: boolean;
+    htmlPath?: string;
+    glyphs?: boolean;
+}
+export declare function runAspIndex(root: string, options: IndexOptions): string;