mikoshi-construct 0.1.3 → 0.3.0

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "mikoshi-construct",
   "type": "module",
-  "version": "0.1.3",
+  "version": "0.3.0",
   "description": "Bootstrap for AI-native software projects. Start with a proven engineering workflow instead of an empty repository.",
   "author": "Eli Tabrisov",
   "license": "MIT",
-  "homepage": "https://github.com/E1i/mikoshi-construct#readme",
+  "homepage": "https://e1i.github.io/mikoshi-construct/",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/E1i/mikoshi-construct.git"
@@ -49,23 +49,28 @@
     "tsup": "^8.5.1",
     "tsx": "^4.23.13",
     "typescript": "^5.9.3",
+    "vitepress": "2.0.0-alpha.20",
     "vitest": "^5.0.0",
     "yaml": "^2.9.1"
   },
   "scripts": {
     "build": "tsup",
+    "changeset": "changeset",
+    "ci": "pnpm run quality",
+    "composition:check": "tsx scripts/composition/check.ts",
+    "composition:render": "tsx scripts/composition/sync-docs.ts",
     "dev": "tsx src/cli.ts",
+    "docs:build": "vitepress build docs",
+    "docs:dev": "vitepress dev docs",
+    "docs:preview": "vitepress preview docs",
     "lint": "eslint .",
     "lint:fix": "eslint --fix .",
-    "typecheck": "tsc --noEmit",
+    "privacy:check": "tsx scripts/privacy/check.ts",
+    "quality": "pnpm composition:check && pnpm privacy:check && pnpm lint && pnpm typecheck && pnpm test",
+    "release": "pnpm build && changeset publish",
     "test": "vitest run",
     "test:watch": "vitest",
-    "quality": "pnpm composition:check && pnpm lint && pnpm typecheck && pnpm test",
-    "composition:render": "tsx scripts/composition/sync-docs.ts",
-    "composition:check": "tsx scripts/composition/check.ts",
-    "ci": "pnpm run quality",
-    "changeset": "changeset",
-    "version-packages": "changeset version",
-    "release": "pnpm build && changeset publish"
+    "typecheck": "tsc --noEmit",
+    "version-packages": "changeset version"
   }
 }

package/templates/ai/claude/_claude/agents/architect.md

@@ -24,15 +24,11 @@ Work through, in this order, and write nothing down until you have:
 5. The explicit constraints the implementer must respect, and the acceptance criteria that make
    the task statable.
 
-Your final message is data, not prose. Return exactly one JSON object:
+Return these fields; the runtime validates the shape against the schema it gives you.
 
-```json
-{
-  "decision": "the design in a few sentences, including what stays unchanged and why",
-  "contractChanges": "operations or schemas to add or change in the API contract, or empty",
-  "compositionChanges": "composition model nodes or edges to change, or empty",
-  "constraints": ["one constraint per entry"],
-  "acceptance": ["one verifiable criterion per entry"],
-  "files": ["files to create or change"]
-}
-```
+- `decision` — the design in a few sentences, including what stays unchanged and why.
+- `contractChanges` — operations or schemas to add or change in the API contract, empty when none.
+- `compositionChanges` — composition model nodes or edges to change, empty when none.
+- `constraints` — one constraint per entry, each one the implementer must respect.
+- `acceptance` — one verifiable criterion per entry.
+- `files` — the files to create or change.

package/templates/ai/claude/_claude/agents/harness.md

@@ -26,15 +26,11 @@ When git is usable, also inspect `git diff` (staged and unstaged) for:
 Report the security leg separately from the rest when a failure comes from a security lint rule,
 a contract security test or the secret scan, so the reader sees the invariant, not just the tool.
 
-Your final message is data, not prose. Return exactly one JSON object:
+Return these fields; the runtime validates the shape against the schema it gives you.
 
-```json
-{
-  "passed": true,
-  "failureExcerpt": "the failing command and its last relevant lines, empty when passed",
-  "securityFinding": "the invariant that failed, empty when none",
-  "diffStat": "output of git diff --stat",
-  "testsWeakened": false,
-  "contractChanged": false
-}
-```
+- `passed` — whether every harness command succeeded.
+- `failureExcerpt` — the failing command and its last relevant lines, empty when passed.
+- `securityFinding` — the invariant that failed, empty when none.
+- `diffStat` — the output of `git diff --stat`, or why git could not be used.
+- `testsWeakened` — whether a test was deleted, renamed away, skipped or narrowed.
+- `contractChanged` — whether a file under `contracts/` changed.

package/templates/ai/claude/_claude/agents/implementer.md

@@ -27,14 +27,10 @@ Constraints at this effort level:
 If the task is ambiguous about a contract, a boundary or which of two designs is meant, stop and
 report `blocked` with one precise question. Do not pick one.
 
-Your final message is data, not prose. Return exactly one JSON object:
+Return these fields; the runtime validates the shape against the schema it gives you.
 
-```json
-{
-  "status": "done | failed | blocked",
-  "summary": "one or two sentences on what changed",
-  "files": ["paths you changed"],
-  "harnessTail": "last lines of the harness output, empty when blocked",
-  "question": "the single question when blocked, otherwise empty"
-}
-```
+- `status` — `done`, `failed` or `blocked`.
+- `summary` — one or two sentences on what changed.
+- `files` — the paths you changed.
+- `harnessTail` — the last lines of the harness output, empty when blocked.
+- `question` — the single question when blocked, otherwise empty.

package/templates/ai/claude/_claude/commands/plan.md

@@ -12,6 +12,8 @@ Rules:
 - Two to six tasks. Each task is independently verifiable by the harness and leaves the tree green.
 - Each task has two to four acceptance criteria that a harness run or a test can confirm. "Works" is
   not a criterion; "GET /v1/things returns 200 with the `Thing` schema and the contract test passes" is.
+- A criterion is verified by what the task changes itself. If satisfying it needs an action outside the
+  task, it belongs to that task, not this one.
 - Order tasks so the contract and composition changes come first, then implementation, then anything
   that consumes the new behaviour.
 - Classify each task `low`, `medium` or `high` with the rules in `architecture/principles.md`

package/templates/ai/claude/_claude/skills/implement/SKILL.md

@@ -23,17 +23,52 @@ repository's CLAUDE.md and `construct.json`.
    a JSON object:
    `{ "task": ..., "acceptance": [...], "effort": "low|medium|high", "harness": { "command": ..., "extra": [...] } }`
    where `harness.command` comes from `construct.json` and `harness.extra` lists any area-specific
-   commands CLAUDE.md names for the files the task touches (usually empty).
-   The user's `/implement` invocation is the opt-in the tool requires.
+   commands CLAUDE.md names for the files the task touches (usually empty). `retryLimit` is optional
+   and defaults to `0`: a rejected response is not re-asked, and the run stops with the validator's
+   error so a person reads it. Each retry is a whole new agent call that repeats the agent's
+   exploration from scratch — measured at roughly three million billable tokens for an architect —
+   and it cannot fix a contradiction in the task, because the agent may not change the task. Raise it
+   only when a rejected response is expected to be a transient shape error rather than a bad brief.
+   The user's `/implement` invocation is the opt-in the tool requires. Note the run identifier the
+   Workflow tool reports when it launches the run and again when it completes; step 4 records it.
+   The design step runs inside the ladder, not before it, and its outcome is one of the `attempts`
+   like any other. The statuses a run can return are:
+   - `done` — a rung passed the harness and every design step the run took completed.
+   - `degraded` — a rung passed the harness, but a design step was rejected by the schema and the
+     run continued without it. The result's `effort` is the class that actually executed.
+   - `design incomplete` — a high-effort run whose architect was rejected by the schema. No
+     implementer ran without a spec; the result carries the validator's text in `validationError`.
+   - `failed` — every rung ran and the harness stayed red; `lastFailure` carries the excerpt.
+   - `blocked` — the last rung stopped on a question; `question` carries it verbatim.
 4. Record the run: append one JSON line to `.construct/runs.jsonl` (create the directory if needed)
-   with `at` (ISO time), `task` (first 120 characters), `effort` (the class you chose), `status`,
-   the rung that finished (`effort` from the result), `attempts` from the result, and the Workflow
-   tool's own accounting for the run — `agents`, `tokens`, `toolUses`, `seconds` — exactly as it
-   reported them. This log is what tunes the ladder later; workflow scripts have no filesystem
-   access, so it is written here, not by the script. `.construct/` is gitignored.
+   with exactly these fields and no others:
+   - `run` — the Workflow run identifier from step 3. It is the key `construct cost` joins the entry
+     to the runtime's session data on. Never invent one: an entry without it is reported as
+     unjoinable, which is the truth about it.
+   - `at` — the ISO timestamp.
+   - `task` — the task text, first 120 characters.
+   - `effort` — the class the run performed: the result's `effort` when it carries one, and only
+     then the class you chose in step 1. A run whose design step did not complete is never written
+     down as `high`; the result has already degraded it.
+   - `status` — the result's status verbatim, one of the five in step 3.
+   - `rung` — the effort of the rung that finished: `effort` from the result when it carries one,
+     otherwise the `effort` of the last entry in `attempts`.
+   - `attempts` — the result's `attempts` array verbatim; each entry carries its `rung`, `effort`,
+     `outcome` and the `reason` that separates an invalid response shape from a red harness, from a
+     blocked report and from a design the schema rejected.
+   - `agents`, `tokens`, `toolUses`, `seconds` — the Workflow tool's own accounting for the run,
+     exactly as it reported it. Write `"unknown"` for a token figure it did not report, never `0`.
+   The ledger carries counts and reasons only — never a prompt, a response or any other message
+   content. This log is what tunes the ladder later; workflow scripts have no filesystem access, so
+   it is written here, not by the script. Nothing enforces this step: the ledger is L0, and
+   `construct cost` reconciles it against the runtime instead of trusting it. `.construct/` is
+   gitignored.
 5. Relay the result: status, the effort rung that succeeded and how many attempts it took, the
    files changed, and the harness tail. When the status is `blocked`, put the architect's or
-   implementer's question to the user verbatim. When `failed`, give the last failure excerpt.
+   implementer's question to the user verbatim. When `failed`, give the last failure excerpt. When
+   `design incomplete`, say that the design step did not complete and give `validationError` as the
+   runtime reported it; when `degraded`, say which design step was rejected and that the reported
+   class is the one that executed, not the one that was requested.
    Unless `construct.json` sets `report.usage` to `false`, end with one usage line for this run,
    from the Workflow tool's own accounting: agents, subagent tokens, tool uses, wall time — so the
    cost of the rung that succeeded is on record next to the result. When `construct` is on the PATH,

package/templates/ai/claude/scripts/construct/implement.workflow.mjs

@@ -2,7 +2,7 @@ export const meta = {
   name: 'implement',
   description: 'Implement a task at low effort, verify with the harness, escalate on repeated failure or ambiguity',
   phases: [
-    { title: 'Design', detail: 'architect, only for high effort or after a blocked or failed attempt' },
+    { title: 'Design', detail: 'architect inside the run, for high effort before the first rung and after a blocked or failed attempt' },
     { title: 'Implement', detail: 'implementer at the current rung' },
     { title: 'Verify', detail: 'harness against the working tree' },
   ],
@@ -52,10 +52,48 @@ const SPEC = {
   },
 }
 
+const DEFAULT_RETRY_LIMIT = 0
+const DESIGN_EFFORT = 'xhigh'
+const EFFORT_WITHOUT_DESIGN = { high: 'medium', xhigh: 'medium' }
+
 const task = args.task
 const acceptance = args.acceptance ?? []
 const harness = { command: 'pnpm run quality', extra: [], ...(args.harness ?? {}) }
 const rungs = LADDERS[args.effort] ?? LADDERS.low
+const retryLimit = Number.isInteger(args.retryLimit) && args.retryLimit >= 0 ? args.retryLimit : DEFAULT_RETRY_LIMIT
+
+let lastValidationError = null
+
+function retryPrompt(prompt, validationError) {
+  return `${prompt}\n\nThe previous response did not match the shape the runtime validates. The validator reported:\n${validationError}\n\nReturn the same fields again with that corrected.`
+}
+
+async function askOnce(prompt, options) {
+  try {
+    const value = await agent(prompt, options)
+    return value == null
+      ? { value: null, validationError: 'the agent returned no object the schema could validate' }
+      : { value, validationError: null }
+  }
+  catch (error) {
+    return { value: null, validationError: String(error?.message ?? error) }
+  }
+}
+
+async function ask(prompt, options) {
+  let validationError = null
+  for (let attempt = 0; attempt <= retryLimit; attempt++) {
+    const answer = await askOnce(validationError == null ? prompt : retryPrompt(prompt, validationError), options)
+    if (answer.value != null) {
+      lastValidationError = null
+      return answer.value
+    }
+    validationError = answer.validationError
+    log(`${options.label}: response rejected by the schema — ${validationError}`)
+  }
+  lastValidationError = validationError
+  return null
+}
 
 function harnessPrompt() {
   return [
@@ -89,25 +127,61 @@ function implementerPrompt(spec, feedback) {
 
 let spec = null
 let feedback = null
+let designComplete = false
+let designFailed = false
+let designError = ''
 const attempts = []
 
+function performedEffort(effort) {
+  return designComplete ? effort : (EFFORT_WITHOUT_DESIGN[effort] ?? effort)
+}
 
-if (args.effort === 'high') {
+async function design(rung, reason, label) {
   phase('Design')
-  spec = await agent(architectPrompt('The task is classified as high effort; design it before any implementation.'), {
+  const result = await ask(architectPrompt(reason), {
     agentType: 'architect',
-    effort: 'xhigh',
+    effort: DESIGN_EFFORT,
     phase: 'Design',
-    label: 'design',
+    label,
     schema: SPEC,
   })
+  if (result == null) {
+    designComplete = false
+    designFailed = true
+    designError = lastValidationError ?? ''
+    attempts.push({ rung, effort: DESIGN_EFFORT, outcome: 'design schema invalid', reason: designError })
+    log(`${label}: the design step did not complete`)
+    return false
+  }
+  spec = result
+  designComplete = true
+  attempts.push({ rung, effort: DESIGN_EFFORT, outcome: 'designed', reason: '' })
+  return true
+}
+
+function designIncomplete(effort, question) {
+  return {
+    status: 'design incomplete',
+    effort: performedEffort(effort),
+    attempts,
+    validationError: designError,
+    question: question ?? '',
+    lastFailure: feedback ?? '',
+  }
 }
 
 for (const [index, effort] of rungs.entries()) {
   const rung = index + 1
+
+  if (rung === 1 && args.effort === 'high') {
+    const designed = await design(rung, 'The task is classified as high effort; design it before any implementation.', 'design')
+    if (!designed)
+      return designIncomplete(effort)
+  }
+
   phase('Implement')
   log(`rung ${rung}/${rungs.length} @ ${effort}: implementing`)
-  const report = await agent(implementerPrompt(spec, feedback), {
+  const report = await ask(implementerPrompt(spec, feedback), {
     agentType: 'implementer',
     effort,
     phase: 'Implement',
@@ -115,29 +189,25 @@ for (const [index, effort] of rungs.entries()) {
     schema: REPORT,
   })
   if (report == null) {
-    attempts.push({ rung, effort, outcome: 'no report' })
+    attempts.push({ rung, effort, outcome: 'schema invalid', reason: lastValidationError })
     continue
   }
 
   if (report.status === 'blocked') {
-    attempts.push({ rung, effort, outcome: 'blocked', question: report.question })
+    attempts.push({ rung, effort, outcome: 'blocked', reason: report.question, question: report.question })
     if (rung === rungs.length)
       return { status: 'blocked', question: report.question, attempts }
-    spec = await agent(architectPrompt(`The implementer stopped on this question:\n${report.question}`), {
-      agentType: 'architect',
-      effort: 'xhigh',
-      phase: 'Design',
-      label: `design after blocked ${rung}`,
-      schema: SPEC,
-    })
+    const designed = await design(rung, `The implementer stopped on this question:\n${report.question}`, `design after blocked ${rung}`)
+    if (!designed && args.effort === 'high')
+      return designIncomplete(effort, report.question)
     feedback = null
-    log(`rung ${rung}/${rungs.length} @ ${effort}: blocked, architect answered`)
+    log(`rung ${rung}/${rungs.length} @ ${effort}: blocked, architect ${designed ? 'answered' : 'did not answer'}`)
     continue
   }
 
   phase('Verify')
   log(`rung ${rung}/${rungs.length} @ ${effort}: running ${harness.command}`)
-  const verdict = await agent(harnessPrompt(), {
+  const verdict = await ask(harnessPrompt(), {
     agentType: 'harness',
     effort: 'low',
     phase: 'Verify',
@@ -145,13 +215,21 @@ for (const [index, effort] of rungs.entries()) {
     schema: VERDICT,
   })
   const passed = verdict?.passed === true && verdict.testsWeakened === false
-  attempts.push({ rung, effort, outcome: passed ? 'passed' : 'failed', securityFinding: verdict?.securityFinding ?? '' })
+  attempts.push(verdict == null
+    ? { rung, effort, outcome: 'schema invalid', reason: lastValidationError, securityFinding: '' }
+    : {
+        rung,
+        effort,
+        outcome: passed ? 'passed' : 'harness failed',
+        reason: passed ? '' : (verdict.testsWeakened ? 'a test was deleted, skipped or narrowed' : verdict.failureExcerpt),
+        securityFinding: verdict.securityFinding ?? '',
+      })
   log(`rung ${rung} @ ${effort}: ${passed ? 'harness passed' : 'harness failed'}`)
 
   if (passed) {
     return {
-      status: 'done',
-      effort,
+      status: designFailed && !designComplete ? 'degraded' : 'done',
+      effort: performedEffort(effort),
       attempts,
       files: report.files,
       summary: report.summary,
@@ -162,7 +240,7 @@ for (const [index, effort] of rungs.entries()) {
   }
 
   feedback = verdict == null
-    ? 'The harness produced no verdict.'
+    ? `The harness produced no verdict the schema could validate: ${lastValidationError}`
     : verdict.testsWeakened
       ? `A test was deleted, skipped or narrowed. Restore it and make the implementation pass it.\n${verdict.failureExcerpt}`
       : verdict.failureExcerpt
@@ -170,16 +248,11 @@ for (const [index, effort] of rungs.entries()) {
     feedback = `Security invariant failed: ${verdict.securityFinding}\n${feedback}`
 
   if (rung === rungs.length - 1) {
-    phase('Design')
     log(`rung ${rung}/${rungs.length} failed twice: architect redesigns before the last rung`)
-    spec = await agent(architectPrompt(`Two rungs have failed the harness. Latest failure:\n${feedback}\n\nDecide whether the approach, the contract or the boundary is wrong before the last attempt.`), {
-      agentType: 'architect',
-      effort: 'xhigh',
-      phase: 'Design',
-      label: 'design before last rung',
-      schema: SPEC,
-    })
+    const designed = await design(rung, `Two rungs have failed the harness. Latest failure:\n${feedback}\n\nDecide whether the approach, the contract or the boundary is wrong before the last attempt.`, 'design before last rung')
+    if (!designed && args.effort === 'high')
+      return designIncomplete(effort)
   }
 }
 
-return { status: 'failed', attempts, lastFailure: feedback }
+return { status: 'failed', attempts, lastFailure: feedback, effort: performedEffort(rungs[rungs.length - 1]) }

package/templates/ai/cursor/_cursor/rules/construct.mdc

@@ -11,7 +11,7 @@ areas, defects vs accepted variance), `architecture/security-invariants.md`.
 The harness command is in `construct.json` (`harness.command`). A change is done only when it passes.
 API changes start from the contract file named in `construct.json` (`contracts.path`); regenerate the
 types with `pnpm contracts:types` before implementing. Composition models in the directory
-`construct.json` names as `discovery.composition` are the source of the diagrams; edit the model and run
+`construct.json` names as `discovery.markers.composition.file` are the source of the diagrams; edit the model and run
 `pnpm composition:render`, never the rendered block.
 
 Discovery: when asked to "run construct discovery", follow the `construct-discover` rule in this

package/templates/ai/shared/_claude/commands/construct-discover.md

@@ -9,8 +9,8 @@ not verify by reading code; where the codebase is inconsistent, record an open q
 inventing a rule.
 
 Scope: `$ARGUMENTS` (empty means every marker). The markers, and the file each one lives in, are
-listed under `discovery` in `construct.json` (the text markers in `AGENTS.md`, the composition models
-in the directory `discovery.composition` names). Every marker is a block between
+listed under `discovery.markers` in `construct.json` (the text markers in `AGENTS.md`, the composition
+models in the directory `discovery.markers.composition.file` names). Every marker is a block between
 `<!-- construct:discover:<name> -->` and `<!-- /construct:discover:<name> -->`; replace the placeholder
 line inside the block and nothing outside it. `construct doctor` reports any marker still holding the
 placeholder.
@@ -37,7 +37,9 @@ Work in this order:
 2. **Inventory.** Read `construct.json`, `package.json`, the directory tree two levels deep, the entry
    points (servers, app factories, `main.ts`, CLI scripts, workers), the API contract if there is
    one, and every `*.config.ts` / `config.ts`. Note the package manager, runtime, database and clients, CI, deployment
-   and existing conventions. Do not write yet.
+   and existing conventions. Do not write yet. Record the commit this run starts from: set
+   `discovery.baseSha` in `construct.json` to the output of `git rev-parse HEAD`, or `null` where the
+   repository has no commit yet.
 3. **`product`** (AGENTS.md): what the system does, in one paragraph, and the one flow where a
    defect costs the most (money, identity, data). If the repository is empty apart from the baseline,
    say so in one line.
@@ -54,7 +56,7 @@ Work in this order:
 8. **`high-effort-areas`** (AGENTS.md): the paths where a wrong low-effort guess is expensive —
    attribution, authentication, money, schema, anything a shipped client depends on. This list is what
    `/implement` uses to classify a task as `high`.
-9. **`composition`** (`<discovery.composition>/*.yaml` from `construct.json`): one model per real flow the code has today
+9. **`composition`** (`<discovery.markers.composition.file>/*.yaml` from `construct.json`): one model per real flow the code has today
    (the HTTP app, a worker, a sync, a CLI, the browser bootstrap) — small, one per flow, every `path`
    must exist. A baseline model, when the construct shipped one, is updated, not duplicated; a
    repository that had code before the construct starts with no model and needs at least one for its
@@ -71,5 +73,24 @@ Work in this order:
     `npx mikoshi-construct doctor` when the CLI is not installed; it names every marker that still
     holds the placeholder.
 
+13. **Record what you wrote, in the manifest and nowhere else.** Provenance belongs in
+    `construct.json`; never add a byline, an authorship note or a hash to a marker body. Set
+    `discovery.filledAt` to the time you finished, and for each marker you filled set
+    `discovery.markers.<name>` to `{"file": "<the file it lives in>", "authoredBy": "construct",
+    "sha": "<sha256 of the body you wrote>"}`. A marker you did not fill keeps the entry it had.
+    The body is the text between `<!-- construct:discover:<name> -->` and
+    `<!-- /construct:discover:<name> -->` with leading and trailing whitespace stripped; for
+    `composition` it is every `*.yaml` in the directory, sorted by name, each as its filename, a
+    newline and its contents, joined by newlines. Compute it, never estimate it:
+
+    ```bash
+    node -e 'const{createHash}=require("node:crypto"),{readFileSync}=require("node:fs");const[f,m]=process.argv.slice(1);const d=readFileSync(f,"utf8"),o=`<!-- construct:discover:${m} -->`,c=`<!-- /construct:discover:${m} -->`;console.log(createHash("sha256").update(d.slice(d.indexOf(o)+o.length,d.indexOf(c)).trim()).digest("hex"))' AGENTS.md product
+    node -e 'const{createHash}=require("node:crypto"),{readFileSync,readdirSync}=require("node:fs"),p=require("node:path");const d=process.argv[1],b=readdirSync(d).filter(n=>n.endsWith(".yaml")).sort().map(n=>`${n}\n${readFileSync(p.join(d,n),"utf8")}`).join("\n");console.log(createHash("sha256").update(b).digest("hex"))' architecture/composition
+    ```
+
+    This is what keeps a statement the tool wrote from later reading as one the repository stands
+    behind. The moment the owner edits a marker its body stops matching the recorded sha and
+    `construct doctor` reads it as theirs — the edit is the evidence, and there is no command to run.
+
 Report: which markers you filled, which you left as open questions and why, and the harness result.
 Do not commit.

package/templates/base/architecture/decisions/README.md

@@ -0,0 +1,26 @@
+# Decisions
+
+One file per decision that shapes what this project is allowed to claim. A decision lands here when
+reversing it would cost more than making it did, or when a later reader would otherwise re-open it
+from scratch. Read this directory before re-opening a question it already answers, and add a record
+rather than restating a decision in a plan or a commit message.
+
+Each record carries four sections: the context it was taken in, the decision itself, the
+consequences it accepts, and how it is enforced.
+
+Enforcement is named on a scale, so the strength of a decision is visible rather than implied:
+
+| Level | Enforced by |
+|---|---|
+| L0 | text only — nothing checks it |
+| L1 | review — a human is the check |
+| L2 | a local hook — bypassable with `--no-verify` |
+| L3 | CI — it runs on every push |
+| L4 | CI that blocks the merge |
+
+A decision enforced only by review says so; that is the honest answer, not a gap to hide.
+
+Records are named `NNNN-a-short-title.md` and numbered in the order they were taken.
+
+| # | Decision | Enforced at |
+|---|---|---|

package/templates/base/architecture/principles.md

@@ -68,7 +68,9 @@ isolated and manageable — and to treat accidental complexity as a defect.
   reconsider the decomposition, coupling or abstraction instead of pushing through.
 
 The checklists that turn these principles into questions to answer before a change are in
-[checklists.md](checklists.md).
+[checklists.md](checklists.md). A decision that shapes what this project may claim is recorded once in
+[decisions/](decisions/README.md), with the level at which it is enforced, instead of being restated in
+a plan or a commit message.
 
 ## Security
 

package/templates/presets/monorepo/baseline/eslint.config.mjs.eta

@@ -4,11 +4,27 @@ const WORKSPACE_PACKAGES = {{workspacePackages}}
 
 const ALLOWED_WORKSPACE_IMPORTS = {{allowedWorkspaceImports}}
 
-const PROCESS_ENV = 'MemberExpression[object.name="process"][property.name="env"]'
+const PROCESS_ENV_MEMBER = 'MemberExpression[object.name="process"][property.name="env"]'
+const PROCESS_ENV_VIA_GLOBAL_THIS = 'MemberExpression[object.object.name="globalThis"][object.property.name="process"][property.name="env"]'
+const PROCESS_ENV_DESTRUCTURED = 'VariableDeclarator[init.name="process"] > ObjectPattern > Property[key.name="env"]'
+const PROCESS_ENV = `:matches(${PROCESS_ENV_MEMBER}, ${PROCESS_ENV_VIA_GLOBAL_THIS}, ${PROCESS_ENV_DESTRUCTURED})`
+
 const PROCESS_MEMBER = 'MemberExpression[object.name="process"]'
-const RAW_REQUEST_DATA = 'MemberExpression[object.name="req"][property.name=/^(body|query|params)$/]'
-const RAW_SQL = 'CallExpression[callee.object.name="sql"][callee.property.name="raw"]'
-const SHARED_IMPORT = ':matches(ImportDeclaration, ExportNamedDeclaration, ExportAllDeclaration)[source.value=/^{{scope}}\\/shared(\\/|$)/]'
+const PROCESS_VIA_GLOBAL_THIS = 'MemberExpression[object.name="globalThis"]:matches([property.name="process"], [property.value="process"])'
+const PROCESS_BINDING = 'VariableDeclarator[init.name="process"]'
+const PROCESS = `:matches(${PROCESS_MEMBER}, ${PROCESS_VIA_GLOBAL_THIS}, ${PROCESS_BINDING})`
+
+const RAW_REQUEST_MEMBER = 'MemberExpression[object.name="req"][property.name=/^(body|query|params)$/]'
+const RAW_REQUEST_DESTRUCTURED = 'VariableDeclarator[init.name="req"] > ObjectPattern > Property[key.name=/^(body|query|params)$/]'
+const RAW_REQUEST_ALIASED = 'VariableDeclarator[id.type="Identifier"][init.name="req"]'
+const RAW_REQUEST_DATA = `:matches(${RAW_REQUEST_MEMBER}, ${RAW_REQUEST_DESTRUCTURED}, ${RAW_REQUEST_ALIASED})`
+
+const RAW_SQL = 'MemberExpression[object.name="sql"]:matches([property.name="raw"], [property.value="raw"])'
+
+const SHARED_SPECIFIER = '/^{{scope}}\\/shared(\\/|$)/'
+const SHARED_IMPORT = `:matches(ImportDeclaration, ExportNamedDeclaration, ExportAllDeclaration, ImportExpression)[source.value=${SHARED_SPECIFIER}]`
+const SHARED_REQUIRE = `CallExpression[callee.name="require"][arguments.0.value=${SHARED_SPECIFIER}]`
+const SHARED_MODULE = `:matches(${SHARED_IMPORT}, ${SHARED_REQUIRE})`
 
 function dependencyBoundary([directory, allowed]) {
   const forbidden = WORKSPACE_PACKAGES.filter(name => !allowed.includes(name))
@@ -32,7 +48,7 @@ const dependencyBoundaries = Object.entries(ALLOWED_WORKSPACE_IMPORTS)
   .map(dependencyBoundary)
 
 const NO_PROCESS_OUTSIDE_CONFIG = {
-  selector: PROCESS_MEMBER,
+  selector: PROCESS,
   message: 'An app touches process only in config.ts: read configuration through readConfig() and pass the value on',
 }
 const NO_PROCESS_ENV_IN_PACKAGE = {
@@ -48,7 +64,7 @@ const NO_RAW_SQL = {
   message: 'SQL is never built from raw strings: interpolate tables and columns into the sql template instead of sql.raw',
 }
 const NO_SHARED_OUTSIDE_CONTRACTS = {
-  selector: SHARED_IMPORT,
+  selector: SHARED_MODULE,
   message: 'Contract types enter an app only through src/contracts/types.ts: import them from there',
 }