@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
@@ -10,7 +10,7 @@
10
10
  # `gh pr merge --admin` (blocked outright), `gh pr merge --auto` when the
11
11
  # resolved base is the default branch, and the raw-git escape of merging a
12
12
  # `story/*`/`issue/*` branch directly into an `integration/*` branch (the
13
- # reviewable path is `gh pr merge <n> --squash --delete-branch`).
13
+ # reviewable path is `gh pr merge <n> --merge --delete-branch`).
14
14
  # 2. `git commit` messages must follow Conventional Commits.
15
15
  # 3. `gh issue|pr create|edit|comment|review` must not pass a multi-line body
16
16
  # inline via `--body`; `--body-file` (or stdin `--body-file -`) is required.
@@ -19,6 +19,14 @@
19
19
  # allowed. The tag-push detector matches an exact `vX.Y.Z` ref position
20
20
  # (bare token or refspec destination), not any substring, so a branch
21
21
  # named e.g. `issue/42-bump-v1.2.3` is not misdetected as a tag push.
22
+ #
23
+ # Rules 1 and 4 read each command's arguments from its own simple-command
24
+ # segment (split at `&&`, `||`, `;`, `|`, `&`, and newlines outside quotes —
25
+ # see command_segments()), never from the rest of the command string. A
26
+ # chained `gh pr create --base main` is not a push to `main`, a `--tags` in a
27
+ # commit message is not a tag push, and every push or merge in a chain is
28
+ # checked, not only the last one (issue #256).
29
+ #
22
30
  # 5. (Issue #178) The same "no write to the default branch" invariant as
23
31
  # rule 1, enforced on the mutating GitHub MCP tool surface, not just
24
32
  # `Bash`. Before this rule, `.claude/settings.json` matched `"Bash"`
@@ -214,22 +222,112 @@ tokenize() {
214
222
  printf '%s' "$1" | xargs -n1 -- printf '%s\n' 2>/dev/null
215
223
  }
216
224
 
217
- # Does any `git push` destination token in $norm equal $1? Checks bare tokens
218
- # and the destination (right-hand) side of `src:dst` refspecs; strips a
219
- # leading `+` (force-push shorthand) before comparing. Flags are skipped.
225
+ # Split the raw command into simple-command segments, one per output line,
226
+ # at `&&`, `||`, `;`, `|`, `&`, and newlines outside single or double quotes
227
+ # (backslash escapes honored). Every rule that reads a command's arguments
228
+ # reads them from its own segment, never from the rest of the string. Before
229
+ # this, `git push -u origin feat && gh pr create --base main` read `main` as
230
+ # a push destination, `--tags` anywhere in the string read as a tag push, and
231
+ # a greedy `.*git push` match checked only the LAST push in a chained
232
+ # command, so `git push origin main && git push origin feat` was allowed
233
+ # (issue #256). Portable awk only: macOS ships BSD awk, not gawk.
234
+ command_segments() {
235
+ printf '%s\n' "$cmd" | awk '
236
+ { s = s (NR > 1 ? "\n" : "") $0 }
237
+ END {
238
+ out = ""; q = ""; n = length(s)
239
+ for (i = 1; i <= n; i++) {
240
+ c = substr(s, i, 1)
241
+ if (q != "") {
242
+ # Inside quotes a newline is part of the argument, never a
243
+ # separator: map it to a space so the segment stays whole.
244
+ if (c == "\n") { out = out " "; continue }
245
+ if (c == q) { q = ""; out = out c; continue }
246
+ if (c == "\\" && q == "\"" && i < n) {
247
+ d = substr(s, i + 1, 1); i++
248
+ if (d != "\n") out = out c d # backslash-newline is a continuation
249
+ continue
250
+ }
251
+ out = out c
252
+ continue
253
+ }
254
+ if (c == "\\" && i < n) {
255
+ d = substr(s, i + 1, 1); i++
256
+ if (d != "\n") out = out c d # backslash-newline is a continuation
257
+ continue
258
+ }
259
+ if (c == "\"" || c == "\047") { q = c; out = out c; continue }
260
+ if (c == ";" || c == "|" || c == "&" || c == "\n") { out = out "\n"; continue }
261
+ out = out c
262
+ }
263
+ print out
264
+ }'
265
+ }
266
+
267
+ # Segments matching the extended regex $1, whitespace-normalized, one per line.
268
+ segments_matching() {
269
+ command_segments | tr -s ' \t' ' ' | grep -E -- "$1"
270
+ }
271
+
272
+ # Argument tokens following EACH `git push` in segment $1, one per line.
273
+ # Quotes, backticks, parentheses, and separators are stripped from tokens so
274
+ # `$(git push origin main)` and `bash -c "git push origin main"` still yield
275
+ # `main`. Every occurrence in the segment is read, not just the last one.
276
+ push_tokens() {
277
+ printf '%s\n' "$1" | awk '{ n = split($0, parts, /git[ \t]+push/); for (i = 2; i <= n; i++) print parts[i] }' \
278
+ | tr -s ' \t' '\n\n' | tr -d "\"'\`();|&" | sed 's/[<>].*//' | grep -v '^$'
279
+ }
280
+
281
+ # A command word counts when it appears at a segment's start, after
282
+ # whitespace, after an opening quote, backtick, or parenthesis, or after a
283
+ # path (`/usr/bin/git`).
284
+ _cmd_prefix="(^|[[:space:](\`\"'/])"
285
+ _push_segment_re="${_cmd_prefix}git +push([[:space:]]|$)"
286
+
287
+ # Does any `git push` destination in the command equal branch $1? Reads each
288
+ # push segment's own tokens only. Checks bare tokens and the destination
289
+ # (right-hand) side of `src:dst` refspecs, strips a leading `+` (force-push
290
+ # shorthand) and a `refs/heads/` prefix before comparing. Flags are skipped.
220
291
  push_targets_ref() {
221
- local target="$1" rest tok dst
222
- rest="$(printf '%s' "$norm" | sed -n 's/.*git[[:space:]][[:space:]]*push[[:space:]][[:space:]]*//p')"
223
- for tok in $rest; do
224
- case "$tok" in
225
- -*) continue ;;
226
- esac
227
- tok="${tok#+}"
228
- dst="${tok##*:}"
229
- if [ "$tok" = "$target" ] || [ "$dst" = "$target" ]; then
230
- return 0
231
- fi
232
- done
292
+ local target="$1" seg tok dst
293
+ while IFS= read -r seg; do
294
+ while IFS= read -r tok; do
295
+ case "$tok" in
296
+ -*) continue ;;
297
+ esac
298
+ tok="${tok#+}"
299
+ dst="${tok##*:}"
300
+ tok="${tok#refs/heads/}"
301
+ dst="${dst#refs/heads/}"
302
+ if [ "$tok" = "$target" ] || [ "$dst" = "$target" ]; then
303
+ return 0
304
+ fi
305
+ done < <(push_tokens "$seg")
306
+ done < <(segments_matching "$_push_segment_re")
307
+ return 1
308
+ }
309
+
310
+ # Does any push segment push tags? `--tags`, `--follow-tags`, and `--mirror`
311
+ # (which pushes every ref, tags included) as flags of the push itself; a
312
+ # `refs/tags/` refspec; or a destination that is exactly `vX.Y.Z` — anchored,
313
+ # so a branch named e.g. `issue/42-bump-v1.2.3` is not a tag push. The words
314
+ # appearing elsewhere in the command (a commit message, an echo) do not count.
315
+ push_is_tag_push() {
316
+ local seg tok dst
317
+ while IFS= read -r seg; do
318
+ while IFS= read -r tok; do
319
+ case "$tok" in
320
+ --tags | --follow-tags | --mirror) return 0 ;;
321
+ *refs/tags/*) return 0 ;;
322
+ -*) continue ;;
323
+ esac
324
+ tok="${tok#+}"
325
+ dst="${tok##*:}"
326
+ if printf '%s' "$dst" | grep -Eq '^v[0-9]+\.[0-9]+\.[0-9]+$'; then
327
+ return 0
328
+ fi
329
+ done < <(push_tokens "$seg")
330
+ done < <(segments_matching "$_push_segment_re")
233
331
  return 1
234
332
  }
235
333
 
@@ -384,7 +482,7 @@ gh_pr_merge_target() {
384
482
 
385
483
  # `git push` targeting the default branch (resolved dynamically; not hardcoded
386
484
  # to `main` so a repo on `master`/`trunk` is protected identically).
387
- if printf '%s' "$norm" | grep -Eq '(^|[;&|[:space:]])git +push'; then
485
+ if printf '%s' "$norm" | grep -Eq "$_push_segment_re|[;&|]git +push"; then
388
486
  default_branch="$(resolve_default_branch)"
389
487
  if push_targets_ref "$default_branch"; then
390
488
  block "pushing to '$default_branch' is not allowed. Open a PR; only the user may merge into $default_branch."
@@ -392,7 +490,7 @@ if printf '%s' "$norm" | grep -Eq '(^|[;&|[:space:]])git +push'; then
392
490
  fi
393
491
 
394
492
  # `git merge`: two independent checks.
395
- if printf '%s' "$norm" | grep -Eq '(^|[;&|[:space:]])git +merge([[:space:]]|$)'; then
493
+ if printf '%s' "$norm" | grep -Eq "${_cmd_prefix}git +merge([[:space:]]|$)|[;&|]git +merge([[:space:]]|$)"; then
396
494
  current_branch="$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo '')"
397
495
  default_branch="$(resolve_default_branch)"
398
496
 
@@ -404,23 +502,33 @@ if printf '%s' "$norm" | grep -Eq '(^|[;&|[:space:]])git +merge([[:space:]]|$)';
404
502
  # 1b. Raw-git escape: merging a story/issue branch directly into an
405
503
  # integration branch bypasses PR review entirely. This is the confirmed
406
504
  # live defect's unreviewable path — block it and name the reviewable one.
407
- merge_arg="$(strip_merge_ref_prefix "$(git_merge_arg)")"
408
- case "$current_branch" in
409
- integration/*)
410
- case "$merge_arg" in
411
- story/*|issue/*)
412
- block "raw 'git merge' of a story/issue branch into an integration branch is not allowed — it bypasses PR review. Use 'gh pr merge <n> --squash --delete-branch' instead."
413
- ;;
414
- esac
415
- ;;
416
- esac
505
+ # Checked per segment, so every merge in a chained command is read with
506
+ # its own arguments (issue #256).
507
+ _full_norm="$norm"
508
+ while IFS= read -r norm; do
509
+ merge_arg="$(strip_merge_ref_prefix "$(git_merge_arg)")"
510
+ case "$current_branch" in
511
+ integration/*)
512
+ case "$merge_arg" in
513
+ story/*|issue/*)
514
+ block "raw 'git merge' of a story/issue branch into an integration branch is not allowed — it bypasses PR review. Use 'gh pr merge <n> --merge --delete-branch' instead."
515
+ ;;
516
+ esac
517
+ ;;
518
+ esac
519
+ done < <(segments_matching "${_cmd_prefix}git +merge([[:space:]]|$)")
520
+ norm="$_full_norm"
417
521
  fi
418
522
 
419
523
  # `gh pr merge`: resolve the PR's actual base via `gh pr view` (the `--base`
420
524
  # flag does not exist on `gh pr merge` — it belongs to `gh pr create` — so a
421
525
  # text check for it was always vacuous and blocked the tool's own canonical
422
526
  # merge command). Fails CLOSED if the lookup itself fails; see header.
423
- if printf '%s' "$norm" | grep -Eq '(^|[;&|[:space:]])gh +pr +merge([[:space:]]|$)'; then
527
+ # Checked per segment, so every `gh pr merge` in a chained command is read
528
+ # with its own arguments and flags (issue #256). Commands inside the loop read
529
+ # stdin from /dev/null so they cannot consume the segment list.
530
+ _full_norm="$norm"
531
+ while IFS= read -r norm; do
424
532
  # `--admin` bypasses branch protection outright; never allowed for agents.
425
533
  if printf '%s' "$norm" | grep -Eq -- '(^|[[:space:]])--admin([[:space:]]|$)'; then
426
534
  block "'gh pr merge --admin' bypasses branch protection and is not allowed for agents. Only the user may merge with --admin, or via GitHub's UI/API directly."
@@ -450,9 +558,9 @@ if printf '%s' "$norm" | grep -Eq '(^|[;&|[:space:]])gh +pr +merge([[:space:]]|$
450
558
  lookup_ok=0
451
559
  if command -v gh >/dev/null 2>&1; then
452
560
  if [ -n "$view_arg" ]; then
453
- base="$(gh pr view "$view_arg" --json baseRefName -q .baseRefName 2>/dev/null)" && lookup_ok=1
561
+ base="$(gh pr view "$view_arg" --json baseRefName -q .baseRefName 2>/dev/null </dev/null)" && lookup_ok=1
454
562
  else
455
- base="$(gh pr view --json baseRefName -q .baseRefName 2>/dev/null)" && lookup_ok=1
563
+ base="$(gh pr view --json baseRefName -q .baseRefName 2>/dev/null </dev/null)" && lookup_ok=1
456
564
  fi
457
565
  fi
458
566
 
@@ -462,7 +570,7 @@ if printf '%s' "$norm" | grep -Eq '(^|[;&|[:space:]])gh +pr +merge([[:space:]]|$
462
570
  block "could not verify the PR's base branch via '$verify_cmd' (gh missing, unauthenticated, or a network error). Refusing to merge (fail-closed): an unverified base could be the default branch. Do not fall back to an unverified merge path or a different tool surface — stop and ask the user to check 'gh auth status'/network access, or merge it themselves."
463
571
  fi
464
572
 
465
- default_branch="$(resolve_default_branch)"
573
+ default_branch="$(resolve_default_branch </dev/null)"
466
574
  if [ "$base" = "$default_branch" ]; then
467
575
  block "merging a PR into '$default_branch' is not allowed. Only the user may merge into $default_branch."
468
576
  fi
@@ -472,7 +580,8 @@ if printf '%s' "$norm" | grep -Eq '(^|[;&|[:space:]])gh +pr +merge([[:space:]]|$
472
580
  if printf '%s' "$norm" | grep -Eq -- '(^|[[:space:]])--auto([[:space:]]|$)' && [ "$base" = "$default_branch" ]; then
473
581
  block "'gh pr merge --auto' on a PR targeting '$default_branch' is not allowed. Only the user may merge into $default_branch."
474
582
  fi
475
- fi
583
+ done < <(segments_matching "${_cmd_prefix}gh +pr +merge([[:space:]]|$)")
584
+ norm="$_full_norm"
476
585
 
477
586
  # --- Rule 2: Conventional Commits for git commit ------------------------------
478
587
  # Inspect inline -m / --message messages. Commits via editor or -F file are not
@@ -508,44 +617,23 @@ fi
508
617
  # Agents may not create, move, delete, or force tags, push tags, or cut a
509
618
  # GitHub release. Reading tags is allowed: `git tag -l`, `git tag --list`,
510
619
  # `git tag -n`, `git tag` with no args, and `git describe --tags`.
511
- if printf '%s' "$norm" | grep -Eq '(^|[;&|[:space:]])git +tag([[:space:]]|$)'; then
620
+ # Checked per segment (issue #256): one read form must not let another
621
+ # segment's tag creation through, e.g. `git tag --list; git tag v1.0.0`.
622
+ while IFS= read -r _seg; do
512
623
  # Allow pure list/read forms.
513
- if printf '%s' "$norm" | grep -Eq '(^|[;&|[:space:]])git +tag +(-l|--list|-n[0-9]*)([[:space:]]|$)'; then
624
+ if printf '%s' "$_seg" | grep -Eq "${_cmd_prefix}git +tag +(-l|--list|-n[0-9]*)([[:space:]\"'\`)]|$)"; then
514
625
  :
515
- elif printf '%s' "$norm" | grep -Eq '(^|[;&|[:space:]])git +tag[[:space:]]*$'; then
626
+ elif printf '%s' "$_seg" | grep -Eq '(^|[[:space:]])git +tag[[:space:]]*$'; then
516
627
  : # `git tag` with no further arguments lists tags.
517
628
  else
518
629
  block "creating, moving, deleting, or forcing a git tag is not allowed. Tags are human-only, annotated, and point at a 'main' commit. See github-ops 'Tags'."
519
630
  fi
520
- fi
631
+ done < <(segments_matching "${_cmd_prefix}git +tag([[:space:]]|$)")
521
632
 
522
- # Block tag pushes: `--tags`, refs/tags/*, or a push whose destination token
523
- # (bare, or the right-hand side of a `src:dst` refspec) is an exact `vX.Y.Z`
524
- # ref — not merely a substring, so a branch like `issue/42-bump-v1.2.3` is not
525
- # misdetected as a tag push.
526
- if printf '%s' "$norm" | grep -Eq '(^|[;&|[:space:]])git +push'; then
527
- is_tag_push=0
528
- if printf '%s' "$norm" | grep -Eq -- '--tags'; then
529
- is_tag_push=1
530
- elif printf '%s' "$norm" | grep -Eq 'refs/tags/'; then
531
- is_tag_push=1
532
- else
533
- rest="$(printf '%s' "$norm" | sed -n 's/.*git[[:space:]][[:space:]]*push[[:space:]][[:space:]]*//p')"
534
- for tok in $rest; do
535
- case "$tok" in
536
- -*) continue ;;
537
- esac
538
- tok="${tok#+}"
539
- dst="${tok##*:}"
540
- if printf '%s' "$dst" | grep -Eq '^v[0-9]+\.[0-9]+\.[0-9]+$'; then
541
- is_tag_push=1
542
- break
543
- fi
544
- done
545
- fi
546
- if [ "$is_tag_push" -eq 1 ]; then
547
- block "pushing a tag is not allowed. Tags are created and pushed by a human only. See github-ops 'Tags'."
548
- fi
633
+ # Block tag pushes, read from each push segment's own arguments only: see
634
+ # push_is_tag_push.
635
+ if push_is_tag_push; then
636
+ block "pushing a tag is not allowed. Tags are created and pushed by a human only. See github-ops 'Tags'."
549
637
  fi
550
638
 
551
639
  # Block `gh release create` (cutting a release implies creating a tag).
@@ -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
 
@@ -78,6 +78,7 @@ fix(web): stop double-submitting the checkout form
78
78
  - PR title **MUST** follow Conventional Commits (e.g., `feat: implement issue 37`).
79
79
  - PR description **MUST** include `Closes #<issue-number>`.
80
80
  5. You **MUST** ensure the task list in the GitHub Issue matches the local `/workstream/tasks-*.md` file.
81
+ 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.
81
82
 
82
83
  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.
83
84
 
@@ -144,14 +145,17 @@ When `workstream/decisions-<feature>.md` exists and was read per step 2 above:
144
145
  5. `technical-writer` validation **MUST** include a drift/stale-doc check report, and completion **MUST NOT** proceed while unresolved drift remains.
145
146
  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.
146
147
  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.
147
- 8. The PR **MUST** be converted from draft to ready for review.
148
- 9. The PR **MUST** be approved by the appropriate reviewer per the merge authority policy in `github-ops`:
149
- - PRs targeting an **integration branch**: `planner` reviews and approves.
150
- - PRs targeting **`main`**: the **user** reviews and approves.
151
- 10. The PR **MUST** be merged by the authorized party (planner for integration branches, user for `main`).
152
- 11. You **MUST NOT** close the GitHub Issue until the PR is approved **AND** merged.
153
- 12. You **MUST NOT** close the issue while the PR is still in draft or pending review.
154
- 13. You **MUST** notify the user when the PR is ready for review — explicitly inform them so they can review and merge.
148
+ 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.
149
+ 9. The PR **MUST** be converted from draft to ready for review.
150
+ 10. The PR **MUST** be approved by the appropriate reviewer per the merge authority policy in `github-ops`:
151
+
152
+ - PRs targeting an **integration branch**: `planner` reviews and approves.
153
+ - PRs targeting **`main`**: the **user** reviews and approves.
154
+
155
+ 11. The PR **MUST** be merged by the authorized party (planner for integration branches, user for `main`).
156
+ 12. You **MUST NOT** close the GitHub Issue until the PR is approved **AND** merged.
157
+ 13. You **MUST NOT** close the issue while the PR is still in draft or pending review.
158
+ 14. You **MUST** notify the user when the PR is ready for review — explicitly inform them so they can review and merge.
155
159
 
156
160
  ---
157
161
 
@@ -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