create-ccc-tutor 0.1.0

package/template/.harness/skills/constitution-edit/SKILL.md

@@ -0,0 +1,292 @@
+---
+name: constitution-edit
+description: Edit the project constitution.md and update its Sync Impact Report. Use when the user wants to add, modify, or remove a principle in Section 2 (Project Identity), Section 3 (Project Red Lines), or the slot registry. CANNOT modify Section 1 (Universal Core) — those are harness-guaranteed invariants that no edit can remove. Generates a versioned Sync Impact Report at the top of constitution.md. Trigger when the user invokes /constitution-edit, says "edit the constitution", "add a red line", "update project identity", or similar intent.
+allowed-tools: Read, Edit, Bash(date:*), Bash(grep:*), Bash(git diff:*), Bash(git status:*)
+argument-hint: <description of the change>
+---
+
+# /constitution-edit
+
+Edit `constitution.md` Section 2 (Project Identity), Section 3 (Project Red Lines), or the slot registry, and prepend a versioned Sync Impact Report HTML comment that documents the change.
+
+> *Spec-Kit-pattern audit trail. The Sync Impact Report turns ad-hoc constitution edits into versioned, semver-bumped, auditable changes — without burdening the file with full history (that's what `git log` is for).*
+
+## Language Awareness
+
+This skill's instructions are in English. When you talk to the user (proposing the change, asking for confirmations, summarizing results), use the user's OS locale language. See `CLAUDE.md § Language Awareness`. The text written INTO `constitution.md` stays verbatim per what the user approves; do not translate user-entered content.
+
+## What this skill produces
+
+A modified `constitution.md` with:
+
+1. The approved edit applied to Section 2, Section 3, or the slot registry.
+2. A Sync Impact Report HTML comment prepended at the top of the file, immediately after the title heading and before the existing file-description comment. Format:
+
+```html
+<!-- Sync Impact Report
+Version: <old> → <new> (<MAJOR|MINOR|PATCH> — <short description>)
+Modified items:
+  - <section name> — <what changed>
+  - <section name> — <what changed>
+Templates needing update:
+  - <file path> — <status: ✅ updated / ⚠ pending review / N/A>
+Generated: <ISO 8601 UTC timestamp>
+-->
+```
+
+Only one Sync Impact Report block lives in the file at a time — the most recent one. Prior versions live in `git log`.
+
+## Semver rules
+
+- **MAJOR** — removes or substantively changes a principle that was already in Section 2 / Section 3 / slot registry
+- **MINOR** — adds a new principle to Section 2 / Section 3, or adds a new slot to the registry
+- **PATCH** — wording / clarification / typo / non-semantic refactor
+
+If multiple changes apply in one `/constitution-edit` invocation, take the highest applicable bump.
+
+If no prior Sync Impact Report block exists in `constitution.md`, treat the current state as version `1.0.0`.
+
+---
+
+## Step 0 — Pre-flight
+
+1. Verify `constitution.md` exists at project root:
+
+   ```bash
+   test -f constitution.md
+   ```
+
+   If missing, fail with the message:
+
+   ```
+   constitution.md not found — run /init first.
+   ```
+
+   Halt the skill.
+
+2. Read `constitution.md` fully (Read tool).
+
+3. Extract the current version from any existing Sync Impact Report block at the top:
+
+   ```bash
+   grep -m1 -oE 'Version: [0-9]+\.[0-9]+\.[0-9]+ →' constitution.md
+   ```
+
+   If no Sync Impact Report block exists, treat the current state as `1.0.0`.
+
+---
+
+## Step 1 — Understand the change
+
+1. Parse `$ARGUMENTS` as the change description (free text from the user).
+
+2. If `$ARGUMENTS` is empty, ask the user:
+
+   ```
+   What do you want to change in the constitution? Examples:
+     - "add a red line about no third-party trackers"
+     - "reword the audience to mention enterprises"
+     - "add a slot for retry-policy"
+   ```
+
+   **Wait for user response before continuing.**
+
+3. Identify which section(s) the change will affect:
+
+   - **Section 1 (Universal Core)** → REJECT with the message below and halt:
+
+     ```
+     /constitution-edit cannot modify Section 1 (Universal Core). These are harness-guaranteed invariants that no project edit can remove. If you want to ADD a new project-level red line, use Section 3 instead.
+
+     If you genuinely need a constitutional change at the harness level, modify outcome/constitution.md directly in the harness source — but understand that doing so changes the harness itself, not your project.
+     ```
+
+   - **Section 2 (Project Identity)** → proceed
+   - **Section 3 (Project Red Lines)** → proceed
+   - **Slot registry** (the HTML comment block at the top of `constitution.md`) → proceed
+
+---
+
+## Step 2 — Propose the edit
+
+1. Based on the change description, propose the EXACT text to add / modify / remove.
+
+2. Format the proposal as a diff-style preview, in the user's locale:
+
+   ```
+   Proposed change to <section>:
+
+   <diff-style preview: -old / +new>
+
+   Type:
+     [a] approve as proposed
+     [b] modify (tell me what to change)
+     [c] cancel
+   ```
+
+3. **Wait for user response before continuing.**
+
+   - `[a]` → proceed to Step 3
+   - `[b]` → accept the user's revisions; re-show the proposal; loop until `[a]` or `[c]`
+   - `[c]` → abort silently; write nothing
+
+---
+
+## Step 3 — Determine semver bump
+
+Auto-detect the bump type from the approved change:
+
+| Change shape | Proposed bump |
+|--------------|---------------|
+| Adding new content (new principle / new slot) | MINOR |
+| Removing existing content | MAJOR |
+| Substantively rewording existing content (meaning changes) | MAJOR |
+| Typo / clarification / non-semantic rewording | PATCH |
+
+Show to the user:
+
+```
+Bump type: <type>. Override?
+  [Enter] accept
+  [m] major
+  [n] minor
+  [p] patch
+```
+
+**Wait for user response before continuing.**
+
+Compute the new version from the old one (`X.Y.Z`):
+
+- MAJOR → `(X+1).0.0`
+- MINOR → `X.(Y+1).0`
+- PATCH → `X.Y.(Z+1)`
+
+---
+
+## Step 4 — Apply the edit
+
+Use the Edit tool to apply the approved change from Step 2 to `constitution.md`. This is the content edit only; the Sync Impact Report block is prepended later in Step 7.
+
+---
+
+## Step 5 — Detect affected templates
+
+For each affected slot or principle, identify downstream files that may need review:
+
+1. **If a slot was added or changed**: search for `{{<slot_name>}}` references across the running scope (the harness installation root — typically the project root containing `constitution.md`, `CLAUDE.md`, `AGENTS.md`, and `.harness/`):
+
+   ```bash
+   grep -rln "{{<slot_name>}}" .
+   ```
+
+   Capture matching file paths.
+
+2. **If a Section 2 or Section 3 principle was added**: identify SKILL.md files that consume constitution rules. Heuristic — any SKILL.md referencing `constitution.md` in its body:
+
+   ```bash
+   grep -rln "constitution.md" .harness/skills/ 2>/dev/null
+   ```
+
+   Mark them as needing review.
+
+If no affected templates can be confidently identified, list:
+
+```
+(none detected — review SKILL.md files manually if change is structural)
+```
+
+---
+
+## Step 6 — Generate Sync Impact Report block
+
+Build the report block. Use `date -u +%Y-%m-%dT%H:%M:%SZ` for the timestamp:
+
+```html
+<!-- Sync Impact Report
+Version: <old> → <new> (<bump> — <one-line description>)
+Modified items:
+  - <section> — <what changed>
+Templates needing update:
+  - <file path> — <status>
+Generated: <ISO 8601 UTC timestamp>
+-->
+```
+
+Status values for "Templates needing update":
+
+- `✅ updated` — only used if the skill itself edited the template (this skill does NOT auto-edit templates; reserved for future use)
+- `⚠ pending review` — default for any detected template
+- `N/A` — no templates affected
+
+---
+
+## Step 7 — Prepend to constitution.md
+
+1. If an existing Sync Impact Report block already lives at the top of `constitution.md` (immediately after the title heading), **REPLACE** it with the new block. Do not preserve historic blocks in the file — `git log` is the audit trail.
+
+2. Otherwise, **INSERT** the new block immediately after the title line (`# <project> — Constitution`) and before the next content (typically the existing file-description HTML comment).
+
+Use the Edit tool. After writing, read back and show the top 30 lines of `constitution.md` to the user for visual confirmation.
+
+---
+
+## Step 8 — Wrap up
+
+Display to the user (in their locale):
+
+```
+✓ Constitution updated to version <new>.
+
+Sync Impact Report prepended to constitution.md.
+
+Affected templates (if any) marked ⚠ pending review:
+  - <file1>
+  - <file2>
+
+Next steps:
+  1. Review and update marked templates as needed.
+  2. Commit when ready (use /commit).
+```
+
+If no templates were detected, omit the "Affected templates" list and replace with:
+
+```
+No downstream templates detected as affected.
+```
+
+---
+
+## Rules / Anti-patterns
+
+- **Never edit Section 1 (Universal Core)** — reject at Step 1 with the explicit message.
+- **Never auto-edit downstream templates** — only mark them ⚠ for human review. Auto-modification risks silent corruption.
+- **Never skip the user confirmation at Step 2** — the proposed edit must be approved before it lands.
+- **Never preserve historic Sync Impact Report blocks** in `constitution.md` — exactly one block always; `git log` carries the history.
+- **Never run `git commit` or `git push` from this skill** — edits land as working-tree changes. The user commits via `/commit` when ready.
+- **Never translate user-entered constitution content** — write verbatim what the user approved at Step 2.
+
+---
+
+## Trust contract
+
+- This skill modifies **exactly one file**: `constitution.md`.
+- It never reads, modifies, or deletes any other project file (it MAY read SKILL.md files in Step 5 detection, but does not write to them).
+- Section 1 of `constitution.md` is treated as read-only by this skill.
+- If the user cancels at Step 2, nothing is written.
+- The Sync Impact Report is always prepended fresh — only one block at a time in the file.
+
+---
+
+## Completion criteria
+
+`/constitution-edit` is complete when:
+
+- Step 0 has run (pre-flight checks pass)
+- Step 1 has run (change identified and section confirmed; Section 1 attempts rejected)
+- Step 2 has been approved by the user (or cancelled — in which case nothing else runs)
+- Step 3 has determined the new semver version
+- Step 4 has applied the content edit
+- Step 5 has detected affected templates (or determined none)
+- Step 6 has built the Sync Impact Report block
+- Step 7 has prepended the block to `constitution.md` and shown the result to the user
+- Step 8 has displayed the wrap-up message

package/template/.harness/skills/db-schema/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: db-schema
+description: This skill should be used whenever the project's database schema is being designed, extended, or reviewed. The skill drives stage 3 of the feature workflow and pairs with the project's backend rule doc (referenced via {{rule_sources}}) and the detailed methodology in references/methodology.md. Trigger when the user invokes /db-schema, says "design the schema", "plan the database changes", when a feature spec introduces new data requirements, when writing or reviewing any file under the project's migration directory, when evaluating whether to add a column or create a new table, when designing access-control policies, or when deciding on indexes.
+argument-hint: [feature-name]
+optional: true
+requires: backend_db_type
+---
+
+# /db-schema
+
+Drive stage 3 of the feature workflow: assess the current database schema, design the delta for the feature, and produce a migration.
+
+> **⟦OPTIONAL PLUGIN⟧** This skill is **only loaded when `backend_db_type` is configured** (i.e., the project has a relational data layer the harness manages). If the project has no backend, no managed database, or uses a NoSQL store where `/db-schema` does not apply, the harness should skip this stage entirely and `/spec-finalize` should route directly to `/execution-plan`. /init confirms this at setup.
+
+> **Backend dialect note:** the methodology and examples below default to relational SQL with Postgres-flavored syntax. Adapt the SQL primitives (RLS expressions, type names, UUID generation) to your backend per the slots: `{{rls_auth_function}}`, your DB's timezone-aware timestamp type, your UUID primitive. If your backend's access-control model differs fundamentally (NoSQL document permissions, mesh authz, etc.), the discipline still applies but the syntax does not — adapt the methodology, keep the process.
+
+## Invocation
+
+- Typical: `/db-schema <feature-name>` (e.g., `/db-schema messaging`)
+- The feature name is passed as `$ARGUMENTS` and identifies the spec file at `{{spec_dir}}$ARGUMENTS.md`.
+
+## Authoritative sources
+
+Before doing anything, load:
+
+1. **The project's backend rule doc** — referenced from `{{rule_sources}}` (project-specific hard rules: RLS enabled by default, the `{{rls_auth_function}}` pattern for the project's backend, forward-only migrations, secrets handling, PII flagging, search-index sync, type regeneration, etc.)
+2. **`references/methodology.md`** (in this skill directory) — the full 12-step design process
+3. **`{{spec_dir}}$ARGUMENTS.md`** — the **CEO spec** (Stage 2 artifact, plain language)
+4. **`{{implementation_dir}}$ARGUMENTS-implementation.md`** — the **implementation notes** (Stage 1/2 artifact, manager domain), if it exists. May contain explicit data-shape decisions; read it but don't take it as canonical — the CEO spec is canonical.
+
+The CEO spec drives the data requirements (every persistent entity, access pattern, retention rule). The implementation notes file may contain prior tech decisions; treat them as input, not gospel.
+
+## Workflow for this stage
+
+1. **Survey existing schema** (read-only) — read every file under `{{migration_dir}}`, then the project's typed-DB-bindings file (if any), then query the live DB via the configured backend MCP / database client to confirm migrations and types are in sync. If drift is found, stop and report to the user before proceeding.
+
+2. **Read the feature spec** — extract every data requirement (entities, relationships, access patterns, retention, search/indexing).
+
+3. **Compute the delta** — for each data requirement, decide: reuse existing / add column / add index / new table / modify access-control policy / add access-control policy. Follow the decision table in `references/methodology.md` § 3.
+
+4. **Design per methodology** — follow steps 4–10 in `references/methodology.md`: new tables, indexes, access-control policies, storage, triggers, search-index sync (if applicable), PII flagging.
+
+5. **Present the proposal to the user** — tables to add, columns, indexes, access-control policies, PII comments. Wait for discussion and approval before writing files. **Wait for user response before continuing.**
+
+6. **On approval, write the migration file** — `{{migration_dir}}<timestamp>_$ARGUMENTS.<ext>` using the project's migration generator. Follow the file structure in `references/methodology.md` § 11.
+
+7. **Invoke backend reviewer agent** to review the migration before it is committed. The reviewer is a **mechanical rule reviewer** — it cites rules from the project's backend rule doc (in `{{rule_sources}}`) and `references/methodology.md`. Judgment about whether the migration is _good_ belongs to the auditor in step 9.
+
+8. **Invoke security/privacy reviewer agent** to review the migration. **Mandatory for every migration** — invocation is not conditional on the writer's self-assessment of whether PII / auth / access-control is touched. Self-assessment is a bias source; mechanical invocation removes it. On a migration that does not touch its scope, the reviewer will return `PASS` quickly; that is the cost of removing the bias.
+
+9. **Auditor cross-model review (judgment layer).** After both junior reviewers return `PASS` (or `CONCERNS`, which advances with a warning), invoke the gate with the adversarial preset. The preset wraps the focus text below with skeptical-review framing and a code-shaped attack surface (auth, data loss, idempotency, races, partial failure, schema drift) that maps directly onto migration hazards.
+
+   ```bash
+   AUDITOR_GATE_PRESET=adversarial \
+   AUDITOR_GATE_TARGET_LABEL="<feature-name> Stage 3 migration" \
+   bash .harness/scripts/auditor-gate.sh review <feature-name> 3 \
+     "Review this migration. Junior reviewers from {{junior_reviewers}} have approved project-rule conformance. Your job: catch what they may share blind spots on. Beyond the preset's attack surface, weigh migration-specific traps: access-control holes (a policy that compiles but doesn't enforce what the spec needs — missing 'with check' on insert/update on backends that support it, an 'OR' in the policy that grants more than intended, a USING expression that lets through rows the spec excludes); missing indexes on policy columns or foreign keys; irreversibility traps (a column add that can't be safely rolled forward without data loss, a backfill DEFAULT that is wrong for some pre-existing rows); PII gaps (a personal-data column without a PII comment, or with overly permissive access-control); enum/type evolution pitfalls (adding values is usually fine; renaming or removing values is painful). Do NOT flag: project conventions per the backend rule doc (forward-only migrations, the {{rls_auth_function}} pattern, type conventions, NOT NULL defaults, RLS-enabled-on-every-table)." \
+     {{migration_dir}}<the-migration-file>
+   ```
+
+   - **Exit 0 (PASS / CONCERNS / WAIVED)** → proceed to step 10. For CONCERNS, surface the logged warning path (`.harness/audits/concerns-*.json`) and remind the CEO to review before commit. For WAIVED, surface the `waiver_reason`.
+   - **Exit 2 (FAIL)** → surface every blocking item verbatim, halt. Do not apply the migration. The user fixes the issues and re-invokes `/db-schema`, or applies fixes inline and re-runs the gate manually.
+   - **Exit 1 (script error / Universal Core WAIVED rejected / missing waiver_reason / legacy verdict)** → surface stderr, halt.
+
+10. **Remind the user** to run `bash .harness/scripts/post-migration.sh` after applying the migration **locally**. The script does whatever the project needs after a migration:
+    - **Refresh / reload backend caches** that don't auto-reload on `migration up` (e.g., schema caches in some setups).
+    - **Regenerate typed bindings** from the live local DB. Stage 4 (execution-plan) and any feature code that imports from the typed bindings cannot proceed with stale types.
+    The exact contents of `post-migration.sh` are project-specific; /init seeds it based on the configured `backend_db_type` and `tech_stack`.
+
+11. **Check whether the app is hitting a remote backend project.** Inspect the project's `.env` (or equivalent) for the backend URL. If it points at anything other than a local instance, the migration must ALSO be pushed to the remote project — otherwise smoke-testing the feature in Stage 7 will fail against the remote, even though the local stack is healthy. Apply via the backend's MCP / CLI tool. Managed backends usually auto-refresh their schema cache after a migration applies — no separate restart needed there. Confirm per your backend's documentation.
+
+## Trust contract
+
+- **Surface every reviewer verdict verbatim.** No "reviewer says it's fine, proceeding." The user sees each reviewer's findings and verdict line in full before any next step is taken.
+- **Reviewer invocation is mandatory and ordered.** Backend reviewer first, security/privacy reviewer second (always, not conditional on self-assessment), auditor third. Skill has no judgment authority to skip a reviewer "because the migration looks simple."
+- **Auditor verdict is parsed deterministically from the gate's exit code.** No prose interpretation. The four verdicts are `PASS` (advance silently), `CONCERNS` (advance with logged warning at `.harness/audits/concerns-*.json` for CEO commit-time review), `FAIL` (halt), and `WAIVED` (CEO override only; rejected by the gate if any blocking item cites Universal Core).
+- **On disagreement** (junior reviewers approve, auditor requests changes): auditor wins by default. Surface both views; user overrides explicitly if they disagree.
+- **Migration is not applied locally until all three reviewers advance (PASS, CONCERNS, or — for the auditor only — a CEO-issued WAIVED with valid `waiver_reason`).** Halt-on-FAIL means actually halting; do not "apply locally to test, then fix later." CONCERNS advances but the warning must be surfaced to the CEO before commit.
+
+## Completion criteria
+
+Stage 3 is complete when:
+
+- A new migration file exists under `{{migration_dir}}` and has been applied locally
+- `bash .harness/scripts/post-migration.sh` has been run (cache refreshed + types regenerated)
+- Backend reviewer has returned `PASS` or `CONCERNS` (FAIL halts)
+- Security/privacy reviewer has returned `PASS` or `CONCERNS` (mandatory for every migration, not conditional; FAIL halts)
+- `.harness/scripts/auditor-gate.sh` returned exit 0 for stage 3 (`PASS`, `CONCERNS`, or `WAIVED`) — `.harness/state/auditor-approvals/<feature>-stage3.json` exists with a non-FAIL `verdict`
+- Search-index sync mechanism is documented (if applicable)
+
+## Anti-patterns to reject
+
+See `references/methodology.md` § "Anti-patterns to reject" for the full list. Common ones:
+
+- `select *` in any code
+- Access-control disabled on a table
+- "We'll add access-control later"
+- Renaming a column in place (always additive)
+- Business logic in triggers when the app layer can do it
+
+---
+
+## Checkpoint + decision-log integration (MAGI Archivist)
+
+If schema work happened:
+
+```bash
+.harness/scripts/checkpoint-write.sh \
+  --feature <feature-slug> \
+  --stage 4 \
+  --stage-complete 3 \
+  --artifact-schema <path-to-migration-file> \
+  --append-audit "$(jq -c '{stage:3, verdict, risk:.risk_score, at:now|todate}' .harness/state/auditor-approvals/<feature>-stage3.json)"
+```
+
+If skipped (no backend configured):
+
+```bash
+.harness/scripts/checkpoint-write.sh \
+  --feature <feature-slug> \
+  --stage 4 \
+  --stage-skip 3 --skip-reason "no backend_db_type configured"
+```
+
+MAGI Archivist surfaces skipped stages in the `/pickup` report so users can see deliberate skips vs forgotten stages.
+
+---
+
+## Final message to CEO (natural-language, not slash-command)
+
+After Stage 3 completes (schema designed + migration written + auditor verdict), display (in CEO's OS locale):
+
+```
+✅ Stage 3 完成 — <feature> 的数据库改动设计好了
+   迁移文件: <path>
+   MAGI Verdict: <PASS/CONCERNS/WAIVED>, risk = N
+
+接下来可以：
+  👉 「继续」/「下一步」      — 我做执行计划 (Stage 4 — 列出要改的每个文件)
+  👉 「看迁移」               — 我把迁移文件念给你听
+  👉 「改 schema」+ 说改什么  — 重做 Stage 3
+  👉 「放弃」                 — 不做这个功能了
+```
+
+On "继续" → invoke `/execution-plan <feature>` silently.

package/template/.harness/skills/db-schema/references/methodology.md

@@ -0,0 +1,202 @@
+# DB Schema Methodology
+
+Reference document for designing, reviewing, and evolving the project's database schema. Loaded by `/db-schema` and the project's backend reviewer agent.
+
+> **Dialect note:** the methodology is written for **relational databases with row-level access control** (the most common shape for harness-managed backends). SQL examples below use Postgres-flavored syntax; adapt to your `backend_db_type`. The discipline (12-step process, decision table, design principles) is database-agnostic — the syntax is illustrative.
+
+This document is the **how**. The **what** (hard rules) lives in the project's backend rule doc (referenced via `{{rule_sources}}`) — read both together. Do not restate rules from there; reference them.
+
+## Order of operations
+
+Follow this order every time. Skipping a step causes schema drift or duplicate modeling.
+
+### 1. Survey the existing schema — READ-ONLY
+
+Before proposing anything, know what is already there.
+
+Read in this order:
+
+1. **Every file under `{{migration_dir}}`** — source of truth for schema history. Read every file, not just the latest.
+2. **The project's typed-DB-bindings file** (if any) — generated typed view of the current schema. Confirms what the app currently sees.
+3. **The backend MCP / database client (read-only)** — query the live database to confirm migrations and types are in sync. Flag any drift to the user immediately; do not proceed until resolved.
+
+At the end of this step, produce a **one-paragraph summary** of the schema areas relevant to the feature:
+
+- Which existing tables are related?
+- Which existing columns might be reused?
+- Which access-control policies already cover the relevant rows?
+
+### 2. Read the feature spec
+
+Read `{{spec_dir}}<feature>.md` (Stage 2 artifact). Extract every data requirement:
+
+- Entities that need to be stored
+- Relationships between entities
+- Access patterns (who reads what, who writes what, query shape)
+- Retention / deletion behavior
+- Search / indexing needs
+
+If the spec does not answer one of these, stop and ask the user. Do not guess.
+
+### 3. Compute the delta
+
+Decide, for each data requirement from step 2, one of:
+
+| Outcome                                         | When                                                        |
+| ----------------------------------------------- | ----------------------------------------------------------- |
+| **Reuse existing table/column as-is**           | Existing model already fits                                 |
+| **Add columns to existing table**               | New attribute of an existing entity                         |
+| **Add index to existing table**                 | New query pattern on existing data                          |
+| **Add new table**                               | New entity with no existing home                            |
+| **Modify existing access-control policy**       | New access pattern changes who can read/write existing rows |
+| **Add new access-control policy**               | New table or new CRUD verb on existing table                |
+
+**Never**:
+
+- Rename or drop a column in a single migration — write an additive migration, let the app switch, then drop in a later migration.
+- Reshape an existing table to "fit" a new feature if a new table is cleaner. Solo-maintainable beats clever reuse.
+
+### 4. Design new tables (if any)
+
+For each new table, decide in this order:
+
+1. **Name** — plural, snake_case (or your stack's convention), domain-prefixed only if needed to avoid ambiguity.
+2. **Primary key** — UUID with the backend's generator (e.g., `id uuid primary key default gen_random_uuid()` in Postgres) is the default. Use a composite PK only for pure junction tables.
+3. **Foreign keys** — every relationship declared explicitly. Decide `on delete` per relationship: `cascade` for owned children, `set null` for soft references, `restrict` when deletion should be blocked.
+4. **Timestamps** — `created_at` (timezone-aware) on every table, with default `now()`. `updated_at` only if the app reads it; maintain via trigger (see step 8).
+5. **Columns** — pick the narrowest correct type. Prefer timezone-aware timestamps over naive ones. Prefer unbounded text types over arbitrary length caps unless you genuinely need the cap.
+6. **Constraints** — `not null` by default; only omit when nullability is meaningful. `check` constraints for enumerations and ranges. Unique constraints for business keys.
+
+### 5. Design indexes
+
+For every `WHERE`, `ORDER BY`, and `JOIN` column the app will use, decide:
+
+- **Single-column index** — default for simple equality / range filters.
+- **Composite index** — when queries filter on multiple columns together. Column order matters: equality columns first, then range.
+- **Partial index** — when queries always filter on a boolean/enum (`WHERE is_active = true`). Reduces index size.
+- **No index** — justify in a comment in the migration. Small tables (< ~1000 rows expected) may skip indexes.
+
+Cross-reference the project's backend rule doc for any project-specific indexing rules. Every `WHERE` column either has an index or a justified exclusion comment.
+
+### 6. Design access-control policies
+
+For every table, for every CRUD verb the app uses, write an explicit policy.
+
+Postgres + RLS pattern (adapt to your backend's access-control model):
+
+```sql
+create policy "<verb> own <resource>"
+on <table> for <select|insert|update|delete>
+to authenticated
+using ( <row matches caller via {{rls_auth_function}}> )
+with check ( <row being written matches caller via {{rls_auth_function}}> );
+```
+
+Rules:
+
+- Use the project's configured `{{rls_auth_function}}` for the auth-context expression (set at /init based on `backend_db_type`).
+- Default deny. If a verb has no policy, it is denied.
+- Split "own rows" and "others' rows" into separate policies when access rules differ — clearer than one complex `using` expression.
+- Anonymous policies only when the feature explicitly requires public access; call this out to the user.
+
+### 7. Storage buckets (if the feature uploads files)
+
+If the feature uploads images or files and the backend supports file storage:
+
+1. Declare the bucket in the migration.
+2. Set the file_size_limit and allowed_mime_types in bucket metadata — do not leave these open-ended.
+3. Write storage access-control policies for each CRUD verb the app uses, same pattern as table-level policies.
+4. Reference the project's backend rule doc for the exact constraints.
+
+If the backend doesn't manage file storage natively, document the chosen file-storage approach in the feature's implementation notes.
+
+### 8. Triggers (if needed)
+
+Only add a trigger when the invariant cannot be enforced at the app layer reliably.
+
+Common cases:
+
+- `updated_at` auto-maintenance.
+- Derived/denormalized columns that must stay in sync.
+- Search-index sync (see step 9).
+
+Every trigger declares in a comment:
+
+- **Purpose** — what invariant it enforces
+- **Firing event** — `before insert`, `after update of <cols>`, etc.
+- **Privilege mode** — invoker by default; definer only with a justification comment and security/privacy review.
+
+### 9. Search-index sync (if the table is search-indexed)
+
+If the new/modified table feeds an external search index (Meilisearch, Elasticsearch, Algolia, etc.), document the sync mechanism in the migration file or a sibling `.md`:
+
+- **Trigger-based** — DB trigger writes to an outbox table; an ingest worker / edge function drains it.
+- **Direct push from function** — backend function synchronously updates the search index on mutation.
+- **Periodic job** — only for eventual-consistency-tolerant data.
+
+State which one and why. Required if the project's backend rule doc mandates it.
+
+### 10. PII and security review
+
+If the table contains any of:
+
+- Phone numbers, email addresses, real names
+- Location data (coordinates, addresses)
+- Chat messages or private content
+- Reports, moderation data
+- Payment information
+- Any other personal data per the project's PII definition
+
+**Flag for security/privacy reviewer.** Add a `-- PII: <what>` comment (or your backend's equivalent annotation) above the relevant columns in the migration. The security/privacy reviewer is called at the end of Stage 3 — mandatorily, not conditionally.
+
+### 11. Write the migration
+
+One migration file per logical change. Prefer one migration per feature; split only when the feature has clearly separable phases (e.g., schema first, then seed data).
+
+File name: `{{migration_dir}}<timestamp>_<feature_or_change>.<ext>` — generate with the project's migration tool.
+
+Structure inside the file, in this order:
+
+1. Create new tables
+2. Alter existing tables (add columns, constraints)
+3. Create indexes
+4. Enable access-control on new tables
+5. Create access-control policies
+6. Create functions and triggers
+7. Storage bucket declarations + storage policies (if applicable)
+8. Comments documenting PII, trigger purposes, non-obvious decisions
+
+**Forward-only.** Never write a down migration. To undo, write a new forward migration.
+
+### 12. Regenerate types
+
+After the migration is applied, run the project's type-regeneration command (configured in `.harness/scripts/post-migration.sh`).
+
+This step is part of Stage 3 completion. A feature cannot advance to Stage 4 with stale types.
+
+## Output of a `/db-schema` run
+
+At the end of Stage 3, the following must exist:
+
+- One or more new files under `{{migration_dir}}`, applied locally.
+- An updated typed-DB-bindings file (if the project uses one).
+- Confirmation to the user that search-index sync (if applicable) is documented.
+- Backend reviewer review complete (PASS or CONCERNS; FAIL halts).
+- Security/privacy reviewer review complete (PASS or CONCERNS, mandatory; FAIL halts).
+- Auditor review complete (PASS, CONCERNS, or WAIVED; FAIL halts).
+
+## Anti-patterns to reject
+
+- `select *` in any code — always list columns.
+- Access-control disabled on a table — never. Every table ships with access-control enabled.
+- "We'll add access-control later" — rejected. Policies ship with the table.
+- Rationalizing a missing index with "the table will be small" without a row-count estimate.
+- A policy that mixes "own" and "others'" rules in one `using` expression when splitting would be clearer.
+- Renaming a column to "clean up" — always additive, never in-place.
+- Business logic in database triggers when the app layer can do it — triggers are for invariants, not convenience.
+
+## Reference
+
+- The project's backend rule doc (in `{{rule_sources}}`) — hard rules (access-control enabled, the `{{rls_auth_function}}` pattern, forward-only, secrets, etc.)
+- The project's auth rule doc (in `{{rule_sources}}`) — auth context for access-control policies
+- The project's env rule doc (in `{{rule_sources}}`) — secret handling for backend functions that read/write the DB