engineering-memory 1.10.2 → 1.10.4

package/skill/references/questionnaires.md

@@ -1,6 +1,24 @@
 # Native Questionnaires
 
-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. Web pages are limited to sign in, sign up, initial password change, and email verification.
+Use the host's native questionnaire for every question to the user, including implementation choices, names, clarification, branch/worktree decisions and delivery. Existing answers remain valid through retries and handoffs. Web pages are limited to sign in, sign up, initial password change, and email verification.
+
+## Required decisions stay pending
+
+Use `questionnaire.ask` for a required decision. It records the question before opening a native MCP form. Use a stable question identifier belonging to the current task and decision, so a retry returns to the same question instead of creating another one. A new decision needs its own identifier; an answer to an earlier proposal, branch or delivery does not approve a later one.
+
+Pass `repoRoot`, `questionnaireId`, `message` and two to twelve `options`, each with an `id` and `label`. Identifiers use letters, digits, underscores or hyphens. Set `allowFreeText` only when the user needs to give an answer outside those options. `questionnaire.resume` takes the same `repoRoot` and `questionnaireId`. These tools collect decisions; they do not commit, publish, bind a project or perform the selected action. Apply the accepted answer through the relevant lifecycle tool, checking the current target and version first.
+
+Fixed-choice answers can be replayed from the local receipt. Free text is returned only in the accepting call and is never stored. If a later receipt says the answer is unavailable, recover it from the user's actual answer in the conversation; never reconstruct it from the options. If it cannot be recovered, explain that it must be requested again using a new question identifier.
+
+Read pending questions returned by `session.entry` and `session.resume`. Call `questionnaire.resume` for the question belonging to this work. Do not silently adopt a pending question from another task. Resuming uses the original question; do not rewrite its options under the same identifier.
+
+Only an explicit, valid accepted response answers a question. A timeout, dismissed form, empty response, invalid response, connection loss or ended turn is not an answer. These events leave the decision pending. Never substitute the recommended choice or treat silence as consent. The form's cancel or decline button dismisses the form; if abandoning the work is a meaningful decision, offer it as an explicit answer in the question.
+
+Never use request_user_input_async for a required decision: it does not wait for an answer. Do not end a turn while a required native form is still awaiting the user. Work that does not depend on the answer may continue. If the host removes the form or interrupts the tool call, retain the pending decision and resume that same question when the user returns. Do not automatically reopen dismissed forms in a loop, or use repeated sleeps to claim that a host timer has been disabled.
+
+The host owns the visible form and may impose a transport deadline or close it when the application exits. Engineering Memory preserves the decision without an expiry; it cannot promise that every host keeps a window visible indefinitely. If the host cannot display the form, report that limitation and the pending question identifier. Use a blocking native control only where the host permits it: request_user_input in Codex or AskUserQuestion in Claude. Follow the host's tool restrictions. Never fabricate an answer, silently fall back to an asynchronous question, or begin work that requires the missing decision.
+
+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. Questions and saved answers must not contain credentials, personal data or production payloads. Authentication secrets belong in the existing browser authentication flow. Use an appropriate permitted native control for information that cannot be persisted; do not put it into a durable question's title, options or stored answer.
 
 ## Authentication
 
@@ -42,7 +60,7 @@ Switching off records the decision and ends the subject. Switching back on clear
 
 Changing the organization always means asking for the project again afterwards, because a project belongs to exactly one organization and the old answer cannot survive the change. Run the organization questionnaire, then the project one, then bind the repository to the chosen project with `project.resolve` so the local binding matches what the user just said.
 
-When the repository being bound already has a working system in it — code somebody else wrote, a shape nobody here decided — say so and offer the survey rather than starting as though the project began now. Ask whether to adopt it: read what is there, record its modules, its architecture and the discovery policy that matches its actual layout, and list where it diverges from the rules with what changing and keeping each one would cost. Do not offer a single choice between reworking the project and leaving it alone; that question is asked once per divergence, after the survey, and the adoption rule says why. The survey is a read-only task and changes nothing.
+When the repository being bound already has a working system in it — code somebody else wrote, a shape nobody here decided — present the three project creation modes. Adopt and rework both begin with the exhaustive cross-stack inventory described below; rework then asks per project whether the target preserves behavior or redesigns it. Do not offer a single choice between reworking the project and leaving it alone before the evidence exists. The inventory is read-only and changes nothing.
 
 A task that is still open blocks the switch, and says so plainly. Its lease, its journal and its checkpoints all belong to the project it was opened against, and carrying them into another one records work under a project it did not happen in. Close the open task first, or abandon it with `task.abandon` once the user has said that is what they want, and only then switch. This is about this session's own task and nothing else: another person's unfinished task in the same repository never blocks anything.
 
@@ -50,11 +68,34 @@ A task that is still open blocks the switch, and says so plainly. Its lease, its
 
 Ask whether the current repository belongs to an existing accessible project, should become a new project, or should skip Engineering Memory for this task. When an existing project is chosen, present only projects returned for the authenticated user. Confirm the project selection before saving its user-local binding; no repository file is written.
 
-For a repository the backend has not seen before, ask whether this is an existing codebase import or a greenfield project. Before a local binding or backend task exists, an existing-codebase import may perform one bounded local read-only structural and Figma discovery pass. It must not edit code. Use the findings in a native questionnaire to confirm the initial project profile and the repository-relative patterns that identify new memory resources. Send them as `discoveryUnits`, one unit per kind the project actually has: a client project declares `screen_logic` and `component_mapping`, and a server-side project declares `module_logic`, `data_model` and `api_endpoint` against its own layout. Never ask a server-side project for screen patterns, and never invent a unit for a kind the repository does not contain. Then call `project.setup`; the backend creates the project, owner membership, active profile revision, and pinned discovery policy atomically. Persist the user-local binding only after that succeeds, then start the normal `session.bootstrap` lifecycle. Later discoveries are reviewable memory proposals.
-
-Greenfield setup asks for project name, framework, the response envelope, the exception model, authentication needs, localization languages, storage policy, and the initial discovery patterns. A client project is also asked for the Figma library and screen links if available, the design token sources, the page architecture and the navigation pattern; a server-side project is asked instead for the data layer, the migration tool and how configuration and secrets arrive. A Spring project must also name Maven or Gradle, its Java release, its exact Spring Boot version and its `javax` or `jakarta` namespace before any architecture template is offered; `Spring Boot` alone is not enough information to select compatible source. Record those confirmed values in `initialProjectProfile.metadata.runtimeContract` as `language: "java"`, `languageVersion`, `framework: "spring-boot"`, `frameworkVersion`, `buildTool` and `namespace`. Never infer or invent this object. The backend compares it with each source module and returns no incompatible module; an absent contract means broad Spring rules still apply but no constrained source template is offered. Ask what the project is before deciding which list applies. Do not save a binding unless the setup response contains the active initial profile and discovery policy.
-
-After setup, ask whether to build the project from the organization architecture templates. If the user accepts, follow `scaffolding.md`: confirm the optional modules, then confirm the package name and the concrete class name behind every rename placeholder in one questionnaire, then ask for each required asset role and each tenant-specific value the templates deliberately leave open.
+For a repository the backend has not seen before, ask for the project mode through a native
+questionnaire: `greenfield`, `adopt`, or `rework`. Maturity inspection is read-only evidence and may
+recommend a mode, but it never selects one. Adopt and rework perform an exhaustive cross-stack source
+inventory from committed `HEAD` by default, covering frontend pages/navigation/state/service classes/
+network layers, backend modules/services/data/API, project architecture and connecting contracts.
+The agent labels evidence, inference and unknown while the backend
+persists coverage. There is no bounded survey and no source mutation. Use `project.onboard` with the confirmed mode and profile; only greenfield calls `project.initialize`
+to prepare Git. Send repository-relative discovery units through the existing project.setup/profile
+contract, not as extra initialize fields. A client declares
+`screen_logic` and `component_mapping`; a server declares `module_logic`, `data_model` and
+`api_endpoint`. Never invent a unit the repository does not contain.
+
+Greenfield setup asks for project name, framework, runtime/toolchain contract, response envelope,
+exception model, authentication, localization, storage policy and discovery patterns. A client is
+also asked for Figma and navigation context; a server is asked for its data layer and configuration
+source. Spring still requires Maven or Gradle, Java release, exact Spring Boot version and
+`javax`/`jakarta` namespace before compatible templates are offered. Never infer these values.
+Rework asks per project whether the approved target preserves behavior or redesigns it. Existing
+project membership, active user, tenant scope, explicit code/privacy assignments and scope authority
+remain in force.
+
+After setup, greenfield asks whether to build from organization architecture templates. If accepted,
+follow `scaffolding.md`. For Flutter, the template's real SDK gate must run against the local PATH
+or configured command; missing Flutter is a red result and never triggers a download. Existing
+projects may later use `refresh`, which requires confirmed natural intent and native confirmation,
+uses committed `HEAD` by default, persists resumable units, and never triggers from keywords.
+Module-batched proposal approval binds exact hashes and source revision; incomplete or stale batches
+fail, and raw secrets, headers, customer payloads and PII are excluded.
 
 ## Project Membership
 
@@ -161,3 +202,40 @@ When installing enforcement and an existing pre-commit hook is present, offer:
 - Cancel hook installation
 
 Never overwrite or delete an unknown hook.
+
+### Exact onboarding decisions
+
+Use project.onboard/project.initialize for the four-mode choice and stack-specific profile. Their
+native forms review each independent profile field with its current value visible. Keep and explicit
+deferral are durable answers; an edit uses the bounded native text field in that same question and is
+stored in the exact profile decision. Client profiles
+include Figma, palette, typography/font families/text styles, design system, navigation, platforms and
+languages. Backend profiles include API, auth, storage, migration and environments. Empty knowledge is
+an explicit absence or deferral, never a guessed preference. project.inspect returns a maturity
+classification; it does not select a mode. Choices persist locally before Git and project-wide after
+selecting a project.
+
+memory.sync_start confirms the exact committed source and mode before starting adopt/refresh/rework.
+project.rework_plan confirms an exact approved target and phase digest after learning. memory.review_batch
+reviewAttempt distinguishes a new requested review from a retry of a previously deferred batch. Do not
+turn defer into approve or loop new attempts without the user's intent to reconsider.
+
+The initial context pack may be budgeted. If it reports `additionalMemory`, use
+`memory.catalog({projectId, includeLinked: true, afterId, limit})` to page all authorized linked
+resource headers, then call `memory.read_revisions` with the current session for the exact revisions
+needed. Never assume that the core pack contains every linked record. Source inspection should begin
+with the bounded orientation summary from `project.inspect`; use paged committed-source reads for the
+units being learned.
+
+### Explicit withdrawal and initialization continuation
+
+When the user explicitly cancels the owning work, call `questionnaire.withdraw` with its exact
+identifier and repository/preparation scope. Withdrawal is durable, creates no approval, rejects late
+answers and removes only that pending question from entry/resume. A timeout or dismissed form is not
+cancellation of the work; unanswered decisions remain pending without automatic expiry. Other tasks
+can continue independently. A withdrawn workflow needs a new request key only if the user starts it
+again.
+
+`project.onboard` can save the profile before initialization. Calling `project.initialize` with the
+same request key reuses the profile answers and asks a separate exact Git-initialization confirmation.
+Saving a profile does not authorize filesystem initialization.

package/skill/references/scaffolding.md

@@ -6,12 +6,21 @@ Architecture templates are source modules stored as approved engineering memory.
 
 Engineering rules, quality gates and architecture templates all live on the organization. A project created in a fresh organization inherits none of them.
 
-Call `organization.list` and ask the user which organization the project belongs to before `project.setup`. Creating a new organization is a separate, explicit choice: state plainly that the project will start with no engineering core and no architecture templates, and pass the acknowledgement only after the user confirms that.
+Call `organization.list` and ask the user which organization the project belongs to before
+`project.setup`. If the repository folder is missing, use `questionnaire.ask` or
+`questionnaire.resume` with `preparation: true`; `project.initialize` asks the native confirmation
+before creating the folder and Git repository. Each initialization occurrence carries a unique
+`requestKey`; retries reuse that key, while a new occurrence cannot be authorized by an old answer.
+Preparation question wording omits personal absolute paths from the stored question. Creating a new organization is a separate, explicit
+choice: state plainly that the project will start with no engineering core and no architecture
+templates, and pass the acknowledgement only after the user confirms that.
 
 ## Apply sequence
 
 1. Open the task in `scaffold` mode and complete the normal bootstrap, discovery and `context.prepare_change` steps. Prepare the full set of intended paths before the first write.
-2. Call `architecture.plan`. It returns each module's manifest in apply order with its dependencies, rename map, string replacements, pubspec dependencies, asset contract and tenant-specific points. It carries no file bodies.
+2. Call `architecture.plan`. It returns each module's manifest in apply order with its dependencies,
+   rename map, string replacements, package dependencies, asset contract and tenant-specific points.
+   It carries no file bodies.
 3. Present the optional modules through the native questionnaire. A package-shaped project usually skips the application modules; an application usually takes them.
 4. Treat the modules returned by the backend as the compatibility boundary: it compares each manifest's `compatibility` object with the approved project profile `runtimeContract` before returning it. Read both contracts back and confirm them in the questionnaire; never add a module the plan withheld or substitute a conversational guess. For Spring, the comparison covers Java release, exact Spring Boot release line, build tool and `javax` or `jakarta` namespace. If the plan is empty, say that no compatible starter exists and continue without scaffolding; never upgrade or downgrade the project to make a template fit.
 5. Confirm the naming decisions in one questionnaire: package name and the concrete class name behind every rename placeholder. Never invent a name the user did not choose.
@@ -19,7 +28,7 @@ Call `organization.list` and ask the user which organization the project belongs
 7. Merge every module's `packageDependencies` into the project's dependency manifest — `pubspec.yaml`, `package.json`, whatever the stack uses. Keep the existing constraint when a dependency already exists and report the conflict.
 8. Satisfy the `assetContract`. Ask the user for each required asset role. Never invent an asset, never ship a placeholder binary, and never copy a licensed font from another project.
 9. Resolve every `tenantSpecific` point through the questionnaire: base URLs, backend header contracts, storage key prefixes, supported locales, bundle identifiers. These are deliberately absent from the template. Do not guess them.
-10. Run the stack's generator, compiler or type checker against every emitted source file before calling the scaffold complete. If the required local compiler is unavailable or below the selected template's declared release, stop with the exact tool and version needed rather than claiming the source is valid. This refusal applies only to applying that template, not to using Engineering Memory with an existing project. Then run code generation, localization generation, static analysis and tests that the project requires.
+10. Run the stack's generator, compiler or type checker against every emitted source file before calling the scaffold complete. If the required local compiler is unavailable or below the selected template's declared release, stop with the exact tool and version needed rather than claiming the source is valid. This refusal applies only to applying that template, not to using Engineering Memory with an existing project. Then run code generation, localization generation, static analysis and tests that the project requires. The shipped Flutter gate runs the local SDK's `pub get`, `analyze --no-pub` and `test --no-pub`; it accepts `ENGINEERING_MEMORY_FLUTTER_COMMAND` for a Windows `.bat` launcher and never downloads an SDK.
 11. Reconcile each applied template resource with a `scaffold_applied` reconciliation carrying a short reason, then run `task.verify`.
 
 ## What scaffold mode does and does not relax
@@ -34,6 +43,6 @@ Write the first real unit of work — a screen, a resource — as a separate `wr
 
 When a task establishes a new shared architecture structure, or changes one the templates carry, the template is now stale. Propose the template revision through `memory.propose_revision` with `scope: organization` and `kind: architecture_template`, and let the user approve it like any other permanent memory change.
 
-A template revision must keep its manifest and its content in step: every `## file:` block has a matching `files[]` entry with the same path, byte count and SHA-256, in the same order. The backend rejects a revision whose manifest and content disagree.
+A template revision must keep its manifest and its content in step: every `## file:` block has a matching `files[]` entry with the same path, byte count and SHA-256, in the same order. The backend rejects a revision whose manifest and content disagree. Product defaults are parsed from front matter into `architecture-template/v1`: `scope` is product or organization, `stack` and `moduleKey` are lowercase slugs, `applyOrder` is an integer, `dependsOn` contains lowercase module slugs, `packageDependencies` is a valid `name@constraint` list, and every fenced file block is represented exactly once. `assetContract` and `tenantSpecific` default to empty arrays; they must not be simulated with placeholder assets or hidden template tokens. Validate defaults with the backend product-default loader/parser as well as a compiler.
 
 Templates carry source, not secrets. Never place a real base URL, token, customer payload, licensed binary or personal path in a template revision.