engineering-memory 1.10.2 → 1.10.4

package/runtime/dist/src/runtime/questionnaire-store.js

@@ -0,0 +1,259 @@
+import { randomUUID } from 'node:crypto';
+import { link, readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import * as z from 'zod/v4';
+import { assertManagedPath, ensureManagedDirectory, isNodeError, readJson, removeFile, writeJson, } from '../utilities/files.js';
+import { sha256, stableStringify } from '../utilities/hash.js';
+import { assertSafeToPersist } from './offline-outbox.js';
+const identifier = z.string().regex(/^[A-Za-z0-9_-]{1,100}$/);
+export const questionnaireDefinitionSchema = z.strictObject({
+    questionnaireId: identifier,
+    message: z.string().trim().min(1).max(2000),
+    options: z
+        .array(z.strictObject({
+        id: z
+            .string()
+            .regex(/^[A-Za-z0-9_-]{1,80}$/)
+            .refine((value) => value !== '__other__'),
+        label: z.string().trim().min(1).max(240),
+    }))
+        .min(2)
+        .max(12)
+        .refine((values) => new Set(values.map((value) => value.id)).size === values.length),
+    allowFreeText: z.boolean().default(false),
+    textField: z
+        .strictObject({
+        title: z.string().trim().min(1).max(120),
+        maxLength: z.number().int().min(1).max(2000),
+        requiredForChoice: z
+            .string()
+            .regex(/^[A-Za-z0-9_-]{1,80}$/)
+            .optional(),
+        valueType: z.enum(['text', 'uuid_list']).optional(),
+    })
+        .optional(),
+});
+const scopeSchema = z.strictObject({
+    principalHash: z.string().regex(/^[0-9a-f]{64}$/),
+    repoFingerprint: z.string().regex(/^[0-9a-f]{64}$/),
+    projectId: z.string().uuid().nullable(),
+});
+const storedQuestionSchema = questionnaireDefinitionSchema.extend({
+    schemaVersion: z.literal(1),
+    scope: scopeSchema,
+    contentHash: z.string().regex(/^[0-9a-f]{64}$/),
+    requestKey: z.string().regex(/^questionnaire_[0-9a-f]{64}$/),
+    createdAt: z.string().datetime(),
+});
+const storedAnswerSchema = z.strictObject({
+    requestKey: z.string().regex(/^questionnaire_[0-9a-f]{64}$/),
+    answeredAt: z.string().datetime(),
+    answerAvailable: z.boolean(),
+    withdrawn: z.literal(true).optional(),
+    answer: z.strictObject({ choice: z.string(), text: z.string().optional() }).optional(),
+});
+export function questionnaireAnswerSchema(record) {
+    const textSchema = record.textField
+        ? record.textField.valueType === 'uuid_list'
+            ? z
+                .string()
+                .trim()
+                .min(2)
+                .max(record.textField.maxLength)
+                .refine((value) => {
+                try {
+                    const parsed = JSON.parse(value);
+                    if (!Array.isArray(parsed) || new Set(parsed).size !== parsed.length)
+                        return false;
+                    return z.array(z.string().uuid()).max(10).safeParse(parsed).success;
+                }
+                catch {
+                    return false;
+                }
+            }, 'Enter a JSON array containing valid project IDs.')
+                .optional()
+            : z.string().trim().min(1).max(record.textField.maxLength).optional()
+        : record.allowFreeText
+            ? z.string().trim().min(1).max(2000).optional()
+            : z.never().optional();
+    return z
+        .strictObject({
+        choice: z.enum([
+            ...record.options.map((option) => option.id),
+            ...(record.allowFreeText ? ['__other__'] : []),
+        ]),
+        text: z.preprocess((value) => (typeof value === 'string' && value.trim() === '' ? undefined : value), textSchema),
+    })
+        .refine((answer) => {
+        if (record.textField?.requiredForChoice === answer.choice)
+            return typeof answer.text === 'string';
+        if (answer.choice === '__other__')
+            return typeof answer.text === 'string';
+        return answer.text === undefined;
+    });
+}
+export class QuestionnaireStore {
+    root;
+    constructor(stateRoot) {
+        this.root = join(stateRoot, 'questionnaires');
+    }
+    async ask(scope, input) {
+        const definition = questionnaireDefinitionSchema.parse(input);
+        scopeSchema.parse(scope);
+        assertSafeToPersist(definition);
+        const contentHash = sha256(stableStringify(definition));
+        const question = {
+            ...definition,
+            schemaVersion: 1,
+            scope,
+            contentHash,
+            requestKey: `questionnaire_${sha256(`${stableStringify(scope)}\n${contentHash}\n${randomUUID()}`)}`,
+            createdAt: new Date().toISOString(),
+        };
+        await this.publish(this.pathFor(scope, definition.questionnaireId, 'pending.json'), question);
+        const record = await this.get(scope, definition.questionnaireId);
+        if (!record || record.contentHash !== contentHash) {
+            throw new Error('Questionnaire id was reused with different content. Resume the original question or use a new id.');
+        }
+        return record;
+    }
+    async get(scope, questionnaireId) {
+        const raw = await readJson(this.pathFor(scope, questionnaireId, 'pending.json'), this.root);
+        if (!raw)
+            return null;
+        const question = storedQuestionSchema.parse(raw);
+        const definition = questionnaireDefinitionSchema.parse({
+            questionnaireId: question.questionnaireId,
+            message: question.message,
+            options: question.options,
+            allowFreeText: question.allowFreeText,
+            textField: question.textField,
+        });
+        if (stableStringify(question.scope) !== stableStringify(scope) ||
+            question.questionnaireId !== questionnaireId ||
+            question.contentHash !== sha256(stableStringify(definition))) {
+            throw new Error('Questionnaire scope or content does not match its durable record.');
+        }
+        assertSafeToPersist(question);
+        const rawAnswer = await readJson(this.pathFor(scope, questionnaireId, 'answer.json'), this.root);
+        if (!rawAnswer)
+            return { ...question, status: 'pending' };
+        const answer = storedAnswerSchema.parse(rawAnswer);
+        if (answer.withdrawn) {
+            if (answer.requestKey !== question.requestKey || answer.answerAvailable || answer.answer)
+                throw new Error('Invalid questionnaire withdrawal receipt.');
+            return { ...question, ...answer, status: 'withdrawn' };
+        }
+        if (answer.requestKey !== question.requestKey ||
+            (answer.answerAvailable
+                ? !answer.answer || !question.options.some((option) => option.id === answer.answer.choice)
+                : !question.allowFreeText || answer.answer !== undefined)) {
+            throw new Error('Questionnaire answer does not match its durable question.');
+        }
+        if (answer.answer?.text !== undefined && !question.textField)
+            throw new Error('Questionnaire text answer does not match its durable question.');
+        if (question.textField?.requiredForChoice &&
+            question.textField.requiredForChoice === answer.answer?.choice &&
+            typeof answer.answer?.text !== 'string')
+            throw new Error('Questionnaire text answer is required for this choice.');
+        assertSafeToPersist(answer);
+        return { ...question, ...answer, status: 'answered' };
+    }
+    async pending(scope) {
+        const directory = this.scopeRoot(scope);
+        await ensureManagedDirectory(this.root, directory);
+        const entries = await readdir(directory, { withFileTypes: true });
+        const records = [];
+        for (const entry of entries) {
+            if (!/^[0-9a-f]{64}$/.test(entry.name))
+                continue;
+            if (!entry.isDirectory() || entry.isSymbolicLink())
+                throw new Error('Unsafe questionnaire directory.');
+            const path = await assertManagedPath(this.root, join(directory, entry.name, 'pending.json'), true);
+            const raw = await readJson(path, this.root);
+            if (!raw)
+                continue;
+            const question = storedQuestionSchema.parse(raw);
+            if (sha256(question.questionnaireId) !== entry.name)
+                throw new Error('Questionnaire directory does not match its id.');
+            const record = await this.get(scope, question.questionnaireId);
+            if (record?.status === 'pending')
+                records.push(record);
+        }
+        return records.sort((left, right) => left.createdAt.localeCompare(right.createdAt));
+    }
+    async accept(scope, questionnaireId, requestKey, input) {
+        const record = await this.get(scope, questionnaireId);
+        if (!record || record.requestKey !== requestKey)
+            throw new Error('Questionnaire response is stale or belongs to a different scope.');
+        if (record.status === 'withdrawn')
+            throw new Error('Questionnaire was explicitly withdrawn. Start a new decision if the user resumes the work.');
+        const answer = questionnaireAnswerSchema(record).parse(input);
+        assertSafeToPersist(answer);
+        if (record.status === 'answered') {
+            if (record.answer && stableStringify(record.answer) !== stableStringify(answer))
+                throw new Error('Questionnaire was already answered differently.');
+            return { record, answer: record.answer, replayed: true };
+        }
+        const receipt = {
+            requestKey,
+            answeredAt: new Date().toISOString(),
+            answerAvailable: answer.choice !== '__other__',
+            ...(answer.choice !== '__other__'
+                ? { answer: { choice: answer.choice, ...(answer.text ? { text: answer.text } : {}) } }
+                : {}),
+        };
+        const published = await this.publish(this.pathFor(scope, questionnaireId, 'answer.json'), receipt);
+        const resolved = (await this.get(scope, questionnaireId));
+        if (resolved.status === 'withdrawn')
+            throw new Error('Questionnaire was explicitly withdrawn before this response.');
+        if (!published &&
+            resolved.answer &&
+            stableStringify(resolved.answer) !== stableStringify(answer))
+            throw new Error('Questionnaire was already answered differently.');
+        return { record: resolved, answer: published ? answer : resolved.answer, replayed: !published };
+    }
+    async withdraw(scope, questionnaireId) {
+        const record = await this.get(scope, questionnaireId);
+        if (!record)
+            throw new Error('No questionnaire exists in this scope.');
+        if (record.status !== 'pending')
+            return record;
+        await this.publish(this.pathFor(scope, questionnaireId, 'answer.json'), {
+            requestKey: record.requestKey,
+            answeredAt: new Date().toISOString(),
+            answerAvailable: false,
+            withdrawn: true,
+        });
+        return (await this.get(scope, questionnaireId));
+    }
+    scopeRoot(scope) {
+        scopeSchema.parse(scope);
+        return join(this.root, scope.principalHash, sha256(`${scope.repoFingerprint}\n${scope.projectId ?? ''}`));
+    }
+    pathFor(scope, questionnaireId, filename) {
+        identifier.parse(questionnaireId);
+        return join(this.scopeRoot(scope), sha256(questionnaireId), filename);
+    }
+    async publish(path, value) {
+        assertSafeToPersist(value);
+        const temporaryPath = `${path}.${randomUUID()}.tmp`;
+        await writeJson(temporaryPath, value, this.root);
+        try {
+            const target = await assertManagedPath(this.root, path, true);
+            try {
+                await link(temporaryPath, target);
+                return true;
+            }
+            catch (error) {
+                if (isNodeError(error) && error.code === 'EEXIST')
+                    return false;
+                throw error;
+            }
+        }
+        finally {
+            await removeFile(temporaryPath, this.root);
+        }
+    }
+}
+//# sourceMappingURL=questionnaire-store.js.map

package/runtime/dist/src/utilities/files.js

@@ -136,7 +136,14 @@ export async function ensureManagedDirectory(root, directory) {
             if (!isNodeError(error) || error.code !== 'ENOENT') {
                 throw error;
             }
-            await mkdir(current, { mode: 0o700 });
+            try {
+                await mkdir(current, { mode: 0o700 });
+            }
+            catch (creationError) {
+                if (!isNodeError(creationError) || creationError.code !== 'EEXIST') {
+                    throw creationError;
+                }
+            }
             const created = await lstat(current);
             if (!created.isDirectory() || created.isSymbolicLink()) {
                 throw new Error(`Managed directory could not be created safely: ${current}`);

package/skill/SKILL.md

@@ -7,11 +7,11 @@ description: Enforces the Engineering Memory lifecycle for Codex and Claude in r
 
 This skill is a thin runtime protocol. It contains no proprietary engineering rules. The task-specific rules, project profile, screen logic, component mappings, service contracts, decisions, and quality gates must come from the Engineering Memory MCP server.
 
-Read [lifecycle.md](references/lifecycle.md) before acting in a bound repository. Read [questionnaires.md](references/questionnaires.md) when authentication, project binding, project creation, membership, correction scope, proposal review, or Git-hook choices require user input. Read [memory-updates.md](references/memory-updates.md) before changing screen, component, service, project, or organization memory. Read [scaffolding.md](references/scaffolding.md) before creating a project from the organization architecture templates or changing a template.
+Read [lifecycle.md](references/lifecycle.md) before acting in a bound repository. Read [project-onboarding.md](references/project-onboarding.md) for greenfield, adopt, rework and refresh flows. Read [questionnaires.md](references/questionnaires.md) when authentication, project binding, project creation, membership, correction scope, proposal review, or Git-hook choices require user input. Read [memory-updates.md](references/memory-updates.md) before changing screen, component, service, project, or organization memory. Read [scaffolding.md](references/scaffolding.md) before creating a project from the organization architecture templates or changing a template.
 
 Mandatory behavior:
 
-Use the host's native questionnaire for every question to the user, including implementation choices, names, clarification, branch/worktree decisions and delivery. In Codex use request_user_input when available; in Claude use AskUserQuestion. Never replace the questionnaire with a chat instruction such as 'type this', 'reply yes', or 'write X if you want Y'. Do not open a survey web page. If the required native control is unavailable or prohibited for that kind of question, follow the host's tool restrictions, explain the limitation, and continue only work already authorized; do not fabricate a survey or silently choose an answer. Existing answers remain valid through retries and handoffs.
+Use the host's native questionnaire for every question to the user, including implementation choices, names, clarification, branch/worktree decisions and delivery. For a required decision, read [questionnaires.md](references/questionnaires.md), then use `questionnaire.ask` to open a durable native MCP form and `questionnaire.resume` to return to the same unanswered question. Never use request_user_input_async for a required decision: it does not wait for an answer. When the durable form is unavailable, use a blocking native control only where the host permits it: request_user_input in Codex or AskUserQuestion in Claude. Never replace the questionnaire with a chat instruction such as 'type this', 'reply yes', or 'write X if you want Y'. Do not open a survey web page. If the required native control is unavailable or prohibited for that kind of question, follow the host's tool restrictions, explain the limitation, and continue only work already authorized; do not fabricate a survey or silently choose an answer. A timeout, dismissed form, empty response or ended turn is not an answer. Keep the decision pending and resume it; do not start dependent work or report it as resolved. Existing answers remain valid through retries and handoffs.
 
 1. Discover the repository binding through `session.entry`. Bindings live in the user-level Engineering Memory state directory, outside the repository and installed runtime. No project settings file is required. For a bound repository, the project's knowledge is in the backend, so answer nothing about it before bootstrapping; the absence of local design files or records says nothing about its stored knowledge.
 2. Call `session.entry` before answering anything in a repository, and act on what it reports before the message itself: sign in when it says so, ask for organization and project when nothing has been decided, and stay completely silent about Engineering Memory in a repository where the user switched it off. Record every one of those answers with `session.set_decision`, and only ever from something the user actually said.

package/skill/references/lifecycle.md

@@ -22,6 +22,8 @@ A task nobody is going to finish is abandoned rather than inherited. Ask the use
 
 If an existing task is identified or execution resumes after compaction, call `session.resume`. Reconcile backend sequence, local outbox, Markdown projections, current Git diff, pinned revisions, and the active lease before any further action.
 
+Reconcile pending questions too. A required question remains unanswered across a timeout, dismissed form, interruption or restart. Use `questionnaire.resume` for its recorded identifier and wait for an explicit valid response before dependent work. Follow `questionnaires.md`; do not create a replacement async prompt or consume an unrelated task's answer.
+
 ## Discovery
 
 Perform only read operations until the relevant current code, tests, Figma evidence, Git diff, and returned memory have been inspected.
@@ -81,26 +83,51 @@ Temporary code written to reach or force a path — a pinned state, a fixed serv
 
 Do not write task Markdown files directly. The bridge owns event IDs, expected task versions, atomic projections, outbox state, and synchronization.
 
-## Adopting a Project That Already Exists
-
-A repository bound with a working system in it can be surveyed at any time, not only at the moment
-it is bound. When the user asks for its architecture to be learned, read, recorded or understood,
-that is a survey: open it as a read-only task and follow `engineering-core.adopting-an-existing-project`,
-which says what a survey records and what it must never do.
-
-Four things come out of it and nothing else: the discovery policy that matches the repository's
-actual layout, the architecture already in place recorded on the project profile under
-`architecture.adopted` with the pressure each structure relieves — or `inherited, reason not
-recorded` where nobody knows — one module record per module saying what it owns, and one current
-deviation per divergence, each carrying what the rule says, what the project does, both costs, and
-a decision or an explicit deferral. Everything else is written as later tasks reach it.
-
-The survey changes nothing in the tree. No formatting, no renames, no tidying of dead code it
-finds; leftovers are recorded as observations and decided like any other divergence.
-
-Where the same product has a client and a backend, they are two projects. Adopt them separately,
-then link them with `project.link` once both exist, and ask before linking rather than inferring it
-from the names.
+## Four-mode project onboarding
+
+Use `references/project-onboarding.md` and `engineering-core.adopting-an-existing-project` for the
+full flow. Project creation asks through a native questionnaire for `greenfield`, `adopt`, or
+`rework`; later incremental work is `refresh`. Read-only maturity analysis can recommend a mode but
+cannot select one. Adopt, rework discovery, and refresh use committed `HEAD` by default, walk an
+exhaustive cross-stack source inventory, and classify results as evidence, inference, or unknown.
+The inventory covers frontend pages, navigation, state, service classes and network layers; backend
+modules, services, data and API endpoints; project architecture; and the contracts connecting both
+sides.
+
+Greenfield applies compatible organization architecture modules and gates them with the real local
+toolchain. Adopt and refresh never modify source. Rework asks per project whether the target keeps
+behavior or redesigns it before proposing phased branches and tasks. Existing membership, active
+user, tenant scope, explicit assignments, Project-first strongest-lock-first ordering, supplied
+`EntityManager` transactions, immutable revisions and scope authority remain in force.
+
+The implemented onboarding operations are `project.inspect`, `project.initialize`, `memory.source`,
+`memory.sync_start`, `memory.sync_status`, `memory.sync_inventory`, `memory.sync_plan`,
+`memory.sync_next`, `memory.sync_submit`, `memory.sync_reopen`, `memory.sync_delta`,
+`memory.sync_verify`, `memory.catalog`, `memory.read_revisions`, and `memory.review_batch`.
+`memory.sync_start` snapshots a selected Git ref, persists its commit/tree/manifest hashes and file
+count, and uploads all manifest pages including exclusions. `memory.source` serves only bounded pages
+or exact file reads from that committed snapshot. `memory.sync_status` lists runs or paged units and
+coverage counters without exposing claim tokens.
+
+`memory.sync_plan` uploads semantic units and their paths and dependency keys. The initial plan must
+cover included and removed behavior, but analyzing may add newly discovered cross-module flow units.
+Existing unit identities and definitions remain immutable; every added unit needs the same complete
+submission, exact memory approval references and final verification before the run can complete.
+`memory.sync_next` claims a distinct unit for 15 minutes;
+the saved claim token explicitly resumes or renews that claim. `memory.sync_submit` records evidence,
+all behavior facets, gaps and exact proposal or unchanged revision references. No unit is autoapproved,
+and no historical task or motivation may be invented. Rejected or gapped unfinished units use
+`memory.sync_reopen` with the current expected version. `memory.sync_delta` compares a completed prior
+run's content hashes, memory revisions and transitive dependencies.
+
+`memory.review_batch` displays full proposal texts before a durable native questionnaire records the
+exact proposal IDs, content digests and base revisions. Pending or dismissed approval writes nothing;
+stale batches fail atomically. `memory.sync_verify` requires sealed inventory, complete semantic and
+removed-file coverage, submitted evidence, no unresolved gaps or failed unknown execution, and
+approved immutable references for changed memory. `questionnaire.ask` and `questionnaire.resume`
+support `preparation: true` for missing-folder decisions; `project.initialize` uses that native
+confirmation before preparing the folder and Git repository. Raw secrets, headers, customer payloads
+and PII are never uploaded.
 
 ## The Task Baseline
 

package/skill/references/project-onboarding.md

@@ -0,0 +1,146 @@
+# Project onboarding and memory refresh
+
+## Choose the journey before changing the repository
+
+Call `project.inspect` for the selected directory, including a missing directory. Its maturity
+classification is `missing`, `empty`, `scaffold` or `established`, supported by manifests and
+architecture/state/service/network/data/screen evidence. These are observations, not a mode choice.
+Explain the appropriate options to the user and use `project.onboard` (or `project.initialize` for
+initial Git preparation). The tool opens native forms for the actual mode and profile; do not write
+an answer in chat or infer a choice from the directory classification.
+
+The modes are `greenfield`, `adopt`, `rework` and `refresh`. Initial onboarding offers the first three;
+refresh is available for a selected existing project at any later time. Recognize the user's intent
+semantically in their own phrasing, with no keyword trigger table. Rework asks preserve or redesign
+explicitly. Choosing another mode than the proposed input returns that choice without changing files;
+repeat with the same requestKey and the user's selected mode.
+
+Use a stable requestKey per onboarding occurrence. Profile answers must be collected with native
+forms; each independent field is reviewed separately with its current value visible. The user may
+keep it, explicitly defer it, or request an edit in the same bounded native text field. An edited value
+is persisted as part of the exact decision and reaches the final profile digest; it cannot be silently
+replaced by a later chat value. The onboarding forms confirm the exact
+stack/runtime/architecture, service/API/auth/storage/environment choices and existing backend project
+IDs. For Flutter/React they additionally confirm Figma, color palette, font families and text styles,
+design system, navigation, platforms and languages; for Nest/Spring they confirm migration strategy.
+An explicit absence or deferral is acceptable; a made-up answer is not.
+The local machine's installed runtime is validation capability, not an architecture preference.
+
+`project.initialize` only prepares Git for the approved greenfield mode. It supports missing, empty
+and barely-started non-Git directories without overwriting existing files; parent repositories and
+symbolic links are protected. Choices persist in user-local Engineering Memory state outside the
+repository and installed package. After creating/selecting the backend project, pass projectId to
+`project.onboard` to store its exact choice in the project onboarding history. Include the confirmed
+profile in the normal project/profile proposal; onboarding choices do not independently activate
+engineering rules. `project.onboarding_status` reads those choices and any rework plans. Old projects
+remain uninspected until they opt in.
+
+If a native form is pending, preserve its identifier and resume it. A wizard can return the next
+pending form after one answer is accepted; complete that form and call the originating onboarding
+operation again to advance. Restart reuses answered questions and exact choice data. It never assumes
+approval after a cancellation, empty response or timeout.
+
+## Greenfield architecture and links
+
+Prepare and bind the repository through the existing project.setup flow, then use architecture.plan
+and architecture.module with the approved project profile. Apply the matching Flutter, React, NestJS
+or Spring templates through the scaffold task lifecycle. Replace technical demonstration inputs with
+approved application profile values; a compile fixture is not a user product or a ready live API.
+Flutter exposes injected service/transport, state lifecycle and cancellation, storage boundary,
+navigation and profile-controlled palette/typography. Validate the actual selected toolchain.
+
+List authorized backend/frontend projects when services may already exist. Offer the actual selected
+project IDs in the native profile form. Create approved links with project.link; a selection alone
+never changes a link, and fullstack discipline never replaces membership or link authority. Keep
+unavailable service contracts explicit rather than inventing endpoint behavior.
+
+## Durable deep learning
+
+Adopt, refresh and the learning stage of rework do not modify application source. They inventory and
+learn the whole architecture: modules, service classes, network and API contracts, state management,
+persistence/data models/migrations, navigation, screens/components, localization, deployment,
+authentication, runtime/toolchain and cross-module/end-to-end flows. Record source facts, tested
+behavior, inference and unknown historical reasons separately. Never fabricate historical tasks,
+prior developer decisions or reasons the code cannot establish.
+
+1. `memory.sync_start` opens a durable native confirmation bound to the mode, committed source hash
+   and previousRunId/rework behavior. Only acceptance starts the run. It snapshots the selected HEAD
+   or explicit ref, uploads every manifest page with exclusion reasons and seals the inventory.
+   Dirty worktree changes never silently enter shared memory. Repeating an occurrence reuses its key;
+   another commit requires a new occurrence and its own exact confirmation.
+2. `memory.source` pages the committed manifest or bounded chunks of one exact-commit file. Follow
+   nextCursor/nextOffset until null. Exclusions are reviewable evidence; inspect suspicious exclusions
+   and correct the classifier rather than declaring an incomplete project fully learned. Large owned
+   files remain in scope; bounded Git reads at the same commit can supplement the tool.
+3. `memory.sync_plan` creates meaningful semantic units with module keys, knowledge kinds, source
+   paths and dependency unit keys. Declare applicable architecture/state/services/network/data/UI/flow
+   areas and justify absence with source evidence. File coverage is necessary but does not certify
+   semantic understanding. Do not collapse an application into a generic all-files summary.
+4. `memory.sync_next` leases one unit for fifteen minutes. Save claimToken and use distinct requestKeys
+   for parallel workers; retry the same key after response loss. `memory.sync_status` exposes progress
+   and missing units without exposing another worker's token. No database transaction spans analysis.
+5. `memory.sync_submit` attaches per-path source or actual execution evidence and explicit findings
+   for entry, exit, authority, effects, errors, cancellation, retry, persistence and dependencies.
+   Link concrete witnesses; lack of applicability needs evidence and a reason. A source read and a
+   successful test are separate claims. Automated structural checks cannot prove the prose is true;
+   review the complete module package against actual code and tests before approval.
+6. Reuse the normal KnowledgeResource → pending Proposal → immutable Revision model. Present complete
+   module records, source evidence, uncertainty, deviations and archival actions. `memory.review_batch`
+   binds native approval to exact IDs, content hashes and base revisions, and reviews atomically under
+   existing authority. Deferring makes no change; when the user wants to reconsider, use its returned
+   nextReviewAttempt. Retrying the old attempt preserves the deferral, not an invented approval.
+7. `memory.sync_reopen` uses expectedVersion to repair an unfinished unit. `memory.sync_verify` requires
+   sealed inventory, source/removed-path and declared-area coverage, valid evidence, resolved gaps and
+   approved exact memory references. It cannot replace the Git diff gate for any source-writing task.
+
+## Incremental refresh and Git evidence
+
+Use a completed previousRunId. `memory.sync_delta` refuses an unsealed new inventory and pages changed
+units and dependent flows. With repoRoot on the first page it adds bounded Git history/rename evidence;
+`memory.source` with previousCommit and commit can read further source change pages. Commit IDs and
+source trees establish provenance; commit messages do not establish developer intent. Squash or
+rewritten/missing history falls back explicitly to the persisted file/blob comparison. A missing
+commit is not proof of zero changes.
+
+Review renames against existing resource identities and propose selector relocation rather than
+unnecessarily creating duplicate records. Removed behavior requires reviewed archival with the old
+identity; revision history is retained. Code deviating from a rule does not silently change that rule.
+Known changed memory invalidates its units/dependants. New records are compared against selectors;
+unscoped records may require conservative review because there is no defensible narrow scope.
+A source/memory no-op reuses approved evidence with provenance and creates no gratuitous revisions.
+
+At module boundaries read memory.sync_status with repoRoot. If newer commits exist, keep the pinned
+inspection unchanged and start a new `memory.sync_start` refresh occurrence with the follow-up commit
+and previousRunId; never silently move its baseline or call old coverage current. Read-only completion
+is a coverage decision, not an implementation verification. Long-running analysis must checkpoint its
+remaining units and decisions durably.
+
+The core pack is intentionally bounded. Linked contracts remain inline while they fit the budget; when
+the response reports `additionalMemory`, read the full authorized catalogue with
+`memory.catalog({projectId, includeLinked: true, afterId, limit})`, then use the current session with
+`memory.read_revisions` for the exact revision IDs needed by the task. Do not assume the core pack is
+exhaustive. `memory.catalog` is the paging surface for linked project memory; it does not grant access
+or change project links.
+
+For source orientation, prefer the bounded summary returned by `project.inspect` and its nested stack
+signals. Its `totalFiles`, `omittedFiles`, `prunedDirectories` and `historyTruncated` fields are part
+of the evidence: a nonzero omission or truncated history requires bounded follow-up, not a claim that
+the tree or history was fully read. Use the existing paged `memory.source` pages only for the committed
+paths and symbols required by the chosen unit; do not request or serialize an unbounded full tree.
+
+## Rework target and execution
+
+Complete deep learning first. Propose and approve target architecture in existing immutable knowledge;
+redesign also requires the intended screens, flows and API/service contracts. Build a dependency-ordered
+phase plan with acceptance criteria and branch names, covering every inspected unit by key. Present it
+in full. `project.rework_plan` opens a native form for that exact source/target/phase digest and persists
+real WorkItems and their dependencies; stale targets, incomplete learning or changed idempotency inputs
+must refuse before partial creation. Deferred plans can be submitted under a new explicit requestKey
+when the user requests review again.
+
+Each phase opens an ordinary implementation task on its recorded branch in a separate worktree where
+needed. Preserve all lease, history, reconciliation, self-review, validation, verify, close and delivery
+gates. Cross-project phases use existing work_item.plan/confirm_plan with explicit scope authorization
+and independent per-repository runs. Planning tasks does not perform their implementation.
+
+A deferred individual field or final profile saves no onboarding choice. Retrying that request preserves its deferral. When the user explicitly resumes, use the returned `nextRequestKey` for fresh native decisions; never infer approval from a previous defer.