engineering-memory 0.1.0

package/runtime/package-lock.json

@@ -0,0 +1,137 @@
+{
+  "name": "engineering-memory-mcp-bridge",
+  "version": "0.1.0",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "engineering-memory-mcp-bridge",
+      "version": "0.1.0",
+      "license": "UNLICENSED",
+      "dependencies": {
+        "@modelcontextprotocol/server": "2.0.0",
+        "minimatch": "10.2.6",
+        "zod": "4.4.3"
+      },
+      "bin": {
+        "engineering-memory-bridge": "dist/src/index.js",
+        "engineering-memory-git-gate": "dist/src/git/pre-commit.js"
+      },
+      "devDependencies": {
+        "@types/node": "24.3.0",
+        "prettier": "3.6.2",
+        "typescript": "5.9.2"
+      },
+      "engines": {
+        "node": ">=20"
+      }
+    },
+    "node_modules/@modelcontextprotocol/core": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/@modelcontextprotocol/core/-/core-2.0.0.tgz",
+      "integrity": "sha512-pJCEwGG7Lfr/+PQp9ZTwKXNeO5wzbfKL7H3MYpCorM4oFBoQrdjnBgEoqG+RjhsvS1FKrDbKux+M1HhlnGWqcA==",
+      "dependencies": {
+        "zod": "^4.2.0"
+      },
+      "engines": {
+        "node": ">=20"
+      }
+    },
+    "node_modules/@modelcontextprotocol/server": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/@modelcontextprotocol/server/-/server-2.0.0.tgz",
+      "integrity": "sha512-YhHWdHfpFMQfd0prsEnxKeS3Qz3ytIGmsS0sth4KDjnacIT7hxk6hXHkJ9KysxlkvTM+WZAtQbbcUhdoP4Hvtw==",
+      "dependencies": {
+        "@modelcontextprotocol/core": "2.0.0",
+        "zod": "^4.2.0"
+      },
+      "engines": {
+        "node": ">=20"
+      }
+    },
+    "node_modules/@types/node": {
+      "version": "24.3.0",
+      "resolved": "https://registry.npmjs.org/@types/node/-/node-24.3.0.tgz",
+      "integrity": "sha512-aPTXCrfwnDLj4VvXrm+UUCQjNEvJgNA8s5F1cvwQU+3KNltTOkBm1j30uNLyqqPNe7gE3KFzImYoZEfLhp4Yow==",
+      "dev": true,
+      "dependencies": {
+        "undici-types": "~7.10.0"
+      }
+    },
+    "node_modules/balanced-match": {
+      "version": "4.0.4",
+      "resolved": "https://registry.npmjs.org/balanced-match/-/balanced-match-4.0.4.tgz",
+      "integrity": "sha512-BLrgEcRTwX2o6gGxGOCNyMvGSp35YofuYzw9h1IMTRmKqttAZZVU67bdb9Pr2vUHA8+j3i2tJfjO6C6+4myGTA==",
+      "engines": {
+        "node": "18 || 20 || >=22"
+      }
+    },
+    "node_modules/brace-expansion": {
+      "version": "5.0.9",
+      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-5.0.9.tgz",
+      "integrity": "sha512-ScQ4IuvIEF1TMlP7Zt+vjJ//9zlPb2SDcxWxM3bk8s6t6GGdJ7KO1dCcTidOPJKePW30LE/2cT7wCyPho9/Wxg==",
+      "dependencies": {
+        "balanced-match": "^4.0.2"
+      },
+      "engines": {
+        "node": "20 || >=22"
+      }
+    },
+    "node_modules/minimatch": {
+      "version": "10.2.6",
+      "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-10.2.6.tgz",
+      "integrity": "sha512-vpLQEs+VLCr1nU0BXS07maYoFwlDAH0gngQuuttxIwutDFEMHq2blX+8vpgxDdK3J1PwjCJiep77OitTZ4Ll1A==",
+      "dependencies": {
+        "brace-expansion": "^5.0.8"
+      },
+      "engines": {
+        "node": "18 || 20 || >=22"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/isaacs"
+      }
+    },
+    "node_modules/prettier": {
+      "version": "3.6.2",
+      "resolved": "https://registry.npmjs.org/prettier/-/prettier-3.6.2.tgz",
+      "integrity": "sha512-I7AIg5boAr5R0FFtJ6rCfD+LFsWHp81dolrFD8S79U9tb8Az2nGrJncnMSnys+bpQJfRUzqs9hnA81OAA3hCuQ==",
+      "dev": true,
+      "bin": {
+        "prettier": "bin/prettier.cjs"
+      },
+      "engines": {
+        "node": ">=14"
+      },
+      "funding": {
+        "url": "https://github.com/prettier/prettier?sponsor=1"
+      }
+    },
+    "node_modules/typescript": {
+      "version": "5.9.2",
+      "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.9.2.tgz",
+      "integrity": "sha512-CWBzXQrc/qOkhidw1OzBTQuYRbfyxDXJMVJ1XNwUHGROVmuaeiEm3OslpZ1RV96d7SKKjZKrSJu3+t/xlw3R9A==",
+      "dev": true,
+      "bin": {
+        "tsc": "bin/tsc",
+        "tsserver": "bin/tsserver"
+      },
+      "engines": {
+        "node": ">=14.17"
+      }
+    },
+    "node_modules/undici-types": {
+      "version": "7.10.0",
+      "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-7.10.0.tgz",
+      "integrity": "sha512-t5Fy/nfn+14LuOc2KNYg75vZqClpAiqscVvMygNnlsHBFpSXdJaYtXMcdNLpl/Qvc3P2cB3s6lOV51nqsFq4ag==",
+      "dev": true
+    },
+    "node_modules/zod": {
+      "version": "4.4.3",
+      "resolved": "https://registry.npmjs.org/zod/-/zod-4.4.3.tgz",
+      "integrity": "sha512-ytENFjIJFl2UwYglde2jchW2Hwm4GJFLDiSXWdTrJQBIN9Fcyp7n4DhxJEiWNAJMV1/BqWfW/kkg71UDcHJyTQ==",
+      "funding": {
+        "url": "https://github.com/sponsors/colinhacks"
+      }
+    }
+  }
+}

package/runtime/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "engineering-memory-mcp-bridge",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "license": "UNLICENSED",
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "engineering-memory-bridge": "dist/src/index.js",
+    "engineering-memory-git-gate": "dist/src/git/pre-commit.js"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "format": "prettier --write \"src/**/*.ts\" \"test/**/*.ts\" \"*.json\"",
+    "format:check": "prettier --check \"src/**/*.ts\" \"test/**/*.ts\" \"*.json\"",
+    "start": "node dist/src/index.js",
+    "git-gate": "node dist/src/git/pre-commit.js",
+    "test": "npm run build && node --test dist/test"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/server": "2.0.0",
+    "minimatch": "10.2.6",
+    "zod": "4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "24.3.0",
+    "prettier": "3.6.2",
+    "typescript": "5.9.2"
+  }
+}

package/skill/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: engineering-memory
+description: Enforces the Engineering Memory lifecycle for Codex and Claude in repositories bound by .engineering-memory/project.json. Use for every planning, implementation, review, diagnosis, rework, Figma, component, screen, service, model, navigation, localization, storage, validation, or Git task in a bound repository.
+---
+
+# Engineering Memory
+
+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.
+
+Mandatory behavior:
+
+1. Locate `.engineering-memory/project.json` from the working directory toward the repository root.
+2. Before planning or editing, call `session.bootstrap`. After compaction, a new chat, interruption, or handoff, call `session.resume` first.
+3. Open the task in `read_only` mode for review, diagnosis, planning, or reporting that does not authorize writes; use `scaffold` mode only to apply organization architecture templates to a new project; otherwise use `write` mode. Do read-only discovery, then record the discovery checkpoint.
+4. For a write task, call `context.prepare_change` with the intended paths and record the pre-edit checkpoint before the first edit. Do not edit paths outside the active lease. A read-only task must not acquire a change lease unless the user expands the task to writing and the bridge performs the explicit mode transition.
+5. Use the returned context pack as the engineering authority for the task. Use `memory.query` only for targeted missing context, and `memory.history` to read why the records you are changing became what they are before you design against them.
+6. Record phase, correction, validation, and handoff checkpoints at the required moments. Declare the task's discretionary decisions on the validation-before checkpoint, and when a task repeats a shape, have the first unit reviewed before writing the rest.
+7. For a write task, reconcile every changed screen and component. Propose revisions when semantics changed; otherwise record an explicit no-semantic-memory-change reconciliation.
+8. Before validation, read the changed code back against the rules that govern it and record `task.self_review`. Verification refuses without a review of the current diff, and any later edit requires reviewing again.
+9. Run `task.verify` before claiming completion. Write tasks verify the exact Git diff, active lease, and structured command-bound validation evidence. Read-only tasks verify that the current Git diff hash still equals the baseline captured at bootstrap, plus the required discovery, validation, handoff, pinned-context, and synchronization evidence. Run `task.close` only after verification succeeds. The pre-commit gate must confirm the closed task online; a local verification receipt is insufficient.
+10. After closing a task, ask the delivery question every time — commit, commit and push, or either of those with a draft or ready pull request onto a base branch the user names — and do only what they choose. Once a pull request exists, check whether it merges cleanly and ask before resolving a conflict.
+11. Never commit, push, publish, deploy, approve a permanent memory revision, or overwrite an existing Git hook without explicit user authorization.
+12. Never store tokens, passwords, client secrets, raw headers, raw payloads, customer data, or PII in tool inputs, journals, memory, logs, or generated documentation.
+
+If the repository is unbound, do not silently create or attach a project. Use the native questionnaire workflow. If the user selects task-only skip, do not create a marker or memory records.
+
+If the backend is unavailable, use only an unexpired bridge-provided cached context. Checkpoints may enter the local outbox, but verification, task close, and commit remain blocked until synchronization succeeds.

package/skill/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Engineering Memory"
+  short_description: "Zorunlu proje hafızası ve doğrulama akışı"
+  default_prompt: "Use $engineering-memory to execute this task through the required Engineering Memory lifecycle."
+policy:
+  allow_implicit_invocation: true

package/skill/references/lifecycle.md

@@ -0,0 +1,102 @@
+# Mandatory Lifecycle
+
+## Entry
+
+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.
+
+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.
+
+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.
+
+## Discovery
+
+Perform only read operations until the relevant current code, tests, Figma evidence, Git diff, and returned memory have been inspected.
+
+Read the history of what you are about to change. `context.prepare_change` returns a `history` header for every matched record: how many revisions it has, how many earlier tasks touched it, and the most recent of those tasks. That header is a signpost, not the content — where it shows earlier work, call `memory.history` for those paths or record keys and read what came back: each revision with the task that produced it and the reason given, the earlier tasks with their objectives and how many corrections each of them took, and the task references found in the Git history of those paths.
+
+This is what makes the difference between changing code and understanding it. A screen is the shape it is because of decisions someone made and corrections someone took; changing it without reading them repeats work that was already done and undoes fixes that were already paid for. Verification refuses while a record with earlier work on it was never read, because that omission is invisible in the result until someone hits the same problem again.
+
+### A task that names a flow
+
+A request can be as short as "add the KYC flow from Figma". That is enough, and it is not a licence to guess. Work it out:
+
+1. The Figma address arrives in the core pack as the `figma_reference` record. Never ask where the design lives; read it. If the user names a different file, that is a correction to that record — propose the revision and ask for approval in the same reply, so the next session already knows.
+2. Ask for existing flows with `memory.query` naming the `flow_logic` kind. If the flow is already recorded, read it and its history before touching anything.
+3. Read the flow in Figma: which frames belong to it, the order its prototype links imply, and the node id of every screen. A file-level link is orientation, not evidence.
+4. Read what surrounds it — the screen records the flow starts from and returns to, the navigation contract, the trackers that already exist — and pull `memory.history` wherever the header shows earlier work or a run of corrections.
+5. Decide the entry point, the order, whether a tracker is needed and exactly what it carries, and where the flow ends.
+6. Ask the user what neither Figma nor memory can answer. Where a flow is entered from and what abandoning it halfway does are almost never in the design. Never invent them, and never invent the content of a document the flow displays.
+
+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.
+
+Do not pull history for everything. Pull it for the records the task actually touches, and for anything the header shows a surprising number of corrections on. Record `task.checkpoint` with type `discovery` and update STATE, DECISIONS, DISCOVERY, and HANDOFF projections through the bridge.
+
+Do not write task Markdown files directly. The bridge owns event IDs, expected task versions, atomic projections, outbox state, and synchronization.
+
+## Change Preparation
+
+Skip change preparation for a read-only task. Do not request an edit lease, send changed paths, record `pre_edit`, or reconcile code resources in that mode. If the user later authorizes a change, call `context.prepare_change` with `transitionToWrite: true`, the bridge-owned current task version, intended paths, and current baseline diff. Continue only after the bridge returns the updated write task and lease.
+
+Keep the path set narrow. A lease covering most of the repository returns more knowledge than one response can carry, and the resources that do not fit come back as `deferredResources` instead of content. Every deferred resource is still required: read it with `memory.query` before touching the path it governs, because verification checks the read receipt and will fail without it. Prefer several small leases over one wide one.
+
+For a write task, list the precise relative paths likely to change and call `context.prepare_change`. It must return a change lease and read receipts for every matched required resource. Read the full returned screen, component, service, navigation, localization, storage, or state record before editing its matched path.
+
+Record the `pre_edit` checkpoint after the context pack has been read and before the first mutation. If the path set expands, prepare a new lease before touching the additional path.
+
+## Implementation
+
+Apply the task request, approved decisions, returned engineering rules, backend/API contract, exact Figma evidence, current public API, and current code in that authority order. Keep changes scoped. Do not rewrite an existing component merely to simplify implementation.
+
+Within the returned rules, a requirement that leaves a receipt never outranks one that does not. Tests, generated files, and passing checks are easy to satisfy at the expense of readable code, and that trade is always the wrong way round. When a checkable requirement can only be met by making the code harder to read, or by opening a constructor parameter, interface, injected default, or return value in production code so a test can reach it, the readable code wins and the conflict is stated in the next checkpoint instead of being resolved silently.
+
+When the task repeats a shape across several units — screens, components, endpoints, migrations — build the first one completely, record a `phase_transition` naming it as the reviewable unit, and put it in front of the user before writing the rest. A structural decision replicated across ten units costs ten times as much to undo as the one that is still alone.
+
+Record `phase_transition` whenever work moves between meaningful phases. A phase transition is not needed for every small edit.
+
+## Correction
+
+When the user reports a bug, bad pattern, or architectural correction, call `task.record_correction` immediately before continuing. Fix the active task within scope.
+
+Record it with a `correctionRef` you can reuse, and ask where it belongs **in the same reply**. Recording a correction without a scope leaves the decision open, and `task.verify` refuses to run until every open decision is answered — so a correction that is fixed but never routed cannot reach completion. Send the user's answer with `task.record_correction` again, carrying the same `correctionRef` and the chosen scope.
+
+Then classify the correction before offering anywhere to put it. Ask whether the cause is specific to this project's code, conventions, or design, or whether it is a failure any team using this product would hit. State the classification and the evidence that supports it, because the classification decides which scopes are on the table.
+
+A project-specific correction is offered as task-only or permanent for this project. A product-general correction must additionally offer the organization engineering core and the product defaults that ship to every customer, and the user chooses; never route a product-general correction into a single project silently. Use the native questionnaire described in `questionnaires.md`.
+
+## Validation and Reconciliation
+
+## Self Review
+
+Before validation, read the changed code back against the rules that govern it. Not from memory: reread the returned records for the paths that changed, including anything the context pack deferred, and read the diff as the next person to open the file would. The restraint document is the first thing to hold it against.
+
+Record `task.self_review` naming the resources reviewed and, for every conflict found, the file, the rule, what was wrong and what was done about it. A review that found nothing records an empty finding list, which is a claim about the work rather than a formality.
+
+`task.verify` refuses without a self review of the current diff. Editing after the review invalidates it, which is the point: the last thing that happens to the code is that someone read it against the rules. This exists because a task once shipped code that broke rules it had been given — the rules were present and correct, and nothing in the lifecycle ever asked whether the result matched them.
+
+The review is the agent's own job at the end of the work. Do not wait to be asked for it, and do not treat a passing test suite as a substitute: tests leave a receipt and readability does not, which is exactly why the unreviewed one is the one that degrades.
+
+Before validation begins, declare the discretion the task used. Send it as `decisions` document lines on the `validation_before` checkpoint: every name introduced — class, file, interface, enum, parameter, folder — each with one line on why the code reads better with it than without it; every assumption made where the request did not specify; and every question that could have been asked and was not. Anything that cannot be justified in one line is removed before validation runs. The list is a receipt for the decisions that otherwise leave none, and it is what makes them reviewable by the user.
+
+Record `validation_before`, run proportionate format, generation, static analysis, tests, security scans, and design checks, then record `validation_after` with command results and hashes. Each `task.verify` validation entry must contain the backend validation ID, the exact command, a successful result, and the SHA-256 hash of its sanitized output. Never invent a validation result or reuse a placeholder hash.
+
+Available validation IDs are `format`, `static_analysis`, `tests`, `build`, `codegen`, `localization`, `ui`, `network`, `structure`, `diff_check`, `privacy_scan`, `dependency_audit`, `deploy_smoke`, and `read_only_integrity`. Use the exact set returned by the bridge or required by the changed paths. A handwritten-code task cannot substitute a generic command for analysis or tests. Dependency manifests, lockfiles, build configuration, and deployment configuration require their additional audit or smoke evidence. Read-only tasks require repository-integrity and privacy evidence without a change lease.
+
+For each changed screen or component, call `task.reconcile` with an approved proposal ID or a reasoned `no_semantic_memory_change` result. In a scaffold task, reconcile each applied template resource with a reasoned `scaffold_applied` result instead; files that still match their recorded scaffold hash need no per-file proposal, and every other changed path follows the normal rules. New screens and components require a memory proposal. Changed project contracts, service contracts, Figma mappings, or engineering rules require the corresponding proposal when their semantics changed.
+
+Record `handoff_before`, then call `task.verify`. For a write task, verify the exact changed paths, current diff hash, validations, session, and lease. For a read-only task, send no changed paths, lease, or write baseline; the bridge supplies the current Git diff hash and the backend compares it with the baseline captured at bootstrap while also verifying bootstrap, discovery, validation-before, validation-after, handoff, pinned read receipts, and synchronized outbox evidence. If verification fails, resolve the reported gap and verify again. Do not state that the task is complete while verification is failing, and do not carry on writing code with the failure unaddressed — a task that never verifies never closes, and everything that depends on closing, including the commit gate, silently never happens.
+
+A new screen or component fails verification until its memory exists, which takes four steps in order: `memory.propose_revision` for each new path, the user's explicit approval, `memory.review_proposal`, then `task.reconcile`. The error names the paths. Walk the chain rather than retrying the same verification.
+
+Call `task.close` only after verification and only when the current diff still matches. The Git hook performs a fresh authenticated commit-gate check against the closed task, current membership, repository fingerprint, diff hash, and knowledge revisions. A local receipt alone never authorizes commit. Closing a task does not authorize commit, push, publish, deploy, tag, or merge.
+
+Closing is not the end of the turn either. `task.close` returns the delivery question, and it is asked every time: commit, commit and push, commit and push with a draft pull request, or commit and push with a pull request. The two pull request options take the base branch from the user. Do exactly the one chosen and nothing more.
+
+When a pull request has been opened, keep going: check whether it merges cleanly, report the result with the link, and if it conflicts, name the files and ask whether to resolve them. Never end the turn on a pull request whose mergeability was never checked, and never resolve a conflict without being told to.
+
+## Offline Behavior
+
+An unexpired cached context pack may be used for implementation. The bridge records checkpoints in its outbox. Permanent proposal review, strict verification, task close, and Git commit remain blocked until the backend is reachable and the outbox is synchronized.

package/skill/references/memory-updates.md

@@ -0,0 +1,25 @@
+# Memory Updates
+
+Backend resources are immutable revisions. The local agent drafts structured content, evidence, selectors, affected areas, and regression evidence; the backend validates, stores, versions, and enforces access without running a model.
+
+Use `memory.propose_revision` for project profiles, engineering rules, service contracts, localization contracts, navigation contracts, state contracts, screen logic, component mappings, Figma mappings, current deviations, quality gates, task history, and architecture templates.
+
+Knowledge is layered. `scope: product` proposes a change to the shared engineering core that every organization reads, `scope: organization` proposes one that only this organization reads and which hides the product text for that key, and `scope: project` proposes a record for this project alone. The nearest layer wins when context is delivered. A product-scope proposal is the way a developer improves the product itself from inside their own project, and it requires nothing but the skill.
+
+An architecture template is organization-scoped source, not prose. When a task establishes or changes a shared architecture structure that the templates carry, the template is stale and needs its own revision. Its manifest and content must stay in step: one `files[]` entry per `## file:` block, same path, byte count, SHA-256 and order. See `scaffolding.md`.
+
+Every proposal must include the current `baseRevision`. A conflict means the resource changed after context pinning. Do not overwrite it. Refresh context, compare revisions, and ask the user when the merge changes intent.
+
+Permanent proposals remain inactive until an authorized user explicitly approves them. Call `memory.review_proposal` only after receiving that decision through the native questionnaire.
+
+A proposal created in an earlier session, or created by a bundle import, is found with `memory.list_proposals`. It reports every proposal still waiting for review that this project or its organization can reach, with the reason, the current and base revision numbers, and whether the proposal now needs a rebase. Pass a single `proposalId` to read that proposal's proposed text before putting the decision to the user. Never present a decision the user cannot see the content of, and never approve on the strength of the summary alone. Approval makes the current context lease stale. Call `context.refresh`, reread the changed rule, prepare a new change lease, and rerun affected validation.
+
+A flow record is canonical in the same way a screen record is, and covers what no single screen knows: what the flow is for, every entry point with the screen or route it starts from, the ordered steps each naming its screen record and the Figma node it came from, the tracker that owns it and exactly what data that tracker carries or one sentence on why no tracker is needed, the branch points and what decides them, where the flow returns when it finishes, what happens when the user abandons it halfway, and the questions still open.
+
+A `figma_reference` record is JSON, not prose: the current file key, the file URL that names it, and the root node ids. It is the single address of the design, so a moved or replaced Figma file is a revision of this record rather than a new fact in someone's chat. Approving that revision updates the project's stored Figma configuration in the same transaction, and every later session reads the new address from its core pack without being told.
+
+Screen logic is canonical in the backend. A screen revision should cover purpose, route, entry point, inputs, outputs, viewmodel observables, actions and computed values, tracker and global state, services and business codes, loading, empty and error behavior, Figma frames and components, localization keys, navigation, tests, constraints, selectors, and evidence.
+
+Component mappings should cover the Flutter symbol and path, public API, purpose, states, design tokens, responsive behavior, Figma file and exact node IDs, assets, usage guidance, tests, selectors, and evidence. Mark missing or partial Figma evidence instead of inventing node IDs.
+
+Do not send full source trees, generated files, vendor assets, raw diffs, credentials, or user data as memory content. Prefer relative paths, symbols, hashes, contract summaries, exact approved Figma identifiers, and bounded task-specific evidence.

package/skill/references/questionnaires.md

@@ -0,0 +1,98 @@
+# 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.
+
+## Authentication
+
+When no Engineering Memory session exists, ask whether to sign in, create an account, or skip Engineering Memory for this task. Explain that skip is permitted only for an unbound repository. After sign in or sign up is selected, let the bridge open the browser authentication flow. Never ask for a password in the native questionnaire or chat. If a browser link is expired, rejected, already used, or otherwise unusable, call `auth.signin_browser` with `restart: true` and present only the newly returned URL.
+
+## Organization
+
+Call `organization.list` and ask which organization to work under. List the ones the user already belongs to first, in the order the call returns them, and put **create a new organization** last. Never pick one on their behalf, not even when there is only one — the answer decides where everything the task produces is written.
+
+Creating one asks for two things in the same questionnaire: the organization's name as people write it, and its short identifier. The identifier is the user's to type, not yours to derive: `Limesoft A.Ş.` may well be `limesoft_io`, and guessing it wrong leaves a name nobody recognises in every later listing. It is lowercase letters, digits, underscores and hyphens, it must be unique, and it does not change afterwards, so say that before asking. Then call `organization.create` with both, and continue under the organization it returns; the creator is its owner.
+
+A new organization is not empty. It reads the product engineering core immediately and holds its own revisions only where it later decides to differ.
+
+## Project
+
+Once the organization is chosen, call `project.list` and offer that organization's projects, with **create a new project** last. Ignore projects belonging to other organizations; a listing that mixes them is how work lands in the wrong place. Creating one follows the unbound-repository flow below.
+
+Ask both questions again whenever a chat starts in a repository whose binding you have not confirmed in this session.
+
+## Switching Organization or Project
+
+The user may say mid-chat that they want to change organization or project, in those words or any others that mean it. Take it as an instruction rather than a remark, and act on it.
+
+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.
+
+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 say explicitly that it is being abandoned, and only then switch.
+
+## 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.
+
+For a new backend project, 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 `screenPathPatterns` and `componentPathPatterns` that identify new memory resources. 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.
+
+Greenfield setup asks for project name, framework, Figma library and screen links if available, design token sources, page architecture, backend response envelope, exception model, authentication needs, localization languages, storage policy, navigation pattern, and the initial screen and component path patterns. Never invent missing answers. Do not write a marker 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.
+
+## Project Membership
+
+Ask for the registered email and intended role. Show owner, maintainer, member, and reader effects. Confirm before calling `project.member_add`.
+
+## 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.
+
+## Flow Entry and Exit
+
+Before proposing a flow record, ask the user what the design cannot answer: which screen or route the flow is entered from, and what happens when the user abandons it halfway. Offer the entry points the design and the existing navigation actually allow rather than free text, and say which one you would pick and why. Never guess these — a flow entered from the wrong place is rewritten, not adjusted.
+
+## Figma Address
+
+When the user names a different Figma file or link, treat it as a correction to the `figma_reference` record and propose the revision in the same reply, with the new file key and URL. Ask for approval there and then. Do not carry the new address only in the conversation: the next session reads the record, not the chat.
+
+## Correction Scope
+
+At a natural checkpoint after recording and fixing a user correction, first state how the correction was classified and why, then offer the scopes that classification allows.
+
+A correction specific to this project's code, conventions, or design offers:
+
+- Only this task
+- Permanent for this project
+
+A correction that any team using this product would hit offers those two and also:
+
+- Permanent for the organization engineering core
+- Permanent in the product layer, which every organization reads
+
+Ask this in the same reply that delivers the fix, every time, including corrections to the agent's own mistakes. Do not wait to be reminded and do not batch the question to the end of the task: a fix that is never routed anywhere is repeated in the next session, which means the correction was never really made.
+
+Offer the product option whenever the classification supports it, and say plainly that it changes the shared engineering core every organization reads, because that is a wider decision than an organization revision. It is raised with `memory.propose_revision` at `scope: product` and needs no access to the product's own repository. Never choose between organization and product on the user's behalf.
+
+For any permanent option, show the old rule, proposed rule, reason, affected areas, and regression evidence. Create a proposal but do not approve it until the user explicitly confirms the proposal review.
+
+## Delivery
+
+After `task.close`, and every time, ask the user what to do with the finished work. Nothing has been committed at this point and nothing may be until they answer. Offer exactly these:
+
+- Commit
+- Commit and push
+- Commit, push and open a **draft** pull request
+- Commit, push and open a pull request
+
+The two pull request options take the base branch the pull request targets, typed by the user; the head is the branch the task was done on. Never guess a base branch, and never open a pull request that was not asked for.
+
+Once a pull request exists the work is not finished and the turn does not end there. Check whether it merges cleanly. If it does, say so with the link. If it does not, name the conflicting files and ask whether to resolve them — then wait. Resolving a conflict is a change to someone else's work and needs its own yes.
+
+## Git Hook
+
+When installing enforcement and an existing pre-commit hook is present, offer:
+
+- Chain the existing hook and Engineering Memory verify
+- Keep the existing hook and install verify as a separate command
+- Cancel hook installation
+
+Never overwrite or delete an unknown hook.

package/skill/references/scaffolding.md

@@ -0,0 +1,38 @@
+# Greenfield Scaffolding
+
+Architecture templates are organization-scoped source modules stored as approved engineering memory. A greenfield project reproduces the team architecture from those modules instead of re-deriving it from prose rules. The backend stores, versions and authorizes them; it never generates code. The agent applies the rename map and writes every file itself.
+
+## Organization first
+
+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.
+
+## 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.
+3. Present the optional modules through the native questionnaire. A package-shaped project usually skips the application modules; an application usually takes them.
+4. 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.
+5. For each module in `applyOrder`, call `architecture.module`, apply the rename map and string replacements, write the files, then call `architecture.record_application` with the template path and the written path of every file. Respect `dependsOn`; do not reorder modules.
+6. Merge every module's `pubspecDependencies` into the manifest file. Keep the existing constraint when a dependency already exists and report the conflict.
+7. 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.
+8. 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.
+9. Run code generation and localization generation, then static analysis and tests. Record the validation checkpoints as usual.
+10. 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
+
+Verification exempts a scaffolded file only while its working-tree hash still equals the hash recorded at `architecture.record_application`. That is why a whole module can close with one reconciliation instead of one memory proposal per file: the files came out of approved memory already.
+
+Nothing else is relaxed. A file you edit after scaffolding no longer matches its recorded hash and falls back to the normal screen and component memory rules. A file the template never declared is never exempt. A scaffold task that recorded no applied module fails verification, so scaffold mode cannot be used to skip memory obligations on ordinary work.
+
+Write the first real screen as a separate `write` task. Do not extend the scaffold task to cover feature work.
+
+## Keeping templates current
+
+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.
+
+Templates carry source, not secrets. Never place a real base URL, token, customer payload, licensed binary or personal path in a template revision.