@gtrabanco/pi-agentic-workflow 0.26.0 → 0.31.0

package/dist/extension/index.js

@@ -7,7 +7,9 @@ import { evaluateToolCall, isProtectedPath, normalizeTarget } from "../config/pa
 import { createExtension } from "./factory.js";
 import { readGitStatusBounded } from "./receipt-guard.js";
 import { createPickerComponent, PICKER_MAX_VISIBLE, pagedSelect } from "../settings/picker.js";
-import { createHintStore, stateFilePath } from "../routing/state.js";
+import { createHintStore, createSerenaReadinessStore, stateFilePath } from "../routing/state.js";
+import { createSerenaReadinessGate, readInitWorkspaceRevision } from "../routing/serena-readiness.js";
+import { provisionEngram, readDeclaredServerNamesFrom, resolveEngramBinary, declaredMcpServerPaths } from "./engram.js";
 import { runSettingsConsole } from "../settings/console.js";
 import { readConfigFile, writeConfigFile } from "../settings/store.js";
 import { SETTINGS_COMMAND } from "../routing/types.js";
@@ -171,9 +173,59 @@ function resolveExistingPrefix(target) {
         }
     }
 }
+/**
+ * Pi's MCP registrar, read structurally rather than imported: the package's
+ * peer floor is a range, and a host older than `registerMcpServer` must degrade
+ * (the provisioning module reports `unsupported-host`) instead of throwing at
+ * load.
+ */
+function mcpRegistrar(pi) {
+    const candidate = pi.registerMcpServer;
+    if (typeof candidate !== "function")
+        return null;
+    return (name, config) => {
+        candidate.call(pi, name, config);
+    };
+}
+/**
+ * The server names the operator already has declared — the set the anti-shadow
+ * guard is judged against. Both surfaces are unioned: Pi's own `getMcpServers()`
+ * (read structurally for the same peer-floor reason as the registrar; it is the
+ * merged view the host applies), and the `mcp.json` files Pi reads for this
+ * session, user file and trusted project file alike. Either one answering is
+ * enough to refuse; reading only the user file was the F6 defect, which
+ * registered over a project declaration and then reported precedence over a
+ * file it had never opened.
+ */
+function declaredServerNames(pi, agentDir, ctx) {
+    const names = new Set(readDeclaredServerNamesFrom(declaredMcpServerPaths({ agentDir, cwd: ctx.cwd, projectTrusted: ctx.isProjectTrusted() })));
+    const candidate = pi.getMcpServers;
+    if (typeof candidate === "function") {
+        try {
+            const listed = candidate.call(pi);
+            if (Array.isArray(listed)) {
+                for (const server of listed)
+                    if (typeof server?.name === "string")
+                        names.add(server.name);
+            }
+        }
+        catch {
+            // A host that cannot answer is not a declaration: the file reads stand.
+        }
+    }
+    return [...names];
+}
 export default function extension(pi) {
     const agentDir = getAgentDir();
     const hint = createHintStore({ path: stateFilePath(agentDir) });
+    // One gate for both entry points (AC9): session start says it first, and a
+    // session that begins by running a command says it there instead. The
+    // revision is the bundled init-workspace's own, so an upgrade that ships a
+    // newer provisioning contract can tell the operator the project predates it.
+    const serenaReadiness = createSerenaReadinessGate({
+        store: createSerenaReadinessStore({ path: stateFilePath(agentDir) }),
+        revision: readInitWorkspaceRevision(skillsDir),
+    });
     // Said once per session: an override that was ignored (or a malformed file)
     // is reported the first time the guard runs, never on every tool call.
     let reportedDegradations = false;
@@ -190,6 +242,7 @@ export default function extension(pi) {
         skillsDir,
         agentDir,
         hint,
+        serenaReadiness,
         loadConfig: (ctx) => loadConfig({ agentDir, cwd: ctx.cwd, projectTrusted: ctx.isProjectTrusted() }),
         // The console edits the same files the dispatcher reads (SPEC S4, AC10).
         settings: ({ ctx, catalogue: routed, routing }) => runSettingsConsole({
@@ -204,6 +257,38 @@ export default function extension(pi) {
             writeFile: writeConfigFile,
         }),
     });
+    // One `session_start` listener carries both first chances, in this order.
+    //
+    // The readiness nudge (AC9) hears the session here, and the gate latches so
+    // the command path never repeats it — soft by construction, because the gate
+    // swallows a broken read and a failed latch.
+    //
+    // Memory substrate (feature 66, AC3) comes second: ask-first,
+    // registrable-not-persisted. Registration runs on the session rather than at
+    // load so an older Pi host is reported instead of throwing, and so the
+    // operator reads back exactly what was written. Nothing is provisioned
+    // without the `memory.engram` opt-in, and a config file that does not parse
+    // is never read as one: its consent is unknown, and the refusal says so
+    // instead of telling an opted-in operator to opt in.
+    pi.on("session_start", (_event, ctx) => {
+        const message = serenaReadiness.check(ctx.cwd);
+        if (message)
+            ctx.ui.notify(message, "warning");
+        const projectTrusted = ctx.isProjectTrusted();
+        const loaded = loadConfig({ agentDir, cwd: ctx.cwd, projectTrusted });
+        const report = provisionEngram({
+            consented: loaded.config.memory?.engram === true,
+            configInvalid: !loaded.ok,
+            binaryPath: resolveEngramBinary(),
+            declaredNames: declaredServerNames(pi, agentDir, ctx),
+            register: mcpRegistrar(pi),
+        });
+        // The opt-out stays silent; every other outcome is stated once, in the
+        // module's own words (it already says what was written, or why not).
+        if (report.status !== "not-consented") {
+            ctx.ui.notify(report.message, report.status === "registered" ? "info" : "warning");
+        }
+    });
     pi.on("model_select", (event) => router.noteModelSelect(event.model));
     pi.on("thinking_level_select", (event) => router.noteThinkingLevelSelect(event.level));
     // The inline-receipt path is impossible: a `gh pr comment` carrying a

package/dist/routing/serena-readiness.d.ts

@@ -0,0 +1,77 @@
+import type { SerenaReadinessRecord, SerenaReadinessStore } from "./state.js";
+/**
+ * Serena readiness nudge (feature 67 P5, decision D5 / AC9).
+ *
+ * A pi user who installs this package gets Serena's tools, but the project
+ * config is `init-workspace`'s to write (AC6: one writer, no drift). So this is
+ * the only thing the package may do about a project that was never provisioned:
+ * **say so, once**, and point at the command that fixes it.
+ *
+ * The contract, in four lines:
+ *  - it reads `.serena/project.yml` and reports `missing`, `stale`, `outdated`
+ *    (the bundled init-workspace moved on) or `ready`;
+ *  - it announces **exactly one** message per recorded state, then latches —
+ *    the latch lives in the package's own global state file, so a restart does
+ *    not re-nag (the first-run hint's contract);
+ *  - it writes nothing to the project and nothing to any configuration;
+ *  - every failure is soft: a broken read is `missing`, a failed latch is a
+ *    nuisance, and neither ever throws into a command.
+ */
+/** The one command that owns Serena provisioning. */
+export declare const INIT_WORKSPACE_COMMAND = "/init-workspace";
+/** What a `.serena/project.yml` says about itself — only what this check reads. */
+export interface SerenaConfig {
+    present: boolean;
+    /** The `language_servers` entries, in file order. Empty when absent or empty. */
+    languageServers: string[];
+}
+export type SerenaReadiness = {
+    kind: "missing";
+} | {
+    kind: "stale";
+    detail: string;
+} | {
+    kind: "outdated";
+    recorded: string;
+    revision: string;
+} | {
+    kind: "ready";
+};
+/**
+ * Read the two facts this check needs out of the project config. A tolerant
+ * line scanner, not a YAML parser: the file is written by `init-workspace`, and
+ * the only key read here is the `language_servers` list. Anything it cannot
+ * understand reads as "no servers", which is the fail-closed direction — the
+ * nudge fires rather than a broken config passing silently.
+ */
+export declare function inspectSerenaConfig(text: string | null | undefined): SerenaConfig;
+/**
+ * Decide what this project needs. `recorded` is the latch's last announcement —
+ * a changed shipped revision is itself a trigger, so an upgraded package can
+ * tell the operator that the config predates it.
+ */
+export declare function evaluateSerenaReadiness({ config, recorded, revision, }: {
+    config: SerenaConfig;
+    recorded?: SerenaReadinessRecord;
+    revision: string;
+}): SerenaReadiness;
+/** The one notification this module may produce, or null when there is nothing to say. */
+export declare function serenaReadinessMessage(readiness: SerenaReadiness): string | null;
+export interface SerenaReadinessGate {
+    /** The message to announce for this project, or null when nothing is due. */
+    check(projectKey: string): string | null;
+}
+/**
+ * The gate the two entry points share (session start and the first command
+ * dispatch). One latch per extension instance, so a single session announces at
+ * most once; the persisted record keeps later sessions quiet.
+ */
+export declare function createSerenaReadinessGate({ store, revision, readProject, now, }: {
+    store: SerenaReadinessStore;
+    revision: string;
+    /** Injectable so the suite reads fixtures instead of a real project. */
+    readProject?: (projectKey: string) => string | null;
+    now?: () => string;
+}): SerenaReadinessGate;
+/** The bundled `init-workspace` revision, read from the shipped skill's frontmatter. */
+export declare function readInitWorkspaceRevision(skillsDir: string): string;

package/dist/routing/serena-readiness.js

@@ -0,0 +1,142 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+/**
+ * Serena readiness nudge (feature 67 P5, decision D5 / AC9).
+ *
+ * A pi user who installs this package gets Serena's tools, but the project
+ * config is `init-workspace`'s to write (AC6: one writer, no drift). So this is
+ * the only thing the package may do about a project that was never provisioned:
+ * **say so, once**, and point at the command that fixes it.
+ *
+ * The contract, in four lines:
+ *  - it reads `.serena/project.yml` and reports `missing`, `stale`, `outdated`
+ *    (the bundled init-workspace moved on) or `ready`;
+ *  - it announces **exactly one** message per recorded state, then latches —
+ *    the latch lives in the package's own global state file, so a restart does
+ *    not re-nag (the first-run hint's contract);
+ *  - it writes nothing to the project and nothing to any configuration;
+ *  - every failure is soft: a broken read is `missing`, a failed latch is a
+ *    nuisance, and neither ever throws into a command.
+ */
+/** The one command that owns Serena provisioning. */
+export const INIT_WORKSPACE_COMMAND = "/init-workspace";
+/**
+ * Read the two facts this check needs out of the project config. A tolerant
+ * line scanner, not a YAML parser: the file is written by `init-workspace`, and
+ * the only key read here is the `language_servers` list. Anything it cannot
+ * understand reads as "no servers", which is the fail-closed direction — the
+ * nudge fires rather than a broken config passing silently.
+ */
+export function inspectSerenaConfig(text) {
+    if (typeof text !== "string")
+        return { present: false, languageServers: [] };
+    const lines = text.split(/\r?\n/u);
+    const start = lines.findIndex((line) => /^language_servers:/u.test(line));
+    if (start === -1)
+        return { present: true, languageServers: [] };
+    // Inline form: `language_servers: [markdown, json]`
+    const inline = /^language_servers:\s*\[(.*)\]\s*$/u.exec(lines[start]);
+    if (inline) {
+        return {
+            present: true,
+            languageServers: inline[1]
+                .split(",")
+                .map((entry) => entry.trim().replace(/^["']|["']$/gu, ""))
+                .filter(Boolean),
+        };
+    }
+    const languageServers = [];
+    for (const line of lines.slice(start + 1)) {
+        const item = /^\s+-\s*(.+?)\s*$/u.exec(line);
+        if (!item) {
+            // The list ended (a new top-level key) or the line is blank/comment.
+            if (line.trim() !== "" && !/^\s*#/u.test(line))
+                break;
+            continue;
+        }
+        languageServers.push(item[1].replace(/^["']|["']$/gu, ""));
+    }
+    return { present: true, languageServers };
+}
+/**
+ * Decide what this project needs. `recorded` is the latch's last announcement —
+ * a changed shipped revision is itself a trigger, so an upgraded package can
+ * tell the operator that the config predates it.
+ */
+export function evaluateSerenaReadiness({ config, recorded, revision, }) {
+    if (!config.present)
+        return { kind: "missing" };
+    if (config.languageServers.length === 0) {
+        return {
+            kind: "stale",
+            detail: "the project config lists no language_servers, so no server will start for it",
+        };
+    }
+    if (recorded?.state === "ready" && recorded.revision !== revision) {
+        return { kind: "outdated", recorded: recorded.revision, revision };
+    }
+    return { kind: "ready" };
+}
+/** The one notification this module may produce, or null when there is nothing to say. */
+export function serenaReadinessMessage(readiness) {
+    switch (readiness.kind) {
+        case "missing":
+            return (`pi-agentic-workflow: serena — this project has no .serena/project.yml, so no language server ` +
+                `will start for it. Run ${INIT_WORKSPACE_COMMAND} to provision it (this is said once).`);
+        case "stale":
+            return (`pi-agentic-workflow: serena — ${readiness.detail}. Run ${INIT_WORKSPACE_COMMAND} to rewrite it ` +
+                `(this is said once).`);
+        case "outdated":
+            return (`pi-agentic-workflow: serena — this project's config was provisioned by init-workspace ` +
+                `${readiness.recorded}, and this package ships ${readiness.revision}. Run ${INIT_WORKSPACE_COMMAND} ` +
+                `to bring it up to date (this is said once).`);
+        case "ready":
+            return null;
+    }
+}
+/**
+ * The gate the two entry points share (session start and the first command
+ * dispatch). One latch per extension instance, so a single session announces at
+ * most once; the persisted record keeps later sessions quiet.
+ */
+export function createSerenaReadinessGate({ store, revision, readProject = (projectKey) => {
+    try {
+        return readFileSync(join(projectKey, ".serena", "project.yml"), "utf8");
+    }
+    catch {
+        return null;
+    }
+}, now = () => new Date().toISOString(), }) {
+    let announced = false;
+    return {
+        check(projectKey) {
+            if (announced)
+                return null;
+            announced = true;
+            const config = inspectSerenaConfig(readProject(projectKey));
+            const recorded = store.record(projectKey);
+            const readiness = evaluateSerenaReadiness({ config, recorded, revision });
+            // The latch compares STATE KINDS, not just the presence of a record: a
+            // project that was ready and lost its config is a new thing to say, while
+            // a project still missing one is not.
+            const due = readiness.kind !== "ready" && recorded?.state !== readiness.kind;
+            // Latch second, and always: a ready project still stores its revision, so
+            // a later upgrade has a baseline to compare against.
+            store.latch(projectKey, { state: readiness.kind, revision, at: now() });
+            if (!due)
+                return null;
+            return serenaReadinessMessage(readiness);
+        },
+    };
+}
+/** The bundled `init-workspace` revision, read from the shipped skill's frontmatter. */
+export function readInitWorkspaceRevision(skillsDir) {
+    try {
+        const text = readFileSync(join(skillsDir, "init-workspace", "SKILL.md"), "utf8");
+        const match = /^version:\s*(\S+)\s*$/mu.exec(text.split("\n---", 1)[0] ?? "");
+        return match ? match[1] : "unknown";
+    }
+    catch {
+        return "unknown";
+    }
+}

package/dist/routing/state.d.ts

@@ -37,3 +37,35 @@ export interface ProfileStateStoreOptions {
     writeFile?: (path: string, text: string) => void;
 }
 export declare function createProfileStateStore({ path, readFile, writeFile, }: ProfileStateStoreOptions): ProfileStateStore;
+/**
+ * What the operator was last told about one project's Serena config, keyed by
+ * the project root. The record is the nudge's whole memory: the state kind it
+ * announced and the init-workspace revision that was current when it did.
+ */
+export interface SerenaReadinessRecord {
+    /** The readiness kind announced (`missing`, `stale`, `outdated`, `ready`). */
+    state: string;
+    /** The bundled `init-workspace` revision in force at that moment. */
+    revision: string;
+    /** ISO-8601 timestamp of the announcement. */
+    at: string;
+}
+export interface SerenaReadinessStore {
+    /** The record for `projectKey`, or undefined when this project was never seen. */
+    record(projectKey: string): SerenaReadinessRecord | undefined;
+    /** Persist the record for `projectKey`. Returns false when the write failed. */
+    latch(projectKey: string, record: SerenaReadinessRecord): boolean;
+}
+export interface SerenaReadinessStoreOptions {
+    path: string;
+    readFile?: (path: string) => string | null;
+    writeFile?: (path: string, text: string) => void;
+}
+/**
+ * The nudge's latch, in the package's own global state file beside the
+ * first-run hint and the profile demotion — never inside the project, and never
+ * inside any configuration. Read-merge-write throughout, so no other key in
+ * that file is disturbed; every failure is soft (a latch that cannot be
+ * persisted re-shows the nudge next session, which is a nuisance, not a fault).
+ */
+export declare function createSerenaReadinessStore({ path, readFile, writeFile, }: SerenaReadinessStoreOptions): SerenaReadinessStore;

package/dist/routing/state.js

@@ -129,3 +129,54 @@ export function createProfileStateStore({ path, readFile = readOrNull, writeFile
         },
     };
 }
+/**
+ * The nudge's latch, in the package's own global state file beside the
+ * first-run hint and the profile demotion — never inside the project, and never
+ * inside any configuration. Read-merge-write throughout, so no other key in
+ * that file is disturbed; every failure is soft (a latch that cannot be
+ * persisted re-shows the nudge next session, which is a nuisance, not a fault).
+ */
+export function createSerenaReadinessStore({ path, readFile = readOrNull, writeFile = writeThrough, }) {
+    const readState = () => {
+        const text = readFile(path);
+        if (text === null || text.trim() === "")
+            return {};
+        try {
+            const parsed = JSON.parse(text);
+            if (typeof parsed === "object" && parsed !== null)
+                return parsed;
+        }
+        catch {
+            // Corrupt state: treat as empty, so the nudge is shown rather than lost.
+        }
+        return {};
+    };
+    return {
+        record(projectKey) {
+            const raw = readState().serenaReadiness;
+            if (typeof raw !== "object" || raw === null)
+                return undefined;
+            const entry = raw[projectKey];
+            if (typeof entry !== "object" || entry === null)
+                return undefined;
+            const { state, revision, at } = entry;
+            if (typeof state !== "string" || typeof revision !== "string" || typeof at !== "string")
+                return undefined;
+            return { state, revision, at };
+        },
+        latch(projectKey, record) {
+            const state = readState();
+            const existing = state.serenaReadiness;
+            const perProject = typeof existing === "object" && existing !== null ? existing : {};
+            perProject[projectKey] = record;
+            state.serenaReadiness = perProject;
+            try {
+                writeFile(path, `${JSON.stringify(state, null, 2)}\n`);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        },
+    };
+}

package/dist/settings/console.js

@@ -650,38 +650,84 @@ function describeRouting(file) {
     ];
     return routes.join(" · ");
 }
+/**
+ * The canonical write order for a config file. `dirty()` compares the cleaned
+ * draft against the cleaned file as JSON text, so the order is part of the
+ * contract: the same keys written in a different order would read as an edit.
+ * Keys outside this list are appended in the draft's own order, so a key the
+ * console never prompts for still survives the save (F4).
+ */
+const KEY_ORDER = [
+    "default",
+    "commands",
+    "onUnavailableRoute",
+    "onSettle",
+    "pathProtection",
+    "advance",
+    "recommendedModels",
+    "memory",
+    "profiles",
+    "profileOrder",
+    "profileFallback",
+];
 /**
  * Keep everything the file held or the operator set; drop only what says nothing
  * (an empty route). Eliding by VALUE — treating an explicit `inherit` or `stop` as
  * absent because a shipped default happens to agree — silently discards the only
  * two moves that matter at project scope: switching a command off under a global
  * route, and re-arming fail-closed over a global `inherit` (F4).
+ *
+ * The copy is driven by the draft's OWN keys, not by a list of the keys this
+ * console edits. Enumerating them silently deleted every valid key the console
+ * never prompts for — `memory` (the Engram consent switch, feature 66 AC3),
+ * `pathProtection` and `advance` — so an opt-in written by hand vanished on the
+ * next save with no message and no error (F4/VF-4). A key the parser accepted is
+ * never a key this function may drop.
  */
 function clean(draft) {
-    const file = {};
-    if (draft.default && Object.keys(draft.default).length > 0)
-        file.default = { ...draft.default };
-    const commands = {};
-    for (const [name, route] of Object.entries(draft.commands ?? {})) {
-        if (Object.keys(route).length > 0)
-            commands[name] = { ...route };
-    }
-    if (Object.keys(commands).length > 0)
-        file.commands = commands;
-    if (draft.onUnavailableRoute)
-        file.onUnavailableRoute = draft.onUnavailableRoute;
-    if (draft.onSettle)
-        file.onSettle = draft.onSettle;
-    if (draft.recommendedModels !== undefined)
-        file.recommendedModels = draft.recommendedModels;
-    if (draft.profiles && Object.keys(draft.profiles).length > 0) {
-        file.profiles = structuredClone(draft.profiles);
+    const kept = {};
+    for (const [key, value] of Object.entries(draft)) {
+        if (value === undefined)
+            continue;
+        if (key === "commands") {
+            const commands = {};
+            for (const [name, route] of Object.entries((value ?? {}))) {
+                if (route && Object.keys(route).length > 0)
+                    commands[name] = { ...route };
+            }
+            if (Object.keys(commands).length > 0)
+                kept.commands = commands;
+            continue;
+        }
+        if (key === "profiles") {
+            const profiles = {};
+            for (const [name, profile] of Object.entries((value ?? {}))) {
+                if (profile && Object.keys(profile).length > 0)
+                    profiles[name] = structuredClone(profile);
+            }
+            if (Object.keys(profiles).length > 0)
+                kept.profiles = profiles;
+            continue;
+        }
+        if (Array.isArray(value)) {
+            // `profileOrder` is the only list at this level: an empty order says
+            // nothing, so it is elided exactly as the empty route was.
+            if (value.length > 0)
+                kept[key] = [...value];
+            continue;
+        }
+        if (typeof value === "object" && value !== null && Object.keys(value).length === 0)
+            continue;
+        kept[key] = typeof value === "object" && value !== null ? structuredClone(value) : value;
     }
-    if (draft.profileOrder && draft.profileOrder.length > 0) {
-        file.profileOrder = [...draft.profileOrder];
+    const file = {};
+    for (const key of KEY_ORDER) {
+        if (key in kept)
+            file[key] = kept[key];
     }
-    if (draft.profileFallback && Object.keys(draft.profileFallback).length > 0) {
-        file.profileFallback = { ...draft.profileFallback };
+    for (const key of Object.keys(kept)) {
+        if (!(key in file))
+            file[key] = kept[key];
     }
     return file;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gtrabanco/pi-agentic-workflow",
-  "version": "0.26.0",
+  "version": "0.31.0",
   "description": "Pi package: canonical agentic-workflow skills, friendly slash commands, and per-command model routing.",
   "keywords": [
     "pi-package",
@@ -21,7 +21,8 @@
   "type": "module",
   "pi": {
     "extensions": [
-      "./dist/extension/index.js"
+      "./dist/extension/index.js",
+      "./node_modules/@bacnh85/pi-serena/extensions/index.ts"
     ],
     "skills": [
       "./skills"
@@ -57,8 +58,9 @@
     "@earendil-works/pi-tui": "*"
   },
   "dependencies": {
+    "@bacnh85/pi-serena": "0.10.0",
     "@gtrabanco/agentic-workflow": "0.2.0",
-    "@gtrabanco/agentic-workflow-schema": "4.6.0"
+    "@gtrabanco/agentic-workflow-schema": "4.7.0"
   },
   "devDependencies": {
     "@types/node": "24.13.3",

package/skills/execute-phase/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: execute-phase
 user-invocable: true
-version: 6.1.0
+version: 6.2.1
 argument-hint: <NN-slug> [P<k>|step] [--max-attempts N] [--force]
 allowed-tools: [Bash, Read, Edit, Write, MultiEdit]
 author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
@@ -44,6 +44,8 @@ done:
 ✓ Evidence rows updated (command → exit/digest → output → verified-by)
 ✓ Progress log updated with a dated `YYYY-MM-DD HH:MM` entry that names the
   phase id (what, commit, next)
+✓ Memory boundary ran — the phase's outcome saved under `unit/<NN-slug>/doc`,
+  or the mirror marked pending when the layer is degraded
 ✓ Diff guard passed (on implement steps) — see `diff-guard` in PREFLIGHT.md
 ✓ → Next: block printed as the absolute last output
 ```
@@ -136,7 +138,14 @@ names before implementation), then green. UI/adapter glue may test after.
    output (≤2 lines) | verified-by |`. Append to the Evidence section.
 3. **Progress log**: append a dated entry —
    `YYYY-MM-DD HH:MM — <what was done> → <commit sha> — next: <what is next>`.
-4. **Commit**: `git add <changed files>` then `git commit -m "<type>(<scope>):
+4. **Memory boundary** — this step is a phase transition. Follow
+   [the memory protocol](../unit-lane/references/MEMORY.md): before the first
+   memory read run `agentic-workflow memory probe` once and record its verdict
+   in Evidence; after the step, save the phase id, what it changed, its Evidence
+   outcome and any discovery under `topic_key: "unit/<NN-slug>/doc"`, an explicit
+   `project` and explicit session attribution (§5). A `degraded` verdict is
+   recorded and the mirror marked pending — it never blocks the step.
+5. **Commit**: `git add <changed files>` then `git commit -m "<type>(<scope>):
    <step-summary>"` — run it, paste the SHA.
 
 ### 6. Red gate (repair loop)