opencode-agent-harness 0.0.0-stage → 0.2.0
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.
- package/CHANGELOG.md +23 -0
- package/LICENSE +21 -0
- package/README.md +590 -2
- package/bin/agent-harness.js +3059 -0
- package/contrib/global-plugins/README.md +49 -0
- package/contrib/global-plugins/harness-freshness.ts +355 -0
- package/package.json +48 -4
- package/templates/.agents/AGENTS.md +204 -0
- package/templates/.agents/features/INDEX.md +10 -0
- package/templates/.agents/handoffs/README.md +87 -0
- package/templates/.agents/memory/dev-loop.md +59 -0
- package/templates/.agents/memory/domain-map.md +29 -0
- package/templates/.agents/memory/environments.md +35 -0
- package/templates/.agents/memory/flow-map.md +23 -0
- package/templates/.agents/memory/history.md +7 -0
- package/templates/.agents/memory/locations.md +14 -0
- package/templates/.agents/memory/model-routing.md +261 -0
- package/templates/.agents/memory/orchestration.md +183 -0
- package/templates/.agents/memory/owned-files.md +19 -0
- package/templates/.agents/memory/product-principles.md +37 -0
- package/templates/.agents/memory/quality-parameters.md +37 -0
- package/templates/.agents/memory/stack-versions.md +35 -0
- package/templates/.agents/memory/test-design-parameters.md +36 -0
- package/templates/.agents/nightly.json +17 -0
- package/templates/.agents/qa-plans/README.md +70 -0
- package/templates/.agents/qa-runs/README.md +21 -0
- package/templates/.agents/reviews/README.md +47 -0
- package/templates/.agents/rules/00-operating.md +199 -0
- package/templates/.agents/skills/data-engineer/SKILL.md +31 -0
- package/templates/.agents/skills/devops-engineer/SKILL.md +50 -0
- package/templates/.agents/skills/diagnostics-expert/SKILL.md +44 -0
- package/templates/.agents/skills/docs/SKILL.md +140 -0
- package/templates/.agents/skills/features/SKILL.md +187 -0
- package/templates/.agents/skills/frontend-engineer/SKILL.md +81 -0
- package/templates/.agents/skills/handoff/SKILL.md +85 -0
- package/templates/.agents/skills/mobile-engineer/SKILL.md +101 -0
- package/templates/.agents/skills/planner/SKILL.md +112 -0
- package/templates/.agents/skills/product-manager/SKILL.md +115 -0
- package/templates/.agents/skills/qa-architect/SKILL.md +224 -0
- package/templates/.agents/skills/qa-runner/SKILL.md +64 -0
- package/templates/.agents/skills/security-engineer/SKILL.md +53 -0
- package/templates/.agents/skills/system-architect/SKILL.md +42 -0
- package/templates/.agents/skills/ui-designer/SKILL.md +71 -0
- package/templates/.github/workflows/ci.yml +148 -0
- package/templates/.github/workflows/deploy-uat.yml +95 -0
- package/templates/.github/workflows/nightly.yml +83 -0
- package/templates/.github/workflows/uat-health.yml +41 -0
- package/templates/.husky/pre-push +23 -0
- package/templates/.ignore +28 -0
- package/templates/.opencode/agents/data-engineer.md +37 -0
- package/templates/.opencode/agents/devops-engineer.md +37 -0
- package/templates/.opencode/agents/diagnostics-expert.md +37 -0
- package/templates/.opencode/agents/docs.md +37 -0
- package/templates/.opencode/agents/features.md +21 -0
- package/templates/.opencode/agents/frontend-engineer.md +37 -0
- package/templates/.opencode/agents/handoff.md +21 -0
- package/templates/.opencode/agents/mobile-engineer.md +37 -0
- package/templates/.opencode/agents/planner.md +34 -0
- package/templates/.opencode/agents/product-manager.md +29 -0
- package/templates/.opencode/agents/qa-architect.md +27 -0
- package/templates/.opencode/agents/qa-runner.md +17 -0
- package/templates/.opencode/agents/security-engineer.md +37 -0
- package/templates/.opencode/agents/system-architect.md +37 -0
- package/templates/.opencode/agents/ui-designer.md +37 -0
- package/templates/.opencode/commands/board.md +15 -0
- package/templates/.opencode/commands/checkpoint.md +25 -0
- package/templates/.opencode/commands/feature.md +56 -0
- package/templates/.opencode/commands/finish.md +36 -0
- package/templates/.opencode/commands/next.md +49 -0
- package/templates/.opencode/commands/report.md +55 -0
- package/templates/.opencode/commands/resume.md +39 -0
- package/templates/.opencode/commands/switch-model.md +34 -0
- package/templates/.opencode/commands/tidy.md +49 -0
- package/templates/.opencode/plugins/backlog-notify.ts +57 -0
- package/templates/.opencode/plugins/backlog.ts +272 -0
- package/templates/.opencode/plugins/checkpoint.ts +160 -0
- package/templates/.opencode/plugins/context-guard.ts +1164 -0
- package/templates/.opencode/plugins/diff.ts +85 -0
- package/templates/.opencode/plugins/gates.ts +71 -0
- package/templates/.opencode/plugins/job-notify.ts +241 -0
- package/templates/.opencode/plugins/orient.ts +67 -0
- package/templates/.opencode/plugins/session.ts +89 -0
- package/templates/.opencode/plugins/wait.ts +101 -0
- package/templates/.opencode/plugins/where.ts +70 -0
- package/templates/.opencode/skills/bounded-explore/SKILL.md +38 -0
- package/templates/.opencode/skills/dev-loop/SKILL.md +87 -0
- package/templates/.vercelignore +16 -0
- package/templates/AGENTS.md +27 -0
- package/templates/BACKLOG.md +95 -0
- package/templates/docs/ci-cd-pipeline.md +81 -0
- package/templates/docs/gates.md +128 -0
- package/templates/docs/mcp-integrations.md +97 -0
- package/templates/docs/mobile-testing.md +555 -0
- package/templates/docs/nightly-testing.md +106 -0
- package/templates/docs/wsl-optimizations.md +290 -0
- package/templates/opencode.json +188 -0
- package/templates/scripts/agent-report.js +541 -0
- package/templates/scripts/agent-search.sh +117 -0
- package/templates/scripts/backlog.js +1864 -0
- package/templates/scripts/board-service.sh +207 -0
- package/templates/scripts/checkpoint.js +290 -0
- package/templates/scripts/finalize.js +277 -0
- package/templates/scripts/nightly.js +913 -0
- package/templates/scripts/orient.js +514 -0
- package/templates/scripts/qa/board-client.js +260 -0
- package/templates/scripts/qa/board-lib.js +96 -0
- package/templates/scripts/qa/board-sync.js +469 -0
- package/templates/scripts/qa/capacity-lib.js +916 -0
- package/templates/scripts/qa/check-backlog.js +427 -0
- package/templates/scripts/qa/check-capacity.js +85 -0
- package/templates/scripts/qa/check-ci-policy.js +164 -0
- package/templates/scripts/qa/check-concurrency.js +344 -0
- package/templates/scripts/qa/check-dispatch-config.js +296 -0
- package/templates/scripts/qa/check-docs.js +284 -0
- package/templates/scripts/qa/check-integrate.js +98 -0
- package/templates/scripts/qa/check-linger.js +160 -0
- package/templates/scripts/qa/check-prefix-stability.js +183 -0
- package/templates/scripts/qa/check-product.js +177 -0
- package/templates/scripts/qa/check-qa-plan.js +378 -0
- package/templates/scripts/qa/check-qa-scripts.js +85 -0
- package/templates/scripts/qa/check-quality.js +249 -0
- package/templates/scripts/qa/check-test-wiring.js +253 -0
- package/templates/scripts/qa/ci-triage.js +346 -0
- package/templates/scripts/qa/ci-usage-lib.js +185 -0
- package/templates/scripts/qa/ci-wait-lib.js +294 -0
- package/templates/scripts/qa/command-classifier.js +552 -0
- package/templates/scripts/qa/context-guard-core.js +1618 -0
- package/templates/scripts/qa/diff.js +174 -0
- package/templates/scripts/qa/feature-scaffold.js +224 -0
- package/templates/scripts/qa/fixtures/backlog.md +104 -0
- package/templates/scripts/qa/governance.js +174 -0
- package/templates/scripts/qa/hash-file.js +32 -0
- package/templates/scripts/qa/lease-lib.js +263 -0
- package/templates/scripts/qa/merge-backlog.js +324 -0
- package/templates/scripts/qa/mobile-e2e/analyze-timings.js +300 -0
- package/templates/scripts/qa/mobile-e2e/apk-cache.js +420 -0
- package/templates/scripts/qa/mobile-e2e/backend-build-cache.js +203 -0
- package/templates/scripts/qa/mobile-e2e/boot-emulator.sh +432 -0
- package/templates/scripts/qa/mobile-e2e/build-apk.sh +210 -0
- package/templates/scripts/qa/mobile-e2e/check-flows.js +453 -0
- package/templates/scripts/qa/mobile-e2e/config.yaml +18 -0
- package/templates/scripts/qa/mobile-e2e/device-down.sh +88 -0
- package/templates/scripts/qa/mobile-e2e/device-up.sh +258 -0
- package/templates/scripts/qa/mobile-e2e/ios-simulator-down.sh +72 -0
- package/templates/scripts/qa/mobile-e2e/ios-simulator-up.sh +153 -0
- package/templates/scripts/qa/mobile-e2e/job-events.js +181 -0
- package/templates/scripts/qa/mobile-e2e/prewarm.sh +56 -0
- package/templates/scripts/qa/mobile-e2e/run-detached.sh +222 -0
- package/templates/scripts/qa/mobile-e2e/run-maestro.js +1543 -0
- package/templates/scripts/qa/mobile-e2e/ui-dump.js +327 -0
- package/templates/scripts/qa/models.allowlist.txt +32 -0
- package/templates/scripts/qa/provider-stats.js +878 -0
- package/templates/scripts/qa/run-clean.js +83 -0
- package/templates/scripts/qa/run-gates.js +212 -0
- package/templates/scripts/qa/run-loop.js +220 -0
- package/templates/scripts/qa/session-recon.js +512 -0
- package/templates/scripts/qa/store-lib.js +324 -0
- package/templates/scripts/qa/tool-lib.js +134 -0
- package/templates/scripts/qa/where.js +214 -0
- package/templates/scripts/qa/wslconfig-merge.js +157 -0
- package/templates/scripts/serve.js +1328 -0
- package/templates/scripts/setup-nightly.sh +185 -0
- package/templates/scripts/setup-tmpfs.sh +374 -0
- package/templates/scripts/ship.js +586 -0
- package/templates/scripts/switch-reasoning-model.ps1 +101 -0
- package/templates/scripts/switch-reasoning-model.sh +104 -0
- package/templates/scripts/wait-for.js +342 -0
- package/templates/scripts/wsl-gpu.sh +180 -0
- package/templates/scripts/wsl-tune.sh +261 -0
|
@@ -0,0 +1,204 @@
|
|
|
1
|
+
# Project Rules & Operating Guidelines
|
|
2
|
+
|
|
3
|
+
The canonical rulebook. The always-loaded summary is `.agents/rules/00-operating.md`.
|
|
4
|
+
|
|
5
|
+
## 1. Fact-Based, Zero-Guessing SDLC
|
|
6
|
+
|
|
7
|
+
- **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.
|
|
8
|
+
- **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`.
|
|
9
|
+
- **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.
|
|
10
|
+
- **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.
|
|
11
|
+
- **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.
|
|
12
|
+
|
|
13
|
+
## 2. Dynamic Data & Business-Logic Integrity
|
|
14
|
+
|
|
15
|
+
- **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.
|
|
16
|
+
- **Environment data boundary (never leak test data forward)**: 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. The canonical registry is `.agents/memory/environments.md`.
|
|
17
|
+
|
|
18
|
+
## 3. UI, Mobile Ergonomics & RTL Support
|
|
19
|
+
|
|
20
|
+
- **Zero Native Popups**: Never use `Alert.alert()`, `alert()`, `confirm()`, or `prompt()`. Use inline toasts, bottom sheets, inline state transitions, or haptics.
|
|
21
|
+
- **Progressive Hydration & Cold-Start**: Never render empty states while waiting on async auth/sync. Hydrate from local cache so the UI renders immediately.
|
|
22
|
+
- **The 5 Essential UI States**: Every screen/list component must handle Ideal, Empty (with CTA), Loading (skeleton), Error (retry), and Partial/single-item states.
|
|
23
|
+
- **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`.
|
|
24
|
+
- **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.
|
|
25
|
+
- **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.
|
|
26
|
+
- **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.
|
|
27
|
+
|
|
28
|
+
## 4. Framework & Backend Architecture
|
|
29
|
+
|
|
30
|
+
- **Verify Stack Versions First**: Confirm versions against `.agents/memory/stack-versions.md` before writing framework-specific code. Never assume a newer/older convention.
|
|
31
|
+
- **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.
|
|
32
|
+
- **Privacy & Visibility Tiers**: Enforce the project's tier model (`.agents/memory/domain-map.md` §Visibility tiers) across all data-access endpoints.
|
|
33
|
+
- **Environments**: read `.agents/memory/environments.md` for the three environments (dev/uat/prod), their databases, deploy commands, and seed commands. Live/QA tiers target the `development` DB only.
|
|
34
|
+
|
|
35
|
+
## 5. Token Efficiency & Workflow Discipline
|
|
36
|
+
|
|
37
|
+
- **When NOT to Plan**: No heavy planning docs for simple fixes, CSS/layout tweaks, or single-file changes — execute directly.
|
|
38
|
+
- **Use the dedicated tools, not the shell, for file work**: inspect with `Read` (targeted `offset`/`limit`), `Grep`, and `Glob`; edit with `Edit`/`Write` — never shell `cat`/`ls`/`grep`/`find`/`sed -i` to do what they already do (they ignore the project `.ignore`, return noisy output, and bloat the transcript). Reserve the shell for real commands and pipelines. Carry the working tree with the `shell` tool's `workdir` argument, never a leading `cd <tree> &&` (the context-guard nudges both; it also reroots an exact `cd`).
|
|
39
|
+
- **Precise File Inspections**: Search first (`Grep` / `npm run search`), then read targeted line ranges — never whole 800+ line files blind. Batch independent searches/reads in parallel.
|
|
40
|
+
- **Don't Re-read Unchanged Files**: Edit files already in context directly. A second read of the same path means the region, not the file — use `offset`/`limit` or `Grep` for the changed lines.
|
|
41
|
+
- **Delegate Big Searches**: Use the `explore` subagent for broad multi-file exploration — but bound it first with the `bounded-explore` skill: name the exact paths, one answerable question, and a result budget (≤20 `file:line` pointers + a ≤15-line summary; no whole-file dumps, no transcript replay). An unbounded explore is the most expensive dispatch in the harness (~465K input tokens/call, `0.1.120` recon). A known path or single-symbol lookup is orchestrator work — search/read it inline, don't dispatch.
|
|
42
|
+
- **Locations Map first**: before reading an unknown path, check `.agents/memory/locations.md` (the canonical index) or `Glob` — never guess a path (`read` failures on guessed paths are a measured waste).
|
|
43
|
+
- **Prefer Memory over Re-derivation**: Persist non-obvious facts to `.agents/memory/`; read the relevant memory files before starting.
|
|
44
|
+
- **Run/verify via the `dev-loop` skill**: before running a test tier, single test, seed/reset, the emulator, or the dev server, load the `dev-loop` skill (`skill` tool → `dev-loop`) and read `.agents/memory/dev-loop.md` (project-owned concrete commands, digested by `orient`). It carries the tier map, single-test invocation, `serve.js` lifecycle, `gates`/`where`, and "read the failing gate, don't re-run it blind" — so no session re-derives how to run things.
|
|
45
|
+
- **Step Zero — Subagent & Model Routing (non-negotiable)**: Before touching code, satisfy the dispatch gate (`.agents/rules/00-operating.md` §Step Zero). Personas: `planner`, `frontend-engineer`, `mobile-engineer`, `ui-designer`, `qa-architect`, `qa-runner`, `security-engineer`, `product-manager`, `system-architect`, `diagnostics-expert`, `data-engineer`, `devops-engineer`, `handoff`, `features`, `docs`. Dispatch 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. Dispatch subagents in parallel only when their work is disjoint (see below).
|
|
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
|
+
- **Feature docs, not ceremony**: capture a found item as one light row in
|
|
65
|
+
the canonical `BACKLOG.md` (repo root). **Update the board with the `backlog_*`
|
|
66
|
+
tools (or `node scripts/backlog.js`), never hand-edit `BACKLOG.md`.** `features`
|
|
67
|
+
is a registrar only — it
|
|
68
|
+
registers rows and scaffolds the `.agents/features/<slug>/` tree, never authors
|
|
69
|
+
content. When a feature is picked up, author the doc chain by dispatching each
|
|
70
|
+
author persona **directly** — `intent` (product-manager) → `scope`
|
|
71
|
+
(system-architect, HIGH-risk only) → `plan` (planner) → `tests` (qa-architect).
|
|
72
|
+
For an "investigate + plan" request (no code), dispatch `planner` and/or
|
|
73
|
+
`product-manager` directly — never `features`. Match ceremony to blast radius:
|
|
74
|
+
trivial → none, low → single `intent.md`, high (auth/DB/API/flow-siblings) →
|
|
75
|
+
full chain. Write back first (update the doc before continuing when
|
|
76
|
+
implementation invalidates it), archive on ship. Feature docs are durable and
|
|
77
|
+
complementary to the per-session
|
|
78
|
+
`.agents/qa-plans/<feature-id>.md`/`.agents/handoffs/<feature-id>.md`; the `tests` doc points to the
|
|
79
|
+
feature's QA plan, never duplicates it. The moment a session starts dealing
|
|
80
|
+
with a backlog item, move its `BACKLOG.md` row `Open` → `In progress` (`backlog_take`, pointing
|
|
81
|
+
`Handoff` at the session's handoff file) so active work is visible on the board.
|
|
82
|
+
A `Queued` row is a ready-to-pull lane: `backlog queue <id>` allocates an `Open` row
|
|
83
|
+
into it, and `/next` (or `backlog next --take`) pulls the top-priority `Queued` row
|
|
84
|
+
into `In progress` to start a session (empty queue = stop, never invent work).
|
|
85
|
+
- **Product intent is never optional (no silent skip)**: planning is
|
|
86
|
+
product-first. `intent.md` must define Actor(s) → Need → Outcome → Acceptance
|
|
87
|
+
criteria, and `plan.md` a Value-first sequence + Product concepts applied, read
|
|
88
|
+
against `.agents/memory/product-principles.md`. `npm run test:product` fails any
|
|
89
|
+
feature doc missing these, or a `plan.md` with no `intent.md` — mirroring the
|
|
90
|
+
"QA planning is never optional" ladder: `product-manager`/`planner` →
|
|
91
|
+
orchestrator fallback → (never a silent skip).
|
|
92
|
+
- **QA planning is never optional (no silent skip)**: every change that touches
|
|
93
|
+
code paths MUST get a QA plan before it is verified. The plan is authored by
|
|
94
|
+
`qa-architect` (thinker). If `qa-architect` is not dispatched — for ANY reason,
|
|
95
|
+
including dispatch failure or simply not invoking it — the **main orchestrator
|
|
96
|
+
performs the qa-architect role itself** and writes the same coverage plan into
|
|
97
|
+
a per-change file under `.agents/qa-plans/` (one file per change, named by
|
|
98
|
+
`BACKLOG.md` ID or slug — never edit another change's plan file). The QA
|
|
99
|
+
plan/copy escalation ladder NEVER leaves a code change unplanned: `qa-architect` ->
|
|
100
|
+
orchestrator fallback -> (never a silent skip). `npm run test:qa-plan` enforces
|
|
101
|
+
that every changed code path has a covering assertion or a waivered reason.
|
|
102
|
+
- **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>`.
|
|
103
|
+
- **Dispatch failure ladder & bounded retries** (never silent): **a provider funds/quota error is a STOP, not a failure to work around** — do not retry, do not degrade inline, do not silently skip; announce the failed provider/model + the exact unfinished step, checkpoint, and wait for the user's explicit top-up-complete / continue message before resuming (provider priority: OpenCode Go `opencode-go/*` first, DeepSeek direct `deepseek/*` fallback — the V4 Pro architect tier pins `opencode-go/deepseek-v4-pro#high`, with direct `deepseek/deepseek-v4-pro` as the announced fallback; every fallback announced immediately — see `.agents/memory/model-routing.md`). Otherwise: retry once (resume the same `task_id`); a second retry MUST materially change one of instructions / context / model / decomposition / diagnostics — identical prompt + context + model + failure repeated twice is a loop, so stop and escalate or report instead of repeating. If it still fails, do the work inline and log `degraded: <persona> model: <reason>`; never silently skip.
|
|
104
|
+
- **Bound every dispatch (task spec)** — never hand a persona a bare metric ("get under N lines", "type everything"). Each dispatch prompt carries: `Objective` (one deliverable) → `Working tree` (the exact feature-worktree path/branch — or `main` — this task edits; the subagent verifies it before touching a file) → `Owned files` (exact paths) → `Read-only files` → `Shared contracts (owns|consumes)` → `Done = <gate command + observable metric>` → `Out-of-scope`.
|
|
105
|
+
- **Parallel = disjoint** — run personas in parallel only when their owned files AND shared contracts are disjoint; otherwise serialize, with the shared-contract owner dispatched first.
|
|
106
|
+
- **Orchestrator acceptance gate** — after a persona reports done, re-run the gate yourself (`tsc --noEmit`, `npm run lint:hooks`, `npm run test:quick`) and grep the metric before integrating or committing. A subagent's `Evidence` is a claim, not proof.
|
|
107
|
+
- **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.
|
|
108
|
+
- **Dispatch-value gate** — the existence of a persona is NEVER itself a reason to dispatch it. Dispatch only when the persona produces a distinct deliverable with clear ownership and a measurable `Done =` gate that the main model cannot cheaply do itself. Reads, `git status`/`diff`, worktree/branch ops, commits, merges, final integration, simple moves/search-replace, collecting outputs, summarizing results, and simple command runs are ORCHESTRATOR work — never a subagent. A dispatch that is only a repository read, a search, a git op, a trivial edit, or context the orchestrator already holds is unnecessary and must be done inline.
|
|
109
|
+
- **Complexity threshold → direct execution** — trivial or single-surface/single-file changes (rename, typo, constant, one-line doc, simple CSS, config tweak) bypass planning + fan-out: main model implements → targeted gate → done. The planner may emit `execution_mode: direct` (with a reason) instead of a multi-agent dispatch — planning may REDUCE the number of agents, not just choose which to spawn.
|
|
110
|
+
- **Absorb before spawn** — before a new dispatch, ask whether an already-running or just-completed persona can safely absorb the work within its owned scope and contract; extend that dispatch instead of spawning another. Never cross ownership/contract boundaries to save a dispatch.
|
|
111
|
+
- **Stuck-agent detection** — stop a persona that repeats the same reads, tool calls, test failures, or rewrites the same region with no new evidence or changed files. Classify the blocker, attempt one targeted recovery, then escalate (if justified) or report the blocker — never burn more turns.
|
|
112
|
+
- **Early stop** — a persona terminates as soon as its `Done =` gate passes and its deliverable is verified; it must not keep "improving" past the acceptance bar. Completion is evidence-based (the gate output), never self-reported confidence.
|
|
113
|
+
- **Evidence-based escalation** — escalate a persona 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`.
|
|
114
|
+
- **Compact result propagation** — when one persona's output feeds another, pass the structured `Result`/`Evidence`/`Deferred & risks` summary (or the structured facts: changed files, commands run, test results, contracts changed, blocking issue) — never a full verbose transcript — so later personas consume established facts instead of re-discovering requirements, architecture, or locations.
|
|
115
|
+
- **Synchronous Terminal Commands**: Prefer sync one-shot commands (build/test/lint) that return inline, over background servers/watchers. When a tier genuinely needs a live server (runtime/API tiers) — or any long-lived daemon (emulator, Metro, the adb server, a Maestro driver) — start it detached with `node scripts/serve.js start --cmd "<command>" [--url <health url> | --port <n>] [--name <label>]` — it returns immediately and records the PID under `.serve/`. Never background a long-lived process in your own shell (foreground, `&`, `setsid … &`, `Start-Job`, `Start-Process -NoNewWindow`, or any launch that shares the tool's console): the tree stays attached to the tool's console, so the call hangs until you interrupt it. **A `setsid bash -c '… > log 2>&1' &` is NOT detached**: the redirect lands on the *inner* command, so the detached wrapper keeps the tool's stdout/stderr socket open and the call hangs even after its own shell exits — no timeout fires, because the command itself already finished. `serve.js` spawns with `stdio: "ignore"` (POSIX detached session / Windows hidden console) so the tool returns; if you must launch by hand, redirect the wrapper's own fds: `setsid sh -c 'exec <command>' </dev/null >log 2>&1 &`. `serve.js` prints a "launching" line + heartbeats while waiting (a live start is never silent). Poll the health URL/port to know it is up — with the **bounded waiter**, never `sleep`-and-pray: `node scripts/wait-for.js --health <url>` / `--port <n>` (or the `wait` tool) blocks until ready and returns a terminal status on timeout; on a failed start read `.serve/<name>.out.log`; stop with `node scripts/serve.js stop` / `stop-all` when the tier passes — never leave a dev server running (a device/emulator is reused across runs, not stopped between them). Never pipe a `serve` start or a long test run through a buffering filter (`| Select-Object -Last N`, redirect-to-file-then-read) — let it stream, or the run looks frozen and gets aborted mid-flight. If a live-tier call IS interrupted, don't infer the server state from the abort: verify with `node scripts/serve.js list`, `.serve/<name>.out.log`, `adb devices`, and the health URL before continuing. Never kill a process on a port you didn't start (`node scripts/serve.js list` / port owner first) as a "leftover".
|
|
116
|
+
- **No Output Bloat**: Never paste large files/diffs into chat; apply edits with the edit tool, never print a code block of a change.
|
|
117
|
+
- **Right-Size the QA Tier**: Never run the full regression suite for a CSS/copy tweak.
|
|
118
|
+
- **Gate batching**: make a coherent set of related edits, THEN run the gate once — never edit → gate → edit → gate for micro-edits in the same batch. A gate stays mandatory when the dispatch says so, a dependency needs its result, the batch is complete, or the agent is about to report done. If one edit's failure blocks the batch, resolve it first — but do not re-run an unchanged gate as a ritual.
|
|
119
|
+
- **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 (instructions / context / model / decomposition / diagnostics), or report. A gate repeated with `files_changed = 0`, the same command, and the same failure is a retry loop, not a retry.
|
|
120
|
+
- **Patch / file-write recovery**: on a failed patch or write, refresh the target file, regenerate a targeted patch, and retry ONCE — never blindly replay the identical patch. Record `patch_failure`/`retry` in the session handoff. On repeated failure, switch editing strategy (smaller patch, different anchor, write full file).
|
|
121
|
+
- **Web / network failure handling**: one retry when the failure is transient; then fall back (`webfetch`, repository-local evidence, vendor docs already in context) or report the blocker. Never loop query variations hoping the network changes. Record the failure + fallback in the handoff.
|
|
122
|
+
- **Context budget & checkpointing** (see also `.agents/rules/00-operating.md` §Context budget & lifecycle): the main context is a cumulative cost. One bounded orchestration context per work unit; checkpoint compact deterministic state (task/feature/objective/phase, completed + active dispatches, files changed, contracts, known facts, decisions, risks, next_action) into `.agents/handoffs/<feature-id>.md` when approaching the budgets in `.agents/memory/orchestration.md`; resume in a fresh bounded context from the checkpoint, never by replaying the transcript. `checkpoint_write`/`/checkpoint` and `/resume` make it mechanical (`scripts/checkpoint.js`), and `npm run test:prefix` guards the always-loaded prefix against per-run content. Never kill a running tool call — let it finish, then checkpoint/finish — **except a confirmed wedged launch**: the command's own shell has already exited (no child of the agent process) yet a detached descendant still holds the tool's output socket, so the call can never return. Interrupt it, then verify state (`node scripts/serve.js list`, `.serve/<name>.out.log`, `adb devices`, the health URL/port) before continuing; never wait on it indefinitely, and never infer state from the abort. Keep the stable leading context (rules → persona → project rules) byte-stable so it stays cache-friendly.
|
|
123
|
+
|
|
124
|
+
- **Machine capacity & heavy tiers (never freeze the box)**: parallel sessions are welcome; **parallel heavy tiers are not**. WSL2 is one Linux VM with no per-agent limits, so an emulator + two agents + `next dev` + a gate exhausts RAM, thrashes swap, and starves the host↔VM relay — freezing every terminal at once (2026-09-29: `memory=10GB`, 4 GB swap full, load 60). The machine-readable envelope (min free RAM, max live serves, max heavy tiers, idle-reap age) lives in `.agents/memory/orchestration.md`; `serve.js start` checks it plus a machine-wide heavy lock and **refuses** a heavy launch that would exceed it (naming what is already up; `--force` overrides), `test:capacity` (`node scripts/qa/check-capacity.js`) reports free RAM/swap/load/live serves and fails when the envelope is already exceeded, and `agent-harness doctor` adds host + `.wslconfig` advice. Classification is by **program** (`scripts/qa/command-classifier.js`): a read-only probe that merely names a device serial (`adb -s emulator-5554 …`) or an artifact path (`~/.maestro/…`) is never heavy, and a single live `--group` (the device tier's emulator + dev server) counts as ONE tier so a heavy one-shot runs alongside it (a second long-lived tier is still refused). Diagnose a failed device step with `node scripts/qa/mobile-e2e/ui-dump.js` (live or from a Maestro `screen-hierarchy` artifact), never a hand-rolled `adb`/`python` probe. Stop a dev server when its tier passes; reuse an emulator within a session but stop it at session end (`node scripts/serve.js stop --name <label>` / `stop-all`; `list` shows ages; `prune [--worktrees]` clears dead records so a stopped emulator is not misreported as live). `serve.js` also **auto-closes** an orphaned/idle serve: `reap` stops a serve whose owning session's lease is gone/stale (or an untagged one past `idle_reap_minutes` with no recent log activity) and reconciles an untracked `agent-serve-*` unit left by a killed session — it runs at every `start` and when the context-guard plugin sees `session.deleted`, so a dev server/emulator is not kept alive and orphaned. `stop` now verifies the teardown and **keeps the record** if the process survives (an unverified stop was how a live unit became invisible to `list`/`stop-all`). The RAM-backed tmpfs cache is RAM too — keep it small (`AGENT_TMPFS_PERCENT=25`) during device tiers. Heavy tiers are capped **by default**: `serve.js start` runs them as a transient `user.slice` cgroup with `MemoryMax` from the envelope (`heavy_mem_max_mb`, default 5 GB; `--mem-max 4G --cpu-max 250%` overrides, `--no-cap` opts out). A heavy **one-shot** (an APK/Gradle build, a heavy test tier) runs capped and synchronously through `node scripts/serve.js run --cmd "<cmd>" [--mem-max 3G]` — never inline uncapped (the 2026-09-30 Gradle freeze); `scripts/qa/mobile-e2e/build-apk.sh` does this automatically. Members of one `serve.js --group` share a single combined `group_mem_max_mb` budget (so the `mobile` emulator + dev server cannot each take the full `heavy_mem_max_mb`). Apply the one-time host/VM tuning with `sudo bash scripts/wsl-tune.sh apply` (sysctls + `user.slice` ceiling + a soft `init.scope` `MemoryHigh` backstop for the cgroup agents actually run in + `.wslconfig`; only `wsl --shutdown` on Windows is manual). Details: `docs/wsl-optimizations.md`, `docs/mobile-testing.md`.
|
|
125
|
+
- **MCP servers are context + RAM, so scope them per agent, dev-only.** An MCP tool schema is billed on every request that can see it, and opencode spawns the server outside the `serve.js` capacity envelope. Wire MCP project-side (`opencode.json`): 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 (never uat/prod — `.agents/memory/environments.md`). Do not enable GitHub MCP (the most token-heavy, mostly obviated by direct-land). Details, config shape, and the included servers: `docs/mcp-integrations.md`.
|
|
126
|
+
|
|
127
|
+
## 6. Smart Tiered Testing & Progression Protocol
|
|
128
|
+
|
|
129
|
+
- Never run heavy regression suites blindly for small changes.
|
|
130
|
+
- 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.
|
|
131
|
+
- **Static ≠ Runtime rule**: never declare UI/mobile/API changes verified from static typing alone — execute a real runtime path.
|
|
132
|
+
- **Coverage ≠ label rule**: a tier command verifies a change ONLY when its backing suite actually exercises the changed path. A suite that touches unrelated code proves nothing about this change. `npm run test:qa-plan` mechanically asserts every changed code path is covered by the QA plan (or waivered) before verification — and, via `flow-map.md`, that every touched flow's sibling surfaces and declared optional variants are addressed in the plan's audit (the "fix one, fix all" gate: a web-only diff must still say what the mobile twin does).
|
|
133
|
+
- **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`.
|
|
134
|
+
- **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`):
|
|
135
|
+
| Tier | Scope | Command |
|
|
136
|
+
|---|---|---|
|
|
137
|
+
| 1 | UI/CSS/mobile/copy | `npm run test:quick` |
|
|
138
|
+
| 2 | Routes / page layout | `npm run test:routes` |
|
|
139
|
+
| 3 | API / ORM / transactions | `npm run test:api` |
|
|
140
|
+
| 4 | Data ingestion | the project's data E2E script |
|
|
141
|
+
| 5 | Major release / breaking refactor | `npm run test:verify` |
|
|
142
|
+
| 6 | Security / deps | `npm run test:security` |
|
|
143
|
+
- **Live-server tiers (3+)**: a runtime/API tier that hits real routes needs the
|
|
144
|
+
dev server running. Start it detached with `node scripts/serve.js start --cmd "<dev command>" --url <health url>`
|
|
145
|
+
and stop it when the tier passes (`node scripts/serve.js stop`) — see §5. Live-tier calls: never pipe a start or the
|
|
146
|
+
tier run through a buffering filter (`Select-Object -Last N`) — it looks frozen and invites an abort; if a call IS
|
|
147
|
+
interrupted, don't infer state — verify via `node scripts/serve.js list` + `.serve/<name>.out.log` + the health URL.
|
|
148
|
+
- **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`.
|
|
149
|
+
- **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 (`.agents/memory/environments.md`) is enforced at deploy time by `test:data-hygiene -- --env uat|prod`, not by dev-time runs.
|
|
150
|
+
- **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 (this is the "GAP" rule).
|
|
151
|
+
|
|
152
|
+
## 7. Definition of Done & Continuous Backup
|
|
153
|
+
|
|
154
|
+
Every completed task closes with this gate. **QA gates dev work only:** steps 0-2
|
|
155
|
+
run when the session touched code paths — a backlog-only (or docs-only) change skips
|
|
156
|
+
them. Steps 3-7 are the unconditional session close; they are NOT gated by QA.
|
|
157
|
+
|
|
158
|
+
0. **Feature Completeness Gate** (code changes only):
|
|
159
|
+
- [ ] Product-first: `intent.md` (actor/need/outcome/acceptance) + value-led `plan.md` present — `npm run test:product` green (feature work only).
|
|
160
|
+
- [ ] 5 UI states handled on every affected screen (list them).
|
|
161
|
+
- [ ] No `catch` blocks that only `console.warn` without user-facing feedback.
|
|
162
|
+
- [ ] Haptic/feedback consistency for every user-initiated action.
|
|
163
|
+
- [ ] RTL traced if layout touched; logical properties used.
|
|
164
|
+
- [ ] Cross-screen audit if a new UX pattern was introduced.
|
|
165
|
+
- [ ] No modified file over ~500 lines without extracting components.
|
|
166
|
+
- [ ] No blanket file-level `eslint-disable`/`@ts-nocheck`/`@ts-ignore` suppressions (line-level only, each with a reason).
|
|
167
|
+
- [ ] 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).
|
|
168
|
+
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, **and** every touched flow (`.agents/memory/flow-map.md`) has every sibling surface and declared variant addressed in the plan's `## Parallel-surface & variant audit`, **AND** the executed tier exercised the modified path. The plan also carries `## Test budget` (wall-clock + teardown + tier), `## Oracle & owner` (independent behavior + single owner), and `## Test-design self-check` (T1–T10) — and `npm run test:wiring` is green: an authored test that no package script executes is not coverage (T7), and a suite that passes then idles past its budget is a defect (linger check, T1/T6/T9).
|
|
169
|
+
2. **Security check** (code changes only) — apply `security-engineer` when the change touches data/auth/input/secrets/deps.
|
|
170
|
+
3. **Backlog write-back** (always) — move every task this session shipped from `In progress` to `Archive (shipped · done)` in `BACKLOG.md` (`backlog_archive`, with date/commit), then stage it explicitly: `git add BACKLOG.md` (it starts untracked — `git commit -am` / `git commit` without `add` will NOT pick it up). The board syncs across sessions only through git, so this delta is committed with the code, never left uncommitted. (At session start, the inverse: move the picked-up row `Open` → `In progress` via `backlog_take`, pointing `Handoff` at the session's `.agents/handoffs/<id>.md`, so the board always shows what is actively being worked.)
|
|
171
|
+
4. **Docs write-back** (always, on land) — dispatch the `docs` persona to keep human-facing docs in sync with this session's shipped change: append a `CHANGELOG.md` line that cites 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 on any shipped commit with no changelog entry, so a docs-only `chore`/`docs` commit is not enough — the changelog delta ships in the same commit as the code. Right-size: a copy/CSS tweak needs at most a changelog line.
|
|
172
|
+
5. **Commit** (always) — concise `feat:` / `fix:` / `refactor:` message, including the `BACKLOG.md` and `CHANGELOG.md` deltas.
|
|
173
|
+
6. **Land the branch** (always) — `npm run finalize -- --feature <id>` (or `npm run ship`) integrates on `origin/main`, runs the branch gates (and, when no pre-push hook is installed, the harness process gates itself, so a missing hook cannot skip them), and lands the branch with a **direct fast-forward push to `main`**. There is no PR, no landing label, and no merge train. **Integrate early first**: `git fetch origin && git rebase origin/main` (ship does this), so conflicts surface before the gates. **Ship then waits for CI**: it polls the CI workflow on the landed SHA and exits 0 only once CI is green (or non-zero with the blocker). A concurrent landing (another session pushed first) is resolved automatically by re-fetch + rebase + retry. `--no-ci-wait` stops after landing but is a **pause, not a completion** — the CI run is the completion contract. A session that stops before the branch is landed (and CI confirmed) is not done. `agent-harness doctor --target .` reports whether the cycle is ready.
|
|
174
|
+
7. **Deploy to UAT** (CI-owned) — the `CI` workflow completing successfully on `main` triggers `.github/workflows/deploy-uat.yml`, which deploys the landed SHA to `uat` as a prebuilt artifact (`vercel build` → `vercel deploy --prebuilt`), then runs `prisma migrate deploy` over the direct URL (F-136) + idempotent seed + alias/parity/smoke verification + `npm run test:data-hygiene -- --env uat`. Do NOT run a local `deploy:uat` in the normal flow — it is the emergency path (CI sets `DEPLOY_CI=1`; a local run must not). Production is human-gated and NOT part of a normal task. Never forward dev data — code + schema + idempotent seeds only (`.agents/memory/environments.md`).
|
|
175
|
+
- **Mechanical floor**: a pre-push hook should run `npm run test:quick` (project-provided; the harness does not install git hooks).
|
|
176
|
+
- **Concurrency isolation (never let a concurrent session's WIP block yours)**: the board + a shared working tree means one session's half-done files (e.g. a page referencing translation keys not yet in `messages/*.json`) can fail *another* session's push for no fault of its own. The harness ships mechanical counters:
|
|
177
|
+
- `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 — the collision is *provable*, so it fails fast instead of surfacing as a random `check-translations`/`tsc` error. Declare each row's owned files (`.agents/memory/owned-files.md`, via `backlog owns <id> --files ...`) and the gate fails *exactly* when a dirty file is owned by two In-progress rows (or a tree mixes two sessions' WIP), instead of on every "2+ In progress + dirty" tree. It also reports the live *primary sessions* sharing a checkout via `.serve/sessions/` leases (written/heartbeat by the context-guard plugin): liveness requires the pid **and** a matching process birth token (`bootId` + `/proc` starttime) **and** a fresh heartbeat, so a recycled pid or a session closed without a `session.deleted` event can't linger. That report is **advisory** — two live sessions on a clean tree never fail a push (a clean tree has no WIP to collide over), so a legitimate finalization can no longer be stranded behind an unrelated live session; only the provable dirty-tree contention above fails. `node scripts/qa/check-concurrency.js --prune` clears dead/recycled/stale leases.
|
|
178
|
+
- **Isolate per feature** with `backlog worktree <id>` (or the `backlog_worktree` tool): it creates a `git worktree` + branch for the feature and records the path in the row's `Handoff` cell. Run it from the **main** tree before starting ANY feature — `main` stays board + shippable code only, every feature works in its own checkout, and another session's WIP can't leak into your gates. When a human starts the worktree at a terminal, `--open` launches the agent CLI *inside* it, so the session's lease + gates are scoped to the worktree instead of `main`. Worktrees live in a hidden sibling container (`<repo>/../.worktrees/<repo>/<id>`), and `backlog archive <id>` removes a shipped feature's worktree + merged branch — so the parent folder stays clean and a session leaves nothing hanging after it closes. If a session ended without archiving, `backlog worktree-prune` converges the set: it removes clean worktrees whose branch is already merged and keeps anything unmerged or dirty.
|
|
179
|
+
- **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).
|
|
180
|
+
- **Ordering**: 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.
|
|
181
|
+
- **Snapshot gating**: `node scripts/qa/run-clean.js -- npm run test:quick` runs a project gate against the *committed* state (stashes + restores any dirty files), so a pre-push gate verifies *your* committed work, not the tree. Prefer this wrapper in the pre-push hook for tree-scoped gates.
|
|
182
|
+
- **Lean permissions**: grant only the narrowest `git`/`gh` action needed; escalate only after a command has actually failed.
|
|
183
|
+
- Git may not be on PATH in the default shell — use the full path (`.agents/memory/locations.md`).
|
|
184
|
+
|
|
185
|
+
## 8. Session & Traceability Discipline
|
|
186
|
+
|
|
187
|
+
- **One session = one coherent task**; keep a short checklist as the single source of truth. Use opencode's todo panel (`todowrite`) for multi-step work: create it early, exactly ONE item `in_progress`, mark each item `completed` right after its own verification step, and close every finished item before checkpointing or reporting. A single-step fix needs no list; a stale panel is worse than none.
|
|
188
|
+
- **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.
|
|
189
|
+
- **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`. If a feature needs one changed (a gate or QA-script fix), make the 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` here — do NOT hand-edit the deployed copy. **Route (F-12):** you cannot edit the harness from a session rooted in *this* project — the main-checkout guard blocks a code edit aimed at another checkout, and worktree isolation is per-repo. Make the fix from a session rooted in the harness checkout itself (`opencode` in `~/develop/agent-harness`), edit `templates/` there, release, then `agent-harness update .`; record the harness gap on the board so it is not lost when the project session ends. As of harness `0.1.100` an `update` **fails closed** on a hand-edited harness file (naming it and pointing at `templates/`); `--accept-harness` overwrites deliberately after a backup and rolls the clobber back if `test:quick` goes red. The F-289 incident was exactly this: a project-side `board-sync.js` fix was silently reverted by the next deploy.
|
|
190
|
+
- **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.
|
|
191
|
+
- **Value-first completion report**: close a session by telling the user, in plain language, **what value shipped** (what they now get / what changed for them) and the main **how** — before any file/test/technical detail. The same summary is recorded durably in the handoff's `## Value shipped` + `## How` sections.
|
|
192
|
+
- **Explain at the reader's level**: all user-facing prose (progress updates, plans, explanations, and completion reports) is written for someone who knows the product but not the codebase. Lead with the observable behavior and the affected part of the system in plain terms; treat a code identifier (`syncCatalog()`, `OrderRouter`, a table/route name) as supporting detail — introduced only when precision needs it, and glossed on first use. This is a *level*, not abstraction: stay concrete and technical (no theory or business-speak), but never make an internal symbol the subject of a sentence. Example — low-level: "`dedupeById()` early-returns when `seen.has(id)`."; reader-level: "the importer now skips duplicates it has already seen, so a book no longer appears twice."
|
|
193
|
+
- **Dispatch Log (mandatory)**: every wrap-up opens with `subagent → model → shipped/deferred`. An empty log is non-compliant.
|
|
194
|
+
- **Structured session telemetry**: every handoff records, when known and never fabricated:
|
|
195
|
+
- `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.
|
|
196
|
+
- `work_type` — one of `feature | bugfix | investigation | architecture | planning | qa | security | maintenance | process | conversation | other`.
|
|
197
|
+
- `outcome` — one of `shipped | resolved | deferred | investigation-complete | abandoned | superseded | conversation-only`.
|
|
198
|
+
- `termination_reason` — why the session ended (e.g. `gate-pass`, `checkpoint`, `blocked`, `escalated`, `abandoned`).
|
|
199
|
+
- `model_escalation_evidence` — when the primary session ran on an `escalation_models:` model (`.agents/memory/model-routing.md`), the reason (or `none` when no escalation happened). `npm run report -- --cost` flags a pro-model primary session with no recorded evidence.
|
|
200
|
+
- Retries/escalations with `attempt` numbers and reasons (see §5 bounded retries).
|
|
201
|
+
- `null` / `unknown` when the runtime cannot know a value — never infer exact token/cost numbers from character counts, and never invent values.
|
|
202
|
+
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.
|
|
203
|
+
- **Persist Continuity**: use the `handoff` skill to write your session's file under `.agents/handoffs/` (one per session — never edit another session's). Project history lives in `.agents/memory/history.md`; stack facts in `.agents/memory/stack-versions.md`.
|
|
204
|
+
- **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)
|