opencode-agent-harness 0.0.0-stage → 0.3.14

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (171) hide show
  1. package/CHANGELOG.md +217 -0
  2. package/LICENSE +21 -0
  3. package/README.md +636 -2
  4. package/bin/agent-harness.js +3182 -0
  5. package/contrib/global-plugins/README.md +49 -0
  6. package/contrib/global-plugins/harness-freshness.ts +355 -0
  7. package/package.json +86 -4
  8. package/templates/.agents/AGENTS.md +148 -0
  9. package/templates/.agents/features/INDEX.md +10 -0
  10. package/templates/.agents/handoffs/README.md +87 -0
  11. package/templates/.agents/memory/dev-loop.md +59 -0
  12. package/templates/.agents/memory/domain-map.md +29 -0
  13. package/templates/.agents/memory/environments.md +35 -0
  14. package/templates/.agents/memory/flow-map.md +23 -0
  15. package/templates/.agents/memory/history.md +7 -0
  16. package/templates/.agents/memory/locations.md +14 -0
  17. package/templates/.agents/memory/model-routing.md +261 -0
  18. package/templates/.agents/memory/orchestration.md +183 -0
  19. package/templates/.agents/memory/owned-files.md +19 -0
  20. package/templates/.agents/memory/product-principles.md +37 -0
  21. package/templates/.agents/memory/quality-parameters.md +37 -0
  22. package/templates/.agents/memory/stack-versions.md +35 -0
  23. package/templates/.agents/memory/test-design-parameters.md +36 -0
  24. package/templates/.agents/nightly.json +17 -0
  25. package/templates/.agents/qa-plans/README.md +70 -0
  26. package/templates/.agents/qa-runs/README.md +21 -0
  27. package/templates/.agents/reviews/README.md +47 -0
  28. package/templates/.agents/rules/00-operating.md +199 -0
  29. package/templates/.agents/skills/data-engineer/SKILL.md +31 -0
  30. package/templates/.agents/skills/devops-engineer/SKILL.md +50 -0
  31. package/templates/.agents/skills/diagnostics-expert/SKILL.md +44 -0
  32. package/templates/.agents/skills/docs/SKILL.md +140 -0
  33. package/templates/.agents/skills/features/SKILL.md +187 -0
  34. package/templates/.agents/skills/frontend-engineer/SKILL.md +81 -0
  35. package/templates/.agents/skills/handoff/SKILL.md +85 -0
  36. package/templates/.agents/skills/mobile-engineer/SKILL.md +101 -0
  37. package/templates/.agents/skills/planner/SKILL.md +112 -0
  38. package/templates/.agents/skills/product-manager/SKILL.md +115 -0
  39. package/templates/.agents/skills/qa-architect/SKILL.md +224 -0
  40. package/templates/.agents/skills/qa-runner/SKILL.md +64 -0
  41. package/templates/.agents/skills/security-engineer/SKILL.md +53 -0
  42. package/templates/.agents/skills/system-architect/SKILL.md +42 -0
  43. package/templates/.agents/skills/ui-designer/SKILL.md +71 -0
  44. package/templates/.github/workflows/ci.yml +148 -0
  45. package/templates/.github/workflows/deploy-uat.yml +95 -0
  46. package/templates/.github/workflows/nightly.yml +83 -0
  47. package/templates/.github/workflows/uat-health.yml +41 -0
  48. package/templates/.husky/pre-push +23 -0
  49. package/templates/.ignore +28 -0
  50. package/templates/.opencode/agents/data-engineer.md +37 -0
  51. package/templates/.opencode/agents/devops-engineer.md +37 -0
  52. package/templates/.opencode/agents/diagnostics-expert.md +37 -0
  53. package/templates/.opencode/agents/docs.md +37 -0
  54. package/templates/.opencode/agents/features.md +21 -0
  55. package/templates/.opencode/agents/frontend-engineer.md +37 -0
  56. package/templates/.opencode/agents/handoff.md +21 -0
  57. package/templates/.opencode/agents/mobile-engineer.md +37 -0
  58. package/templates/.opencode/agents/planner.md +34 -0
  59. package/templates/.opencode/agents/product-manager.md +29 -0
  60. package/templates/.opencode/agents/qa-architect.md +27 -0
  61. package/templates/.opencode/agents/qa-runner.md +17 -0
  62. package/templates/.opencode/agents/security-engineer.md +37 -0
  63. package/templates/.opencode/agents/system-architect.md +37 -0
  64. package/templates/.opencode/agents/ui-designer.md +37 -0
  65. package/templates/.opencode/commands/board.md +15 -0
  66. package/templates/.opencode/commands/checkpoint.md +25 -0
  67. package/templates/.opencode/commands/feature.md +56 -0
  68. package/templates/.opencode/commands/finish.md +36 -0
  69. package/templates/.opencode/commands/next.md +49 -0
  70. package/templates/.opencode/commands/report.md +55 -0
  71. package/templates/.opencode/commands/resume.md +39 -0
  72. package/templates/.opencode/commands/switch-model.md +34 -0
  73. package/templates/.opencode/commands/tidy.md +49 -0
  74. package/templates/.opencode/plugins/backlog-notify.ts +57 -0
  75. package/templates/.opencode/plugins/backlog.ts +272 -0
  76. package/templates/.opencode/plugins/checkpoint.ts +160 -0
  77. package/templates/.opencode/plugins/context-guard.ts +1164 -0
  78. package/templates/.opencode/plugins/diff.ts +85 -0
  79. package/templates/.opencode/plugins/gates.ts +71 -0
  80. package/templates/.opencode/plugins/job-notify.ts +241 -0
  81. package/templates/.opencode/plugins/orient.ts +67 -0
  82. package/templates/.opencode/plugins/session.ts +89 -0
  83. package/templates/.opencode/plugins/wait.ts +101 -0
  84. package/templates/.opencode/plugins/where.ts +70 -0
  85. package/templates/.opencode/skills/bounded-explore/SKILL.md +38 -0
  86. package/templates/.opencode/skills/dev-loop/SKILL.md +87 -0
  87. package/templates/.vercelignore +16 -0
  88. package/templates/AGENTS.md +27 -0
  89. package/templates/BACKLOG.md +95 -0
  90. package/templates/docs/ci-cd-pipeline.md +81 -0
  91. package/templates/docs/gates.md +128 -0
  92. package/templates/docs/mcp-integrations.md +97 -0
  93. package/templates/docs/mobile-testing.md +555 -0
  94. package/templates/docs/nightly-testing.md +106 -0
  95. package/templates/docs/wsl-optimizations.md +290 -0
  96. package/templates/opencode.json +188 -0
  97. package/templates/scripts/agent-report.js +541 -0
  98. package/templates/scripts/agent-search.sh +117 -0
  99. package/templates/scripts/backlog.js +1924 -0
  100. package/templates/scripts/board-service.sh +214 -0
  101. package/templates/scripts/checkpoint.js +290 -0
  102. package/templates/scripts/finalize.js +416 -0
  103. package/templates/scripts/nightly.js +913 -0
  104. package/templates/scripts/orient.js +514 -0
  105. package/templates/scripts/qa/board-client.js +323 -0
  106. package/templates/scripts/qa/board-lib.js +96 -0
  107. package/templates/scripts/qa/board-sync.js +499 -0
  108. package/templates/scripts/qa/capacity-lib.js +916 -0
  109. package/templates/scripts/qa/check-backlog.js +434 -0
  110. package/templates/scripts/qa/check-capacity.js +85 -0
  111. package/templates/scripts/qa/check-ci-policy.js +164 -0
  112. package/templates/scripts/qa/check-concurrency.js +344 -0
  113. package/templates/scripts/qa/check-dispatch-config.js +296 -0
  114. package/templates/scripts/qa/check-docs.js +288 -0
  115. package/templates/scripts/qa/check-integrate.js +98 -0
  116. package/templates/scripts/qa/check-linger.js +160 -0
  117. package/templates/scripts/qa/check-prefix-stability.js +187 -0
  118. package/templates/scripts/qa/check-product.js +177 -0
  119. package/templates/scripts/qa/check-qa-plan.js +378 -0
  120. package/templates/scripts/qa/check-qa-scripts.js +85 -0
  121. package/templates/scripts/qa/check-quality.js +249 -0
  122. package/templates/scripts/qa/check-test-wiring.js +253 -0
  123. package/templates/scripts/qa/check-worktrees.js +93 -0
  124. package/templates/scripts/qa/ci-triage.js +346 -0
  125. package/templates/scripts/qa/ci-usage-lib.js +185 -0
  126. package/templates/scripts/qa/ci-wait-lib.js +294 -0
  127. package/templates/scripts/qa/command-classifier.js +552 -0
  128. package/templates/scripts/qa/context-guard-core.js +1618 -0
  129. package/templates/scripts/qa/diff.js +174 -0
  130. package/templates/scripts/qa/feature-scaffold.js +224 -0
  131. package/templates/scripts/qa/fixtures/backlog.md +104 -0
  132. package/templates/scripts/qa/governance.js +174 -0
  133. package/templates/scripts/qa/hash-file.js +32 -0
  134. package/templates/scripts/qa/lease-lib.js +263 -0
  135. package/templates/scripts/qa/merge-backlog.js +324 -0
  136. package/templates/scripts/qa/mobile-e2e/analyze-timings.js +300 -0
  137. package/templates/scripts/qa/mobile-e2e/apk-cache.js +420 -0
  138. package/templates/scripts/qa/mobile-e2e/backend-build-cache.js +203 -0
  139. package/templates/scripts/qa/mobile-e2e/boot-emulator.sh +432 -0
  140. package/templates/scripts/qa/mobile-e2e/build-apk.sh +210 -0
  141. package/templates/scripts/qa/mobile-e2e/check-flows.js +568 -0
  142. package/templates/scripts/qa/mobile-e2e/config.yaml +18 -0
  143. package/templates/scripts/qa/mobile-e2e/device-down.sh +88 -0
  144. package/templates/scripts/qa/mobile-e2e/device-up.sh +258 -0
  145. package/templates/scripts/qa/mobile-e2e/ios-simulator-down.sh +72 -0
  146. package/templates/scripts/qa/mobile-e2e/ios-simulator-up.sh +153 -0
  147. package/templates/scripts/qa/mobile-e2e/job-events.js +181 -0
  148. package/templates/scripts/qa/mobile-e2e/prewarm.sh +56 -0
  149. package/templates/scripts/qa/mobile-e2e/run-detached.sh +222 -0
  150. package/templates/scripts/qa/mobile-e2e/run-maestro.js +1543 -0
  151. package/templates/scripts/qa/mobile-e2e/ui-dump.js +327 -0
  152. package/templates/scripts/qa/models.allowlist.txt +32 -0
  153. package/templates/scripts/qa/provider-stats.js +878 -0
  154. package/templates/scripts/qa/run-clean.js +83 -0
  155. package/templates/scripts/qa/run-gates.js +213 -0
  156. package/templates/scripts/qa/run-loop.js +220 -0
  157. package/templates/scripts/qa/session-recon.js +512 -0
  158. package/templates/scripts/qa/store-lib.js +324 -0
  159. package/templates/scripts/qa/tool-lib.js +134 -0
  160. package/templates/scripts/qa/where.js +214 -0
  161. package/templates/scripts/qa/worktree-hygiene.js +217 -0
  162. package/templates/scripts/qa/wslconfig-merge.js +157 -0
  163. package/templates/scripts/serve.js +1328 -0
  164. package/templates/scripts/setup-nightly.sh +185 -0
  165. package/templates/scripts/setup-tmpfs.sh +374 -0
  166. package/templates/scripts/ship.js +586 -0
  167. package/templates/scripts/switch-reasoning-model.ps1 +101 -0
  168. package/templates/scripts/switch-reasoning-model.sh +104 -0
  169. package/templates/scripts/wait-for.js +342 -0
  170. package/templates/scripts/wsl-gpu.sh +180 -0
  171. package/templates/scripts/wsl-tune.sh +319 -0
@@ -0,0 +1,148 @@
1
+ # Project Rules & Operating Guidelines
2
+
3
+ The canonical rulebook. It carries the durable **standards**; the always-on digest
4
+ is the root `AGENTS.md`, and the operating mechanics (dispatch economics, bounded
5
+ retries, context budget, capacity guards, session checklist) live in
6
+ `.agents/rules/00-operating.md`. Read both first — this file is the detail of
7
+ record for the rules they point at, not a second copy of either.
8
+
9
+ ## 1. Fact-Based, Zero-Guessing SDLC
10
+
11
+ - **Zero-Speculation Rule**: NEVER guess, hypothesize without evidence, or assume the root cause of an error, performance lag, or system behavior. Speculation is forbidden across all personas and workflow stages.
12
+ - **Evidence-First Engineering**: Every diagnostic conclusion, fix, architectural decision, and enhancement MUST be grounded in observable facts: live server logs, telemetry traces, database records, or verified runtime execution. Know the project's debug/log endpoints — they are (or should be) recorded in `.agents/memory/locations.md`.
13
+ - **Mandatory Telemetry Before Fixes**: If logs or telemetry are absent or insufficient, FIRST add structured instrumentation, execute or have the user reproduce, inspect the captured output, and ONLY THEN implement based on that data.
14
+ - **Authentic Runtime Execution**: Never substitute real runtime calls with ad-hoc scripts that bypass actual config, env vars, middleware, or request pipelines. Verify through the real APIs/functions the app uses.
15
+ - **Scientific Progression Gate**: A fix is not complete until live logs or automated runtime tests demonstrate the failure mode no longer occurs in real runtime conditions.
16
+
17
+ ## 2. Dynamic Data & Business-Logic Integrity
18
+
19
+ - **No Hardcoded Mock Lists**: Never create hardcoded lists (fake records, mock reviews, static fallback arrays) without explicit user approval. Prefer dynamic queries and database-backed settings.
20
+ - **Environment data boundary**: three environments — `development` (dirty by design: QA/test data lives here), `uat`, and `production` (both enforced clean). Only code, schema migrations, and idempotent seeds move FORWARD (dev → uat → prod); data never does — no `pg_dump`/restore/copy of one environment's database into another. Registry: `.agents/memory/environments.md`; promotion and QA rules: §7.
21
+
22
+ ## 3. UI, Mobile Ergonomics & RTL Support
23
+
24
+ - **Zero Native Popups**: Never use `Alert.alert()`, `alert()`, `confirm()`, or `prompt()`. Use inline toasts, bottom sheets, inline state transitions, or haptics.
25
+ - **Progressive Hydration & Cold-Start**: Never render empty states while waiting on async auth/sync. Hydrate from local cache so the UI renders immediately.
26
+ - **The 5 Essential UI States**: Every screen/list component must handle Ideal, Empty (with CTA), Loading (skeleton), Error (retry), and Partial/single-item states.
27
+ - **Error-Handling Contract (Mobile)**: Every `catch` block in a native screen must (1) fire an error haptic, (2) set a user-visible error state that renders inline — never `console.warn` alone, and (3) provide a retry or dismissal path. Follow the reference pattern in `.agents/skills/mobile-engineer/SKILL.md`.
28
+ - **Cross-Screen Consistency ("Fix One, Fix All")**: When you implement a UX pattern in one screen, grep for analogous screens and apply it globally; if scope is too large, log a deferred item in the handoff with exact files/patterns. A local-only fix is a regression-in-waiting. Mechanically enforced by `test:qa-plan` via `.agents/memory/flow-map.md`: a change that touches a registered flow must address EVERY sibling surface (other codebases like `mobile/`, other layers) and every declared optional variant in the QA-plan audit — covered `->`, or `audited:` with a reason (including `deferred — logged in handoff`). A sibling the plan does not name fails the gate.
29
+ - **Bidirectional & RTL**: Use logical properties (`ps-*`, `pe-*`, `ms-*`, `me-*`, `text-start`, `text-end`) never physical ones (`pl-*`, `left-*`); use inverted horizontal lists / direction-aware layout in native RTL; pass dynamic `dir` to UI primitives.
30
+ - **Legacy Pruning & Physical Walkthrough**: When introducing a new flow/paradigm, explicitly audit and PRUNE obsolete mechanisms that contradict it — never bolt new steps on top of removed ones. Trace every physical/interaction flow step-by-step from each actor's perspective to eliminate unnecessary friction.
31
+
32
+ ## 4. Framework & Backend Architecture
33
+
34
+ - **Verify Stack Versions First**: Confirm versions against `.agents/memory/stack-versions.md` before writing framework-specific code. Never assume a newer/older convention.
35
+ - **Stack-Specific Gotchas**: Framework/library gotchas (async route params, strict-typing quirks, ORM generator/config layout, native runtime caveats) live in `.agents/memory/stack-versions.md` — read the relevant section before coding against that layer.
36
+ - **Privacy & Visibility Tiers**: Enforce the project's tier model (`.agents/memory/domain-map.md` §Visibility tiers) across all data-access endpoints.
37
+
38
+ ## 5. Dispatch Standards & Workflow Discipline
39
+
40
+ Operating mechanics live in `.agents/rules/00-operating.md` (§Step Zero,
41
+ §Dispatch economics, §Context budget & lifecycle, §Machine capacity, §Verification
42
+ & retry discipline). This section is the detail of record those point at, plus the
43
+ gotchas that do not belong in a digest.
44
+
45
+ - **Step Zero — subagent & model routing (non-negotiable)**: Dispatch the relevant persona via the `subagent` tool — each runs its own `model:`. Do NOT inline persona-owned work on the main model. Read `.agents/memory/model-routing.md` at session start; trivial or single-surface/single-file changes execute directly (00-operating §Dispatch economics).
46
+ - **Persona map**:
47
+ | Work area | Persona |
48
+ |---|---|
49
+ | Task decomposition → value-led dispatch plan (product-first) | `planner` |
50
+ | Web app (React/Next.js/Tailwind/shadcn) | `frontend-engineer` |
51
+ | Mobile native (Expo/React Native) | `mobile-engineer` |
52
+ | Design system / tokens / shared components | `ui-designer` |
53
+ | QA strategy (risk + tier + progression tests) | `qa-architect` |
54
+ | QA execution (run tiers, data cleanup) | `qa-runner` |
55
+ | DB schema / data model / tenancy / sync | `system-architect` |
56
+ | Auth, secrets, input validation, deps | `security-engineer` |
57
+ | Error / performance / API debugging | `diagnostics-expert` |
58
+ | Features, gamification, product journeys | `product-manager` |
59
+ | Data ingestion / entity resolution | `data-engineer` |
60
+ | Deployment (dev→uat→prod promotion) / cron / secrets / build+release | `devops-engineer` |
61
+ | Session wrap-up / handoff | `handoff` |
62
+ | Feature backlog registration + doc-tree scaffolding (registrar only — not authoring) | `features` |
63
+ | Human-facing docs (README / CHANGELOG / docs / ADRs) | `docs` |
64
+ - **Waivers** (the only way to skip a persona): a persona may be skipped only when (a) the change is fully covered by an automated gate on push or in the QA tiers, AND (b) the skip is pre-audited in `.agents/memory/` with a cited pointer. Log every waiver as `waived: <persona>` with `reason: <gate|pointer>`.
65
+ - **Evidence-based escalation**: escalate to the Pro tier only on repeated failure after materially different fixes, contradictory evidence, cross-module reasoning failure, security-sensitive ambiguity, unresolved concurrency/state issues, or a genuinely-blocking workaround risk. Do NOT escalate on a long answer, technical complexity alone, a request for more context, or uncertainty without evidence. Model tiers: `.agents/memory/model-routing.md`.
66
+ - **Dispatch failure ladder**: a provider funds/quota error is a STOP, not a failure to work around — announce the failed provider/model and the exact unfinished step, checkpoint, and wait for the user's explicit top-up-complete message; never retry, degrade inline, or silently skip. Any other failure gets one retry with a materially changed input (instructions / context / model / decomposition / diagnostics); after that, do the work inline and log `degraded: <persona> model: <reason>`. Provider priority and model tiers: `.agents/memory/model-routing.md`; full ladder: 00-operating §Dispatch economics.
67
+ - **No suppression shortcuts**: never accept (or produce) file-level `/* eslint-disable */`, `@ts-nocheck`, or `@ts-ignore` to hit a metric. Suppressions are line-level only and each carries a reason — a file-level disable is a rules violation, not a fix.
68
+ - **No output bloat**: never paste large files/diffs into chat; apply edits with the edit tool, never print a change as a code block.
69
+ - **Repeated-command / retry-loop detection**: never re-run the same command in the same session with the same state expecting a different result. When a command would repeat (`same_failure_turns` / `identical_tool_calls` / `no_state_change_turns` — thresholds in `.agents/memory/orchestration.md`), stop, change something material, or report. A gate repeated with `files_changed = 0`, the same command, and the same failure is a retry loop, not a retry.
70
+ - **Read narrowly**: search first (`Grep`/`Glob`, `npm run search`), then read a targeted `offset`/`limit` range — never read a big file blind. Batch independent reads/searches in parallel; do not re-read a file already in context (use `offset`/`limit` or `Grep` for the changed lines). Tool mechanics: 00-operating §Non-negotiable laws (law 6).
71
+ - **Long-lived processes**: start a dev server, emulator, Metro, or Maestro driver detached through `node scripts/serve.js start --cmd "<command>" [--url <health url> | --port <n>] [--name <label>]`; poll it with `node scripts/wait-for.js` (never `sleep`-and-pray), read `.serve/<name>.out.log` on failure, and `serve.js stop`/`stop-all` when the tier passes. Never background a long-lived process in your own shell — the tree stays attached to the tool's console and the call hangs. A bare `setsid bash -c '… > log 2>&1' &` is NOT detached (the wrapper keeps the tool's socket open); if you must launch by hand, redirect the wrapper's own fds: `setsid sh -c 'exec <command>' </dev/null >log 2>&1 &`. Anti-pattern and recovery: `.agents/skills/mobile-engineer/SKILL.md`, `docs/mobile-testing.md`.
72
+ - **Wedged launch**: never kill a running tool call — let it finish, then checkpoint/finish — except a confirmed wedged launch (the command's shell has exited yet a detached descendant holds the tool's output socket, so the call can never return). Interrupt it, then verify state (`serve.js list`, `.serve/<name>.out.log`, `adb devices`, the health URL/port) before continuing; never wait indefinitely or infer state from the abort.
73
+ - **Capacity classification**: heavy tiers are classified by **program** (`scripts/qa/command-classifier.js`), not by a device serial or artifact path in the arguments; one live `--group` (device tier's emulator + dev server) counts as ONE tier. Diagnose a failed device step with `node scripts/qa/mobile-e2e/ui-dump.js`, never a hand-rolled `adb`/`python` probe. Envelope and guards: 00-operating §Machine capacity; details: `docs/wsl-optimizations.md`.
74
+ - **MCP servers are context + RAM, so scope them per agent, dev-only**: deny the server's tools globally (a `<server>_*` rule in `permissions`) and re-enable only for the persona that needs live external state; point any DB server at the **development** database only. Do not enable GitHub MCP. Details: `docs/mcp-integrations.md`.
75
+ - **Prefer memory over re-derivation**: persist non-obvious facts to `.agents/memory/`, and check `.agents/memory/locations.md` (or `Glob`) before reading an unknown path — never guess a path.
76
+
77
+ ## 6. Smart Tiered Testing & Progression Protocol
78
+
79
+ - Never run heavy regression suites blindly for small changes.
80
+ - **Split QA personas**: `qa-architect` (thinks — inspects the diff, audits gaps, selects the minimal tier, authors progression tests) vs `qa-runner` (does — executes the chosen tier, reports pass/fail verbatim). The thinker never runs; the doer never designs. Because `qa-architect` denies the `shell` action, an architect-authored progression is NOT verifiable until `qa-runner` load-gates it first (`node --check` for `.js` suites; load + ≥ 1 executed assertion for `.ts`) — never let an architect-authored file reach "done" on the strength of a plan alone.
81
+ - **Static ≠ runtime**: never declare UI/mobile/API changes verified from static typing alone — execute a real runtime path that exercises the MODIFIED code.
82
+ - **Coverage ≠ label**: a tier command verifies a change ONLY when its backing suite actually exercises the changed path. `npm run test:qa-plan` mechanically asserts every changed code path is covered by the QA plan (or waivered) — and, via `flow-map.md`, that every touched flow's sibling surfaces and declared optional variants are addressed in the plan's audit.
83
+ - **Test quality & economics rule (T1–T10)**: coverage without test quality produces suites that are green, prove little, and cost a lot. Every proposed assertion must pass the architect's 10-point test-design checklist — independent oracle, executed proof (command + executed assertion count ≥ 1), single owner (no duplicate of an existing gate), hermetic isolation, exit contract + wall-clock budget, cheapest tier that still executes it, wired (not orphaned), a `behavior`/`drift-guard`/`constant-pin` label, a negative fixture for guard claims, and bounded fail-fast prerequisites. Mechanically: `npm run test:wiring` fails any `*.test.*` file no package script executes (T7), and `node scripts/qa/check-linger.js -- <tier command>` fails a suite whose process wall-clock grossly exceeds its runner-reported test time (T1/T6/T9). Tag definitions: `.agents/memory/test-design-parameters.md`; checklist: `.agents/skills/qa-architect/SKILL.md`.
84
+ - **Tiers** (commands are **project-provided** — the target project must define them; the harness ships only its own gates: `test:dispatch`, `test:governance`, `test:qa-plan`, `test:backlog`, `test:product`, `test:docs`, `test:concurrency`, `test:integrate`, `test:quality`, `test:wiring`, `test:linger`, `test:prefix`):
85
+ | Tier | Scope | Command |
86
+ |---|---|---|
87
+ | 1 | UI/CSS/mobile/copy | `npm run test:quick` |
88
+ | 2 | Routes / page layout | `npm run test:routes` |
89
+ | 3 | API / ORM / transactions | `npm run test:api` |
90
+ | 4 | Data ingestion | the project's data E2E script |
91
+ | 5 | Major release / breaking refactor | `npm run test:verify` |
92
+ | 6 | Security / deps | `npm run test:security` |
93
+ - **Live-server tiers (3+)**: a runtime/API tier that hits real routes needs the dev server running; start it detached and stop it when the tier passes (see §5, 00-operating §Machine capacity). Never pipe a live start or tier run through a buffering filter — it looks frozen and invites an abort.
94
+ - **The expensive device/Maestro tier is NIGHTLY, not part of the day loop.** The day loop lands on cheap gates (`test:quick` / `test:api` / `test:routes` / the project's web E2E); it must NOT boot the emulator or run the Maestro matrix by default. `scripts/nightly.js` (installed as a systemd `--user` timer by `agent-harness install-nightly`) runs the full battery off-hours against a `nightly` worktree fast-forwarded to `origin/main`, then reconciles the board: a failing journey with no row → `backlog add "[nightly:flow=<journey>] …"`; a shipped (archived, pending-validation) row whose journey now passes → `backlog archive <id> --closed "nightly-validated …"`; a still-failing journey → `backlog reopen <id>` (journey-level; one row per broken journey, reopened until green). A device-only path is therefore addressed in the QA plan as `audited: device tier deferred to nightly [nightly:flow=<journey>]` — a valid `audited:`/`waived:` reason, not a silent skip. Run a device tier in-session only when the user explicitly asks. See `docs/nightly-testing.md`.
95
+ - **Live QA targets the development environment only**: runtime/API tiers and data-E2E runs execute against the dev database (`DATABASE_URL`). They never touch uat/prod; the forward boundary (§2, `.agents/memory/environments.md`) is enforced at deploy time by `test:data-hygiene -- --env uat|prod`.
96
+ - **Progression Workflow**: for new routes/endpoints/states, (1) author a dedicated assertion path, (2) run the targeted progression test, (3) graduate it into the permanent regression suite. A change is NOT verified if the executed tier's backing suite never exercised the modified path — author a progression test for that path first (the "GAP" rule).
97
+
98
+ ## 7. Definition of Done & Continuous Backup
99
+
100
+ Every completed task closes with this gate. **QA gates dev work only:** steps 0-2
101
+ run when the session touched code paths — a backlog-only (or docs-only) change skips
102
+ them. Steps 3-7 are the unconditional session close; they are NOT gated by QA.
103
+
104
+ 0. **Feature Completeness Gate** (code changes only):
105
+ - [ ] Product-first: `intent.md` (actor/need/outcome/acceptance) + value-led `plan.md` present — `npm run test:product` green (feature work only).
106
+ - [ ] 5 UI states handled on every affected screen (list them).
107
+ - [ ] No `catch` blocks that only `console.warn` without user-facing feedback.
108
+ - [ ] Haptic/feedback consistency for every user-initiated action.
109
+ - [ ] RTL traced if layout touched; logical properties used.
110
+ - [ ] Cross-screen audit if a new UX pattern was introduced.
111
+ - [ ] No modified file over ~500 lines without extracting components.
112
+ - [ ] No blanket file-level `eslint-disable`/`@ts-nocheck`/`@ts-ignore` suppressions (line-level only, each with a reason).
113
+ - [ ] No dead export / oversized file introduced in NEW/GROWN code — `npm run test:quality` green on the diff (rubric: `.agents/memory/quality-parameters.md` P1/P3).
114
+ 1. **QA tier** (code changes only) — `qa-architect` inspects the diff, picks the tier BY COVERAGE (not path-label), records the coverage map in a per-change plan under `.agents/qa-plans/` (one file per change — never edit another change's plan), and authors progression tests for any GAP; if `qa-architect` is not dispatched, the orchestrator plans in its place. `qa-runner` executes and makes it pass (§6). A change is not verified until `npm run test:qa-plan` passes (every changed code path covered or waivered; every touched flow's sibling surfaces and variants addressed in `## Parallel-surface & variant audit`; the executed tier exercised the modified path) and `npm run test:wiring` is green. The plan also carries `## Test budget`, `## Oracle & owner`, and `## Test-design self-check` (T1–T10).
115
+ 2. **Security check** (code changes only) — apply `security-engineer` when the change touches data/auth/input/secrets/deps.
116
+ 3. **Backlog write-back** (always) — move every task this session shipped from `In progress` to `Archive (shipped · done)` (`backlog_archive`, with date/commit), then stage it explicitly: `git add BACKLOG.md` (a bare `git commit -am` will not pick up an untracked board). At session start, the inverse: `backlog_take` moves the picked-up row `Open` → `In progress` with `Handoff` pointing at the session's handoff file. The board syncs across sessions only through git, so these deltas ship with the code.
117
+ 4. **Docs write-back** (always, on land) — keep `CHANGELOG.md` current with a line citing the commit short hash (`git rev-parse --short HEAD`), and update `README.md` / `docs/**` / ADRs when the change adds or renames a subsystem, flow, public API, or hard-to-reverse decision (`.agents/skills/docs/SKILL.md`). `npm run test:docs` fails a shipped commit with no changelog entry, so the changelog delta ships in the same commit as the code. A copy/CSS tweak needs at most a changelog line.
118
+ 5. **Commit** (always) — concise `feat:` / `fix:` / `refactor:` message including the `BACKLOG.md` and `CHANGELOG.md` deltas.
119
+ 6. **Land the branch** (always) — `npm run finalize -- --feature <id>` (or `npm run ship`) integrates on `origin/main`, runs the branch gates (including the harness process gates when no pre-push hook is installed), lands with a **direct fast-forward push to `main`**, then waits for **CI to go green on the landed SHA**. There is no PR, no landing label, and no merge train; a concurrent landing is resolved by re-fetch + rebase + retry. `--no-ci-wait` is a pause, not a completion.
120
+ 7. **Deploy to UAT** (CI-owned) — the `CI` workflow completing on `main` triggers `.github/workflows/deploy-uat.yml`, which deploys the landed SHA to `uat` as a prebuilt artifact, runs `prisma migrate deploy` + idempotent seed + alias/parity/smoke verification, then `npm run test:data-hygiene -- --env uat`. A local `deploy:uat` is the emergency path only; production is human-gated. Never forward dev data — code + schema + idempotent seeds only (§2, `.agents/memory/environments.md`).
121
+ - **Mechanical floor**: a pre-push hook should run `npm run test:quick` (project-provided; the harness does not install git hooks).
122
+ - **Concurrency isolation (never let a concurrent session's WIP block yours)**:
123
+ - `test:concurrency` (`node scripts/qa/check-concurrency.js`) fails a push when the board shows 2+ `In progress` rows while the working tree has uncommitted changes. Declare each row's owned files (`backlog owns <id> --files ...`; `.agents/memory/owned-files.md`) so it fails *exactly* when a dirty file is owned by two In-progress rows. The live-session lease report (`.serve/sessions/`, written by the context-guard plugin) is **advisory** — a clean tree never fails a push. `--prune` clears dead/recycled/stale leases.
124
+ - **Isolate per feature** with `backlog worktree <id>` (or the `backlog_worktree` tool) from the **main** tree before starting ANY feature: it creates a `git worktree` + branch and records the path in the row's `Handoff`. `main` stays board + shippable code only. `--open` launches the agent CLI inside the worktree. Worktrees live under `<repo>/../.worktrees/<repo>/<id>`; `backlog archive <id>` removes a shipped feature's worktree + merged branch, and `backlog worktree-prune` converges the set (removes clean merged worktrees, keeps unmerged or dirty ones).
125
+ - **Row-aware merge driver**: `.gitattributes` routes `BACKLOG.md` through `scripts/qa/merge-backlog.js`, so two sessions editing *disjoint* rows merge by ID instead of conflicting (`agent-harness init/update` wires the driver). A row's `Depends on` cell (`backlog depends <id> --on <ids>`) makes ordering machine-readable — `/next`/`take`/`worktree` skip or refuse a row whose dependencies aren't archived.
126
+ - **Snapshot gating**: `node scripts/qa/run-clean.js -- npm run test:quick` runs a project gate against the *committed* state (stashes + restores dirty files), so a pre-push gate verifies your committed work, not the tree.
127
+ - **Lean permissions**: grant only the narrowest `git`/`gh` action needed; escalate only after a command has actually failed.
128
+ - Git may not be on PATH in the default shell — use the full path (`.agents/memory/locations.md`).
129
+
130
+ ## 8. Session & Traceability Discipline
131
+
132
+ - **Harness-update awareness**: `npx opencode-agent-harness update` auto-commits the harness files it changes as `chore(harness): opencode-agent-harness <old> -> <new>`. If you see such a commit (or modified `.agents/**`, `scripts/qa/**`, `AGENTS.md`, `opencode.json` you didn't touch), do NOT treat it as unexplained — run `git log -1 --stat` / `git show` to see exactly which harness files changed and why, then read the rulebook. Never guess at the cause.
133
+ - **Harness-owned files are fixed upstream, never in this project**: `scripts/qa/**`, `scripts/*.js`, `.opencode/**`, `.agents/skills/**`, `.agents/rules/**`, `.agents/AGENTS.md`, `AGENTS.md`, and opencode config are copied from the harness `templates/` on every `update`. Make a needed change in the harness repo's `templates/` (with a drift-guard test when it is a gate/QA script), release it, and re-run `update` — do NOT hand-edit the deployed copy. **Route (F-12):** a session rooted in this project cannot edit another checkout (the main-checkout guard blocks it, and worktree isolation is per-repo); make the fix from a session rooted in the harness checkout itself, then `agent-harness update .`, and record the harness gap on the board. Since harness `0.1.100`, `update` **fails closed** on a hand-edited harness file; `--accept-harness` overwrites deliberately after a backup and rolls back if `test:quick` goes red (the F-289 incident: a project-side `board-sync.js` fix silently reverted by the next deploy).
134
+ - **Planned vs. Shipped**: at session end, record a "planned → shipped → deferred" delta so aspirational docs are never mistaken for reality. Always verify against live code and schema.
135
+ - **Value-first completion report**: close a session by telling the user, in plain language, **what value shipped** and the main **how**, before any file/test/technical detail; record the same summary in the handoff's `## Value shipped` + `## How`. Full guidance: root `AGENTS.md` and 00-operating §Step Zero.
136
+ - **Explain at the reader's level**: write for someone who knows the product but not the codebase. Lead with observable behavior in plain terms; name a code identifier only when precision needs it, and gloss it on first use. Stay concrete and technical — never make an internal symbol the subject of a sentence. Full guidance: 00-operating §Step Zero.
137
+ - **Dispatch Log (mandatory)**: every wrap-up opens with `subagent → model → shipped/deferred`; a log with 5+ entries also needs a `## Fan-out justification`. An empty log is non-compliant.
138
+ - **Structured session telemetry**: every handoff records, when known and never fabricated:
139
+ - `session` — the primary orchestrator session id from the `session_info` tool. This is the join key for `npm run report -- --cost`, which attaches observed provider cost/tokens/turns (primary + subagent sessions) to the feature.
140
+ - `work_type` — one of `feature | bugfix | investigation | architecture | planning | qa | security | maintenance | process | conversation | other`.
141
+ - `outcome` — one of `shipped | resolved | deferred | investigation-complete | abandoned | superseded | conversation-only`.
142
+ - `termination_reason` — why the session ended (e.g. `gate-pass`, `checkpoint`, `blocked`, `escalated`, `abandoned`).
143
+ - `model_escalation_evidence` — when the primary session ran on an `escalation_models:` model (`.agents/memory/model-routing.md`), the reason (or `none`). `npm run report -- --cost` flags a pro-model primary session with no recorded evidence.
144
+ - Retries/escalations with `attempt` numbers and reasons.
145
+ - `null` / `unknown` when the runtime cannot know a value — never infer exact token/cost numbers from character counts, and never invent values.
146
+ These feed the deterministic `npm run report` (agent-report) so feature economics are measurable without reading transcripts; `--cost` reads only observed provider data from the opencode store.
147
+ - **Persist continuity & checkpoint**: use the `handoff` skill to write your session's file under `.agents/handoffs/` (one per session — never edit another session's). At the `orchestration.md` budget bands, write the bounded state block with `checkpoint_write`/`/checkpoint` and resume with `/resume` — never replay the transcript. Project history lives in `.agents/memory/history.md`; stack facts in `.agents/memory/stack-versions.md`.
148
+ - **Pointers Map Hygiene**: record every created/discovered/changed important location (session archives, scratch scripts, logs, docs, DB targets, env files) in `.agents/memory/locations.md`.
@@ -0,0 +1,10 @@
1
+ # Features — pointer
2
+
3
+ The backlog lives in **`BACKLOG.md`** (repo root) — the canonical task list. Per-feature
4
+ spec docs (`.agents/features/<slug>/` intent · scope · plan · tests) still live here in
5
+ this tree, owned by the `features` persona (`.agents/skills/features/SKILL.md`).
6
+
7
+ This file is a pointer, not a list. Capture a found item as one row in `BACKLOG.md`;
8
+ when a feature is picked up, the orchestrator authors the per-feature doc chain by
9
+ dispatching each author persona directly (`product-manager`/`system-architect`/
10
+ `planner`/`qa-architect`) — `features` only registers the row and scaffolds this tree.
@@ -0,0 +1,87 @@
1
+ # Session handoffs — one file per session
2
+
3
+ Project-owned (like all `.agents/memory/*`). This directory holds the session
4
+ handoff, **sharded**: one file per session instead of a single shared
5
+ `handoff.md`. Each concurrent session owns its own file, so two sessions (e.g.
6
+ `F-003` and `F-035`) never rewrite each other's "where we stopped" — the failure
7
+ mode where one session's wrap-up clobbers another's and its dispatch log is
8
+ silently lost.
9
+
10
+ `npm run test:governance` reads EVERY `.md` file under this directory (plus the
11
+ legacy `.agents/memory/handoff.md` if it exists) and requires each to open with a
12
+ `## Dispatch log` section containing at least one entry — so a session's dispatch
13
+ log is enforced without a shared file. An entry is a bullet line
14
+ (`- <subagent> -> <model> -> <shipped/deferred>`) **or** a markdown table data row
15
+ (`| subagent | model | shipped/deferred |`); both are accepted, so pick one.
16
+ When the log has **5+ entries**, the handoff must also carry a
17
+ `## Fan-out justification` section (or a `dispatch_justification:` line) citing
18
+ the plan's `§Fan-out review` — the 5–7 band in `orchestration.md` where fan-out
19
+ must be justified. That check is forward-only: handoffs dated `2026-09-12` or
20
+ later are enforced; undated legacy handoffs are grandfathered.
21
+
22
+ `npm run report -- --cost` joins the handoff to the observed provider telemetry
23
+ via the `session:` metadata line (get the primary orchestrator id from the
24
+ `session_info` tool). That join maps a feature to its provider group — the
25
+ primary session plus every subagent session it dispatched — so cost per shipped
26
+ feature is measured, never estimated. Record it whenever the session did work.
27
+ The same join flags a primary session observed on an `escalation_models:` model
28
+ (`.agents/memory/model-routing.md`) with no recorded reason: record
29
+ `model_escalation_evidence:` (or `none`) whenever the primary ran a pro model.
30
+
31
+ Mid-session, `scripts/checkpoint.js` (agents: the `checkpoint_write` /
32
+ `checkpoint_resume` tools, or `/checkpoint` / `/resume`) maintains a
33
+ `## Checkpoint (resume)` block in the session's handoff file. It is
34
+ machine-written — replaced in place, never duplicated — and `/resume` prints it
35
+ alone as the bounded state a fresh context continues from, instead of replaying
36
+ the transcript. Do not hand-edit the block; the handoff's own sections stay
37
+ yours.
38
+
39
+ ## Naming & ownership
40
+
41
+ - One file per session. Name it after the `BACKLOG.md` feature ID (`F-003.md`),
42
+ or a short hyphenated slug of the change (`return-no-condition.md`) when there
43
+ is no feature row.
44
+ - **Own your file; never edit another session's file.** That single rule removes
45
+ the collision. To resume a past session, READ its file; to continue the same
46
+ feature in a new session, append a new dated `##`-block — never reorder or
47
+ delete another session's entries.
48
+
49
+ ## Template
50
+
51
+ # Where we stopped (handoff) — <feature-id or slug>
52
+
53
+ Date: <YYYY-MM-DD>
54
+
55
+ ## Dispatch log
56
+ - <subagent → model → shipped/deferred> (empty log = non-compliant session)
57
+
58
+ ## Fan-out justification (required when the dispatch log has 5+ entries)
59
+ - <why each dispatch is distinct/necessary — cite the plan's §Fan-out review>
60
+
61
+ ## Retries (only when a persona was retried)
62
+ - <persona>: <count> — <what changed on the last retry>
63
+
64
+ ## Escalations (only when a persona was escalated)
65
+ - <persona> -> <tier> reason: <evidence> attempt: <n>
66
+
67
+ ## Session metadata (structured — record what is known, never fabricate)
68
+ - session: <ses_... — primary orchestrator id from the session_info tool>
69
+ - work_type: <feature|bugfix|investigation|architecture|planning|qa|security|maintenance|process|conversation|other>
70
+ - outcome: <shipped|resolved|deferred|investigation-complete|abandoned|superseded|conversation-only>
71
+ - termination_reason: <gate-pass|checkpoint|blocked|escalated|abandoned|unknown>
72
+ - checkpoint_count: <n> (omit when 0)
73
+ - model_escalation_evidence: <none | persona -> tier: reason> (required when the primary session ran on an escalation_models model; `none` = explicitly no escalation)
74
+
75
+ ## Value shipped
76
+ - <1-2 plain sentences: what the user now gets and why it matters — no file paths, no tech jargon>
77
+
78
+ ## How (main points)
79
+ - <the key approach in a sentence or two — the "how", not a file manifest>
80
+
81
+ ## Done this session (planned → shipped → deferred)
82
+ - <planned → shipped → deferred, one line each, with file + commit refs>
83
+
84
+ ## Still open / next
85
+ - <deferred items + next-session entry point>
86
+
87
+ Lines starting with `#` are ignored by the gate.
@@ -0,0 +1,59 @@
1
+ # Dev loop — {{PROJECT_NAME}}
2
+
3
+ The **project-owned** half of the `dev-loop` skill (load it with the `skill`
4
+ tool → `dev-loop`). It answers one question so no session re-derives it: *how do
5
+ I run, verify, seed, boot, and debug something in THIS project?* The skill is the
6
+ universal loop (`gates`, `serve.js`, `orient`/`where`, "read the failing gate");
7
+ this file is the concrete commands.
8
+
9
+ `orient` digests this file at session start. Keep it current whenever a command,
10
+ port, tier, or seed changes — this file is **create-if-missing**, so the harness
11
+ never overwrites your edits. Fill every `—`/`(fill in)` cell.
12
+
13
+ ## Test tiers (cheapest that exercises the change first)
14
+
15
+ | Tier | Scope | Command |
16
+ |---|---|---|
17
+ | 1 | types + unit/smoke | `npm run test:quick` |
18
+ | 2 | routes / page render | `npm run test:routes` |
19
+ | 3 | API / ORM / transactions | `npm run test:api` |
20
+ | 5 | full regression | `npm run test:verify` |
21
+ | 6 | security / deps | `npm run test:security` |
22
+
23
+ **Single test** (iterate without running a whole tier):
24
+
25
+ - TS/tsx suite: `npx tsx --test scripts/qa/tests/<name>.test.ts`
26
+ - node:test suite: `node --test scripts/qa/tests/<name>.test.js`
27
+
28
+ ## Dev server
29
+
30
+ - Start: `node scripts/serve.js start --cmd "npm run dev" --url http://localhost:3000`
31
+ - Stop: `node scripts/serve.js stop --name dev`
32
+ - Health URL / port: `http://localhost:3000` (fill in)
33
+
34
+ ## Data (development only — never uat/prod)
35
+
36
+ - Seed: `npm run db:seed`
37
+ - Reset / clean test data after a live run: `—` (project cleanup script)
38
+
39
+ ## Mobile / device (delete this section if there is no native app)
40
+
41
+ - Reset harness/app data: `npm run mobile-e2e:reset`
42
+ - Boot the device tier (adb + emulator + APK + dev server, idempotent):
43
+ `bash scripts/qa/mobile-e2e/device-up.sh`
44
+ - Device tier config: `scripts/qa/mobile-e2e/local.json`
45
+ - Tear down: `bash scripts/qa/mobile-e2e/device-down.sh`
46
+
47
+ ## Nightly E2E (off-hours full battery)
48
+
49
+ - Orchestrator: `npm run nightly -- run` (config: `.agents/nightly.json`).
50
+ - Install/status: `agent-harness install-nightly --target .` / `bash scripts/setup-nightly.sh status`
51
+ - Read the last cycle: `npm run report:nightly` (or `node scripts/nightly.js report`).
52
+ - Default phases: `—` (see `.agents/nightly.json`; the device/Maestro tier runs
53
+ here, never in the day loop — the day loop covers device paths via the
54
+ `audited: device tier deferred to nightly` plan entry).
55
+
56
+ ## Debug / logs
57
+
58
+ - Log endpoints / files: `—` (fill in)
59
+ - DB introspection: `—` (e.g. the project's psql / prisma studio / MCP route)
@@ -0,0 +1,29 @@
1
+ # Domain map — {{PROJECT_NAME}}
2
+
3
+ Project-specific domain facts the persona skills reference. Fill this in during
4
+ `npx opencode-agent-harness init`; keep it current as the domain evolves. The skills read
5
+ this instead of hardcoding domain assumptions.
6
+
7
+ ## Entity model
8
+ <!-- canonical → edition → item chain, plus supporting entities (author, etc.) -->
9
+ _TODO: describe the core and supporting entities and how they relate._
10
+
11
+ ## External sources
12
+ <!-- data sources / integrations, auth, and rate-limit notes -->
13
+ _TODO: list external catalog/data APIs this project ingests from._
14
+
15
+ ## Visibility / privacy tiers
16
+ <!-- e.g. community / private / public — and what each permits -->
17
+ _TODO: enumerate the access tiers and their rules._
18
+
19
+ ## Core state machine(s)
20
+ <!-- the central domain process/FSM that `system-architect` governs -->
21
+ _TODO: name and outline the domain's central lifecycle/state machine._
22
+
23
+ ## Trust & gamification
24
+ <!-- user progression tiers and activity badges -->
25
+ _TODO: define user tiers and rewards._
26
+
27
+ ## Identifiers & acronyms
28
+ <!-- ID formats, domain-specific terms -->
29
+ _TODO: list identifier patterns and glossary terms._
@@ -0,0 +1,35 @@
1
+ # Environments — {{PROJECT_NAME}}
2
+
3
+ The canonical registry of the three environments: **development** → **User
4
+ Acceptance (uat)** → **production**. Read this at session start; keep it current
5
+ whenever you add or change a deploy target, database, or seed command. The
6
+ Definition-of-Done "deploy to UAT" step and the `devops-engineer` persona read it.
7
+
8
+ ## The invariant (non-negotiable)
9
+
10
+ Only three things move **forward** (dev → uat → prod): **code**, **schema
11
+ migrations** (`prisma migrate deploy`), and **idempotent seed scripts**. **Data
12
+ never does** — no `pg_dump` / restore / copy of one environment's database into
13
+ another. Each environment owns its database.
14
+
15
+ - `development` is **dirty by design** — QA/test data lives and dies here.
16
+ - `uat` and `production` are **enforced clean** — idempotent seed only, no test data.
17
+
18
+ ## Registry
19
+
20
+ | Env | App URL | DB env var | Deploy command | Seed command | Owner |
21
+ |---|---|---|---|---|---|
22
+ | development | (local) | `DATABASE_URL` | — | `npm run db:seed` | dev |
23
+ | uat | — | `DATABASE_URL_UAT` | `npm run deploy:uat` | `npm run db:seed -- --env uat` | dev |
24
+ | production | — | `DATABASE_URL_PROD` | `npm run deploy:prod` | — | human-gated |
25
+
26
+ Fill every `—` with the real value for this project. Update this table whenever a
27
+ URL, database, deploy command, or seed command changes.
28
+
29
+ ## Forward-boundary check
30
+
31
+ `test:data-hygiene` scans a target database for test-data markers. It is the
32
+ mechanical guard that keeps test data from leaking forward:
33
+
34
+ - `npm run test:data-hygiene` → scans dev, **warns only** (dev is dirty by design).
35
+ - `npm run test:data-hygiene -- --env uat` / `-- --env prod` → **fails** on any marker.
@@ -0,0 +1,23 @@
1
+ # Flow map — every user-facing flow and where it lives
2
+
3
+ Project-owned (like all `.agents/memory/*`). This is the registry that turns the
4
+ "Fix One, Fix All" rule (`AGENTS.md` §3) into a **gate**:
5
+ `npm run test:qa-plan` reads this file and, for every flow your diff touches,
6
+ requires the QA plan to explicitly address EVERY sibling surface — the same
7
+ behavior implemented anywhere else: another codebase (web vs `mobile/`), another
8
+ layer (API route), another page — and every OPTIONAL variant (state a surface can
9
+ be in, e.g. "condition selector present" vs "absent") before the change may be
10
+ verified.
11
+
12
+ The failure mode this kills: a change to one surface (e.g. web) ships while its
13
+ twin in another codebase silently keeps the old behavior. The diff is web-only so
14
+ per-file coverage looks green, but the flow is now inconsistent — the exact
15
+ "web/mobile return flow" miss.
16
+
17
+ Keep it current: every time a flow gains/removes a surface or variant, update its
18
+ entry here in the same change.
19
+
20
+ ## flow: return
21
+ behavior: "Mark as Returned" — return POST with an optional condition payload (condition selector)
22
+ surfaces: components/LendingActionDrawers.tsx, mobile/features/return/ReturnStatusSheet.tsx, app/api/transactions/[id]/return/route.ts
23
+ variants: condition-selector-present, condition-selector-absent
@@ -0,0 +1,7 @@
1
+ # Project history
2
+
3
+ Durable, non-obvious project facts that don't belong in the session handoff.
4
+ Append one line per milestone/finding with a date; keep it a pointer index, not
5
+ a spec (code and the DB schema are the source of truth).
6
+
7
+ - <YYYY-MM-DD> <fact / decision / gotcha, with file or commit ref>
@@ -0,0 +1,14 @@
1
+ # Locations map
2
+
3
+ Canonical index of where sessions, logs, docs, and data live. Update whenever a
4
+ session creates, discovers, or changes an important location. **Read this before
5
+ reading or editing an unfamiliar path** — a guessed path is a measured waste (the
6
+ context-guard nudges a failed `read`/`edit` back here rather than letting the
7
+ agent re-hunt).
8
+
9
+ - **Repos**:
10
+ - **Logs / telemetry**:
11
+ - **DB / env**:
12
+ - **Docs**:
13
+ - **Session checkpoints / handoffs**: `.agents/handoffs/<feature-id>.md` — one per session/work unit, named for the **BACKLOG feature id** (not `next.md`/`pending.md`). Write with the `checkpoint_write` tool, load with `checkpoint_resume <feature-id>` (or `/resume`). List what exists with `Glob .agents/handoffs/*.md` before assuming a name.
14
+ - **AI session archives**: opencode: <path>; antigravity: <path>; vscode: <path> (record each front-end's session/history path — the docs reconstruction bundle reads these)