engineering-memory 1.8.0 → 1.10.0

package/skill/references/lifecycle.md

@@ -4,15 +4,17 @@
 
 Sign-in decides nothing beyond who the user is. The organization and the project are chosen after it, through the questionnaires in `questionnaires.md`, and both listings end with an option to create a new one. Ask for both whenever this session has not already confirmed them, and ask again the moment the user says they want to change either — changing the organization always means choosing the project again.
 
-Treat `.engineering-memory/project.json` as the binding authority. The marker contains only `projectId` and `schemaVersion`. Never infer a binding from a directory name or Git remote when a marker exists. Schema 1 markers retain the legacy commit-aware repository identity so existing bindings keep working. Schema 2 markers use the canonical remote or main-worktree identity, which stays unchanged when an unborn repository receives its first commit. Never rewrite or upgrade a marker by hand.
+Use the binding returned by `session.entry` as the authority. The bridge stores the selected project and repository identity under `~/.engineering-memory/origins/<api-hash>/project-bindings/`, outside the installed runtime and working tree. It imports a legacy `.engineering-memory/project.json` once, preserving its schema and exact backend fingerprint for existing tasks and receipts. It leaves that file unchanged; after migration the file is optional and may be removed through the repository's normal Git workflow. New bindings never create it. Never infer a selection from a directory or remote, and never edit binding records by hand. Separate clones or a changed remote require a new explicit selection; worktrees of the same checkout share the local binding.
 
 An archived project is recoverable state, not a missing or conflicting binding. When an owner receives `project.restore`, use the `projectId` and `expectedVersion` in its data and call that operation before retrying. A non-owner receives `project.member_list` instead: list the members, identify a project owner and explain that the owner must restore the exact project before this session can retry. Use `project.list` with `includeArchived: true` when an owner must first select the archived project. Never create or bind a replacement project to escape archive state.
 
 For a bound repository, call `session.bootstrap` before producing a plan or changing files. Supply the current repository root, project ID, task ID or stable local task slug, objective, task kind, task mode, and current Git diff hash. Use `read_only` for review, diagnosis, planning, or reporting without write authority; use `scaffold` when the task applies organization architecture templates to a new project; use `write` when the request authorizes repository changes. The bridge records the read-only Git diff hash as the immutable task baseline, including a pre-existing dirty worktree. Use the returned task ID, task version, context session ID, pinned revisions, project profile, engineering rules, prior task documents, quality gates, and current deviations.
 
-Before the first edit of a write task, settle the branch. Ask the user through the native questionnaire whether to open a branch for this task and which name to use, offering the convention the returned rules carry. Do this once, at the start, not at commit time — the commit gate runs long after the work is written, and by then the wrong branch has already cost something. A read-only task never creates a branch.
+Every new write or scaffold task settles its branch through the native questionnaire before it opens, including when HEAD is already on a feature branch. Offer a task branch or an explicit choice to stay on the current branch. Call `task.branch` with the exact `externalTaskId` and either `name` or `keepCurrent`, then call `session.bootstrap` in its returned `repoRoot`. An existing branch name checks it out. Creating a branch remains optional; recording the user's choice does not. A read-only task needs no branch decision, but `context.prepare_change` with `transitionToWrite` requires one before editing.
 
-Two tasks in one repository need two branches, and one working tree can only have one checked out. A second checkout is what `git worktree` is for: `git worktree add ../<repo>-<task> -b <branch>` gives the task its own directory and its own branch against the same repository, and the chat for that task runs there. Engineering Memory treats them as one project — the fingerprint comes from the repository, not the directory — while each task measures only what changed in its own tree. Offer this when a task starts in a repository that already has a live task, and never ask somebody to switch branches in a tree another task is using.
+The choice belongs to that task and worktree, survives retry and client restart, and cannot be consumed by a different task. Reuse an existing answer rather than asking again. A named branch stays fixed through prepare, verify, close and commit; closing never replaces it. Return with `task.branch` using the same task slug and recorded branch when a gate reports a mismatch. Legacy tasks without a recorded branch and tasks explicitly kept on detached HEAD remain compatible; they are not restricted to a named branch. Older clients remain supported during the minimum-version compatibility window.
+
+Parallel development needs separate working directories. If another task owns the current worktree, offer a separate worktree through the questionnaire. Call `task.branch` with `externalTaskId`, `name`, and `worktreePath`; run bootstrap and all subsequent file, test and Git commands in its returned `repoRoot`. This creates or reuses an appropriate Git worktree and uses the same user-local binding and repository identity without writing a project marker. Never switch another task's working directory. Reservations are shared by clients using the same worktree; close or abandon releases that task's reservation. An interrupted close can release it through resume.
 
 A repository holds as many tasks as the people working in it. Never treat somebody else's unfinished task as a reason this one cannot proceed: no task waits on another task's review, reconciliation, verification or close, and nothing that is already verified or closed is undone by what happens elsewhere. When `session.resume` reports more than one live task for this repository, it lists them and the right move is to ask the user which one this is, never to guess and never to adopt the one that happens to be most recent.
 
@@ -41,22 +43,21 @@ A request can be as short as "add the KYC flow from Figma". That is enough, and
 
 Then propose the `flow_logic` record and stop. The plan is not a message in the chat; it is the proposal, and the user approving it is the approval. Do not write the second screen before that approval exists — a flow's shape replicated across six screens costs six times as much to undo, and verification refuses a task that adds several screens without an approved flow record reconciled to it.
 
-### Work that spans both sides of a product
+### Work that spans multiple projects
+
+Before implementation, load `work_item.plan` for the selected requirement and inspect current and authorized linked API/flow contracts. Decide whether backend, web, mobile or several projects need changes, even if the user mentioned only one interface. Fullstack covers every development area but never grants project membership or permission to expand scope.
+
+If another project needs changes beyond the requested scope, explain the concrete missing behavior and use the native questionnaire to ask whether to include it. Do not use a chat instruction or invent approval. An explicit instruction already authorizing both sides is sufficient; reuse it. Call `work_item.confirm_plan` only with that approved scope, the common branch and a short reason. Resume an existing plan rather than asking again. An unavailable project needs administrator coordination; do not infer or bind its repository.
+
+One WorkItem UUID coordinates independent EngineeringTask runs, one per selected repository. Use the recorded branch name (for example `task/kan-101`) in each repository, and a separate worktree for each concurrent task. `task.branch` with the exact externalTaskId records the existing user choice and creates or adopts the branch in a suitable worktree. Use its returned repoRoot for subsequent tools and file commands. Never switch another task's reserved worktree.
+
+Open each side with the same workItemId and its own repository binding when work reaches that side. Each side has its own lease, reconciliation, verify, close and commit gate. Check `work_item.runs` and sibling checkpoints when handing off; one side completing does not prove all selected projects are complete. A plan's scope and branch cannot change while an implementation run is active. Read-only analysis does not acquire application write rights; its later write transition must satisfy discipline and the confirmed plan.
 
-When the request covers both halves of a linked product — a flow that needs endpoints as well
-as screens — and the user's discipline covers both, it is one work item and two tasks: one in
-each repository. Verification and the commit gate stay per repository because a commit is.
+### Administration, product management and QA
 
-Ask which side to start on and select the work item before opening the first task. When the work
-moves to the other side, open its task with the same `workItemId` and that repository's root —
-every tool takes `repoRoot`, and both stay open at once. The backend accepts that id only from the
-current project or a directly linked project the account can work in, and derives the display key
-from the work item. `context.prepare_change` then returns `siblingTasks`: the other task's
-objective, status and recent checkpoints, so a decision taken on one side is visible on the other
-without anyone repeating it. A legacy key is never an authorization boundary; key-only tasks can
-see siblings only inside directly linked projects where the account is already a member.
+Administrative authority and work discipline are independent. Organization admins can manage projects, assignments, repository URLs and work items in their organization. A global admin has those rights only in organizations they actively belong to. Ordinary users need a live explicit project assignment. Fullstack/backend/web/mobile/frontend disciplines govern implementation, while project overrides do not grant administration.
 
-Do not open the second task speculatively. Open it when the work actually reaches that side.
+An assigned product manager can create, edit, assign, archive and restore work items through the work_item tools. Designer work includes design context and requirement participation; it does not grant general application code leases. A tester can create an unassigned bug and record `work_item.record_test` evidence, then track it with `work_item.test_results`. QA evidence must contain no credentials, PII or production payloads and must identify the exact requirement version. A passed result never silently marks the requirement done. Organization administration separately permits backlog management regardless of discipline.
 
 ### A task that reports a defect
 

package/skill/references/questionnaires.md

@@ -1,6 +1,6 @@
 # Native Questionnaires
 
-Use Codex or Claude native question controls. Do not open a custom survey web page. 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. 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.
 
 ## Authentication
 
@@ -40,7 +40,7 @@ The user may say mid-chat that they want to change organization or project, swit
 
 Switching off records the decision and ends the subject. Switching back on clears it and runs the organization and project questions again.
 
-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 marker matches what the user just said.
+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.
 
@@ -48,11 +48,11 @@ A task that is still open blocks the switch, and says so plainly. Its lease, its
 
 ## Unbound Repository
 
-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 before writing the marker.
+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 marker 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. Write the returned marker only after that succeeds, then start the normal `session.bootstrap` lifecycle. Later discoveries are reviewable memory proposals.
+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 write a marker unless the setup response contains the active initial profile and discovery policy.
+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.
 
@@ -62,7 +62,7 @@ Ask for the registered email and intended role. Show owner, maintainer, member,
 
 ## Branch
 
-At the start of a write task, before the first edit, ask whether to open a branch for it and confirm the name. Offer the convention the returned engineering rules state, the current branch as the alternative, and let the user name something else. Never create a branch during read-only analysis, and never create one without asking. When the repository already has another live task, add a third option — a separate worktree for this one — and say what it means: its own directory, its own branch, the same project, and the other task's tree left alone.
+Ask once for every new write or scaffold task, on any branch, and before a read-only task transitions to writing. Offer a new or existing task branch, or explicitly continuing on the current branch; use the naming convention from the returned rules. When another task owns the worktree, offer a separate directory and branch for parallel work. Pass the exact `externalTaskId` and either `name` or `keepCurrent` to `task.branch`; for a separate worktree also supply `worktreePath`. Continue in the returned `repoRoot`. Retries and handoffs reuse the stored choice. Read-only analysis does not create a branch or consume another task's answer.
 
 ## Flow Entry and Exit