patchwork-os 1.2.0-beta.2.canary.747 → 1.2.0-beta.2.canary.749

package/dist/privacy/undeclaredSteps.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Which agent steps carry no `data_policy`, and what actually feeds them?
+ *
+ * ADR-0021 is fail-soft: a step with no `data_policy` is classified `internal`
+ * and the boundary lets it through. That is the correct default — it is what
+ * keeps the boundary inert on upgrade — but it means an undeclared step is
+ * invisible in exactly the way a declared one is not. Measured 2026-08-26 on
+ * the reference install: **132 of 214** privacy-shadow observations carried
+ * `labelSource: "assumed"`, and installed recipes declared `data_policy` on
+ * **20 of 87** agent steps against **22 of 22** in the shipped templates.
+ *
+ * ## Why this reports the FEEDING TOOLS and not just the step
+ *
+ * A classification describes what the step HANDLES, "including whatever its
+ * tools return" — that rule is in CLAUDE.md and it is the whole difficulty. A
+ * prompt whose text mentions nothing sensitive can still be handed a mailbox by
+ * the step above it, which is precisely why `morning-brief` declares `personal`
+ * while its prompt only says how to go and fetch things.
+ *
+ * So a report that listed undeclared steps would tell an operator WHERE to look
+ * and nothing about WHAT to write. This resolves each `{{ref}}` in the prompt
+ * back to the step that produced it and names that step's tool, which is the
+ * evidence the classification actually rests on.
+ *
+ * ## It suggests nothing
+ *
+ * Deliberately no recommended classification, not even a conservative one.
+ * Guessing a label and presenting it as a starting point is how an unexamined
+ * claim ends up declared — and a declared-but-wrong label is strictly worse
+ * than an assumed one, because it stops looking like a gap. The operator reads
+ * the tools and decides. Same reason `privacy suggest` emits `privacy.shadow`
+ * and never the enforcing `privacy.destinations` key.
+ *
+ * Read-only. Output is OPERATOR DATA — it names real installed recipes — so it
+ * is quoted as a measurement and never pasted into an issue or a fixture.
+ */
+/** A `{{ref}}` in a prompt, resolved back to whatever produced it. */
+export interface FeedingOutput {
+    /** The `into:` key referenced by the prompt. */
+    ref: string;
+    /** Tool that produced it, or undefined when nothing in this recipe does. */
+    tool?: string;
+    /** True when the producing step is itself an agent. */
+    fromAgent?: boolean;
+}
+export interface UndeclaredStep {
+    recipe: string;
+    /** Step id, or a positional label when the step declares none. */
+    stepId: string;
+    /** Resolved `{{ref}}`s, so the reader can classify from what flows in. */
+    feeds: FeedingOutput[];
+    /** Refs the prompt uses that no step in this recipe produces. */
+    unresolvedRefs: string[];
+}
+export interface UndeclaredReport {
+    /** Recipes examined — the denominator. */
+    recipesScanned: number;
+    /** Every agent step found, declared or not. The other denominator. */
+    agentSteps: number;
+    declared: number;
+    undeclared: UndeclaredStep[];
+    /** Recipes that could not be parsed. Reported, never silently dropped. */
+    unreadable: string[];
+}
+/** `{{a.b}}` / `{{ a }}` → the root key. Filters template helpers and literals. */
+export declare function refsIn(prompt: string): string[];
+/**
+ * Analyse one already-parsed recipe. Takes parsed YAML rather than a path so
+ * the caller owns file access and this stays trivially testable.
+ */
+export declare function undeclaredInRecipe(recipeName: string, parsed: unknown): {
+    agentSteps: number;
+    declared: number;
+    steps: UndeclaredStep[];
+};
+export declare function formatUndeclared(r: UndeclaredReport): string;

package/dist/privacy/undeclaredSteps.js

@@ -0,0 +1,166 @@
+/**
+ * Which agent steps carry no `data_policy`, and what actually feeds them?
+ *
+ * ADR-0021 is fail-soft: a step with no `data_policy` is classified `internal`
+ * and the boundary lets it through. That is the correct default — it is what
+ * keeps the boundary inert on upgrade — but it means an undeclared step is
+ * invisible in exactly the way a declared one is not. Measured 2026-08-26 on
+ * the reference install: **132 of 214** privacy-shadow observations carried
+ * `labelSource: "assumed"`, and installed recipes declared `data_policy` on
+ * **20 of 87** agent steps against **22 of 22** in the shipped templates.
+ *
+ * ## Why this reports the FEEDING TOOLS and not just the step
+ *
+ * A classification describes what the step HANDLES, "including whatever its
+ * tools return" — that rule is in CLAUDE.md and it is the whole difficulty. A
+ * prompt whose text mentions nothing sensitive can still be handed a mailbox by
+ * the step above it, which is precisely why `morning-brief` declares `personal`
+ * while its prompt only says how to go and fetch things.
+ *
+ * So a report that listed undeclared steps would tell an operator WHERE to look
+ * and nothing about WHAT to write. This resolves each `{{ref}}` in the prompt
+ * back to the step that produced it and names that step's tool, which is the
+ * evidence the classification actually rests on.
+ *
+ * ## It suggests nothing
+ *
+ * Deliberately no recommended classification, not even a conservative one.
+ * Guessing a label and presenting it as a starting point is how an unexamined
+ * claim ends up declared — and a declared-but-wrong label is strictly worse
+ * than an assumed one, because it stops looking like a gap. The operator reads
+ * the tools and decides. Same reason `privacy suggest` emits `privacy.shadow`
+ * and never the enforcing `privacy.destinations` key.
+ *
+ * Read-only. Output is OPERATOR DATA — it names real installed recipes — so it
+ * is quoted as a measurement and never pasted into an issue or a fixture.
+ */
+function isRecord(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+/** `{{a.b}}` / `{{ a }}` → the root key. Filters template helpers and literals. */
+export function refsIn(prompt) {
+    const out = new Set();
+    for (const m of prompt.matchAll(/\{\{\s*([A-Za-z_][\w.-]*)/g)) {
+        const root = m[1].split(".")[0];
+        out.add(root);
+    }
+    return [...out];
+}
+/**
+ * Analyse one already-parsed recipe. Takes parsed YAML rather than a path so
+ * the caller owns file access and this stays trivially testable.
+ */
+export function undeclaredInRecipe(recipeName, parsed) {
+    if (!isRecord(parsed) || !Array.isArray(parsed.steps)) {
+        return { agentSteps: 0, declared: 0, steps: [] };
+    }
+    const raw = parsed.steps;
+    // into-key -> producing tool, built first so a prompt can be resolved against
+    // steps that appear before OR after it. Order is the runner's problem, not
+    // this report's.
+    const producers = new Map();
+    for (const s of raw) {
+        if (!isRecord(s))
+            continue;
+        const agent = isRecord(s.agent) ? s.agent : undefined;
+        const into = typeof s.into === "string"
+            ? s.into
+            : agent && typeof agent.into === "string"
+                ? agent.into
+                : undefined;
+        if (!into)
+            continue;
+        producers.set(into, {
+            ...(typeof s.tool === "string" ? { tool: s.tool } : {}),
+            fromAgent: agent !== undefined,
+        });
+    }
+    let agentSteps = 0;
+    let declared = 0;
+    const steps = [];
+    for (let i = 0; i < raw.length; i++) {
+        const s = raw[i];
+        if (!isRecord(s))
+            continue;
+        const agent = isRecord(s.agent) ? s.agent : undefined;
+        if (!agent)
+            continue;
+        agentSteps++;
+        // `data_policy` sits on the agent block in shipped templates; accept it at
+        // step level too rather than reporting a false positive over a spelling.
+        if (agent.data_policy !== undefined || s.data_policy !== undefined) {
+            declared++;
+            continue;
+        }
+        const prompt = typeof agent.prompt === "string" ? agent.prompt : "";
+        const feeds = [];
+        const unresolved = [];
+        for (const ref of refsIn(prompt)) {
+            const p = producers.get(ref);
+            if (p) {
+                feeds.push({
+                    ref,
+                    ...(p.tool ? { tool: p.tool } : {}),
+                    ...(p.fromAgent ? { fromAgent: true } : {}),
+                });
+            }
+            else {
+                unresolved.push(ref);
+            }
+        }
+        steps.push({
+            recipe: recipeName,
+            stepId: typeof s.id === "string"
+                ? s.id
+                : typeof s.into === "string"
+                    ? s.into
+                    : `step_${i}`,
+            feeds,
+            unresolvedRefs: unresolved,
+        });
+    }
+    return { agentSteps, declared, steps };
+}
+export function formatUndeclared(r) {
+    const L = [];
+    L.push("[privacy] agent steps with no data_policy");
+    // Denominator first, always: "67 undeclared" reads as an alarm, "67 of 87"
+    // is the fact.
+    L.push(`  ${r.undeclared.length} of ${r.agentSteps} agent step(s) across ${r.recipesScanned} recipe(s) declare none`);
+    if (r.unreadable.length > 0) {
+        L.push(`  ${r.unreadable.length} recipe(s) could not be parsed`);
+    }
+    L.push("");
+    if (r.undeclared.length === 0) {
+        L.push(r.agentSteps === 0
+            ? "  no agent steps found — nothing to classify"
+            : "  ✓ every agent step declares a data_policy");
+        L.push("");
+        return `${L.join("\n")}\n`;
+    }
+    let current = "";
+    for (const s of r.undeclared) {
+        if (s.recipe !== current) {
+            current = s.recipe;
+            L.push(`  ${current}`);
+        }
+        const fed = s.feeds.length === 0
+            ? "no step output flows in"
+            : s.feeds
+                .map((f) => `${f.ref}${f.tool ? ` <- ${f.tool}` : f.fromAgent ? " <- agent" : ""}`)
+                .join(", ");
+        L.push(`      ${s.stepId}: ${fed}`);
+        if (s.unresolvedRefs.length > 0) {
+            L.push(`        (unresolved refs: ${s.unresolvedRefs.join(", ")})`);
+        }
+    }
+    L.push("");
+    L.push("  Classify by what the step HANDLES, including whatever its tools return —");
+    L.push("  a prompt that mentions nothing sensitive can still be handed a mailbox by");
+    L.push("  the step above it. No classification is suggested here on purpose: a");
+    L.push("  declared-but-wrong label is worse than an assumed one, because it stops");
+    L.push("  looking like a gap.");
+    L.push("");
+    return `${L.join("\n")}\n`;
+}
+//# sourceMappingURL=undeclaredSteps.js.map

package/dist/privacy/undeclaredSteps.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"undeclaredSteps.js","sourceRoot":"","sources":["../../src/privacy/undeclaredSteps.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAyCH,SAAS,QAAQ,CAAC,CAAU;IAC1B,OAAO,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;AAClE,CAAC;AAED,mFAAmF;AACnF,MAAM,UAAU,MAAM,CAAC,MAAc;IACnC,MAAM,GAAG,GAAG,IAAI,GAAG,EAAU,CAAC;IAC9B,KAAK,MAAM,CAAC,IAAI,MAAM,CAAC,QAAQ,CAAC,4BAA4B,CAAC,EAAE,CAAC;QAC9D,MAAM,IAAI,GAAI,CAAC,CAAC,CAAC,CAAY,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAW,CAAC;QACtD,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAChB,CAAC;IACD,OAAO,CAAC,GAAG,GAAG,CAAC,CAAC;AAClB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAChC,UAAkB,EAClB,MAAe;IAEf,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;QACtD,OAAO,EAAE,UAAU,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC;IACnD,CAAC;IACD,MAAM,GAAG,GAAG,MAAM,CAAC,KAAkB,CAAC;IAEtC,8EAA8E;IAC9E,2EAA2E;IAC3E,iBAAiB;IACjB,MAAM,SAAS,GAAG,IAAI,GAAG,EAAiD,CAAC;IAC3E,KAAK,MAAM,CAAC,IAAI,GAAG,EAAE,CAAC;QACpB,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC;YAAE,SAAS;QAC3B,MAAM,KAAK,GAAG,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;QACtD,MAAM,IAAI,GACR,OAAO,CAAC,CAAC,IAAI,KAAK,QAAQ;YACxB,CAAC,CAAC,CAAC,CAAC,IAAI;YACR,CAAC,CAAC,KAAK,IAAI,OAAO,KAAK,CAAC,IAAI,KAAK,QAAQ;gBACvC,CAAC,CAAC,KAAK,CAAC,IAAI;gBACZ,CAAC,CAAC,SAAS,CAAC;QAClB,IAAI,CAAC,IAAI;YAAE,SAAS;QACpB,SAAS,CAAC,GAAG,CAAC,IAAI,EAAE;YAClB,GAAG,CAAC,OAAO,CAAC,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACvD,SAAS,EAAE,KAAK,KAAK,SAAS;SAC/B,CAAC,CAAC;IACL,CAAC;IAED,IAAI,UAAU,GAAG,CAAC,CAAC;IACnB,IAAI,QAAQ,GAAG,CAAC,CAAC;IACjB,MAAM,KAAK,GAAqB,EAAE,CAAC;IACnC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACpC,MAAM,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC;QACjB,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC;YAAE,SAAS;QAC3B,MAAM,KAAK,GAAG,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;QACtD,IAAI,CAAC,KAAK;YAAE,SAAS;QACrB,UAAU,EAAE,CAAC;QACb,2EAA2E;QAC3E,yEAAyE;QACzE,IAAI,KAAK,CAAC,WAAW,KAAK,SAAS,IAAI,CAAC,CAAC,WAAW,KAAK,SAAS,EAAE,CAAC;YACnE,QAAQ,EAAE,CAAC;YACX,SAAS;QACX,CAAC;QACD,MAAM,MAAM,GAAG,OAAO,KAAK,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC;QACpE,MAAM,KAAK,GAAoB,EAAE,CAAC;QAClC,MAAM,UAAU,GAAa,EAAE,CAAC;QAChC,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC;YACjC,MAAM,CAAC,GAAG,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YAC7B,IAAI,CAAC,EAAE,CAAC;gBACN,KAAK,CAAC,IAAI,CAAC;oBACT,GAAG;oBACH,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;oBACnC,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;iBAC5C,CAAC,CAAC;YACL,CAAC;iBAAM,CAAC;gBACN,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YACvB,CAAC;QACH,CAAC;QACD,KAAK,CAAC,IAAI,CAAC;YACT,MAAM,EAAE,UAAU;YAClB,MAAM,EACJ,OAAO,CAAC,CAAC,EAAE,KAAK,QAAQ;gBACtB,CAAC,CAAC,CAAC,CAAC,EAAE;gBACN,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,KAAK,QAAQ;oBAC1B,CAAC,CAAC,CAAC,CAAC,IAAI;oBACR,CAAC,CAAC,QAAQ,CAAC,EAAE;YACnB,KAAK;YACL,cAAc,EAAE,UAAU;SAC3B,CAAC,CAAC;IACL,CAAC;IACD,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC;AACzC,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,CAAmB;IAClD,MAAM,CAAC,GAAa,EAAE,CAAC;IACvB,CAAC,CAAC,IAAI,CAAC,2CAA2C,CAAC,CAAC;IACpD,2EAA2E;IAC3E,eAAe;IACf,CAAC,CAAC,IAAI,CACJ,KAAK,CAAC,CAAC,UAAU,CAAC,MAAM,OAAO,CAAC,CAAC,UAAU,yBAAyB,CAAC,CAAC,cAAc,yBAAyB,CAC9G,CAAC;IACF,IAAI,CAAC,CAAC,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC5B,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,UAAU,CAAC,MAAM,gCAAgC,CAAC,CAAC;IACnE,CAAC;IACD,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACX,IAAI,CAAC,CAAC,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC9B,CAAC,CAAC,IAAI,CACJ,CAAC,CAAC,UAAU,KAAK,CAAC;YAChB,CAAC,CAAC,8CAA8C;YAChD,CAAC,CAAC,6CAA6C,CAClD,CAAC;QACF,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACX,OAAO,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC;IAC7B,CAAC;IACD,IAAI,OAAO,GAAG,EAAE,CAAC;IACjB,KAAK,MAAM,CAAC,IAAI,CAAC,CAAC,UAAU,EAAE,CAAC;QAC7B,IAAI,CAAC,CAAC,MAAM,KAAK,OAAO,EAAE,CAAC;YACzB,OAAO,GAAG,CAAC,CAAC,MAAM,CAAC;YACnB,CAAC,CAAC,IAAI,CAAC,KAAK,OAAO,EAAE,CAAC,CAAC;QACzB,CAAC;QACD,MAAM,GAAG,GACP,CAAC,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC;YAClB,CAAC,CAAC,yBAAyB;YAC3B,CAAC,CAAC,CAAC,CAAC,KAAK;iBACJ,GAAG,CACF,CAAC,CAAC,EAAE,EAAE,CACJ,GAAG,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,EAAE,CACzE;iBACA,IAAI,CAAC,IAAI,CAAC,CAAC;QACpB,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC,CAAC;QACpC,IAAI,CAAC,CAAC,cAAc,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAChC,CAAC,CAAC,IAAI,CAAC,6BAA6B,CAAC,CAAC,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACtE,CAAC;IACH,CAAC;IACD,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACX,CAAC,CAAC,IAAI,CACJ,4EAA4E,CAC7E,CAAC;IACF,CAAC,CAAC,IAAI,CACJ,6EAA6E,CAC9E,CAAC;IACF,CAAC,CAAC,IAAI,CACJ,wEAAwE,CACzE,CAAC;IACF,CAAC,CAAC,IAAI,CACJ,2EAA2E,CAC5E,CAAC;IACF,CAAC,CAAC,IAAI,CAAC,uBAAuB,CAAC,CAAC;IAChC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACX,OAAO,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC;AAC7B,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "patchwork-os",
-  "version": "1.2.0-beta.2.canary.747",
+  "version": "1.2.0-beta.2.canary.749",
   "description": "Your personal AI runtime, local-first. Patchwork OS gives any AI model a consistent set of tools, YAML recipes, a delegation policy with approval queue, and a durable trace memory — all on your machine, all under your policy.",
   "type": "module",
   "main": "dist/index.js",