@llipe.com/dev-tasks 0.16.1 → 0.16.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (43) hide show
  1. package/.claude/agents/developer.md +45 -31
  2. package/.claude/agents/github-ops.md +2 -2
  3. package/.claude/agents/technical-writer.md +11 -9
  4. package/.claude/agents/verifier.md +15 -0
  5. package/.claude/commands/planner.md +61 -13
  6. package/.claude/commands/product-engineer.md +54 -8
  7. package/.claude/hooks/git-guard.sh +152 -64
  8. package/.claude/skills/git-ops/SKILL.md +6 -6
  9. package/.claude/skills/implement/SKILL.md +12 -8
  10. package/.claude/skills/memo-cli-usage/REFERENCE.md +11 -11
  11. package/.claude/skills/memo-cli-usage/SKILL.md +11 -9
  12. package/.github/agents/developer.agent.md +45 -31
  13. package/.github/agents/github-ops.agent.md +2 -2
  14. package/.github/agents/planner.agent.md +61 -13
  15. package/.github/agents/product-engineer.agent.md +54 -8
  16. package/.github/agents/technical-writer.agent.md +11 -9
  17. package/.github/agents/verifier.agent.md +15 -0
  18. package/.github/instructions/implement.instructions.md +12 -8
  19. package/.github/skills/git-ops/SKILL.md +6 -6
  20. package/.github/skills/memo-cli-usage/REFERENCE.md +11 -11
  21. package/.github/skills/memo-cli-usage/SKILL.md +11 -9
  22. package/.kiro/agents/developer.md +45 -31
  23. package/.kiro/agents/github-ops.md +2 -2
  24. package/.kiro/agents/planner.md +61 -13
  25. package/.kiro/agents/product-engineer.md +54 -8
  26. package/.kiro/agents/technical-writer.md +11 -9
  27. package/.kiro/agents/verifier.md +15 -0
  28. package/.kiro/hooks/scripts/git-guard.sh +96 -10
  29. package/.kiro/skills/git-ops/SKILL.md +6 -6
  30. package/.kiro/skills/memo-cli-usage/REFERENCE.md +11 -11
  31. package/.kiro/skills/memo-cli-usage/SKILL.md +11 -9
  32. package/.kiro/steering/implement.md +12 -8
  33. package/AGENTS.md +7 -5
  34. package/AGENTS.md.template +3 -1
  35. package/CHANGELOG.md +49 -0
  36. package/CLAUDE.md +2 -1
  37. package/CLAUDE.md.template +2 -1
  38. package/TESTING.md +47 -29
  39. package/dist/core/checks/decision-log-format.d.ts +24 -3
  40. package/dist/core/checks/decision-log-format.d.ts.map +1 -1
  41. package/dist/core/checks/decision-log-format.js +43 -3
  42. package/dist/core/checks/decision-log-format.js.map +1 -1
  43. package/package.json +8 -6
@@ -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:
@@ -54,13 +54,97 @@ block() {
54
54
  exit 2
55
55
  }
56
56
 
57
+ # Split the raw command into simple-command segments, one per output line,
58
+ # at `&&`, `||`, `;`, `|`, `&`, and newlines outside single or double quotes
59
+ # (backslash escapes honored). Every rule that reads a command's arguments
60
+ # reads them from its own segment, never from the rest of the string. Before
61
+ # this, `git push -u origin feat && gh pr create --base main` read `main` as
62
+ # a push destination, `--tags` anywhere in the string read as a tag push, and
63
+ # a greedy `.*git push` match checked only the LAST push in a chained
64
+ # command, so `git push origin main && git push origin feat` was allowed
65
+ # (issue #256). Portable awk only: macOS ships BSD awk, not gawk.
66
+ command_segments() {
67
+ printf '%s\n' "$cmd" | awk '
68
+ { s = s (NR > 1 ? "\n" : "") $0 }
69
+ END {
70
+ out = ""; q = ""; n = length(s)
71
+ for (i = 1; i <= n; i++) {
72
+ c = substr(s, i, 1)
73
+ if (q != "") {
74
+ # Inside quotes a newline is part of the argument, never a
75
+ # separator: map it to a space so the segment stays whole.
76
+ if (c == "\n") { out = out " "; continue }
77
+ if (c == q) { q = ""; out = out c; continue }
78
+ if (c == "\\" && q == "\"" && i < n) {
79
+ d = substr(s, i + 1, 1); i++
80
+ if (d != "\n") out = out c d # backslash-newline is a continuation
81
+ continue
82
+ }
83
+ out = out c
84
+ continue
85
+ }
86
+ if (c == "\\" && i < n) {
87
+ d = substr(s, i + 1, 1); i++
88
+ if (d != "\n") out = out c d # backslash-newline is a continuation
89
+ continue
90
+ }
91
+ if (c == "\"" || c == "\047") { q = c; out = out c; continue }
92
+ if (c == ";" || c == "|" || c == "&" || c == "\n") { out = out "\n"; continue }
93
+ out = out c
94
+ }
95
+ print out
96
+ }'
97
+ }
98
+
99
+ # Segments matching the extended regex $1, whitespace-normalized, one per line.
100
+ segments_matching() {
101
+ command_segments | tr -s ' \t' ' ' | grep -E -- "$1"
102
+ }
103
+
104
+ # Argument tokens following EACH `git push` in segment $1, one per line.
105
+ # Quotes, backticks, parentheses, and separators are stripped from tokens so
106
+ # `$(git push origin main)` and `bash -c "git push origin main"` still yield
107
+ # `main`. Every occurrence in the segment is read, not just the last one.
108
+ push_tokens() {
109
+ printf '%s\n' "$1" | awk '{ n = split($0, parts, /git[ \t]+push/); for (i = 2; i <= n; i++) print parts[i] }' \
110
+ | tr -s ' \t' '\n\n' | tr -d "\"'\`();|&" | sed 's/[<>].*//' | grep -v '^$'
111
+ }
112
+
113
+ # A command word counts when it appears at a segment's start, after
114
+ # whitespace, after an opening quote, backtick, or parenthesis, or after a
115
+ # path (`/usr/bin/git`).
116
+ _cmd_prefix="(^|[[:space:](\`\"'/])"
117
+ _push_segment_re="${_cmd_prefix}git +push([[:space:]]|$)"
118
+
119
+ # Does any `git push` destination in the command equal branch $1? Reads each
120
+ # push segment's own tokens only; checks bare tokens and the right-hand side
121
+ # of `src:dst` refspecs, stripping a leading `+` and a `refs/heads/` prefix.
122
+ push_targets_ref() {
123
+ local target="$1" seg tok dst
124
+ while IFS= read -r seg; do
125
+ while IFS= read -r tok; do
126
+ case "$tok" in
127
+ -*) continue ;;
128
+ esac
129
+ tok="${tok#+}"
130
+ dst="${tok##*:}"
131
+ tok="${tok#refs/heads/}"
132
+ dst="${dst#refs/heads/}"
133
+ if [ "$tok" = "$target" ] || [ "$dst" = "$target" ]; then
134
+ return 0
135
+ fi
136
+ done < <(push_tokens "$seg")
137
+ done < <(segments_matching "$_push_segment_re")
138
+ return 1
139
+ }
140
+
57
141
  # --- Rule 1: never merge/push into main ---------------------------------------
58
- # Block `git push ... main` (pushing to the main branch) and any merge/PR-merge
59
- # that targets main. Branch-creation and normal feature pushes are unaffected.
60
- case "$norm" in
61
- *"git push"*" main"*|*"git push"*":main"*|*"git push"*" origin main"*|*"git push"*" HEAD:main"*)
62
- block "pushing to 'main' is not allowed. Open a PR; only the user may merge into main." ;;
63
- esac
142
+ # Block a push whose destination is main, and any merge/PR-merge that targets
143
+ # main. Branch-creation and normal feature pushes are unaffected, including a
144
+ # feature push chained with `gh pr create --base main` (issue #256).
145
+ if push_targets_ref main; then
146
+ block "pushing to 'main' is not allowed. Open a PR; only the user may merge into main."
147
+ fi
64
148
 
65
149
  # `git merge` while the checked-out branch is main (i.e. merging INTO main).
66
150
  if printf '%s' "$norm" | grep -Eq '(^|[;&|[:space:]])git +merge([[:space:]]|$)'; then
@@ -71,17 +155,19 @@ if printf '%s' "$norm" | grep -Eq '(^|[;&|[:space:]])git +merge([[:space:]]|$)';
71
155
  fi
72
156
 
73
157
  # `gh pr merge` targeting main (either via --base main or merging a PR onto main).
74
- if printf '%s' "$norm" | grep -Eq 'gh +pr +merge'; then
75
- if printf '%s' "$norm" | grep -Eq -- '--base[ =]main|-B[ =]main'; then
158
+ # Checked per segment, so a later `gh pr create --base main` in the same
159
+ # command is not read as this merge's base (issue #256).
160
+ while IFS= read -r _seg; do
161
+ if printf '%s' "$_seg" | grep -Eq -- "(--base|-B)[ =][\"']?main([^[:alnum:]_./-]|$)"; then
76
162
  block "merging a PR into 'main' is not allowed. Only the user may merge into main."
77
163
  fi
78
164
  # No explicit base given: gh defaults to the PR's base. Warn-block to be safe
79
165
  # for the common case where PRs target main. Story PRs targeting integration
80
166
  # branches should pass --base <integration-branch> explicitly.
81
- if ! printf '%s' "$norm" | grep -Eq -- '--base[ =]|-B[ =]'; then
167
+ if ! printf '%s' "$_seg" | grep -Eq -- '--base[ =]|-B[ =]'; then
82
168
  block "refusing 'gh pr merge' without an explicit --base. PRs to main require user approval; for integration branches pass --base <integration-branch>."
83
169
  fi
84
- fi
170
+ done < <(segments_matching 'gh +pr +merge')
85
171
 
86
172
  # --- Rule 2: Conventional Commits for git commit ------------------------------
87
173
  # Inspect inline -m / --message messages. Commits via editor or -F file are not
@@ -96,13 +96,13 @@ Before merging any PR or branch, verify:
96
96
 
97
97
  Choose the appropriate strategy based on context:
98
98
 
99
- | Strategy | When to Use | Command |
100
- | ---------------- | ----------------------------------------------------------------------------------- | ------------------------------------------- |
101
- | **Squash merge** | Issue/story PRs → integration (planner) or `main` (user); delete the source branch. | `gh pr merge <pr> --squash --delete-branch` |
102
- | **Merge commit** | Integration PRs → `main` (user); preserve the story history. | `gh pr merge <pr> --merge` |
103
- | **Rebase merge** | Not part of the issue/story/integration policy; use only when explicitly approved. | `gh pr merge <pr> --rebase` |
99
+ | Strategy | When to Use | Command |
100
+ | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------- |
101
+ | **Merge commit** | **Default for every PR.** Issue/story PRs → integration (planner) or `main` (user), and integration PRs → `main` (user). Preserves every commit. | `gh pr merge <pr> --merge --delete-branch` |
102
+ | **Squash merge** | Not part of the policy; use only when the user explicitly asks for a single-commit history on a specific PR. | `gh pr merge <pr> --squash --delete-branch` |
103
+ | **Rebase merge** | Not part of the policy; use only when the user explicitly approves it on a specific PR. | `gh pr merge <pr> --rebase` |
104
104
 
105
- **Default**: Issue/story PRs use squash with branch deletion; integration PRs use a merge commit. Planner handles integration targets, and the user handles `main`.
105
+ **Default**: Every PR merges by merge commit, so the per-task Conventional Commits survive to `main`. Issue/story PRs also delete the source branch. Planner handles integration targets, and the user handles `main`. Never squash or rebase unless the user asks for it on a specific PR.
106
106
 
107
107
  ### 6. Resolve Merge Conflicts
108
108
 
@@ -257,10 +257,10 @@ memo-cli 1.3.0 adds a second axis of scoping — **banks** — and a third field
257
257
 
258
258
  A bank is a namespace for entries, resolved in this priority order (B3): `--bank <id>` flag > `$MEMO_BANK` env var > `config.bank.default` > `kb`. `kb` is the shared, org-wide knowledge base every repo reads from by default; any other bank id (kebab-case or UUID) is a **private** bank — conventionally named `<agent-name>-memory` (e.g. `developer-memory`, `technical-writer-memory`, `product-engineer-memory`, `planner-memory`) for a long-lived agent's own session memory.
259
259
 
260
- Export the bank once per session so every subsequent command inherits it:
260
+ **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.
261
261
 
262
262
  ```bash
263
- export MEMO_BANK=developer-memory
263
+ memo write --bank developer-memory ... # bank id convention: <agent-name>-memory
264
264
  ```
265
265
 
266
266
  `kb` and private banks are isolated from each other: a `search`/`list`/`recall` scoped to a private bank never returns `kb` entries and vice versa, unless you explicitly pass `--bank kb`.
@@ -275,7 +275,7 @@ export MEMO_BANK=developer-memory
275
275
 
276
276
  `--kind` is case-insensitive (`--kind Self`, `--kind SELF`, `--kind self` all normalize to `self`). Default kind is `episodic` in a private bank, `semantic` in `kb`.
277
277
 
278
- **Rule of thumb for agent definitions in this repository:** intent/outcome entries are `--kind episodic --session ISSUE-<n> --bank $MEMO_BANK`; ADR/decision entries stay `--kind semantic --bank kb`.
278
+ **Rule of thumb for agent definitions in this repository:** intent/outcome entries are `--kind episodic --session ISSUE-<n> --bank <agent>-memory`; ADR/decision entries stay `--kind semantic --bank kb`.
279
279
 
280
280
  ---
281
281
 
@@ -298,7 +298,7 @@ Episodic example — intent entry in a private bank:
298
298
  memo write \
299
299
  --kind episodic \
300
300
  --session ISSUE-42 \
301
- --bank $MEMO_BANK \
301
+ --bank <agent>-memory \
302
302
  --rationale "Context: Starting ISSUE-42. Decision: implement via a middleware. Impact: affects the auth pipeline." \
303
303
  --tags "auth,issue-42,intent,middleware" \
304
304
  --entry-type decision \
@@ -391,7 +391,7 @@ Most-recent-first listing with optional date range.
391
391
  ### `memo timeline` — Replay Episodic Memory
392
392
 
393
393
  ```bash
394
- memo timeline --bank $MEMO_BANK --session ISSUE-42 --json
394
+ memo timeline --bank <agent>-memory --session ISSUE-42 --json
395
395
  ```
396
396
 
397
397
  Replays episodic memory **in sequence order** — never ranked. Two shapes:
@@ -479,7 +479,7 @@ Migrates legacy v1 stored payloads to schema v2, idempotently (a point that alre
479
479
  ### `memo recall` — One-Call Context Restore
480
480
 
481
481
  ```bash
482
- memo recall "<task description>" --bank $MEMO_BANK --json
482
+ memo recall "<task description>" --bank <agent>-memory --json
483
483
  ```
484
484
 
485
485
  The 1.3.0 replacement for the four-command session-start sequence (`list` + `tags list` + `search` + `search --scope related`). Gathers, in one call (≤ 4 s target):
@@ -504,7 +504,7 @@ When the budget is tight, sections are trimmed in this order: `conflicts` → `l
504
504
 
505
505
  **On failure:** `memo recall` exits `2` on an embeddings failure (`EMBEDDING_API_ERROR`) or a mid-gather Qdrant failure (`QDRANT_OPERATION_FAILED`) — there is no partial-bundle fallback. Treat this the same as any other exit-`2` failure: surface the warning, and continue the session without recalled context rather than blocking on it.
506
506
 
507
- **When `$MEMO_BANK` is unset** (resolves to `kb`): `SELF`, `MINE`, and `LAST SESSION` are omitted from the response entirely (omitted keys, not empty arrays) — you still get `POLICIES`, `SHARED`, `CONFLICTS`.
507
+ **When no private bank is passed** (resolves to `kb`): `SELF`, `MINE`, and `LAST SESSION` are omitted from the response entirely (omitted keys, not empty arrays) — you still get `POLICIES`, `SHARED`, `CONFLICTS`.
508
508
 
509
509
  **Fallback when `memo recall` is unavailable** (`memo --version` below `1.3.0`, or the command errors as unrecognized): fall back to the four-command sequence documented under **Session Start — Restore Context** in `SKILL.md`.
510
510
 
@@ -571,7 +571,7 @@ Exactly one of `--id`, `--all-by-repo`, or `--all-by-org` is required.
571
571
  memo setup validate
572
572
 
573
573
  # 2. Restore SELF, POLICIES, SHARED, MINE, LAST SESSION, CONFLICTS in one bundle
574
- memo recall "<current task or feature description>" --bank $MEMO_BANK --json
574
+ memo recall "<current task or feature description>" --bank <agent>-memory --json
575
575
  ```
576
576
 
577
577
  **Fallback (`memo --version` below `1.3.0`):** run this sequence instead, before writing a single line of code:
@@ -968,12 +968,12 @@ memo setup init --repo <r> --org <o> --domain <d> # Initialize conf
968
968
  memo setup validate # Verify config
969
969
  memo setup show [--json] # Display config
970
970
 
971
- memo recall "<task>" --bank $MEMO_BANK [--json] # Restore full context (1.3.0+)
971
+ memo recall "<task>" --bank <agent>-memory [--json] # Restore full context (1.3.0+)
972
972
  memo write --rationale "..." --tags "a,b,c" [--json] # Record a semantic decision (kb)
973
- memo write --kind episodic --session ID --bank $MEMO_BANK [--json] # Record an intent/outcome entry
973
+ memo write --kind episodic --session ID --bank <agent>-memory [--json] # Record an intent/outcome entry
974
974
  memo search "query" [--scope related] [--bank ID] [--kind K] [--json] # Semantic search
975
975
  memo list [--from DATE] [--to DATE] [--bank ID] [--kind K] [--json] # Browse entries
976
- memo timeline [--session ID] --bank $MEMO_BANK [--last N] [--json] # Replay episodic memory in order
976
+ memo timeline [--session ID] --bank <agent>-memory [--last N] [--json] # Replay episodic memory in order
977
977
  memo tags list [--sort frequency] [--json] # Discover tags
978
978
  memo inspect [--json] # Global facets
979
979
  memo bank list [--json] # List all banks
@@ -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
@@ -82,6 +82,7 @@ fix(web): stop double-submitting the checkout form
82
82
  - PR title **MUST** follow Conventional Commits (e.g., `feat: implement issue 37`).
83
83
  - PR description **MUST** include `Closes #<issue-number>`.
84
84
  5. You **MUST** ensure the task list in the GitHub Issue matches the local `/workstream/tasks-*.md` file.
85
+ 6. **memo intent (when memo-cli is available):** Before the first implementation sub-task, you **MUST** run the memo-cli Availability Check and write the episodic intent entry defined in the `developer` agent contract (**memo-cli Integration → Intent Entry**), naming the bank literally (`--bank developer-memory`, never `--bank $MEMO_BANK`). Record `memo_intent` as `written(<id>)`, `failed(<reason>)`, or `skipped(<reason>)` — a failed write is retried once and then reported, never dropped silently.
85
86
 
86
87
  If `github-ops` delegation is unavailable in the current runtime, you **MUST** apply `github-ops` conventions directly and explicitly note that fallback in your status output.
87
88
 
@@ -148,14 +149,17 @@ When `workstream/decisions-<feature>.md` exists and was read per step 2 above:
148
149
  5. `technical-writer` validation **MUST** include a drift/stale-doc check report, and completion **MUST NOT** proceed while unresolved drift remains.
149
150
  6. A `qa-engineer` pass **MUST** have run and `coverage_gate` **MUST** be recorded as `PASS`, `FAIL`, or `SKIPPED(<reason>)`. The reason **MUST** be non-empty when skipped; an omitted field is treated as incomplete. A `FAIL` or `SKIPPED` value does not block completion — only omission does.
150
151
  7. A `verifier` audit in `audit` mode **MUST** have run against the delivered implementation, with its human-readable summary posted to the issue/PR. This gate is mandatory and non-skippable — it **MUST NOT** be skipped regardless of drift findings, and drift findings reported by this audit **MUST NOT** block completion. This condition is satisfied once the audit has run and been posted; any resulting drift is handled by `product-engineer`'s `activity-drift-reconciliation` flow after this gate, not before it.
151
- 8. The PR **MUST** be converted from draft to ready for review.
152
- 9. The PR **MUST** be approved by the appropriate reviewer per the merge authority policy in `github-ops`:
153
- - PRs targeting an **integration branch**: `planner` reviews and approves.
154
- - PRs targeting **`main`**: the **user** reviews and approves.
155
- 10. The PR **MUST** be merged by the authorized party (planner for integration branches, user for `main`).
156
- 11. You **MUST NOT** close the GitHub Issue until the PR is approved **AND** merged.
157
- 12. You **MUST NOT** close the issue while the PR is still in draft or pending review.
158
- 13. You **MUST** notify the user when the PR is ready for review — explicitly inform them so they can review and merge.
152
+ 8. **memo outcome (when memo-cli is available):** Before the PR is converted to ready for review, you **MUST** write the episodic outcome entry defined in the `developer` agent contract (**memo-cli Integration → Outcome Entry**) and record `memo_outcome` as `written(<id>)`, `failed(<reason>)`, or `skipped(<reason>)`. A `failed` or `skipped` value does not block completion — only an omitted field does.
153
+ 9. The PR **MUST** be converted from draft to ready for review.
154
+ 10. The PR **MUST** be approved by the appropriate reviewer per the merge authority policy in `github-ops`:
155
+
156
+ - PRs targeting an **integration branch**: `planner` reviews and approves.
157
+ - PRs targeting **`main`**: the **user** reviews and approves.
158
+
159
+ 11. The PR **MUST** be merged by the authorized party (planner for integration branches, user for `main`).
160
+ 12. You **MUST NOT** close the GitHub Issue until the PR is approved **AND** merged.
161
+ 13. You **MUST NOT** close the issue while the PR is still in draft or pending review.
162
+ 14. You **MUST** notify the user when the PR is ready for review — explicitly inform them so they can review and merge.
159
163
 
160
164
  ---
161
165
 
package/AGENTS.md CHANGED
@@ -4,10 +4,11 @@ Portable, repo-installed workflow harness for structured, PRD-driven AI-assisted
4
4
 
5
5
  ## Contracts
6
6
 
7
- | File | Owner | Purpose |
8
- | ------------- | ------------- | ---------------------------------------------- |
9
- | `/DESIGN.md` | `ux-engineer` | Canonical design-system tokens and UI guidance |
10
- | `/TESTING.md` | `qa-engineer` | Layer taxonomy, runners, thresholds, fixtures |
7
+ | File | Owner | Purpose |
8
+ | ----------------- | ------------------ | ---------------------------------------------- |
9
+ | `/DESIGN.md` | `ux-engineer` | Canonical design-system tokens and UI guidance |
10
+ | `/TESTING.md` | `qa-engineer` | Layer taxonomy, runners, thresholds, fixtures |
11
+ | `docs/roadmap.md` | `product-engineer` | PRD phases/waves: done, in progress, missing |
11
12
 
12
13
  If `/DESIGN.md` is missing and scope includes UI work, agents **MUST** create a baseline before finalizing design-dependent outputs. An unfilled `/TESTING.md` placeholder means "no standard established", never permission.
13
14
 
@@ -113,7 +114,8 @@ All agents **MUST**:
113
114
  - Run `qa-engineer` at completion gate (record `coverage_gate: PASS | FAIL | SKIPPED(<reason>)`)
114
115
  - Run `verifier` audit (mandatory, non-skippable) before PR is ready; drift findings route to `product-engineer`
115
116
  - Follow test-first design: write tests before implementation code
116
- - If `memo-cli` is available: read/write entries per role
117
+ - If `memo-cli` is available: read/write entries per role, naming `--bank <id>` literally on every command (never `--bank $MEMO_BANK`), and report every write as `written(<id>)`, `failed(<reason>)`, or `skipped(<reason>)` — never drop a failure silently
118
+ - Keep `docs/roadmap.md` current: `product-engineer` reads it at session start and adds a row per PRD phase/wave; `planner` reads it in Phase 0 and updates the delivered rows in the consolidated PR; `verifier` reports a mismatch with merged work as an advisory finding
117
119
  - **Foundation documents: resolve the new name, fall back to the old one.** The canonical names are `docs/product.md` and `docs/tech.md`. A repository installed before the rename still carries `docs/product-context.md` and `docs/technical-guidelines.md`, and `dev-tasks update` never renames a consumer-owned file on its own. So when **reading** a foundation document, resolve the new name first and fall back to the old one only when the new name is absent; when **writing**, always write the new name. Propose `dev-tasks migrate docs` on encountering an old name. This applies to every agent and skill that reads these documents, for one release cycle (FR-45)
118
120
  - Deliver a runbook in the **same PR** as any new or materially changed script under `templates/scripts/`, workflow under `templates/workflows/` or `.github/workflows/`, or `infra-engineer` change kind (FR-49a). Updating an existing runbook satisfies this
119
121
  - Route a docs-structure failure in `validate` to `technical-writer`, never to `housekeeping` (FR-51): `technical-writer` owns documentation structure and content
@@ -8,6 +8,7 @@ Portable, repo-installed workflow harness for structured, PRD-driven AI-assisted
8
8
  | ------------- | ------------- | ---------------------------------------------- |
9
9
  | `/DESIGN.md` | `ux-engineer` | Canonical design-system tokens and UI guidance |
10
10
  | `/TESTING.md` | `qa-engineer` | Layer taxonomy, runners, thresholds, fixtures |
11
+ | `docs/roadmap.md` | `product-engineer` | PRD phases/waves: done, in progress, missing |
11
12
 
12
13
  If `/DESIGN.md` is missing and scope includes UI work, agents **MUST** create a baseline before finalizing design-dependent outputs. An unfilled `/TESTING.md` placeholder means "no standard established", never permission.
13
14
 
@@ -113,7 +114,8 @@ All agents **MUST**:
113
114
  - Run `qa-engineer` at completion gate (record `coverage_gate: PASS | FAIL | SKIPPED(<reason>)`)
114
115
  - Run `verifier` audit (mandatory, non-skippable) before PR is ready; drift findings route to `product-engineer`
115
116
  - Follow test-first design: write tests before implementation code
116
- - If `memo-cli` is available: read/write entries per role
117
+ - If `memo-cli` is available: read/write entries per role, naming `--bank <id>` literally on every command (never `--bank $MEMO_BANK`), and report every write as `written(<id>)`, `failed(<reason>)`, or `skipped(<reason>)` — never drop a failure silently
118
+ - Keep `docs/roadmap.md` current: `product-engineer` reads it at session start and adds a row per PRD phase/wave; `planner` reads it in Phase 0 and updates the delivered rows in the consolidated PR; `verifier` reports a mismatch with merged work as an advisory finding
117
119
  - **Foundation documents: resolve the new name, fall back to the old one.** The canonical names are `docs/product.md` and `docs/tech.md`. A repository installed before the rename still carries `docs/product-context.md` and `docs/technical-guidelines.md`, and `dev-tasks update` never renames a consumer-owned file on its own. So when **reading** a foundation document, resolve the new name first and fall back to the old one only when the new name is absent; when **writing**, always write the new name. Propose `dev-tasks migrate docs` on encountering an old name. This applies to every agent and skill that reads these documents, for one release cycle (FR-45)
118
120
  - Deliver a runbook in the **same PR** as any new or materially changed script under `templates/scripts/`, workflow under `templates/workflows/` or `.github/workflows/`, or `infra-engineer` change kind (FR-49a). Updating an existing runbook satisfies this
119
121
  - Route a docs-structure failure in `validate` to `technical-writer`, never to `housekeeping` (FR-51): `technical-writer` owns documentation structure and content
package/CHANGELOG.md CHANGED
@@ -5,6 +5,55 @@ All notable changes to this project will be documented in this file.
5
5
  The format is based on [Keep a Changelog](https://keepachangelog.com/),
6
6
  and this project adheres to [Semantic Versioning](https://semver.org/).
7
7
 
8
+ ## [0.16.4] - 2026-10-06
9
+
10
+ ### Changed
11
+
12
+ - chore: validation update pre release
13
+ - chore(lock): reformat pnpm-lock.yaml with prettier
14
+
15
+ ## [0.16.3] - 2026-10-06
16
+
17
+ ### Added
18
+
19
+ - feat: quality-gate hardening — PR validate CI, coverage baseline, format scope, decision-log row validation (#245, #246, #247, #248) (#265)
20
+
21
+ ### Changed
22
+
23
+ - chore: prettier update
24
+ - refactor(merge-policy): default issue/story PR merges to merge commit (#267)
25
+
26
+ ## [0.16.2] - 2026-10-02
27
+
28
+ ### Fixed
29
+
30
+ - fix(git-guard): read each command's arguments from its own segment (#257)
31
+ - fix(memo): make memo writes succeed and add docs/roadmap.md (#255)
32
+
33
+ ## [Unreleased]
34
+
35
+ ### Changed
36
+
37
+ - refactor(merge-policy): the default merge strategy for issue and story PRs is now a merge commit (`gh pr merge <n> --merge --delete-branch`) instead of squash, so the per-task Conventional Commits survive to `main`; squash and rebase merges require an explicit user request on a specific PR. Updated in `git-ops`, `github-ops`, and `planner` on all three platforms, and in the `git-guard` hook guidance (#266)
38
+
39
+ ### Added
40
+
41
+ - feat(roadmap): `docs/roadmap.md` overview of PRD phases and waves, owned by `product-engineer`, updated by `planner` in the consolidated PR, and checked by a `verifier` roadmap-mismatch finding (#254)
42
+ - feat(memo): `product-engineer` writes confirmed grilling decisions to `kb`; `planner` verifies per-story memo fields and writes one run-outcome entry (#253)
43
+ - feat(ci): `validate.yml` runs `pnpm run validate` on every pull request, with runbook `docs/runbooks/runbook-diagnose-pr-validate.md` (#248)
44
+ - feat(test): `@vitest/coverage-v8` and `pnpm run test:coverage`; coverage baseline recorded (not enforced) in `TESTING.md`; coverage stays out of `validate` (#247)
45
+
46
+ ### Fixed
47
+
48
+ - fix(git-guard): read each command's arguments from its own segment of a chained command, so a feature push followed by `gh pr create --base main` or a commit message mentioning tags no longer blocks, and every push, merge, and tag command in a chain is checked instead of only the last one (#256)
49
+ - fix(memo): name memo banks literally instead of `--bank $MEMO_BANK`, which is empty in a fresh shell and made every write fail; use `--manual` for `technical-writer` `kb` entries without provenance; record every write result in the closeout payload and gate merges on its presence (#253)
50
+ - fix(checks): decision-log rows whose cell count differs from the header now fail with `cell-count-mismatch` instead of being parsed with shifted columns (#245)
51
+ - fix(deps): `brace-expansion` pnpm overrides bounded to their own major (patched floors unchanged) (#247)
52
+
53
+ ### Changed
54
+
55
+ - chore(format): `format` and `format:check` cover `.claude/`, `.github/`, and `.kiro/` (#246)
56
+
8
57
  ## [0.16.1] - 2026-09-23
9
58
 
10
59
  ### Fixed
package/CLAUDE.md CHANGED
@@ -20,6 +20,7 @@ All work in this repository **MUST**:
20
20
  - Use canonical `package.json` script names for JS/TS projects: `lint`, `lint:fix`, `format`, `format:check`, `typecheck`, `test`, `test:unit`, `test:integration`, `test:e2e`, `audit`, `validate`.
21
21
  - Before developer/planner completion, enforce and record quality gates: `test`, `lint`, `format:check`, `typecheck`, `audit`.
22
22
  - `qa-engineer` runs at the completion gate, before the `verifier` audit, and records `coverage_gate: PASS | FAIL | SKIPPED(<reason>)`. Skipping requires a non-empty reason; omitting the field is treated as incomplete.
23
+ - `docs/roadmap.md` is the roadmap overview — one row per PRD phase or wave with status (`Not started` / `In progress` / `Done`), issues/PRs, and what is missing. `product-engineer` reads it at session start and owns its rows; `planner` reads it in Phase 0 and updates the rows a run delivers in the consolidated PR; the `verifier` reports a roadmap mismatch with merged work as an advisory finding.
23
24
  - `/TESTING.md` is the canonical testing contract — owned by `qa-engineer`, kept current by `developer`, and treated as "no standard established" while unfilled.
24
25
  - Reference GitHub Issues in branch names and commits; follow the `github-ops` conventions for all GitHub artifacts (issues, PRs, branches, labels, milestones, comments).
25
26
  - Treat `/DESIGN.md` as the source of truth for visual tokens, components, and design guidance; update it whenever UI contracts change.
@@ -40,7 +41,7 @@ GitHub operations run through the **`gh` CLI** (over Bash). The `github-ops` sub
40
41
 
41
42
  ## memo-cli (Optional)
42
43
 
43
- If `memo-cli` is installed and `memo setup validate` passes: `product-engineer` reads context at session start; `developer` writes intent/outcome entries per story; `technical-writer` writes one entry per ADR and significant doc change. If installed but not configured, ask the user to run `memo setup init` first. If not installed, skip silently. See the `memo-cli-usage` skill.
44
+ If `memo-cli` is installed and `memo setup validate` passes: `product-engineer` reads context at session start and writes each confirmed grilling decision to `kb`; `developer` writes intent/outcome entries per story; `technical-writer` writes one entry per ADR and significant doc change; `planner` verifies per-story memo fields and writes one run-outcome entry. Every memo command names `--bank <id>` literally — never `--bank $MEMO_BANK`, which is empty in a fresh shell and makes memo-cli reject the write. Every write is reported as `written(<id>)`, `failed(<reason>)`, or `skipped(<reason>)`; a failure is never dropped silently. If installed but not configured, ask the user to run `memo setup init` first. If not installed and `memo.config.json` is absent, skip; if `memo.config.json` exists but the binary is missing, warn. See the `memo-cli-usage` skill.
44
45
 
45
46
  ---
46
47
 
@@ -20,6 +20,7 @@ All work in this repository **MUST**:
20
20
  - Use canonical `package.json` script names for JS/TS projects: `lint`, `lint:fix`, `format`, `format:check`, `typecheck`, `test`, `test:unit`, `test:integration`, `test:e2e`, `audit`, `validate`.
21
21
  - Before developer/planner completion, enforce and record quality gates: `test`, `lint`, `format:check`, `typecheck`, `audit`.
22
22
  - `qa-engineer` runs at the completion gate, before the `verifier` audit, and records `coverage_gate: PASS | FAIL | SKIPPED(<reason>)`. Skipping requires a non-empty reason; omitting the field is treated as incomplete.
23
+ - `docs/roadmap.md` is the roadmap overview — one row per PRD phase or wave with status (`Not started` / `In progress` / `Done`), issues/PRs, and what is missing. `product-engineer` reads it at session start and owns its rows; `planner` reads it in Phase 0 and updates the rows a run delivers in the consolidated PR; the `verifier` reports a roadmap mismatch with merged work as an advisory finding.
23
24
  - `/TESTING.md` is the canonical testing contract — owned by `qa-engineer`, kept current by `developer`, and treated as "no standard established" while unfilled.
24
25
  - Reference GitHub Issues in branch names and commits; follow the `github-ops` conventions for all GitHub artifacts (issues, PRs, branches, labels, milestones, comments).
25
26
  - Treat `/DESIGN.md` as the source of truth for visual tokens, components, and design guidance; update it whenever UI contracts change.
@@ -40,7 +41,7 @@ GitHub operations run through the **`gh` CLI** (over Bash). The `github-ops` sub
40
41
 
41
42
  ## memo-cli (Optional)
42
43
 
43
- If `memo-cli` is installed and `memo setup validate` passes: `product-engineer` reads context at session start; `developer` writes intent/outcome entries per story; `technical-writer` writes one entry per ADR and significant doc change. If installed but not configured, ask the user to run `memo setup init` first. If not installed, skip silently. See the `memo-cli-usage` skill.
44
+ If `memo-cli` is installed and `memo setup validate` passes: `product-engineer` reads context at session start and writes each confirmed grilling decision to `kb`; `developer` writes intent/outcome entries per story; `technical-writer` writes one entry per ADR and significant doc change; `planner` verifies per-story memo fields and writes one run-outcome entry. Every memo command names `--bank <id>` literally — never `--bank $MEMO_BANK`, which is empty in a fresh shell and makes memo-cli reject the write. Every write is reported as `written(<id>)`, `failed(<reason>)`, or `skipped(<reason>)`; a failure is never dropped silently. If installed but not configured, ask the user to run `memo setup init` first. If not installed and `memo.config.json` is absent, skip; if `memo.config.json` exists but the binary is missing, warn. See the `memo-cli-usage` skill.
44
45
 
45
46
  ---
46
47