@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.
- package/.claude/agents/developer.md +45 -31
- package/.claude/agents/technical-writer.md +11 -9
- package/.claude/agents/verifier.md +15 -0
- package/.claude/commands/planner.md +60 -12
- package/.claude/commands/product-engineer.md +54 -8
- package/.claude/hooks/git-guard.sh +151 -63
- package/.claude/skills/implement/SKILL.md +12 -8
- package/.claude/skills/memo-cli-usage/REFERENCE.md +11 -11
- package/.claude/skills/memo-cli-usage/SKILL.md +11 -9
- package/.github/agents/developer.agent.md +45 -31
- package/.github/agents/planner.agent.md +60 -12
- package/.github/agents/product-engineer.agent.md +54 -8
- package/.github/agents/technical-writer.agent.md +11 -9
- package/.github/agents/verifier.agent.md +15 -0
- package/.github/instructions/implement.instructions.md +12 -8
- package/.github/skills/memo-cli-usage/REFERENCE.md +11 -11
- package/.github/skills/memo-cli-usage/SKILL.md +11 -9
- package/.kiro/agents/developer.md +45 -31
- package/.kiro/agents/planner.md +60 -12
- package/.kiro/agents/product-engineer.md +54 -8
- package/.kiro/agents/technical-writer.md +11 -9
- package/.kiro/agents/verifier.md +15 -0
- package/.kiro/hooks/scripts/git-guard.sh +96 -10
- package/.kiro/skills/memo-cli-usage/REFERENCE.md +11 -11
- package/.kiro/skills/memo-cli-usage/SKILL.md +11 -9
- package/.kiro/steering/implement.md +12 -8
- package/AGENTS.md +7 -5
- package/AGENTS.md.template +3 -1
- package/CHANGELOG.md +19 -0
- package/CLAUDE.md +2 -1
- package/CLAUDE.md.template +2 -1
- package/package.json +1 -1
|
@@ -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
|
-
#
|
|
218
|
-
#
|
|
219
|
-
#
|
|
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"
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
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
|
|
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
|
|
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
|
-
|
|
408
|
-
|
|
409
|
-
|
|
410
|
-
|
|
411
|
-
|
|
412
|
-
|
|
413
|
-
|
|
414
|
-
|
|
415
|
-
|
|
416
|
-
|
|
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> --squash --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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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' "$
|
|
624
|
+
if printf '%s' "$_seg" | grep -Eq "${_cmd_prefix}git +tag +(-l|--list|-n[0-9]*)([[:space:]\"'\`)]|$)"; then
|
|
514
625
|
:
|
|
515
|
-
elif printf '%s' "$
|
|
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
|
-
|
|
631
|
+
done < <(segments_matching "${_cmd_prefix}git +tag([[:space:]]|$)")
|
|
521
632
|
|
|
522
|
-
# Block tag pushes
|
|
523
|
-
#
|
|
524
|
-
|
|
525
|
-
|
|
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).
|
|
@@ -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.
|
|
148
|
-
9. The PR **MUST** be
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
-
|
|
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
|
|
49
|
+
memo recall "<current task description>" --bank <agent>-memory --json
|
|
48
50
|
```
|
|
49
51
|
|
|
50
|
-
If
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|