@llipe.com/dev-tasks 0.16.1 → 0.16.2

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.
@@ -21,10 +21,12 @@ If validation fails, run: `memo setup init --repo <repo> --org <org> --domain <d
21
21
 
22
22
  ## Banks and Kinds (memo-cli 1.3.0+)
23
23
 
24
- A **bank** is a namespace an agent's entries live in — the shared `kb` (default, semantic knowledge base) or a private bank like `developer-memory`, one per long-lived agent. Set `--bank <id>` on any command, or export `MEMO_BANK` for the session so every command picks it up by default:
24
+ A **bank** is a namespace an agent's entries live in — the shared `kb` (default, semantic knowledge base) or a private bank like `developer-memory`, one per long-lived agent. Set `--bank <id>` on any command.
25
+
26
+ **Agents: always pass `--bank <id>` literally on every command.** Agent runtimes run each shell command in a fresh shell, so an `export MEMO_BANK=…` from an earlier command is gone by the next one. An unquoted empty `$MEMO_BANK` is dropped by the shell, and the flag parser then reads the next token as the bank id (`--bank --rationale …` → bank `--rationale`), which memo-cli rejects with `VALIDATION_FAILED` (dev-tasks issue #253). Never write `--bank $MEMO_BANK` in an agent prompt or command.
25
27
 
26
28
  ```bash
27
- export MEMO_BANK=developer-memory # bank id convention: <agent-name>-memory
29
+ memo write --bank developer-memory ... # bank id convention: <agent-name>-memory
28
30
  ```
29
31
 
30
32
  Every entry has a **kind**:
@@ -44,10 +46,10 @@ Rule of thumb: episodic entries are per-session chatter that lives in your priva
44
46
  **memo-cli 1.3.0+:** one call restores the full context bundle (SELF, POLICIES, SHARED, MINE, LAST SESSION, CONFLICTS):
45
47
 
46
48
  ```bash
47
- memo recall "<current task description>" --bank $MEMO_BANK --json
49
+ memo recall "<current task description>" --bank <agent>-memory --json
48
50
  ```
49
51
 
50
- If `$MEMO_BANK` is unset, `recall` resolves to `kb` and omits the private-only sections (`SELF`, `MINE`, `LAST SESSION`).
52
+ If no bank is passed (and `MEMO_BANK` is unset), `recall` resolves to `kb` and omits the private-only sections (`SELF`, `MINE`, `LAST SESSION`).
51
53
 
52
54
  **Fallback (`memo --version` < 1.3.0, or `memo recall` unavailable):** run the four-command sequence instead:
53
55
 
@@ -75,7 +77,7 @@ Synthesize findings (either path) into:
75
77
  memo write \
76
78
  --kind episodic \
77
79
  --session ISSUE-<number> \
78
- --bank $MEMO_BANK \
80
+ --bank <agent>-memory \
79
81
  --rationale "Context: Starting ISSUE-<##> because <trigger>. Decision: implement via <approach>, preserving <constraints>. Impact: affects <modules/contracts>." \
80
82
  --tags "<domain>,issue-<number>,intent,<impact-tag>" \
81
83
  --entry-type decision \
@@ -91,7 +93,7 @@ memo write \
91
93
  memo write \
92
94
  --kind episodic \
93
95
  --session ISSUE-<number> \
94
- --bank $MEMO_BANK \
96
+ --bank <agent>-memory \
95
97
  --rationale "Context: Completed ISSUE-<##>. Delivery: shipped <behavior>, deviations <none|details>, AC <x/y> verified. Impact: quality gates test=<p/f>; lint=<p/f>; format:check=<p/f>; typecheck=<p/f>; audit=<p/f>." \
96
98
  --tags "<domain>,issue-<number>,outcome,gates-pass" \
97
99
  --entry-type decision \
@@ -180,12 +182,12 @@ No memo action in Phase 2. `memo used` and `memo decay` arrive with memo-cli 1.4
180
182
 
181
183
  ```
182
184
  memo setup validate # Verify config
183
- memo recall "<task>" --bank $MEMO_BANK --json # Restore full context (1.3.0+)
185
+ memo recall "<task>" --bank <agent>-memory --json # Restore full context (1.3.0+)
184
186
  memo write --rationale "..." --tags "a,b,c" --json # Record a semantic decision (kb)
185
- memo write --kind episodic --session ID --bank $MEMO_BANK # Record an intent/outcome entry
187
+ memo write --kind episodic --session ID --bank <agent>-memory # Record an intent/outcome entry
186
188
  memo search "query" [--scope related] --json # Semantic search
187
189
  memo list [--limit N] --json # Browse recent
188
- memo timeline [--session ID] --bank $MEMO_BANK --json # Replay episodic memory in order
190
+ memo timeline [--session ID] --bank <agent>-memory --json # Replay episodic memory in order
189
191
  memo tags list [--sort frequency] --json # Discover tags
190
192
  memo inspect --json # Global facets
191
193
  memo bank list --json # List all banks
@@ -118,15 +118,17 @@ Follow `.kiro/steering/implement.md`:
118
118
  - Run `git rev-parse --abbrev-ref HEAD` to determine the current branch.
119
119
  - If HEAD is the default branch (`main`) or does not match `issue/*` or `story/*` pattern, you **MUST** create a new branch before proceeding, then open the Draft PR immediately after the first commit on that branch. You **MUST NOT** write implementation code, create files, or make commits while on the default branch.
120
120
  - If HEAD is already a valid feature branch (matching `issue/*` or `story/*`), confirm the Draft PR exists and proceed. If the branch has no commits yet, no PR can exist — open it immediately after the first commit.
121
- 5. Execute one sub-task at a time in checklist order. For each behavioral sub-task, follow **test-first**: write/update tests first, verify they fail for the right reason, then implement to make them pass.
122
- 6. After each completed sub-task: mark `[x]` locally and in GitHub, pause for approval if step-gated.
123
- 7. When all sub-tasks are complete:
121
+ 5. **memo intent (when memo is available):** Before writing any implementation code, run the memo-cli Availability Check and write the intent entry (see **memo-cli Integration → Intent Entry**). Record `memo_intent` as `written(<id>)`, `failed(<reason>)`, or `skipped(<reason>)`.
122
+ 6. Execute one sub-task at a time in checklist order. For each behavioral sub-task, follow **test-first**: write/update tests first, verify they fail for the right reason, then implement to make them pass.
123
+ 7. After each completed sub-task: mark `[x]` locally and in GitHub, pause for approval if step-gated.
124
+ 8. When all sub-tasks are complete:
124
125
  - Verify all acceptance criteria.
125
126
  - Run mandatory quality gates and record results (`test`, `lint`, `format:check`, `typecheck`, `audit`; `validate` if available).
126
127
  - For migration-bearing changes, confirm migration artifact/rollback notes and execute apply only after explicit user confirmation.
127
128
  - Invoke `qa-engineer` to run the testing-standard check and the coverage and gap report, and record `coverage_gate`. This runs before the `verifier` audit so the audit can consume the gap report as test evidence.
128
129
  - Invoke `verifier` in `audit` mode against the delivered implementation, and post its human-readable summary to the issue/PR via `github-ops` comment conventions. This step is mandatory and non-skippable; drift findings reported by `verifier` do not block this step or PR/issue completion.
129
130
  - Invoke `technical-writer` for documentation update and drift/stale-doc validation.
131
+ - Write the memo outcome entry (see **memo-cli Integration → Outcome Entry**) and record `memo_outcome` as `written(<id>)`, `failed(<reason>)`, or `skipped(<reason>)`.
130
132
  - Convert PR from Draft to Ready for Review.
131
133
 
132
134
  ---
@@ -191,11 +193,9 @@ When diagnosing a bug, regression, or unclear failure during implementation, you
191
193
 
192
194
  ### Bank Declaration
193
195
 
194
- This agent's bank id is `developer-memory`, stable for the agent's life (PRD §15). Export it before any memo command in the session:
196
+ This agent's bank id is `developer-memory`, stable for the agent's life (PRD §15). Every memo command below names it **literally** with `--bank developer-memory`.
195
197
 
196
- ```bash
197
- export MEMO_BANK=developer-memory
198
- ```
198
+ You **MUST NOT** rely on `export MEMO_BANK=…` from an earlier command, and **MUST NOT** write `--bank $MEMO_BANK`. Agent runtimes run each shell command in a fresh shell, so an exported variable is gone by the next call; an empty `$MEMO_BANK` is dropped by the shell and the flag parser takes the next token as the bank id (`--bank --rationale …` → bank `--rationale`), which memo-cli rejects with `VALIDATION_FAILED`. This is the defect that left consumer banks empty (issue #253).
199
199
 
200
200
  ### Availability Check
201
201
 
@@ -205,18 +205,19 @@ At the start of every execution session, check if memo-cli is configured:
205
205
  which memo && memo setup validate
206
206
  ```
207
207
 
208
- - If `memo` is not found, skip all memo operations silently.
209
- - If `memo` is found but validation fails, ask: "memo-cli is installed but not configured for this repository. Run `memo setup init --repo <repo> --org <org> --domain <domain>` to configure it."
208
+ - If `memo` is not found **and** `memo.config.json` does not exist, skip all memo operations and record `memo_intent: skipped(memo-not-installed)` / `memo_outcome: skipped(memo-not-installed)`.
209
+ - If `memo` is not found **but** `memo.config.json` exists, the repository expects memo: warn the user ("memo-cli is configured for this repository (`memo.config.json`) but the `memo` binary is not on PATH in this session — no memo entries will be written.") and record `skipped(memo-unavailable)` for both fields. Never skip silently in this case.
210
+ - If `memo` is found but validation fails, ask: "memo-cli is installed but not configured for this repository. Run `memo setup init --repo <repo> --org <org> --domain <domain>` to configure it." If the run continues without it, record `skipped(memo-not-configured)`.
210
211
 
211
212
  ### Session Start — Restore Context
212
213
 
213
214
  When memo is available and `memo --version` is `1.3.0` or later, restore context with a single call:
214
215
 
215
216
  ```bash
216
- memo recall "<story or issue description>" --bank $MEMO_BANK --json
217
+ memo recall "<story or issue description>" --bank developer-memory --json
217
218
  ```
218
219
 
219
- `recall` returns one bundle — SELF, POLICIES, SHARED, MINE, LAST SESSION, CONFLICTS — in a single `<4s` call (SELF/MINE/LAST SESSION are omitted when `$MEMO_BANK` is unset or resolves to `kb`). If `memo recall` exits `2` (embeddings failure), surface the warning on stderr and continue the session without recalled context rather than blocking.
220
+ `recall` returns one bundle — SELF, POLICIES, SHARED, MINE, LAST SESSION, CONFLICTS — in a single `<4s` call. If `memo recall` exits `2` (embeddings failure), surface the warning on stderr and continue the session without recalled context rather than blocking.
220
221
 
221
222
  **Fallback — `memo --version` is below `1.3.0`:** run the four-command sequence instead:
222
223
 
@@ -247,45 +248,55 @@ Choose the most specific entry type:
247
248
 
248
249
  ### Intent Entry — Before Starting a Story
249
250
 
250
- Write an intent entry **before beginning implementation** of any story or issue, as an episodic entry scoped to this session in this agent's bank:
251
+ Write an intent entry **before beginning implementation** of any story or issue (Execution Flow step 5), as an episodic entry scoped to this session in this agent's bank:
251
252
 
252
253
  ```bash
253
254
  memo write \
254
255
  --kind episodic \
255
256
  --session ISSUE-<n> \
256
- --bank $MEMO_BANK \
257
+ --bank developer-memory \
257
258
  --rationale "Context: Starting ISSUE-<##> because <trigger/need>. Decision: implement via <approach>, preserving <constraints/non-goals>, with expected files <key files>. Impact: affects <user/module/contract impact> and introduces risks <if any>." \
258
259
  --tags "<domain>,issue-<number>,intent,<impact-tag>[,<boundary-tag>]" \
259
- --entry-type decision \
260
- --source agent \
261
- --story "ISSUE-<number>" \
262
- --on-duplicate consolidate \
263
- --json
260
+ --entry-type decision \
261
+ --source agent \
262
+ --story "ISSUE-<number>" \
263
+ --on-duplicate consolidate \
264
+ --json
264
265
  ```
265
266
 
266
267
  ### Outcome Entry — After Completing a Story
267
268
 
268
- Write an outcome entry as part of the **Completion Gate**, after all tests pass and before converting the PR to Ready for Review, as an episodic entry scoped to this session in this agent's bank:
269
+ Write an outcome entry as part of the **Completion Gate** (Execution Flow step 8), after all tests pass and before converting the PR to Ready for Review, as an episodic entry scoped to this session in this agent's bank. Record what was learned, not only what shipped — a rejected approach, a surprise in the codebase, or a constraint discovered mid-story is the most valuable content of this entry:
269
270
 
270
271
  ```bash
271
272
  memo write \
272
273
  --kind episodic \
273
274
  --session ISSUE-<n> \
274
- --bank $MEMO_BANK \
275
- --rationale "Context: Completed ISSUE-<##> after implementing <scope>. Delivery: shipped <behavior>, deviations <none|details>, AC <x/y> verified. Impact: quality gates test=<pass|fail>; lint=<pass|fail>; format:check=<pass|fail>; typecheck=<pass|fail>; audit=<pass|fail>; docs=<clean|drift-fixed>; migration=<none|details>." \
276
- --tags "<domain>,issue-<number>,outcome,gates-pass[,<impact-tag>][,<boundary-tag>]" \
277
- --entry-type decision \
278
- --source agent \
279
- --commit "$(git rev-parse HEAD)" \
280
- --story "ISSUE-<number>" \
281
- --files "<comma-separated key files modified>" \
282
- --on-duplicate consolidate \
283
- --json
275
+ --bank developer-memory \
276
+ --rationale "Context: Completed ISSUE-<##> after implementing <scope>. Delivery: shipped <behavior>, deviations <none|details>, AC <x/y> verified. Learned: <rejected approaches, surprises, constraints discovered|none>. Impact: quality gates test=<pass|fail>; lint=<pass|fail>; format:check=<pass|fail>; typecheck=<pass|fail>; audit=<pass|fail>; docs=<clean|drift-fixed>; migration=<none|details>." \
277
+ --tags "<domain>,issue-<number>,outcome,gates-pass[,<impact-or-boundary-tag>]" \
278
+ --entry-type decision \
279
+ --source agent \
280
+ --commit "$(git rev-parse HEAD)" \
281
+ --story "ISSUE-<number>" \
282
+ --files "<comma-separated key files modified>" \
283
+ --on-duplicate consolidate \
284
+ --json
284
285
  ```
285
286
 
287
+ memo-cli accepts 2–5 tags per entry and rejects more with `VALIDATION_FAILED`; keep both templates within that limit.
288
+
286
289
  Session sequence numbers (`--seq`) auto-increment per `--session`; do not pass `--seq` explicitly unless replaying a specific position.
287
290
 
288
- ADR and durable-decision entries are **not** written by `developer` — they stay `--kind semantic` in `kb`, authored by `technical-writer` with `--provenance <csv>` (citing the episodic ids that informed the decision) or `--manual`, per PRD K3.
291
+ ### Write Results Are Recorded, Never Swallowed
292
+
293
+ Every `memo write` above returns JSON with the new entry's `id` on success, and a non-zero exit with an error on failure.
294
+
295
+ - On success, record the id: `memo_intent: written(<id>)` / `memo_outcome: written(<id>)`.
296
+ - On failure, read the error, fix the command if the error names a flag or value you supplied, and retry **once**. If it still fails, record `failed(<error code or first line of the error>)` and state it in the closeout summary. A failed memo write does not block the story, but it **MUST NOT** be dropped silently.
297
+ - Both fields are **mandatory** in the closeout payload. Omitting either one marks the story incomplete.
298
+
299
+ ADR and durable-decision entries are **not** written by `developer` — they stay `--kind semantic` in `kb`, authored by `technical-writer` and `product-engineer`, per PRD K3.
289
300
 
290
301
  ### Session Close
291
302
 
@@ -306,7 +317,7 @@ Before marking a Story/Issue done:
306
317
  7. `technical-writer` agent **MUST** have run and produced both a delta report and a drift/stale-doc validation result.
307
318
  8. `/docs` **MUST** be updated to current state.
308
319
  9. `/workstream` **SHOULD** be cleaned (active artifacts retained, obsolete artifacts archived/removed).
309
- 10. If memo-cli is available, an episodic outcome entry **MUST** be written to `$MEMO_BANK` (`memo write --kind episodic --session ISSUE-<n> --bank $MEMO_BANK …`) before PR conversion.
320
+ 10. The memo intent and outcome writes **MUST** have been attempted when memo-cli is available (`memo write --kind episodic --session ISSUE-<n> --bank developer-memory …`, before PR conversion), and `memo_intent` / `memo_outcome` **MUST** be recorded as `written(<id>)`, `failed(<reason>)`, or `skipped(<reason>)`. A `failed` or `skipped` value does not block completion; an omitted field does.
310
321
  11. PR **MUST** be ready, approved, and merged.
311
322
  12. You **MUST NOT** close the GitHub Issue until all conditions above are met.
312
323
  13. For multi-story implementations, you **MUST** run a checklist cross-check between GitHub Issue tasks and `/workstream/tasks-*.md` and report any mismatch resolution.
@@ -367,6 +378,8 @@ workstream_files:
367
378
  - typecheck: PASS | FAIL | NOT RUN
368
379
  - audit: PASS | FAIL | NOT RUN
369
380
  coverage_gate: PASS | FAIL | SKIPPED(<reason>)
381
+ memo_intent: written(<id>) | failed(<reason>) | skipped(<reason>)
382
+ memo_outcome: written(<id>) | failed(<reason>) | skipped(<reason>)
370
383
  checklist_sync: synced | mismatch-fixed | blocked
371
384
  verifier_audit: run | blocked
372
385
  fidelity_verdict: High | Medium | Low | none
@@ -380,6 +393,7 @@ Rules for this payload:
380
393
 
381
394
  - The markers `BEGIN CLOSEOUT PAYLOAD` and `END CLOSEOUT PAYLOAD` **MUST** appear exactly as written.
382
395
  - Every field is required. Use `none`, `NOT RUN`, or `blocked` when a value does not exist.
396
+ - `memo_intent` and `memo_outcome` are always present. `skipped(<reason>)` (memo not installed, not configured, or unavailable in this session) and `failed(<reason>)` (the write was attempted and errored after one retry) are valid values that do not block the merge; `planner` treats an absent field as an incomplete story.
383
397
  - `planner` may treat the story as incomplete if either marker or any required field is missing.
384
398
 
385
399
  Do not dump full files unless explicitly requested.
@@ -88,13 +88,39 @@ If any required input is missing, ask one focused question with a default option
88
88
 
89
89
  ### Bank Declaration
90
90
 
91
- This agent's bank id is `planner-memory`, stable for the agent's life (PRD §15). Export it before any memo command in the session:
91
+ This agent's bank id is `planner-memory`, stable for the agent's life (PRD §15). Name it **literally** in every memo command (`--bank planner-memory`); never rely on an `export MEMO_BANK=…` from an earlier command and never write `--bank $MEMO_BANK` — each shell command runs in a fresh shell, the variable is empty, and memo-cli rejects the resulting bank id (issue #253).
92
+
93
+ ### Availability Check
94
+
95
+ At the start of every run:
92
96
 
93
97
  ```bash
94
- export MEMO_BANK=planner-memory
98
+ which memo && memo setup validate
95
99
  ```
96
100
 
97
- `planner` does not read or write memo entries itself — orchestration-scoped context comes from the task file/GitHub milestone, and each delegated `developer` subagent runs its own `memo recall`/`memo write` sequence scoped to `developer-memory`. This declaration exists for AC parity with the other long-lived agent definitions and for any future orchestration-level use of `--bank $MEMO_BANK`.
101
+ - If `memo` is not found and `memo.config.json` does not exist, skip all memo operations.
102
+ - If `memo` is not found but `memo.config.json` exists, warn the user that the repository expects memo-cli but the binary is not on PATH in this session, and record `memo_run_outcome: skipped(memo-unavailable)`. Never skip silently in this case.
103
+
104
+ ### Responsibilities
105
+
106
+ - **Per story — verify, don't write.** Each delegated `developer` subagent writes its own intent/outcome entries to `developer-memory`. Planner verifies them through the closeout payload's `memo_intent` / `memo_outcome` fields (merge gate 3). An absent field means the story is incomplete; `skipped(<reason>)` or `failed(<reason>)` is reported in the story status table and does not block the merge.
107
+ - **Per run — write one outcome entry.** Before opening the consolidated PR (Phase 5 step 6), write one episodic entry summarizing the run:
108
+
109
+ ```bash
110
+ memo write \
111
+ --kind episodic \
112
+ --session <plan-id> \
113
+ --bank planner-memory \
114
+ --rationale "Context: Ran <plan-id> (<PRD/milestone>, <roadmap phase/wave>). Delivery: <n> stories merged, <n> blocked, integration branch <branch>. Learned: <recurring failures, rework, dependency surprises, gates that caught real problems|none>. Memo coverage: <n>/<n> stories with written intent+outcome; <skipped/failed summary|none>." \
115
+ --tags "<domain>,<plan-id>,run-outcome,<roadmap-phase-tag>" \
116
+ --entry-type decision \
117
+ --source agent \
118
+ --commit "$(git rev-parse HEAD)" \
119
+ --on-duplicate consolidate \
120
+ --json
121
+ ```
122
+
123
+ Record the result as `memo_run_outcome: written(<id>) | failed(<reason>) | skipped(<reason>)` in the planner state file and the consolidated PR body. On failure, fix the command if the error names a flag or value you supplied and retry once; never drop a failure silently.
98
124
 
99
125
  ### Session Close
100
126
 
@@ -139,6 +165,10 @@ Expected return for each issue:
139
165
 
140
166
  Map milestone issues into the same internal story model used by Option A.
141
167
 
168
+ ### Roadmap Read
169
+
170
+ Read `docs/roadmap.md` (the roadmap overview — see **Roadmap Maintenance** below). Identify the PRD and the phase/wave row this run delivers, and state it when confirming the source. If the file is missing, or no row matches this run's scope, say so and ask `product-engineer` (or the user) to add the row before Phase 4; do not invent a row's scope yourself.
171
+
142
172
  Confirm source and story count before Phase 0.5.
143
173
 
144
174
  ---
@@ -367,6 +397,7 @@ Integration target branch: {{ integration_branch }}
367
397
  Test-first: YES — write/update tests before implementation for each behavioral sub-task
368
398
  Test plan: {{ test_plan_path | default: "none — derive tests from acceptance criteria" }}
369
399
  Decision log: {{ decision_log_path }}
400
+ Memo: if memo-cli is available, write the intent entry before coding and the outcome entry before PR conversion, with `--bank developer-memory` named literally; return `memo_intent` and `memo_outcome` in the closeout payload
370
401
 
371
402
  Implement only this story scope.
372
403
  Follow test-first design: for each behavioral sub-task, write tests first, verify they fail, then implement.
@@ -452,7 +483,7 @@ For each completed story PR:
452
483
 
453
484
  1. Verify PR base branch is the integration branch.
454
485
  2. Verify required checks are successful.
455
- 3. Verify delegated closeout payload reports `docs_drift_status` as `clean` or `drift-fixed`.
486
+ 3. Verify delegated closeout payload reports `docs_drift_status` as `clean` or `drift-fixed`, and carries both `memo_intent` and `memo_outcome` fields. An absent memo field marks the story incomplete (retry the closeout once, as for any missing payload field); a `skipped(<reason>)` or `failed(<reason>)` value is recorded in the story status table and does **NOT** block the merge.
456
487
  4. Verify delegated quality gates are all `PASS` (`test`, `lint`, `format:check`, `typecheck`, `audit`).
457
488
  5. Verify the delegated closeout payload reports `coverage_gate` with a value of `PASS`, `FAIL`, or `SKIPPED(<reason>)` carrying a non-empty reason. An omitted field means the QA gate was never reached — treat the story as incomplete. A `FAIL` or `SKIPPED` value does **NOT** block the merge; only omission does.
458
489
  6. Verify the delegated closeout payload reports `verifier_audit: run` — this confirms `developer` invoked the mandatory `verifier` audit for this story. This check is a merge gate on trigger evidence only; the audit's drift findings (`fidelity_verdict`/`highest_drift_impact`/`drift_findings`) **MUST NOT** block the merge.
@@ -489,14 +520,18 @@ After all stories are merged into integration:
489
520
  2. Invoke `qa-engineer` at **PRD scope** (all packages affected by the merged stories, all layers) for a coverage and gap rollup. Report a PRD-level `coverage_gate` that aggregates per-story gates. Scope to packages affected by the merged stories, not the entire workspace.
490
521
  3. Invoke `verifier` in `audit` mode for a **PRD-level rollup audit** against the full integrated scope (all merged stories on the integration branch, cross-checked against the source PRD/spec/milestone). This is mandatory and non-skippable — it runs whether or not any story-level drift was previously reported. Post the resulting human-readable summary to the plan/milestone issue via `github-ops` comment conventions. Rollup drift findings **MUST NOT** block the consolidated PR handoff; Unintended/Intended drift routes to `product-engineer`'s `activity-drift-reconciliation` flow.
491
522
  4. Invoke `technical-writer` for a planner-level drift/stale-doc validation pass against integrated changes; unresolved drift **MUST** block handoff.
492
- 5. Open one consolidated PR from integration branch to `main`.
493
- 6. **Do NOT merge.** Notify the user that the consolidated PR is ready for their review.
494
- 7. Wait for the user to approve and merge the PR into `main`.
495
- 8. **Post-integration deploy handoff (conditional).** When the merged scope includes deployable changes and the repository declares environments in `infra/environments.yaml`, planner **MUST** hand the deploy off to `infra-engineer` rather than running any platform write or deploy command itself. This handoff is conditional — it applies only when infrastructure/deploy scope is present; a docs- or test-only integration triggers no deploy. Planner names `infra-engineer` as the owner of the post-integration deploy (dev on merge to `main`, production behind the protected-environment reviewer on the release tag via the `deploy-ops` workflow templates) and never invokes `deploy.sh`, `release.sh`, `flyctl`, `aws`, or `supabase` directly.
496
- 9. Before final handoff, **MUST** ensure the local working branch is the integration branch used for this run:
497
- - Preferred: run `git checkout integration/<plan-id>-<short-description>`.
498
- - Alternative (if checkout is not possible in the current runtime): explicitly verify and report current branch, and provide the exact checkout command the user can run.
499
- 10. Final user response **MUST** include a `PR Directives (User Action Required)` section with:
523
+ 5. **Roadmap update (mandatory).** Update the run's row(s) in `docs/roadmap.md` on the integration branch, so the change ships in the consolidated PR itself: set `Status` (`Done` when every story in the phase/wave merged, otherwise `In progress`), fill `Issues/PRs` with the story issues and the consolidated PR, rewrite `What's missing` to the remaining scope (`—` when none), and set the `Last updated` date. A consolidated PR without this roadmap change is incomplete. See **Roadmap Maintenance** below.
524
+ 6. **memo run outcome.** Write the per-run outcome entry described in **memo-cli Integration → Responsibilities** and record `memo_run_outcome`.
525
+ 7. Open one consolidated PR from integration branch to `main`.
526
+ 8. **Do NOT merge.** Notify the user that the consolidated PR is ready for their review.
527
+ 9. Wait for the user to approve and merge the PR into `main`.
528
+ 10. **Post-integration deploy handoff (conditional).** When the merged scope includes deployable changes and the repository declares environments in `infra/environments.yaml`, planner **MUST** hand the deploy off to `infra-engineer` rather than running any platform write or deploy command itself. This handoff is conditional — it applies only when infrastructure/deploy scope is present; a docs- or test-only integration triggers no deploy. Planner names `infra-engineer` as the owner of the post-integration deploy (dev on merge to `main`, production behind the protected-environment reviewer on the release tag via the `deploy-ops` workflow templates) and never invokes `deploy.sh`, `release.sh`, `flyctl`, `aws`, or `supabase` directly.
529
+ 11. Before final handoff, **MUST** ensure the local working branch is the integration branch used for this run:
530
+
531
+ - Preferred: run `git checkout integration/<plan-id>-<short-description>`.
532
+ - Alternative (if checkout is not possible in the current runtime): explicitly verify and report current branch, and provide the exact checkout command the user can run.
533
+
534
+ 12. Final user response **MUST** include a `PR Directives (User Action Required)` section with:
500
535
 
501
536
  - consolidated PR URL
502
537
  - current CI/check status
@@ -510,6 +545,8 @@ Consolidated PR should include:
510
545
  - Per-story changed files and test results
511
546
  - Manual validation instructions per story
512
547
  - Integration test summary
548
+ - Roadmap row(s) updated in `docs/roadmap.md` (before → after status)
549
+ - Memo coverage: per-story `memo_intent` / `memo_outcome` values and `memo_run_outcome`
513
550
 
514
551
  PR title **MUST** follow Conventional Commits and PR body **MUST** follow `github-ops` conventions.
515
552
 
@@ -517,6 +554,17 @@ Planner **MUST NOT** merge the consolidated PR. Only the user may approve and me
517
554
 
518
555
  ---
519
556
 
557
+ ## Roadmap Maintenance
558
+
559
+ `docs/roadmap.md` is the one-page overview of every PRD's phases or waves: what is done, what is in progress, and what is missing. It is an index over the PRDs, GitHub issues, and merged PRs — when they disagree, they win and the roadmap is corrected.
560
+
561
+ - **Read** it in Phase 0 (see **Roadmap Read**).
562
+ - **Update** the run's row(s) in Phase 5 step 5, in the consolidated PR. Never leave the roadmap claiming `In progress` for a phase this run finished, or `Done` for one it did not.
563
+ - Change only the rows this run touched; rows for other PRDs belong to `product-engineer` and to the planner runs that deliver them.
564
+ - The `verifier` rollup audit (Phase 5 step 3) compares the roadmap against merged work and reports a mismatch as an advisory finding.
565
+
566
+ ---
567
+
520
568
  ## Error Handling
521
569
 
522
570
  | Situation | Action |
@@ -101,17 +101,38 @@ If any required input is missing, you **MUST** ask concise clarifying questions.
101
101
 
102
102
  ---
103
103
 
104
- ## memo-cli Integration (When Available)
104
+ ## Roadmap Maintenance
105
105
 
106
- ### Bank Declaration
106
+ `docs/roadmap.md` is the one-page overview of every PRD's phases or waves: what is done, what is in progress, and what is missing. `product-engineer` owns its rows and structure; `planner` updates the status of the rows a run delivers. It is an index over the PRDs, GitHub issues, and merged PRs — when they disagree, they win and the roadmap is corrected.
107
107
 
108
- This agent's bank id is `product-engineer-memory`, stable for the agent's life (PRD §15). Export it before any memo command in the session:
108
+ - **Read it at session start**, in every mode, before any activity, so a new PRD or issue is placed against what already exists and what is still missing.
109
+ - **Create it** in Init Mode, or the first time a PRD is written in a repository that has none, from the template shape below.
110
+ - **Add rows when a PRD is created or changed** (`activity-refine`): one row per delivery phase or wave the PRD defines, or a single `All` row when it defines none, each `Not started`. A PRD changelog that adds, removes, or re-scopes a phase updates its rows in the same change.
111
+ - **Fill `Issues/PRs` when stories are published** (`activity-publish-github`), and set the row to `In progress` once its first story is being implemented.
112
+ - **Correct it during drift reconciliation** (`activity-drift-reconciliation`) when a `verifier` roadmap-mismatch finding is confirmed.
113
+ - Never mark a row `Done` yourself on the strength of a plan; `Done` requires merged work, and `planner` sets it in the consolidated PR that delivers it.
109
114
 
110
- ```bash
111
- export MEMO_BANK=product-engineer-memory
115
+ Shape (one table, one row per PRD phase or wave, newest PRD first):
116
+
117
+ ```markdown
118
+ # Roadmap
119
+
120
+ Last updated: YYYY-MM-DD
121
+
122
+ | PRD | Phase/Wave | Scope (one line) | Status | Issues/PRs | What's missing |
123
+ | ---------------------------------------- | ---------- | ---------------- | ----------- | ----------- | ---------------- |
124
+ | [prd-<name>](requirements/prd-<name>.md) | 1 | <scope> | Not started | #12, PR #20 | <remaining or —> |
112
125
  ```
113
126
 
114
- `product-engineer` does not write episodic or semantic entries itself (see below), so this declaration exists for AC parity with the other long-lived agent definitions and for any future read-side use of `--bank $MEMO_BANK`.
127
+ `Status` is exactly one of `Not started`, `In progress`, `Done`.
128
+
129
+ ---
130
+
131
+ ## memo-cli Integration (When Available)
132
+
133
+ ### Bank Declaration
134
+
135
+ This agent's bank id is `product-engineer-memory`, stable for the agent's life (PRD §15). The decisions this agent records go to the shared `kb` (see **Decision Write-Back** below), not its private bank. Name the bank **literally** in every memo command (`--bank kb`); never rely on an `export MEMO_BANK=…` from an earlier command and never write `--bank $MEMO_BANK` — each shell command runs in a fresh shell, the variable is empty, and memo-cli rejects the resulting bank id (issue #253).
115
136
 
116
137
  ### Availability Check
117
138
 
@@ -121,7 +142,8 @@ At the start of every session, verify memo-cli is configured:
121
142
  which memo && memo setup validate
122
143
  ```
123
144
 
124
- - If `memo` is not found, skip all memo operations silently.
145
+ - If `memo` is not found and `memo.config.json` does not exist, skip all memo operations.
146
+ - If `memo` is not found but `memo.config.json` exists, warn the user that the repository expects memo-cli but the binary is not on PATH in this session, so no decisions will be recorded in memo. Never skip silently in this case.
125
147
  - If `memo` is found but validation fails, ask: "memo-cli is installed but not configured for this repository. Run `memo setup init --repo <repo> --org <org> --domain <domain>` to configure it."
126
148
 
127
149
  ### Session Start — Restore Context
@@ -165,7 +187,31 @@ Before making design choices in `activity-refine`, `activity-generate-spec`, or
165
187
  memo search "<specific topic, technology, or module>" --json
166
188
  ```
167
189
 
168
- **product-engineer does NOT write to memo.** All writes are delegated to `technical-writer` (ADRs and doc changes) and `developer` (intent/outcome entries).
190
+ ### Decision Write-Back — After Each Grilling Exit Gate
191
+
192
+ The decisions made with the user during refinement and specification are the most durable knowledge the workflow produces; they **MUST** reach memo, not only `workstream/decisions-<feature>.md`.
193
+
194
+ When `activity-grill`'s exit gate is satisfied (the WHAT phase in `activity-refine`, the HOW phase in `activity-generate-spec`, or Issue Mode refinement), write **one `kb` entry per user-answered decision row** recorded in that phase. Skip self-resolved rows (`Accepted rec.` is `n/a`): they restate knowledge that already exists. Do not batch several decisions into one entry.
195
+
196
+ ```bash
197
+ memo write \
198
+ --kind semantic \
199
+ --bank kb \
200
+ --manual \
201
+ --rationale "<feature>#D-NN (<WHAT|HOW>): <question in one sentence>. Decided: <answer>. Why: <reason given or the accepted recommendation's reasoning>. Rejected: <alternatives considered|none>." \
202
+ --tags "<domain>,<feature>,decision,<phase-lowercase>,<feature>-d-NN" \
203
+ --entry-type decision \
204
+ --story "<issue-or-feature-id-if-known>" \
205
+ --files "workstream/decisions-<feature>.md" \
206
+ --on-duplicate consolidate \
207
+ --json
208
+ ```
209
+
210
+ - `--manual` is correct here: the decision was made by the user in conversation, so it has no episodic provenance, and memo-cli rejects an agent-sourced semantic entry without one.
211
+ - A row that supersedes an earlier decision is written as a new entry naming the superseded ID in its rationale; `--on-duplicate consolidate` merges near-duplicates.
212
+ - **Write results are recorded, never swallowed.** Report the written ids (or `skipped(<reason>)`) in the phase's completion summary. On failure, fix the command if the error names a flag or value you supplied and retry once; then report `failed(<error>)`. A failed write never blocks the phase.
213
+
214
+ `technical-writer` still owns ADR and doc-change entries, and `developer` owns per-story intent/outcome entries.
169
215
 
170
216
  ### Session Close
171
217
 
@@ -346,13 +346,9 @@ Ensure:
346
346
 
347
347
  ### Bank Declaration
348
348
 
349
- This agent's bank id is `technical-writer-memory`, stable for the agent's life (PRD §15). Export it before any memo command in the session:
349
+ This agent's bank id is `technical-writer-memory`, stable for the agent's life (PRD §15). Name banks **literally** in every memo command (`--bank kb`, `--bank technical-writer-memory`); never rely on an `export MEMO_BANK=…` from an earlier command and never write `--bank $MEMO_BANK` — each shell command runs in a fresh shell, the variable is empty, and memo-cli rejects the resulting bank id (issue #253).
350
350
 
351
- ```bash
352
- export MEMO_BANK=technical-writer-memory
353
- ```
354
-
355
- ADR and decision entries this agent writes stay `--kind semantic` in `kb` (never in `$MEMO_BANK`) — see **Write Template** below.
351
+ ADR and decision entries this agent writes stay `--kind semantic` in `kb` (never in its private bank) — see **Write Template** below.
356
352
 
357
353
  ### Availability Check
358
354
 
@@ -362,7 +358,8 @@ At the start of every run, check if memo-cli is configured:
362
358
  which memo && memo setup validate
363
359
  ```
364
360
 
365
- - If `memo` is not found, skip all memo operations silently.
361
+ - If `memo` is not found and `memo.config.json` does not exist, skip all memo operations.
362
+ - If `memo` is not found but `memo.config.json` exists, warn the user that the repository expects memo-cli but the binary is not on PATH in this session, and report `memo: skipped(memo-unavailable)` in the run summary. Never skip silently in this case.
366
363
  - If `memo` is found but validation fails (missing `memo.config.json` or env vars), **STOP** and ask: "memo-cli is installed but not configured for this repository. Run `memo setup init --repo <repo> --org <org> --domain <domain>` to configure it, then re-run."
367
364
 
368
365
  ### Read Before Write
@@ -403,7 +400,7 @@ memo write \
403
400
  --tags "<domain-tag>,<entry-nature-tag>,<story-ref-if-known>" \
404
401
  --entry-type <decision|structure|integration_point> \
405
402
  --source agent \
406
- --provenance "<csv of episodic entry ids this decision consolidates, if any>" \
403
+ --provenance "<csv of episodic entry ids this decision consolidates>" \
407
404
  --commit "$(git rev-parse HEAD)" \
408
405
  --story "<issue-or-story-id-if-known>" \
409
406
  --files "<path/to/doc.md>,<path/to/adr.md>" \
@@ -411,7 +408,12 @@ memo write \
411
408
  --json
412
409
  ```
413
410
 
414
- ADR and durable-decision entries are always `--kind semantic` in `kb`, never in `$MEMO_BANK` — this agent is the one long-lived agent that writes to the shared `kb`, not a private bank. Per PRD K3, a `semantic` entry with `--source agent` **MUST** carry `--provenance <csv>` (the episodic entry ids — typically `developer`'s intent/outcome entries — that informed the decision) unless `--manual` is passed instead (human-authored, no episodic origin).
411
+ ADR and durable-decision entries are always `--kind semantic` in `kb`, never in a private bank. Per PRD K3, memo-cli **rejects** a `semantic` entry with `--source agent` and no provenance (`VALIDATION_FAILED`), so choose exactly one form:
412
+
413
+ - **Provenance known:** find the episodic ids that informed the decision — typically `developer`'s intent/outcome entries for the story — with `memo list --bank developer-memory --session ISSUE-<n> --json`, and pass them as `--source agent --provenance "<id1>,<id2>"`.
414
+ - **No episodic ids found:** drop both `--source agent` and `--provenance`, and pass `--manual` instead. Never pass an empty `--provenance ""`.
415
+
416
+ **Write results are recorded, never swallowed.** On success, the JSON response carries the entry `id`; list every written id in the run summary. On failure, fix the command if the error names a flag or value you supplied and retry once; if it still fails, report `memo: failed(<error>)` in the run summary. A failed write does not block the documentation run, but it **MUST NOT** be dropped silently.
415
417
 
416
418
  **Rationale quality rule:** Answer three questions in one coherent paragraph: (1) what changed and why it was needed, (2) what was decided or documented, (3) what it affects downstream. Never use bullet points inside `--rationale`.
417
419
 
@@ -249,6 +249,21 @@ new category. Never hold a PR on it.
249
249
  | Test-harness setup | `qa-engineer` |
250
250
  | Tooling setup | `housekeeping` |
251
251
 
252
+ ## Roadmap-Mismatch Finding
253
+
254
+ `docs/roadmap.md` is the one-page index of every PRD's phases or waves and their status. It goes stale silently unless something compares it with what actually merged, so that comparison lives here as a finding.
255
+
256
+ **Trigger** (PRD-level rollup audits, and story audits whose story completes a phase or wave). Report the finding when any of these hold:
257
+
258
+ 1. The audited work completes a PRD phase or wave, and its roadmap row is not `Done` in the delivered tree.
259
+ 2. A roadmap row is `Done`, but the audited scope shows that phase's stories unmerged or its acceptance criteria unmet.
260
+ 3. The audited PRD defines a phase or wave with no roadmap row, or `docs/roadmap.md` is missing while `docs/requirements/` holds a PRD.
261
+ 4. A row's `Issues/PRs` or `What's missing` contradicts the audited issues and PRs.
262
+
263
+ **Not a finding:** rows for PRDs outside the audited scope; a row left `In progress` while some of its stories are still open.
264
+
265
+ **The finding is advisory.** Like every other drift item it is **non-blocking to PR readiness and to issue completion**, and it routes to `product-engineer`'s `activity-drift-reconciliation` flow, which corrects the row. Classify it with the existing impact/intent vocabulary. Never hold a PR on it.
266
+
252
267
  ## Failure Triage Workflow (Randomized Tests)
253
268
 
254
269
  When a randomized or fuzz test fails, follow this sequence: