Wrapup

/wrapup — Feature Completion Wrap-Up

You are closing out a completed feature after it has been merged. This skill ensures ADLC artifacts are finalized, knowledge is captured, and the team has a clear summary of what shipped.

Ethos

!test -s .adlc/ETHOS.md && cat .adlc/ETHOS.md || echo No ethos found — run /init to vendor .adlc/ETHOS.md

Context

• Active specs: !grep -rl -e status:.approved -e status:.in-progress -e status:.complete --include requirement.md .adlc/specs || echo No specs found
• Knowledge directory: !ls .adlc/knowledge/ || echo No knowledge directory
• Current branch: !git branch --show-current || echo Not a git repo
• Recent merges: !git log --oneline --merges -10 || echo No merge history

Input

Target: $ARGUMENTS

Prerequisites

Before proceeding, verify that .adlc/context/architecture.md and .adlc/context/conventions.md exist. If any of these files are missing, stop and tell the user: "The .adlc/ structure hasn't been initialized. Run /init first to set up the project context."

Instructions

Step 1: Identify the Feature

1. If given a REQ ID, locate all artifacts under .adlc/specs/REQ-xxx-*/
2. If no REQ ID given, infer from the current branch name or recent merge commits
3. Read the requirement spec, architecture doc, and all task files
4. Detect repository mode — read .adlc/config.yml in the primary repo. If it declares more than one entry under repos:, this is cross-repo mode; otherwise single-repo mode. In cross-repo mode also read pipeline-state.json from the spec directory — it holds the per-repo branch/worktree/PR/merge state.

Step 2: Commit, Push, and Merge

Determine the repo set to operate on:

• Single-repo mode: operate on the current repo only. Skip to the single-repo steps below.
• Cross-repo mode from /proceed: pipeline-state.json already lists touched repos; each repos[<id>].merged reflects whether /proceed Phase 8 already merged that PR. Walk mergeOrder and for each repo either confirm it's merged (no-op) or run the single-repo merge sequence inside that repo's worktree.
• Cross-repo mode standalone: no pipeline-state.json — fall back to detecting touched repos from the config and checking for feature branches/open PRs in each. Proceed with the single-repo merge sequence in each repo that has pending work, in merge_order from the config.

Single-repo merge sequence — run this block inside each target repo's worktree (same mechanics as before):

1. Branch check FIRST — never commit on main. Run git -C <worktree> branch --show-current. If it reports main (or master), stop: create a feature branch (e.g., agent/REQ-xxx-slug or feat/REQ-xxx-slug) and switch to it with git checkout -b <branch> BEFORE touching any files. If you're already on a worktree branch from /proceed Phase 0, continue.
2. Check git -C <worktree> status and git -C <worktree> diff for any uncommitted changes related to the feature
3. If there are uncommitted changes:
   • Stage all relevant files (avoid secrets, .env, credentials)
   • Create a commit with message: feat(REQ-xxx): <summary of changes>
   • Include Co-Authored-By: Claude <noreply@anthropic.com>
4. Push the branch to remote with git -C <worktree> push -u origin <branch>
5. If no PR exists for this branch, create one using adlc_forge_pr_create (source partials/forge.sh with the guarded spelling from conventions.md "Bash in skills" in the same fence; from inside the worktree, or with -R <owner/repo>) with a summary of what shipped — PR ops route through the forge adapter, never direct gh (REQ-520 BR-1)
6. If CI checks exist, monitor the pipeline with gh run watch and report the result
7. Rebase onto current main before merging — in a sprint or long-running pipeline, upstream main may have advanced since the branch was cut. Run git -C <worktree> fetch origin main and check whether the branch is behind: git -C <worktree> merge-base --is-ancestor origin/main HEAD. If that command fails (exit 1), the branch is behind main and must be updated:
   • git -C <worktree> rebase origin/main
   • If there are conflicts, STOP and surface them to the user — do not try to resolve semantic conflicts blindly
   • On clean rebase, force-push with lease: git -C <worktree> push --force-with-lease
   • Re-run gh pr checks <prUrl> and wait for CI to re-pass before merging
8. Verify PR status is mergeable: adlc_forge_pr_view <prUrl> --json mergeable,mergeStateStatus should report MERGEABLE and a clean merge state (on GitHub; ADO normalizes via pr_view). If not, stop and surface the reason.
9. Merge the PR using adlc_forge_pr_merge <prUrl> --squash --delete-branch. In cross-repo mode, update pipeline-state.json — set repos[<id>].merged = true. Check branch_deleted in the output (BUG-195). gh's post-merge cleanup routinely aborts when the default branch is checked out in another worktree — the normal state for a pipeline session. The adapter completes the remote deletion itself and reports branch_deleted=1 (or skipped-fork). If it reports branch_deleted=0, the remote branch survived: run the exact git push origin --delete <branch> the warn= line names before continuing. Branch on this field, never on the warn= prose.
10. Capture cleanup state BEFORE leaving the branch. You must record three things while you are still on the feature branch in the feature worktree, because the subsequent git checkout main may only work in the main worktree and you will lose the ability to look these up afterwards:
    • Branch name: BRANCH=$(git -C <worktree> branch --show-current)
    • Current working-tree path: WT_PATH=<worktree>
    • Main worktree path: MAIN_WT=$(git -C <worktree> worktree list --porcelain | awk '/^worktree /{p=$(2)} /^branch refs\/heads\/main$/{print p; exit}')
11. Move to the main worktree and update it: git -C "$MAIN_WT" checkout main && git -C "$MAIN_WT" pull
12. Clean up local branch and worktree (run from $MAIN_WT):
    • If "$WT_PATH" differs from "$MAIN_WT" (i.e., the work happened in a separate worktree), remove it: git -C "$MAIN_WT" worktree remove "$WT_PATH". This handles BOTH the /proceed pattern (.worktrees/REQ-xxx) and the Claude Code harness pattern (.claude/worktrees/<slug>) without hardcoding either path.
    • If the feature branch still exists locally after the squash-merge (git does not recognize squash-merges as merged, so git branch --merged will miss it), delete it: git -C "$MAIN_WT" branch -D "$BRANCH". Squash-merge is the default, so expect this to be the common case.
    • Prune any lingering remote-tracking refs: git -C "$MAIN_WT" fetch --prune
13. Verify cleanup: git -C "$MAIN_WT" worktree list should no longer include $WT_PATH, and git -C "$MAIN_WT" branch should no longer include $BRANCH. If either is still present, stop and surface the reason rather than silently moving on.

Cross-repo aggregate log: after walking every touched repo, emit a one-line summary per repo: <repo-id>: merged <prUrl>, worktree cleaned or <repo-id>: already merged (from /proceed Phase 8).

Step 3: Update ADLC Artifact Statuses

<!-- retrieval-status: lifecycle-write -->

• complete — the terminal REQ status written by step 1 below

<!-- /retrieval-status -->

complete is the status /spec Step 1.6 must be able to retrieve. The block above is the machine-readable declaration tools/lint-skills's retrieval-status-parity check reads; if this status is ever changed here without updating /spec's exclusion list, the check fails rather than letting spec retrieval go silently empty (BUG-194).

1. Set the requirement's frontmatter status to complete

2. Set all task statuses to complete

3. Update the updated date on all modified artifacts to today's date

4. If any tasks were deferred or descoped, note them in the requirement file under a "Deferred" section

5. If pipeline-state.json exists in the spec directory, write the complete terminal record — a partial write leaves a state file that contradicts the repo (BUG-193). All five:

   • "completed": true
   • "currentPhase": 8
   • 8 appended to completedPhases (append; do not replace the array)
   • a final phaseHistory entry for phase 8 naming the merge commit
   • repos[<id>].merged = true for every touched repo whose PR is merged — verify against the forge (adlc_forge_pr_view <prUrl> --fields state,mergedAt) rather than assuming, since /wrapup may be running standalone after an out-of-band merge

   Setting completed:true while leaving completedPhases at [0..7] or merged:false is the failure this list exists to prevent. Re-read the file after writing and confirm all five.

Step 4: Capture Knowledge

Evaluate whether any decisions, patterns, or lessons should be persisted:

Architectural Decisions

• Were any new patterns introduced? If so, propose an update to .adlc/context/architecture.md
• Were any existing patterns modified or deprecated?

Assumptions Validated or Invalidated

• Review assumptions from the requirement spec
• Log any that were validated, invalidated, or still unresolved to .adlc/knowledge/assumptions/
• Use the assumption template (check .adlc/templates/assumption-template.md first, fall back to ~/.claude/skills/templates/assumption-template.md)
• Name files: ASSUME-xxx-slug.md. Determine the next ID with the reservation-aware allocator adlc_alloc_id assume (REQ-546 BR-12): it atomically reserves the number on this repo's origin (refs/adlc/ids/assume/<NNN>) BEFORE returning it, so concurrent /wrapup runs across clones of one repo — or concurrent /sprint wrapups — cannot double-allocate an ASSUME id. The per-checkout .adlc/.next-assume counter is now a CACHE: max(remote, local) + 1 supersedes the old "never re-scan after the counter exists" rule, and the mkdir-lock + symlink pre-check (LESSON-014, LESSON-110) now live inside adlc_alloc_id. Source the partial and call it in the SAME fenced block (fenced blocks don't share shell state):

  if [ -f .adlc/partials/id-alloc.sh ]; then . .adlc/partials/id-alloc.sh; else . ~/.claude/skills/partials/id-alloc.sh; fi
  ASSUME_NUM=$(adlc_alloc_id assume)
  # `exit 1` inside adlc_alloc_id's subshell terminates only the subshell — guard parent.
  [ -n "$ASSUME_NUM" ] || { echo "ERROR: failed to allocate ASSUME number — aborting" >&2; exit 1; }

  The reservation is PER-REPO scoped (BR-12): the ref is pushed to and derived from ONLY this repo's origin, never sibling repos, keeping the per-project namespace while making it collision-safe across clones. Derivation mirrors the lesson kind — the merged .adlc/knowledge/assumptions/ scan on the origin default branch PLUS the reservation namespace, no branch source — so historical ASSUME ids raise the high-water with no backfill and a stale clone cannot lower it. Degradation stays loud-not-blocking: an offline /wrapup still allocates (with a warning) from max(local counter, local assumptions scan) + 1, and the REQ-545 recheck remains the late tripwire.

Lessons Learned

Provenance-classifying harness (BUG-228): if your shell tool classifies each command's reach and pins the session to a local tier when it cannot prove it — Teton Code's shell does — run none of this step's shell blocks (telemetry, gate, or adlc-read). Go straight to the fallback path, reading with your harness's own file-read tool, and say in your reply that the delegate was skipped for this reason instead of running the fallback's stderr emit or the telemetry emit. No spelling of those blocks classifies as in-reach (adlc-read is not a recognised verb and the partials run by path), so any one of them pins the turn — see partials/delegate-gate.md "Provenance-classifying harnesses".

Before the gate check, create a skill-invocation flag and capture the start time for telemetry (REQ-424 ghost-skip detection):

if [ -f .adlc/partials/delegate-tools-path.sh ]; then . .adlc/partials/delegate-tools-path.sh; else . ~/.claude/skills/partials/delegate-tools-path.sh; fi
flag=$("$DELEGATE_TOOLS"/skill-flag.sh create)
trap '"$DELEGATE_TOOLS"/skill-flag.sh clear "$flag" 2>/dev/null || true' EXIT  # cleanup on abort
"$DELEGATE_TOOLS"/skill-flag.sh mark "$flag" start_s "$(date -u +%s)"

The telemetry state (start_s, invoked, exit, reason) is persisted to the flag-file sidecar via skill-flag.sh mark, NOT to shell variables, because SKILL.md fenced blocks do not share shell state (single-fence-safe telemetry, REQ-522 BR-4). The resolution block reads it back with skill-flag.sh read.

Decide drafting strategy via the shared predicate (REQ-416 ADR-2 — see partials/delegate-gate.md), then proceed down the appropriate branch:

if [ -f .adlc/partials/delegate-gate.sh ]; then . .adlc/partials/delegate-gate.sh; else . ~/.claude/skills/partials/delegate-gate.sh; fi
if [ -f .adlc/partials/delegate-tools-path.sh ]; then . .adlc/partials/delegate-tools-path.sh; else . ~/.claude/skills/partials/delegate-tools-path.sh; fi
adlc_delegate_gate_check; gate=$?
"$DELEGATE_TOOLS"/skill-flag.sh mark "$flag" reason "$ADLC_DELEGATE_GATE_REASON"
case $gate in
  0) ;;  # delegated path — see "Delegated drafting" below
  1) ;;  # disabled path (ADLC_DISABLE_DELEGATE=1, or not opted in) — see "Fallback drafting" below
  2) ;;  # unavailable path (adlc-read not on PATH) — see "Fallback drafting" below
esac

Delegated drafting (gate passes — adlc-read is on PATH and ADLC_DISABLE_DELEGATE is not 1):

MANDATORY — no agent discretion. When the gate passes AND step 1 resolved a transcript, invoking adlc-read to draft the lessons is required, not optional. Exactly two non-delegated outcomes are acceptable on the gate-pass path: (a) adlc-read was actually invoked and exited non-zero (→ api-error fallback), or (b) step 1's discovery legitimately produced no transcript — no candidates at all, or no candidate mentioning the REQ id — so there was nothing to delegate. Case (b) never reaches the call site, so invoked is never marked and the resolver records fallback/gate=fail; it is therefore NOT rewritten into a ghost-skip (that rewrite keys on gate=pass). Drafting the lessons-learned yourself from a transcript you did resolve, instead of calling adlc-read — for ANY reason, including "short session", "few lessons", or "faster to just write them" — is a compliance violation, NOT a fallback. emit-telemetry.sh mechanically rewrites any gate-pass fallback record whose reason is not api-error into a ghost-skip, so a hand-written reason cannot disguise a skipped call — the skip surfaces in check-delegation.sh counts regardless of how the emit is labeled.

1. Locate the Claude Code session JSONL whose recent content mentions the active REQ — content-anchored discovery (REQ-423). The original heuristic ("newest JSONL under the repo-root-encoded path") silently picked the wrong transcript when a session was opened at a parent directory and later navigated into the repo. The walk starts at the current working tree and climbs to (and including) $HOME, collects candidate JSONLs at each level, and picks the one whose last 200 lines contain a word-boundary match for the active REQ id. Emits exactly one stderr line per invocation stating which JSONL was chosen and why.

   Two failure modes are answered by refusing, not guessing. If no candidates exist at all, or if a REQ id was available and no candidate mentions it, $JSONL stays empty and control falls through to Fallback drafting — Claude writes the lesson from the conversation it actually ran. A well-formed lesson synthesized from an unrelated transcript is worse than no delegation, so "newest wins" is only used when there is no anchor id to check against.

   Path encoding must match Claude Code exactly. Claude Code replaces every non-alphanumeric character in the absolute path with -, so . collapses too. Encoding only / produced -…-adlc-toolkit-.claude-worktrees-<slug> where the real directory is -…-adlc-toolkit--claude-worktrees-<slug>, which meant sessions run inside a Claude Code harness worktree (<repo>/.claude/worktrees/<slug>) never matched at the worktree level; the walk then reached the repo-root dir full of older, unrelated sessions and the "newest" fallback quietly served one of those. Any change to the encoder must be re-verified against a real ~/.claude/projects/ listing, not reasoned about in the abstract.

   # Start the walk at the CURRENT working tree, NOT at a de-worktree'd repo root. When the
   # session runs inside a Claude Code harness worktree (`<repo>/.claude/worktrees/<slug>`),
   # that worktree has its OWN project dir under ~/.claude/projects/ holding the only
   # transcript of this session — de-worktree-ing here would skip it and land on the repo
   # root's older, unrelated sessions. The upward walk below reaches the repo root anyway,
   # so nothing is lost by starting deeper. (The former `sed 's|/\.worktrees/.*$||'` was
   # also dead code for the harness pattern: it strips `/.worktrees/`, not `/.claude/worktrees/`.)
   ROOT=$(git rev-parse --show-toplevel 2>/dev/null) || ROOT="$PWD"
   # Normalize $HOME (strip any trailing slash) so the loop terminator and prefix check are reliable.
   HOME_NORM="${HOME%/}"
   PROJECTS_DIR="$HOME_NORM/.claude/projects"
   
   # Claude Code encodes an absolute path into a ~/.claude/projects/ directory name by
   # replacing EVERY non-alphanumeric character with '-'. Both '/' and '.' are replaced,
   # which is why `<repo>/.claude/worktrees/<slug>` encodes to `<repo>--claude-worktrees-<slug>`
   # (double dash), and why the leading '/' becomes the leading '-' with no separate prefix
   # step. Encoding only '/' produced `-.claude-` and never matched any real directory.
   #
   # Pure parameter expansion, NOT `sed`: this runs once per ancestor level and once per
   # project-dir entry on the slow path, so a fork here is multiplied by (levels x entries).
   # A `sed` version measured ~15s on a deep path with 500 project dirs; this is instant.
   # `${1}` braced because Skill argument templating rewrites an unbraced dollar-digit
   # before the block ever reaches a shell. `[!...]` (not `[^...]`) is the portable
   # negated-class form — verified byte-identical to the sed output in bash AND zsh.
   adlc_encode_project_dir() { printf '%s' "${1//[!A-Za-z0-9]/-}"; }
   
   # Build candidate list: walk from $ROOT up to (and including) $HOME, encoding each ancestor.
   # Hard guard: only enumerate paths that are $HOME or a descendant of $HOME — defends against
   # scanning other users' / system session data (BR-6) even if $ROOT is itself above $HOME
   # (e.g., user opened Claude at /Users with no project loaded).
   CANDIDATES=()
   DIR="$ROOT"
   case "$DIR/" in
       "$HOME_NORM"/|"$HOME_NORM"/*) ;;  # OK — $DIR is $HOME or under $HOME
       *) DIR="" ;;                       # outside $HOME — skip discovery entirely
   esac
   if [ -n "$DIR" ] && [ -n "$HOME_NORM" ]; then
       while [ -n "$DIR" ] && [ "$DIR" != "/" ]; do
           WANT=$(adlc_encode_project_dir "$DIR")
           MATCHES=""
           if [ -d "$PROJECTS_DIR/$WANT" ]; then
               # Fast path: our encoding is the real name. This is the case for every
               # directory Claude Code has actually created, so the scan below almost
               # never runs.
               MATCHES="$WANT"
           else
               # Slow path: no exact hit. Re-scan the REAL listing and compare both sides
               # through the SAME encoder, so a character Claude Code encodes differently
               # than we predict (e.g. '_') still matches — the lookup keeps working
               # without us having to re-derive the encoder table. Only entries that
               # normalize to $WANT are accepted, so this cannot widen the walk beyond
               # the ancestor being considered.
               while IFS= read -r entry; do
                   [ -n "$entry" ] || continue
                   [ "$(adlc_encode_project_dir "$entry")" = "$WANT" ] || continue
                   MATCHES="$MATCHES$entry

" done < <(ls -1 "$PROJECTS_DIR" 2>/dev/null) fi while IFS= read -r entry; do [ -n "$entry" ] || continue # BR-7 sanitization before the name is used as a path component. The encoder # makes '.' unreachable in $WANT, but on the slow path $entry comes off the # filesystem, so the explicit .. case-reject stays as the definitive # traversal guard and the regex as a secondary check on the permitted alphabet. case "$entry" in ..) continue ;; esac printf '%s' "$entry" | grep -qE '^-[A-Za-z0-9_.-]+$' || continue ENC_DIR="$PROJECTS_DIR/$entry" [ -d "$ENC_DIR" ] || continue # ls dir | grep, not ls glob: zsh errors on unmatched globs ("no # matches found") instead of passing the pattern through. while IFS= read -r f; do [ -n "$f" ] && CANDIDATES+=("$ENC_DIR/$f") done < <(ls -t "$ENC_DIR" 2>/dev/null | grep '.jsonl$') # %s\n, not %s: read returns false on a final line with no terminator, so a # newline-less $MATCHES (the single-entry fast path) would skip the loop entirely. # The extra blank line this adds on the slow path is dropped by the -n guard above. done < <(printf '%s\n' "$MATCHES") # Terminate after processing $HOME — BR-6: never walk above (would otherwise scan # /Users/, /, etc. and expose other users' session data). [ "$DIR" = "$HOME_NORM" ] && break DIR=$(dirname "$DIR") done fi

JSONL="" if [ ${#CANDIDATES[@]} -eq 0 ]; then echo "/wrapup: session JSONL — no candidates found; skipping delegation" >&2 # JSONL stays empty — step 2 below guards on [ -n "$JSONL" ] and falls through to # Fallback drafting (BR-9 — same as today's REQ-414 cold-path behavior). else # Phase 1: id-match — word-boundary fixed-string grep on last 200 lines of each candidate # (ADR-1). -wF is portable across BSD grep (macOS) and GNU grep AND is injection-safe # against any regex metacharacters that might appear in $REQ_ID. First match wins; walk # order is repo-root first, so the closest-to-repo match is preferred. if [ -n "$REQ_ID" ]; then for c in "${CANDIDATES[@]}"; do if tail -n 200 "$c" 2>/dev/null | grep -qwF "$REQ_ID"; then JSONL="$c" echo "/wrapup: session JSONL — matched $REQ_ID in $(basename "$c")" >&2 break fi done fi # Phase 2: no candidate matched the anchor id. if [ -z "$JSONL" ] && [ -n "$REQ_ID" ]; then # REFUSE, do not guess. When a REQ id was available and NO candidate mentions it, # every candidate is by definition a transcript of different work — delegating one # yields a confident, well-formed lesson about the wrong feature, which is strictly # worse than not delegating. Leave $JSONL empty so step 2 falls through to Fallback # drafting, where Claude drafts from the in-context conversation it actually ran. echo "/wrapup: session JSONL — $REQ_ID not mentioned in any of ${#CANDIDATES[@]} candidate(s); REFUSING to delegate a non-matching transcript — drafting directly instead" >&2 elif [ -z "$JSONL" ]; then # No anchor id to check against, so newest-in-closest-dir is the only signal # available. Architecture note: this is newest-within-the-first-candidate-directory, # not globally newest across all ancestor dirs — accepted approximation per REQ-423. # Slice form, not [0]: zsh arrays are 1-indexed, so ${CANDIDATES[0]} is # silently empty there; ${CANDIDATES[@]:0:1} is first-element in bash AND zsh. JSONL="${CANDIDATES[@]:0:1}" echo "/wrapup: session JSONL — no REQ id provided; using newest $(basename "$JSONL")" >&2 fi fi