mikoshi-construct 0.1.0

package/templates/ai/shared/AGENTS.md.eta

@@ -0,0 +1,123 @@
+# {{projectName}}
+
+Context for coding agents and automated reviewers working on {{projectName}}. This repository runs on a
+construct materialized by `mikoshi-construct` v{{constructVersion}}: architecture policy in
+[architecture/](architecture/), a harness that proves every change, and the rules that apply to all
+code in [architecture/principles.md](architecture/principles.md). What follows is what is specific to
+this repository. Sections marked "not discovered yet" are filled by construct discovery
+(`/construct-discover` in Claude Code, "run construct discovery" in Cursor), then kept current by
+whoever changes the thing they describe.
+
+## What this product does
+
+<!-- construct:discover:product -->
+_Not discovered yet — run `/construct-discover`._
+<!-- /construct:discover:product -->
+
+## Module map
+
+<!-- construct:discover:module-map -->
+_Not discovered yet — run `/construct-discover`._
+<!-- /construct:discover:module-map -->
+
+## Commands
+
+```bash
+pnpm dev             # run the service locally
+pnpm run quality     # the harness: contract + composition checks, lint, typecheck, tests — the CI gate and the agent gate
+{{#if contracts}}
+pnpm contracts:types # regenerate {{contractTypesOutput}} after editing the API contract
+{{/if}}
+pnpm composition:render # regenerate architecture diagrams after editing a composition model
+pnpm lint:fix        # ESLint with --fix; ESLint is the only formatter
+```
+
+Use `pnpm run quality` / `pnpm run ci` — bare `pnpm ci` is a pnpm install builtin, not this script.
+
+<!-- construct:discover:commands -->
+_Not discovered yet — run `/construct-discover`._
+<!-- /construct:discover:commands -->
+
+## Harness
+
+`{{harnessCommand}}` is the gate for any change. A change is not done until it passes; a pass is
+reported by the harness, never by the implementer. Security invariants and the check that enforces
+each one: [architecture/security-invariants.md](architecture/security-invariants.md).
+
+{{#if contracts}}
+## Contract
+
+[{{contractPath}}]({{contractPath}}) is the HTTP contract. The service validates requests against it,
+consumers read the types generated into [{{contractTypesOutput}}]({{contractTypesOutput}}), and
+`oasdiff` flags breaking changes on pull requests. An API change edits the contract first, runs
+`pnpm contracts:types`, then implements.
+
+{{/if}}
+## Architecture
+
+The principles in [architecture/principles.md](architecture/principles.md) apply; this is how they map
+here.
+
+- *Composition roots.*
+  <!-- construct:discover:composition-roots -->
+  _Not discovered yet — run `/construct-discover`._
+  <!-- /construct:discover:composition-roots -->
+- *Dependency policy.*
+  <!-- construct:discover:dependency-policy -->
+  _Not discovered yet — run `/construct-discover`._
+  <!-- /construct:discover:dependency-policy -->
+- *Composition models* and their rendered diagrams: [{{compositionDir}}/]({{compositionDir}}/).
+
+## Reasoning budget
+
+High-effort areas — a task that touches one of these is classified `high` and designed before it is
+implemented (see `/implement`):
+
+<!-- construct:discover:high-effort-areas -->
+_Not discovered yet — run `/construct-discover`._
+<!-- /construct:discover:high-effort-areas -->
+
+{{#if contracts}}
+Always high, whatever discovery finds: [{{contractPath}}]({{contractPath}}),
+`{{compositionDir}}/`, `eslint.config.mjs`, and every row of
+[architecture/security-invariants.md](architecture/security-invariants.md).
+{{/if}}
+{{#unless contracts}}
+Always high, whatever discovery finds: `{{compositionDir}}/`, `eslint.config.mjs`, and every
+row of [architecture/security-invariants.md](architecture/security-invariants.md).
+{{/unless}}
+
+## Conventions the harness does not enforce
+
+No comments in source (functional pragmas such as `eslint-disable*` and `@ts-expect-error` are
+compiler input and are never removed). `async`/`await` over promise chains where the enclosing context
+can be async. Tests live in `tests/**` as `*.test.ts`, never beside the source, and every new or
+changed logic module ships its test in the same change. ESLint is the only formatter.
+
+## Real defects vs accepted variance
+
+Treat as real defects:
+
+- A new or changed logic module with no test file.
+- A response shape that drifts from the API contract, or a breaking change to a `/v1` endpoint that
+  was not identified deliberately.
+- A secret, API key or connection string written into any file. Config references the environment.
+- Any row of [architecture/security-invariants.md](architecture/security-invariants.md) that a change
+  weakens.
+
+<!-- construct:discover:defects-vs-variance -->
+_Not discovered yet — run `/construct-discover`._
+<!-- /construct:discover:defects-vs-variance -->
+
+Treat as accepted variance and do not report: formatting, quoting and import order (ESLint owns
+them); the `.js` suffix on relative TypeScript imports (NodeNext ESM requires it); the absence of
+comments or JSDoc.
+
+## Open questions
+
+These look like conventions but the codebase is not consistent about them. Confirm before treating
+them as rules.
+
+<!-- construct:discover:open-questions -->
+_Not discovered yet — run `/construct-discover`._
+<!-- /construct:discover:open-questions -->

package/templates/ai/shared/AGENTS.md.existing.eta

@@ -0,0 +1,50 @@
+## Construct
+
+This repository runs on a construct materialized by `mikoshi-construct` v{{constructVersion}}:
+architecture policy in [architecture/](architecture/), a harness (`{{harnessCommand}}`) that proves
+every change, and the rules that apply to all code in
+[architecture/principles.md](architecture/principles.md). The blocks below are filled by construct
+discovery (`/construct-discover` in Claude Code, "run construct discovery" in Cursor). Where this
+document, or another one in the repository, already covers a block, discovery records a pointer to it
+rather than a copy — one source of truth per concern.
+
+Product and the flow where a defect costs the most:
+<!-- construct:discover:product -->
+_Not discovered yet — run `/construct-discover`._
+<!-- /construct:discover:product -->
+
+Module map:
+<!-- construct:discover:module-map -->
+_Not discovered yet — run `/construct-discover`._
+<!-- /construct:discover:module-map -->
+
+Commands beyond the harness (`{{harnessCommand}}`):
+<!-- construct:discover:commands -->
+_Not discovered yet — run `/construct-discover`._
+<!-- /construct:discover:commands -->
+
+Composition roots:
+<!-- construct:discover:composition-roots -->
+_Not discovered yet — run `/construct-discover`._
+<!-- /construct:discover:composition-roots -->
+
+Dependency policy, and where lint enforces it:
+<!-- construct:discover:dependency-policy -->
+_Not discovered yet — run `/construct-discover`._
+<!-- /construct:discover:dependency-policy -->
+
+High-effort areas — a task touching one is classified `high` and designed before it is implemented
+(always high: the API contract, `{{compositionDir}}/`, the lint policy, every security invariant):
+<!-- construct:discover:high-effort-areas -->
+_Not discovered yet — run `/construct-discover`._
+<!-- /construct:discover:high-effort-areas -->
+
+Real defects vs accepted variance, beyond what this document already lists:
+<!-- construct:discover:defects-vs-variance -->
+_Not discovered yet — run `/construct-discover`._
+<!-- /construct:discover:defects-vs-variance -->
+
+Open questions — things that look like conventions but are not applied consistently:
+<!-- construct:discover:open-questions -->
+_Not discovered yet — run `/construct-discover`._
+<!-- /construct:discover:open-questions -->

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

@@ -0,0 +1,75 @@
+---
+description: Discover this repository and fill the construct's discovery markers — the step that turns a materialized baseline into a project-specific workflow.
+argument-hint: [area to (re)discover, or empty for everything]
+---
+
+You are running construct discovery. The CLI detected facts (`construct.json`); your job is to
+interpret the system and record what an agent must know to work here safely. Write nothing you did
+not verify by reading code; where the codebase is inconsistent, record an open question instead of
+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
+`<!-- 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.
+
+Two rules for a repository that already documents itself:
+
+- **One source of truth.** If a block's content already exists elsewhere — a module map in
+  `README.md`, review standards in `best_practices.md`, invariants a PR reviewer reads — the marker
+  body is a pointer to that place (path and heading), not a copy. Do not duplicate, and do not merge
+  the existing document into the construct's files unless the user asks.
+- **Move nothing.** Existing composition models, docs and scripts stay where they are; `construct.json`
+  already records where the models live. If a construct file links to a path that differs from the
+  real one, say so in the report instead of renaming directories.
+
+Work in this order:
+
+1. **Wire the harness.** In a repository that existed before the construct, `init` kept the
+   existing `eslint.config.mjs`, `tsconfig.json`, `vitest.config.ts` and `quality` script. Before
+   anything else make them cover what the construct added: ESLint ignores
+   `scripts/construct/*.workflow.mjs` (top-level `return`), TypeScript includes `scripts/**/*.ts`,
+   Vitest includes `scripts/tests/**/*.test.ts`, and the harness command runs `composition:check`
+   (and `contracts:check` when a contract exists). Then run the harness; it must be green before
+   discovery starts. Skip this step when the construct created those files itself.
+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.
+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.
+4. **`module-map`** (AGENTS.md): a table `Path | Purpose` of the top-level modules that exist. Only
+   what exists.
+5. **`commands`** (AGENTS.md): dev, build, test and operational scripts from `package.json` that the
+   baseline block above does not already list, one line each. Remove the placeholder if there are none.
+6. **`composition-roots`** (AGENTS.md): the files where services are constructed and routes, jobs or
+   handlers are mounted, and the rule for adding a new one.
+7. **`dependency-policy`** (AGENTS.md, and `eslint.config.mjs`): which modules or packages may import
+   which. Describe it in one paragraph and make sure `eslint.config.mjs` enforces it — extend the
+   policy blocks there (`ALLOWED_WORKSPACE_IMPORTS`, the `restrictSyntax` rules); a declared policy
+   that lint does not enforce is not a policy.
+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
+   (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
+   main entry point. Add a `doc:` markdown with the `<!-- composition:<id> -->` block, run
+   `pnpm composition:render`, and confirm `pnpm composition:check` passes.
+10. **`security-invariants`** (`architecture/security-invariants.md`): rows in the form
+   `Invariant | Enforced by` for the system-specific invariants — ownership checks, role middleware,
+   integer money, closed DTOs. Name the lint rule, test or scanner that enforces each; write `review`
+   only when nothing mechanical exists yet, and prefer adding the check to writing the word.
+11. **`defects-vs-variance`** and **`open-questions`** (AGENTS.md): what a reviewer must flag here
+    beyond the baseline list, and what looks like a convention but is not consistently applied.
+12. **Prove it.** Run the harness command from `construct.json`. Fix anything discovery broke (a
+    stale rendered diagram, a lint rule with no matching file). Then run `construct doctor`, or
+    `npx mikoshi-construct doctor` when the CLI is not installed; it names every marker that still
+    holds the placeholder.
+
+Report: which markers you filled, which you left as open questions and why, and the harness result.
+Do not commit.

package/templates/ai/shared/_claude/rules/conventions.md

@@ -0,0 +1,63 @@
+# Code conventions
+
+Repository-wide conventions for new code and the code you touch. Architecture, security and the reasoning
+budget are in [architecture/principles.md](../../architecture/principles.md).
+
+## Comments
+
+- **Write no comments.** Not per-line, not "why" comments, not file-header blocks, not JSDoc/TSDoc
+  prose — including on exported functions and on shared types other packages consume. The code is
+  read directly; it should explain itself.
+- A comment that feels necessary is a signal to make the code self-describing: extract a named
+  function, introduce a named constant, rename a variable, or push the fact into a test name where
+  it is executable. Move the knowledge into an identifier — don't delete it along with the comment.
+- **Pragmas are not comments and are never stripped**: `eslint-disable*`, `@ts-expect-error`,
+  `@ts-ignore`, `stylelint-disable*`, and triple-slash `/// <reference … />` directives, which are
+  compiler input. Where a lint config sets `reportUnusedDisableDirectives`, a refactor that removes
+  the need for a suppression must delete its directive in the same commit.
+
+## Async
+
+- Prefer `async`/`await` to `.then()` / `.catch()` / `.finally()` chains **where the enclosing
+  context can be async**.
+- That qualifier is load-bearing. Never run a blanket codemod: check the enclosing context first.
+  Chains legitimately survive in Vue `onMounted`, DOM and extension event listeners,
+  `MutationObserver` callbacks, and `init(): void` methods; and as behaviour, not style, in a
+  `.catch()` supplying a default inside a `??` chain, a `.catch()` on one member of `Promise.all`
+  so one failure doesn't sink the batch, a two-arg `.then(onOk, onErr)` settle-to-Result adapter,
+  and `new Promise(() => {})` sentinels that never resolve during navigation teardown.
+- When a call must be fire-and-forget from a synchronous context, write
+  `void (async () => { … })()` with `try`/`catch` inside, not a `.catch()` tail.
+
+## Design
+
+- When something owns state or varies in behaviour — services, repositories, gateways, cached-resource
+  wrappers, anything with injected dependencies — and the abstraction checklist in [architecture/checklists.md](../../architecture/checklists.md) passes, use a
+  class and the named pattern that fits: Template Method, Strategy, Repository, **Singleton** (one
+  owner per concept: a single client, config or cache instance, not module-level mutable state),
+  **Factory / Abstract Factory** (branching construction, so call sites stay free of `switch`).
+- A pattern earns its place by removing duplication or a conditional, never as decoration. Prefer
+  composition and constructor injection to inheritance chains and to singletons reached by import.
+- Pure transformations stay plain functions. A class of only static methods is a namespace with
+  ceremony — no polymorphism, harder to tree-shake, more awkward to test. Prefer classes that *call*
+  pure functions.
+- DRY / SOLID / minimum surface: reuse before writing; one owner per concept, so state and derived
+  data are not recomputed per consumer; prefer deleting to adding. Dead exports, incomplete barrel
+  files, and pass-through wrappers that add nothing get removed, not migrated.
+- A class that has grown several unrelated responsibilities is split into collaborators in their own
+  files, not sectioned off inside one file.
+
+## Lint and formatting
+
+- If a repo has an ESLint config, it is the single source of truth for style. Don't add Prettier, don't
+  turn on `formatOnSave`, and don't hand-format code to taste.
+- Fix style by running the repo's lint script with `--fix`, never by reformatting manually.
+- Match the surrounding code's existing idiom rather than imposing a different one. This does **not**
+  extend to comments — existing comments in a file are never a reason to add more; see Comments above.
+
+## pnpm
+
+- In a workspace with a `catalog:` block in `pnpm-workspace.yaml`, package manifests reference
+  `"catalog:"` instead of hardcoding a version.
+- `pnpm ci` is pnpm's own install builtin. To run a script named `ci`, always write `pnpm run ci`
+  (same care for any script whose name collides with a pnpm builtin).

package/templates/ai/shared/_claude/rules/secrets.md

@@ -0,0 +1,8 @@
+# Secrets and configuration
+
+- Never write an API key, token or connection secret into a config file — including gitignored or
+  otherwise local-only files. Local config still gets backed up, synced and read by other tools.
+- Config files reference secrets through placeholders that resolve at runtime from the process
+  environment (`${VAR}`, `${VAR:-default}`); the real values live only in the shell environment.
+- When a plan depends on a specific config syntax — variable expansion, default fallbacks, a particular
+  frontmatter key — verify against the tool's official documentation before building on it.

package/templates/ai/shared/_claude/rules/tests.md

@@ -0,0 +1,6 @@
+# Tests
+
+- Tests never sit next to source. `src/` stays product-only; unit tests live in `<app|package>/tests/**`
+  mirroring the `src/` layout, named `*.test.ts` (Vitest).
+- End-to-end and API integration specs live in a top-level `e2e/` directory as `*.spec.ts` (Playwright).
+- Every new or changed logic module ships with its matching test file in the same PR — not a follow-up.

package/templates/base/_editorconfig

@@ -0,0 +1,12 @@
+root = true
+
+[*]
+indent_style = space
+indent_size = 2
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.md]
+trim_trailing_whitespace = false

package/templates/base/_github/workflows/security.yml

@@ -0,0 +1,41 @@
+name: Security
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  schedule:
+    - cron: '0 6 * * 1'
+
+permissions:
+  contents: read
+
+jobs:
+  secrets:
+    name: Secret scan
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+
+      - name: Scan the history for committed secrets
+        run: |
+          docker run --rm -v "$PWD:/repo" ghcr.io/gitleaks/gitleaks:latest \
+            detect --source /repo --no-banner --redact --exit-code 1
+
+  dependencies:
+    name: Dependency audit
+    runs-on: ubuntu-latest
+    continue-on-error: true
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: pnpm/action-setup@v6
+
+      - uses: actions/setup-node@v7
+        with:
+          node-version-file: .nvmrc
+
+      - name: Report vulnerable dependencies of high severity or above
+        run: pnpm audit --audit-level=high

package/templates/base/_gitignore

@@ -0,0 +1,11 @@
+node_modules/
+dist/
+coverage/
+*.log
+*.tsbuildinfo
+.eslintcache
+.DS_Store
+.env
+.env.*
+!.env.example
+.construct/

package/templates/base/_gitleaks.toml

@@ -0,0 +1,2 @@
+[extend]
+useDefault = true

package/templates/base/_nvmrc.eta

@@ -0,0 +1 @@
+{{nodeMajor}}

package/templates/base/_vscode/settings.json

@@ -0,0 +1,22 @@
+{
+  "prettier.enable": false,
+  "editor.formatOnSave": false,
+  "eslint.useFlatConfig": true,
+  "editor.codeActionsOnSave": {
+    "source.fixAll.eslint": "explicit",
+    "source.organizeImports": "never"
+  },
+  "eslint.rules.customizations": [
+    { "rule": "style/*", "severity": "off", "fixable": true },
+    { "rule": "format/*", "severity": "off", "fixable": true },
+    { "rule": "*-indent", "severity": "off", "fixable": true },
+    { "rule": "*-spacing", "severity": "off", "fixable": true },
+    { "rule": "*-spaces", "severity": "off", "fixable": true },
+    { "rule": "*-order", "severity": "off", "fixable": true },
+    { "rule": "*-dangle", "severity": "off", "fixable": true },
+    { "rule": "*-newline", "severity": "off", "fixable": true },
+    { "rule": "*quotes", "severity": "off", "fixable": true },
+    { "rule": "*semi", "severity": "off", "fixable": true }
+  ],
+  "eslint.validate": ["javascript", "typescript", "json", "jsonc", "yaml", "markdown", "css"]
+}

package/templates/base/architecture/checklists.md

@@ -0,0 +1,42 @@
+# Checklists
+
+Answer these before the change, not after. They apply the principles in
+[principles.md](principles.md); the harness proves the result.
+
+Before introducing a new abstraction:
+
+1. What concrete problem does it solve?
+2. Is the complexity required by the domain, an NFR, or an external contract?
+3. Can the same requirement be satisfied with fewer components?
+4. Does the abstraction reduce coupling, or merely move it?
+
+When changing execution flow:
+
+1. Update the composition root and, where the repo keeps one, the composition model.
+2. Make sequence, parallelism, routing and fan-out explicit there.
+3. Do not hide orchestration inside unrelated domain objects.
+4. Regenerate rendered diagrams from the model; never edit a rendered diagram by hand.
+
+Before a substantial architectural change:
+
+1. Identify the affected contracts, domain boundaries, dependencies and composition.
+2. Check whether an existing artifact already describes the area; update that source of truth
+   before touching dependent implementation when a contract or composition changes.
+3. Implement.
+4. Validate that the implementation conforms to the contract and the dependency policy.
+5. Regenerate generated docs and diagrams from their sources.
+6. Delete obsolete abstractions and documentation instead of stacking compatibility layers.
+   Never create a second representation of a decision when an existing source of truth can be
+   updated.
+
+When adding a dependency:
+
+1. Check the repo's Dependency Policy (or the default in principles.md).
+2. Verify the dependency direction.
+3. Prefer an existing capability over introducing another dependency.
+
+When making a local change:
+
+1. Identify which boundary should contain the change.
+2. Do not leak implementation details across that boundary.
+3. If unrelated components must change, reconsider the decomposition.

package/templates/base/architecture/principles.md

@@ -0,0 +1,113 @@
+# Architecture principles
+
+These principles are the construct's core. They are stack-agnostic and apply to every change in this
+repository, by humans and by AI agents alike. Repo-specific facts (paths, scripts, boundaries) live in
+[CLAUDE.md](../CLAUDE.md) and [AGENTS.md](../AGENTS.md); where the two genuinely conflict, the repo wins.
+
+**CLI detects facts. Agent interprets the system.** The construct baseline was materialized by
+`mikoshi-construct`; everything that requires understanding this codebase was, or will be, written by
+the agent during discovery (`/construct-discover`) and refined as the project evolves.
+
+## Before writing code
+
+- Read the surrounding structure first — design tokens, utility and layout classes, existing services
+  and helpers, the neighbouring files' idiom — and reuse what is already there before writing anything
+  new. Most tasks are a call to something that exists, not a new abstraction.
+- The smallest correct diff wins. Extend an existing abstraction rather than adding a parallel one;
+  prefer deleting to adding.
+- Split heavy logic into small single-purpose files rather than letting a file grow past the point
+  where its responsibility can be named in one phrase. One concept, one owner, one home.
+- **These rules govern new code and the code you touch.** Match a file's surrounding idiom; never
+  mass-convert its units, selectors or query style as a side effect of an unrelated change.
+
+## Architecture
+
+«Localize complexity, make it explicit, and don't introduce complexity that the problem does not
+require.» The goal is not to eliminate complexity but to keep the necessary complexity explicit,
+isolated and manageable — and to treat accidental complexity as a defect.
+
+- **Decompose by responsibility and domain boundaries.** Split a system into meaningful components,
+  never by mechanically adding layers, services or abstractions.
+- **Isolate change and implementation details.** Components talk through explicit contracts and
+  stable interfaces. A change inside one component must not require understanding or editing
+  unrelated parts.
+- **Keep the architecture simple.** No abstraction, pattern, service or dependency without a
+  concrete reason. Prefer the simplest design that meets the requirements and NFRs.
+- **Make composition explicit.** Execution flow — sequencing, parallelism, routing, fan-out/fan-in,
+  retries and timeouts where they matter, external boundaries — lives in a composition root (an app
+  factory, a CLI/cron entry, an extension init), separate from the implementation it wires. A repo's
+  `CLAUDE.md` names its composition roots; where none is named, the app's entry/wiring file is the
+  root. Orchestration is never hidden inside a domain object. Where a repo keeps composition models
+  (small, one per flow, machine-readable), diagrams are rendered views of them, never the source:
+  edit the model and regenerate. No single global graph of every implementation detail.
+- **One source of truth per concern.** API behaviour → the API contract (OpenAPI or equivalent).
+  External or event messages → event contracts. Execution and composition → the composition model.
+  Domain behaviour → domain code and its tests. Dependency boundaries → lint rules. NFRs → a
+  requirements document only where nothing mechanical can express them. Never duplicate the same
+  fact across README, contract, diagram and implementation; when a representation is generated,
+  change the source, never the output. Prefer an executable or validated artifact over a descriptive
+  one whenever the property can be checked mechanically — a file nobody validates against is just
+  another README.
+- **API changes start from the contract.** The implementation conforms to it, consumers read the
+  types generated from it, and a breaking change is identified explicitly before it ships, never
+  discovered afterwards. The contract carries external behaviour only: no internal implementation
+  details and no business rules that are not part of what the API promises.
+- **Separate concerns by level.** Domain (what the business means and which rules exist),
+  Application (how use cases are orchestrated), Infrastructure (how technical capabilities are
+  implemented), Contracts (what a boundary promises its consumers), Composition (how components
+  are connected and executed), Dependency Policy (which dependencies and directions are allowed).
+  These are names for *what a piece of code is*, used to decide where a change belongs — not folders
+  to create. Keep the repo's existing organisation (feature folders, role suffixes) and never add a
+  layer it does not already have.
+- **Default dependency policy** when the repo declares none: apps depend on packages; packages never
+  depend on apps; shared/leaf packages depend on no internal package; no cycles; prefer an existing
+  capability over another dependency. Higher-level business logic never depends on infrastructure
+  implementation details. A declared policy lives in lint configuration so it is enforced, not read.
+- **Accidental complexity is a design smell.** When a change needs unrelated components understood,
+  crosses a boundary it should not, or touches several layers for a local behaviour change,
+  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).
+
+## Security
+
+Security is a validation dimension of its own, separate from functional correctness, and unit
+tests alone do not cover it.
+
+When a vulnerability or unsafe pattern is found:
+
+1. Fix it.
+2. Add a regression test when the behaviour is testable.
+3. Add or update a static-analysis rule when the issue is a reusable code pattern.
+4. Check whether a dependency caused it; update or replace the dependency when it did.
+5. Never suppress or ignore a finding without documenting why.
+
+A finding that appears more than once is an architectural problem, not a symptom to fix again:
+find the common root cause, move the protection to a shared boundary, add automated enforcement,
+and update the architecture or dependency policy if needed. The durable form of a finding is a
+named invariant with a named check — lint, a contract-level test, response validation, an
+integration test or a scanner — recorded once where reviewers read it. `review` as the only check
+is allowed, but it is the weakest and is listed as such.
+
+## Reasoning budget
+
+Reasoning effort is a budget, not a default. Implementation work starts at low effort under explicit
+constraints; the harness (the repo's quality gate: lint, types, tests, contract and composition
+checks, security rules) proves the result; more effort is spent only when the harness fails
+repeatedly or the task is ambiguous.
+
+- **Classify before starting.** *low*: an existing pattern to copy, a contract already defined, no
+  architecture change, no new dependency, nothing security-sensitive. *medium*: a new endpoint or
+  integration, a change across several modules, a non-trivial refactor. *high*: an architecture or
+  domain-boundary change, a contract redesign, a security-model or dependency-policy change,
+  ambiguous requirements, or repeated medium failure.
+- **Low effort means stronger constraints, not looser ones.** Implement only the requested change,
+  follow the neighbouring pattern, add no abstraction and no dependency, touch no unrelated module,
+  never delete, skip or weaken a test, ship the test with the logic, run the harness before
+  reporting.
+- **High effort means design first.** Inspect the boundaries, weigh alternatives, update the
+  contract and composition model before the implementation, state the decision.
+- **Escalate by evidence**: low → retry low with the failure in hand → medium → high. Ambiguity at
+  any rung goes to design, never to a guess. Reserve the ladder for tasks with a statable acceptance
+  criterion; one-line edits stay inline.

package/templates/base/architecture/security-invariants.md

@@ -0,0 +1,17 @@
+# Security invariants
+
+Security is its own review dimension. Each invariant names what enforces it; `review` means the
+reviewer is the only check, so weigh those the most. A finding that recurs is an architectural
+problem: move the protection to a shared boundary and add a check rather than fixing the symptom
+again. Method: [principles.md § Security](principles.md#security).
+
+The baseline rows below are enforced by files this construct materialized. Discovery adds the rows
+that are specific to this system — the ones where money, identity or data can be corrupted.
+
+| Invariant | Enforced by |
+|-----------|-------------|
+| No secret, token or connection string in any file, including gitignored ones; config references `${VAR}` placeholders | `.github/workflows/security.yml` runs gitleaks over the history on every push and pull request (`.gitleaks.toml` keeps the default ruleset live); review |
+| Dependencies with known high-severity vulnerabilities are visible | `security.yml` runs `pnpm audit` weekly and on pull requests, reporting only |
+<!-- construct:discover:security-invariants -->
+_Not discovered yet — run `/construct-discover`._
+<!-- /construct:discover:security-invariants -->

package/templates/harness/_github/workflows/ci.yml.eta

@@ -0,0 +1,31 @@
+# The harness on every pull request and push to main: `pnpm run quality` is the single gate,
+# for humans and for AI agents alike. Keep it green; extend it in package.json, not here.
+
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  quality:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: pnpm/action-setup@v6
+
+      - uses: actions/setup-node@v7
+        with:
+          node-version-file: .nvmrc
+          cache: pnpm
+
+      - name: Install
+        run: pnpm install --frozen-lockfile
+
+      - name: Quality
+        run: {{harnessCommand}}

package/templates/harness/eslint.config.mjs

@@ -0,0 +1,13 @@
+import antfu from '@antfu/eslint-config'
+
+export default antfu(
+  {
+    isInEditor: false,
+    typescript: {
+      tsconfigPath: './tsconfig.json',
+    },
+  },
+  {
+    ignores: ['**/dist/**', '**/node_modules/**', 'pnpm-lock.yaml', 'scripts/construct/*.workflow.mjs'],
+  },
+)