@geraldmaron/construct 1.0.0 → 1.0.1

package/templates/distribution/run.mjs

@@ -0,0 +1,187 @@
+#!/usr/bin/env node
+/**
+ * .construct/run.mjs — project-local Construct launcher.
+ *
+ * Resolves the right Construct install for the project and forwards every
+ * argument and stream to it. Settings.json hooks invoke this file
+ * (`node .construct/run.mjs hook <name>`) so the hook command is identical
+ * for every peer who clones the project, regardless of whether they have
+ * Construct globally installed or have run `npm install`.
+ *
+ * Resolution order:
+ *
+ *   0. `CONSTRUCT_DEV_PATH` env var — if set, points at a Construct checkout
+ *      and the launcher invokes its `bin/construct`. Used for development
+ *      and smoke tests; not consulted in normal runs.
+ *
+ *   1. Workspace `node_modules/@geraldmaron/construct/bin/construct` — if a
+ *      `npm install` has materialised Construct in this project's node_modules,
+ *      use that. Fastest, no network.
+ *
+ *   2. `npx -p @geraldmaron/construct@<version> construct …` — if Node ≥ 18
+ *      is on PATH but the package isn't installed locally. npx caches the
+ *      package after the first run. The version pin comes from
+ *      `.construct/version` next to this file.
+ *
+ *   3. Globally installed `construct` on PATH — if neither of the above
+ *      hit but the user has installed Construct globally.
+ *
+ *   4. Cached binary at `.construct/cache/bin/construct-<os>-<arch>` — if
+ *      a previous bootstrap downloaded the matching single-file binary
+ *      from GitHub Releases.
+ *
+ *   5. Docker container — if the docker daemon is reachable, invoke
+ *      `ghcr.io/geraldmaron/construct:<pinned-version>` with the project
+ *      bind-mounted at /work. Lets language-agnostic projects (no Node,
+ *      no global construct, no binary) still execute hooks. Disable with
+ *      `CONSTRUCT_DISABLE_DOCKER=1` for environments where docker is
+ *      reachable but undesirable (e.g. CI runners that prefer fail-fast).
+ *
+ *   6. Print a precise error with the exact install commands and exit
+ *      with the documented exit code (127 = command not found).
+ *
+ * The launcher is intentionally tiny and dependency-free so it never
+ * needs `npm install` to be runnable. It uses only Node's stdlib.
+ */
+
+import { spawn, spawnSync } from 'node:child_process';
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const PROJECT_ROOT = resolve(HERE, '..');
+const VERSION_FILE = join(HERE, 'version');
+const CACHE_BIN_DIR = join(HERE, 'cache', 'bin');
+
+function readPinnedVersion() {
+  try {
+    const v = readFileSync(VERSION_FILE, 'utf8').trim();
+    if (v && /^[0-9]+\.[0-9]+\.[0-9]+(-[A-Za-z0-9.-]+)?$/.test(v)) return v;
+  } catch { /* file missing or unreadable */ }
+  return null;
+}
+
+function isExecutable(path) {
+  try {
+    return statSync(path).isFile();
+  } catch { return false; }
+}
+
+function commandOnPath(cmd) {
+  const probe = spawnSync(process.platform === 'win32' ? 'where' : 'which', [cmd], {
+    encoding: 'utf8',
+  });
+  if (probe.status !== 0) return null;
+  const first = probe.stdout.split(/\r?\n/).find(Boolean);
+  return first || null;
+}
+
+function runForeground(cmd, args, opts = {}) {
+  const child = spawn(cmd, args, {
+    stdio: 'inherit',
+    cwd: opts.cwd || PROJECT_ROOT,
+    env: { ...process.env, ...(opts.env || {}) },
+  });
+  child.on('exit', (code) => process.exit(code ?? 1));
+  child.on('error', (err) => {
+    process.stderr.write(`[construct] launcher failed to spawn ${cmd}: ${err.message}\n`);
+    process.exit(127);
+  });
+}
+
+function tryDevPath() {
+  const dev = process.env.CONSTRUCT_DEV_PATH;
+  if (!dev) return false;
+  const candidate = join(dev, 'bin', 'construct');
+  if (!isExecutable(candidate)) return false;
+  runForeground(process.execPath, [candidate, ...process.argv.slice(2)]);
+  return true;
+}
+
+function tryNodeModules() {
+  const candidate = join(
+    PROJECT_ROOT,
+    'node_modules', '@geraldmaron', 'construct', 'bin', 'construct'
+  );
+  if (!isExecutable(candidate)) return false;
+  runForeground(process.execPath, [candidate, ...process.argv.slice(2)]);
+  return true;
+}
+
+function tryNpx(version) {
+  if (!commandOnPath('npx')) return false;
+  const spec = version ? `@geraldmaron/construct@${version}` : '@geraldmaron/construct';
+  runForeground('npx', ['-p', spec, '--', 'construct', ...process.argv.slice(2)]);
+  return true;
+}
+
+function tryGlobal() {
+  const found = commandOnPath('construct');
+  if (!found) return false;
+  runForeground(found, process.argv.slice(2));
+  return true;
+}
+
+function tryCachedBinary() {
+  const arch = process.arch === 'arm64' ? 'arm64' : 'x64';
+  const os = process.platform === 'darwin' ? 'darwin'
+    : process.platform === 'win32' ? 'windows'
+    : 'linux';
+  const ext = process.platform === 'win32' ? '.exe' : '';
+  const candidate = join(CACHE_BIN_DIR, `construct-${os}-${arch}${ext}`);
+  if (!isExecutable(candidate)) return false;
+  runForeground(candidate, process.argv.slice(2));
+  return true;
+}
+
+function tryDocker(version) {
+  if (process.env.CONSTRUCT_DISABLE_DOCKER === '1') return false;
+  if (!commandOnPath('docker')) return false;
+  // Confirm the daemon is reachable, not just that the CLI is installed.
+  const info = spawnSync('docker', ['info'], { stdio: 'ignore' });
+  if (info.status !== 0) return false;
+  const tag = version || 'latest';
+  const image = `ghcr.io/geraldmaron/construct:${tag}`;
+  const userHome = process.env.HOME || process.env.USERPROFILE || '';
+  const hostConstructDir = userHome ? join(userHome, '.construct') : null;
+  const dockerArgs = [
+    'run', '--rm', '-i',
+    '-v', `${PROJECT_ROOT}:/work`,
+    '-w', '/work',
+    '-e', 'CONSTRUCT_PROJECT_ROOT=/work',
+  ];
+  if (hostConstructDir) {
+    dockerArgs.push('-v', `${hostConstructDir}:/data/.construct`);
+  }
+  dockerArgs.push(image, ...process.argv.slice(2));
+  runForeground('docker', dockerArgs);
+  return true;
+}
+
+function fail() {
+  const v = readPinnedVersion();
+  process.stderr.write(
+    '[construct] No Construct install found.\n' +
+    '\n' +
+    '  This project pins Construct' + (v ? ` ${v}` : '') + ' but no runtime resolved.\n' +
+    '\n' +
+    '  Pick one:\n' +
+    '    - Install Node.js 18+ from https://nodejs.org and re-run.\n' +
+    '    - Install Construct globally:  npm install -g @geraldmaron/construct\n' +
+    '    - Install Docker:              docker pull ghcr.io/geraldmaron/construct\n' +
+    '    - Bootstrap a binary:           ./.construct/bootstrap.sh   (POSIX)\n' +
+    '                                    powershell -File .construct/bootstrap.ps1   (Windows)\n'
+  );
+  process.exit(127);
+}
+
+const version = readPinnedVersion();
+
+if (tryDevPath()) { /* spawned */ }
+else if (tryNodeModules()) { /* spawned */ }
+else if (tryNpx(version)) { /* spawned */ }
+else if (tryGlobal()) { /* spawned */ }
+else if (tryCachedBinary()) { /* spawned */ }
+else if (tryDocker(version)) { /* spawned */ }
+else fail();

package/templates/docs/adr.md

@@ -5,23 +5,59 @@
 - **Deciders**: {names}
 - **Supersedes**: {ADR-NNN or none}
 
+<!--
+Before drafting, read rules/common/framing.md.
+
+Required framing rule: every section below must describe the domain
+problem and the decision. Not the ticket. Not the PRD filename. Not the
+meeting that prompted the ADR. A principal engineer who has never seen
+the triggering inputs should be able to read this doc and understand the
+decision and why it was made.
+
+Owning specialist: cx-architect (see rules/common/doc-ownership.md).
+-->
+
+## Problem
+<!--
+The decision-forcing tension in the domain. State what is currently
+true and what pressure makes a choice unavoidable.
+
+Must NOT reference:
+- Jira/Linear ticket IDs or titles
+- PRD filenames or document structure
+- Chat transcripts or meeting notes
+- Process-level framing ("we need to decide how to document X")
+
+Should reference:
+- The constraint that makes this non-trivial
+- The cost of not deciding
+- What is observably broken, ambiguous, or at risk
+-->
+
 ## Context
-<!-- The forces at play. What is true today that makes a decision necessary? What constraints bound the space? -->
+<!-- Forces at play beyond the core problem. What else is true today that bounds the decision space? Prior ADRs, architectural constraints, external commitments. -->
 
 ## Decision
 <!-- The position taken, in one or two sentences. State it as a commitment, not a proposal. -->
 
 ## Rationale
-<!-- Why this decision over the alternatives. The load-bearing reasons. -->
+<!-- Why this decision over the alternatives. The load-bearing reasons, cited to the evidence. If the rationale leans on external references (standards, prior art, vendor behavior), cite them. -->
 
-## Consequences
-<!-- What becomes easier and what becomes harder once this is in effect. Include second-order effects. -->
+## Rejected alternatives
+<!--
+For each alternative considered, one paragraph covering:
+- What the alternative was (concretely enough to be evaluated)
+- The specific reason it was rejected (not "we preferred the chosen option")
+- What evidence or constraint made it inferior
 
-## Alternatives considered
-<!-- Other options and the specific reason each was rejected. One paragraph per alternative. -->
+An ADR without rejected alternatives is a proposal, not a decision.
+-->
+
+## Consequences
+<!-- What becomes easier, what becomes harder, what is now locked in. Include second-order effects and the new constraints this decision imposes. -->
 
 ## Reversibility
-<!-- Is this a one-way or two-way door? What would it take to reverse? When would we revisit? -->
+<!-- Is this a one-way or two-way door? What would it take to reverse? Under what conditions would we revisit? -->
 
 ## References
-<!-- Prior ADRs, PRDs, research, tickets, discussions. -->
+<!-- Primary sources, prior ADRs, research briefs, standards. Execution artifacts (tickets, chat) may be listed for traceability but never as load-bearing reasoning. -->

package/templates/docs/changelog-entry.md

@@ -0,0 +1,43 @@
+# Changelog: {version} — {YYYY-MM-DD}
+
+- **Version**: {semver or date-based tag}
+- **Type**: major | minor | patch | hotfix
+- **Authors**: {names}
+- **Status**: draft | released
+
+<!--
+Keep entries user-facing. Describe what changed and why it matters, not how it
+was implemented. Group under standard headings. Link to issues or PRDs when helpful.
+-->
+
+## Added
+
+<!-- New features, endpoints, capabilities, or commands. -->
+
+## Changed
+
+<!-- Behaviour changes, interface updates, performance improvements. -->
+
+## Fixed
+
+<!-- Bug fixes. Link to issue numbers when available. -->
+
+## Deprecated
+
+<!-- Features that are still working but will be removed in a future release. -->
+
+## Removed
+
+<!-- Features removed in this release. Note migration path if one exists. -->
+
+## Security
+
+<!-- Vulnerability fixes. Reference CVE numbers if applicable. -->
+
+## Migration notes
+
+<!-- Breaking changes and what users need to do. Omit section if none. -->
+
+## References
+
+<!-- PRDs, RFCs, ADRs, or tracker issues that drove this release. -->

package/templates/docs/construct_guide.md

@@ -0,0 +1,149 @@
+# Welcome to Construct
+
+This file was generated by `construct init` to help you get oriented. It's safe to edit — Construct only writes it once, then leaves it alone.
+
+**Full docs:** [https://geraldmaron.github.io/construct/v2/](https://geraldmaron.github.io/construct/v2/)
+
+## What Construct is doing in your project
+
+You added Construct as a dev dependency. That gave you:
+
+- **One AI persona to address: `@construct`.** In your editor (Claude Code, OpenCode, Codex, Cursor, or Copilot), you talk to one entity. Behind the scenes, 28 specialists (architect, engineer, security, SRE, designer, …) pick up the work based on what you asked for.
+- **Hard gates.** Every code change runs through commit-time policy: no secrets, tests green, docs current, comments lint-clean. Bypass exists for every gate but leaves an audit trail.
+- **Persistent state.** Your active work, decisions, and history survive across sessions and editor restarts.
+
+You don't need to manage any of that — it all runs locally.
+
+## Files Construct created in your project
+
+You'll see these in `git status`:
+
+| Path | What it is | Touch? |
+|---|---|---|
+| `.construct/` | Launcher for hooks. Don't edit. Regenerated on `npm install`. | No |
+| `.claude/agents/` | The 29 persona definitions. Regenerated on `npm install`. | No |
+| `.claude/commands/` | Slash commands. Regenerated on `npm install`. | No |
+| `.claude/settings.json` | Hooks + MCP server config. Construct keys are managed; your additions are preserved. | Carefully |
+| `.cx/` | Per-project session state (active work, recent decisions). Construct writes here. | Read-mostly |
+| `.beads/` | Issue tracker data. Use `bd <cmd>` to interact. | Via CLI |
+| `AGENTS.md` | Operating rules the agent reads at session start. | Yes — your house rules go here |
+| `plan.md` | Active work plan. Local-only (gitignored). | Yes — your current focus |
+| `docs/` | Documentation lanes (ADRs, PRDs, memos, …). | Yes — this is your team's docs |
+| `construct_guide.md` | This file. Friendly orientation. | Yes — adapt to your team |
+
+## Where to drop information you want Construct to use
+
+Three intake paths, ordered by formality:
+
+1. **`.cx/inbox/`** — drop a file here (URL, screenshot, paste, anything). The embed daemon watches the directory; when a file lands, it ingests it into the local knowledge base within a second or two and writes a triage packet to `.cx/intake/pending/` describing the new content, its R&D classification (intake type, stage, owner persona, recommended chain), its suggested docs lane, and existing docs that overlap. The agent surfaces pending intake at the next session start and you can ask it to process them — propose updates to existing PRDs/RFCs/ADRs or scaffold new ones — based on the prepared context.
+2. **`docs/intake/`** — for proper intake batches (research notes, evidence from a meeting, raw source material). Has a template. Survives in git history.
+3. **`AGENTS.md`** — for rules and conventions you want the agent to follow every time. "We prefer functional components. Don't introduce new dependencies without flagging." Read at session start.
+
+For URLs or quick notes, the easiest path is to drop a file into `~/Downloads` and run:
+
+```bash
+construct drop                # ingests the most recent download/desktop file
+```
+
+## How to talk to Construct
+
+In your editor:
+
+```
+@construct help me add OAuth to the login flow
+```
+
+Construct will classify the request, route to the right specialists (architect for design, engineer for implementation, security for review), and stream results back to you in one conversation.
+
+You can also invoke a specialist directly if you know what you want:
+
+```
+@cx-security audit the auth middleware for OWASP top 10
+```
+
+The full list of personas lives in `.claude/agents/`. Run `construct list` to see them with descriptions.
+
+## How to change Construct settings
+
+Two scopes:
+
+**Per-project** (committed, shared with peers): edit `.claude/settings.json`. Construct owns the `hooks` block and a known set of `mcpServers` keys (memory, context7, playwright, github, sequential-thinking, construct-mcp); your additions are preserved on `npm install`. Other top-level keys are yours to control.
+
+**Per-machine** (private to you): edit `~/.construct/config.env`. This is where your API keys, consent flags, and local-service credentials live. Standard `KEY=value` format.
+
+After editing settings, run:
+
+```bash
+construct sync               # regenerate platform adapters from any registry changes
+construct doctor             # verify everything's healthy
+```
+
+## Local services
+
+If you ran `construct init` and have Docker, you have three things running locally on Construct's reserved port block (`54329-54339`, chosen to avoid colliding with Next.js, Postgres, Redis, etc.):
+
+**Telemetry backend** (LLM observability — see your traces, costs, and quality scores)
+
+- URL: <http://localhost:54330>
+
+**Postgres + pgvector** (the database that backs hybrid retrieval)
+
+- URL: `postgresql://construct:construct@127.0.0.1:54329/construct`
+- Saved as `DATABASE_URL` in `~/.construct/config.env`
+
+**Vector storage** (semantic search over your project + ingested docs)
+
+- Backend: Postgres + pgvector (384d embeddings, `Xenova/all-MiniLM-L6-v2` model)
+- Model auto-downloaded to `~/.construct/cache/embeddings/` on first use (~22 MB, one time)
+- Run `construct search "your query"` to see it work
+
+If you skipped Docker, Construct falls back to a local JSON vector index at `~/.construct/vector/index.json` and stops emitting traces — semantic search still works, just slower at scale, and the telemetry backend isn't available.
+
+All ports bind to `127.0.0.1` only; nothing is reachable from other machines on your network.
+
+## Useful commands
+
+| Command | What it does |
+|---|---|
+| `construct init` | One-time per-machine: spins up local services, writes config |
+| `construct config [mode <m>]` | Show active deployment mode (solo / team / enterprise) or set a new one |
+| `construct doctor` | Health check across config, services, agents, hooks |
+| `construct sync` | Regenerate platform adapters (Claude Code, OpenCode, Codex, Cursor) |
+| `construct up` / `construct down` | Start / stop local services |
+| `construct status` | Live runtime status (services, providers, daemons) |
+| `construct intake list / show / done / skip / reopen` | Drive the R&D intake queue produced from `.cx/inbox/` |
+| `construct graph from-intake <id>` | Generate a task graph from a triaged intake packet |
+| `construct drop` | Ingest the most recent downloaded file |
+| `construct search "..."` | Hybrid file + SQL + semantic search over project state |
+| `construct uninstall` | Interactive teardown — never touches Docker or your code |
+
+Full reference: <https://geraldmaron.github.io/construct/v2/docs/reference/cli>
+
+## Updating Construct
+
+```bash
+npm update @geraldmaron/construct
+```
+
+That refreshes the agents, hooks, and slash commands in `.claude/` and `.construct/`. Your `.cx/`, `AGENTS.md`, `plan.md`, and `docs/` content is untouched.
+
+## When things go wrong
+
+```bash
+construct doctor              # most issues surface here with a fix hint
+construct down && construct up  # restart local services
+```
+
+Troubleshooting guide: <https://geraldmaron.github.io/construct/v2/docs/operations/troubleshooting>
+
+## Next steps
+
+- [Connect your editor](https://geraldmaron.github.io/construct/v2/docs/start/connect-your-editor) if you haven't already.
+- [Run your first task](https://geraldmaron.github.io/construct/v2/docs/start/first-task) to feel the flow.
+- Skim [the architecture](https://geraldmaron.github.io/construct/v2/docs/concepts/architecture) when you have 10 minutes — it'll save you hours later.
+
+If you'd rather have a teammate walk you through it, the persona itself can:
+
+```
+@construct give me a tour of this project — what's wired up, what's optional, what should I look at first
+```

package/templates/docs/evidence-brief.md

@@ -19,13 +19,13 @@ source lists or grouped findings. Keep em dashes rare.
 <!-- State the minimum signal needed to proceed. Example: two independent customers, three repeated mentions, or one severe enterprise blocker. -->
 
 ## Sources
-<!-- Table: source, date, customer or actor, link/path, confidence. -->
+<!-- Table: source, source class, date/access date, customer or actor, link/path, confidence, and whether it is direct evidence or secondhand summary. -->
 
 ## What we observed
 <!-- Factual observations only. Separate direct evidence from interpretation. -->
 
 ## Patterns
-<!-- Synthesized themes across sources. Include strength of signal and counter-evidence. -->
+<!-- Synthesized themes across sources. Include strength of signal, counter-evidence, and whether themes are observation or inference. -->
 
 ## Open asks
 <!-- Customer or stakeholder asks that are not yet committed requirements. -->

package/templates/docs/meta-prd.md

@@ -16,41 +16,162 @@ Write with a balance of structured paragraphs, compact tables, and selective bul
 Avoid a wall of bullets. Keep em dashes rare; prefer commas, periods, or parentheses.
 -->
 
-## Purpose
-<!-- One or two paragraphs. What product practice or system this Meta PRD improves, and why that matters now. -->
+## Summary
+<!--
+One paragraph (3-5 sentences). What product practice or operating system is
+being defined or changed, who runs it, and what becomes different about how
+the org decides, documents, or evaluates work once this ships.
+-->
+
+## Background
+<!--
+The current state of the operating system: which workflow, template, eval
+loop, or governance process is in play today, and what's actually happening
+when teams or agents use it. Cite real examples — recent PRDs, prior decisions,
+trace evidence, support tickets — not hypotheticals.
+-->
+
+## Problem
+<!--
+The failure mode in the current process. Name who feels it, how often, and
+what breaks downstream. Keep solutions out of this section.
+
+Examples of the right shape:
+- "PRDs ship without rejected alternatives, so reviewers re-litigate decisions
+  three weeks in. Happens on ~40% of PRDs in the last quarter."
+- "Postmortems are written by the on-call who shipped the bug, so the action
+  items reflect their proposals — not independent review."
+-->
 
-## Operating problem
-<!-- Describe the failure mode in the current process. Name who feels it, how often, and what breaks downstream. -->
+## Goals
+<!--
+What success looks like for the operating system. Three to five outcomes max.
+Examples: "PRDs cite primary sources by default", "Postmortems get peer
+review before publish", "ADR rejection rate drops from 60% to under 20%".
+-->
 
-## Scope
-<!-- What part of the product operating system changes. Include the teams, agents, templates, workflows, tools, or decision points affected. -->
+## Outcome
+<!--
+What is concretely different about how work moves through the org once this
+operating model is adopted. Written from the practitioner's perspective:
+"When I open a PRD, I'm prompted to record rejected alternatives before
+the doc enters review."
+-->
+
+## In scope and out of scope
+
+| | Description |
+|---|---|
+| **In scope** | <which templates, workflows, agents, gates, or evals are touched> |
+| **Out of scope** | <related operating systems explicitly deferred — name the reason> |
+| **Adjacent (deferred)** | <natural follow-up changes not in this Meta PRD> |
 
 ## Principles
-<!-- A short list of durable rules this system must preserve. Keep each principle testable enough to guide tradeoffs. -->
+<!--
+Durable rules this operating system must preserve across phases. Each
+principle should be testable enough to guide tradeoffs when phases conflict.
+-->
 
 ## Inputs and evidence
-<!-- What evidence the system consumes: customer notes, interviews, traces, Jira issues, PRDs, research, analytics, support tickets, or prior decisions. State minimum evidence thresholds where useful. -->
+<!--
+What evidence the system consumes — customer notes, interviews, traces, Jira
+issues, PRDs, research, analytics, support tickets, prior decisions. State
+minimum evidence thresholds where useful (e.g. "two independent customer
+interviews before a PRD enters review").
+-->
+
+## Phases
+
+<!--
+Each phase below holds its own goal, status, workflow requirements (MR),
+and document + evaluation requirements (DR), with acceptance criteria
+inline next to each. Use `MR-<phase>.<n>` and `DR-<phase>.<n>` so
+requirements can be referenced from reviews, traces, and evals.
+
+MR = Workflow requirement: how the process or agent workflow must behave;
+observable in generated artifacts, workflow state, or tool behavior.
+
+DR = Document + evaluation requirement: how outputs are shaped, reviewed,
+and scored; required sections, evidence rules, citation rules, formatting
+constraints, anti-patterns, rubric dimensions, pass/fail checks.
 
-## Workflow requirements
-<!-- Numbered requirements for the process or agent workflow. Use MR-1, MR-2, etc. Each requirement should be observable in generated artifacts, workflow state, or tool behavior. -->
+Status values: not started | in progress | shipped | deferred.
+-->
+
+### Phase 1 — <name>
+
+- **Goal**: <what this phase delivers>
+- **Status**: not started
+
+**Workflow**
+
+- **MR-1.1** — <imperative statement of how the workflow must behave>
+  - *Acceptance*: <how a reviewer or trace verifies this without asking the author>
+- **MR-1.2** — <...>
+  - *Acceptance*: <...>
+
+**Document + evaluation**
+
+- **DR-1.1** — <required section, evidence rule, citation rule, formatting constraint, or anti-pattern>
+  - *Acceptance*: <rubric dimension, pass/fail check, or trace signal that proves it>
+
+### Phase 2 — <name>
+
+- **Goal**: <what this phase delivers>
+- **Status**: not started
+
+**Workflow**
+
+- **MR-2.1** — <...>
+  - *Acceptance*: <...>
+- **MR-2.2** — <...>
+  - *Acceptance*: <...>
+
+**Document + evaluation**
 
-## Document standards
-<!-- Required sections, tone, evidence rules, citation rules, formatting constraints, and anti-patterns. State how this differs from a normal PRD. -->
+- **DR-2.1** — <...>
+  - *Acceptance*: <...>
+
+### Phase 3 — <name>
+
+- **Goal**: <what this phase delivers>
+- **Status**: not started
+
+**Workflow**
+
+- **MR-3.1** — <...>
+  - *Acceptance*: <...>
+
+**Document + evaluation**
+
+- **DR-3.1** — <...>
+  - *Acceptance*: <...>
 
 ## Human approval gates
-<!-- Where a person must review, approve, reject, or supply missing context before the system writes externally or treats a document as approved. -->
+<!--
+Where a person must review, approve, reject, or supply missing context before
+the system writes externally or treats a document as approved. Name the gate,
+the reviewer role, and the timeout policy if no reviewer responds.
+-->
 
-## Evaluation
-<!-- How quality will be measured. Include rubric dimensions, pass/fail checks, trace evidence, and examples of unacceptable output. -->
+## Failure modes and mitigations
 
-## Failure modes
-<!-- What could go wrong if the system is followed too literally, over-automated, or used with weak evidence. Include mitigations. -->
+| Failure mode | Likelihood | Impact | Mitigation |
+|---|---|---|---|
+| <how this could go wrong if followed too literally, over-automated, or used with weak evidence> | low / med / high | low / med / high | <guardrail or escape hatch> |
 
 ## Rollout
-<!-- How this operating model becomes the default. Include migration steps, owners, training, and when older templates or workflows are retired. -->
+<!--
+How this operating model becomes the default. Migration steps, owners,
+training, deprecation date for the older template or workflow. Name what
+happens to in-flight work (grandfathered or migrated).
+-->
 
 ## Open questions
-<!-- Questions that could change the operating model. Each should have an owner and decision date. -->
+
+| Question | Owner | Decision needed by |
+|---|---|---|
+| <unknown that could change the operating model> | <name> | <YYYY-MM-DD> |
 
 ## References
 <!-- Linked examples, prior PRDs, Meta PRDs, research, tickets, traces, or decisions. -->