forgedock 1.1.6 → 1.1.8

package/commands/work-on/investigate.md

@@ -90,6 +90,171 @@ Print these blocks to stdout before Phase 1A begins. During Phase 1B (step 3 —
 
 ---
 
+## Phase 0.6: Forge Ledger Pre-Recall <!-- Added: forge#1740 -->
+
+**Goal**: Query the Forge Ledger knowledge index for prior cards matching this issue's title terms, affected files, and symbols — **before reading any code**. Inject above-threshold results with explicit delta-verification framing so the investigator builds on prior knowledge rather than re-deriving it.
+
+**This phase is non-blocking** — if the index is absent, empty, or returns no match above threshold, log a single line and proceed to Phase 1A. Never stall the pipeline for recall.
+
+**Relationship to Phase 0.5**: Phase 0.5 retrieves structured priors from the Gist-based FORGE:MEMORY_INDEX (coarse keyword scoring over MEMORY_ENTRY lines). Phase 0.6 queries the Forge Ledger index (BM25 over structured knowledge cards, indexed by `build-knowledge-index.mjs`). Both are complementary and both run — neither replaces the other.
+
+### Step 1: Probe for index
+
+```bash
+RECALL_PATH="${REPO_PATH:-$(git rev-parse --show-toplevel 2>/dev/null)}/bin/recall.mjs"
+LEDGER_AVAILABLE=0
+
+if [ -f "$RECALL_PATH" ]; then
+  # Quick probe: does the index exist and have at least one card?
+  PROBE=$(node "$RECALL_PATH" --doctor 2>/dev/null | grep "^Total cards:" | grep -v "^Total cards:    0" || true)
+  [ -n "$PROBE" ] && LEDGER_AVAILABLE=1
+fi
+
+if [ "$LEDGER_AVAILABLE" -eq 0 ]; then
+  echo "[recall] Forge Ledger index absent or empty — skipping Phase 0.6, proceeding to Phase 1A"
+  # → Continue to Phase 1A
+fi
+```
+
+### Step 2: Build combined query (title terms + symbols + affected files)
+
+Extract query components from the issue body and title. The recall CLI accepts free text (BM25 ranked) plus repeated `--file` flags (exact-match boost):
+
+```bash
+# Extract title keywords: lowercase, remove stop words, keep noun/verb tokens (≥4 chars)
+ISSUE_TITLE=$(gh issue view {NUMBER} {GH_FLAG} --json title --jq '.title' 2>/dev/null || echo '')
+TITLE_TERMS=$(echo "$ISSUE_TITLE" | tr '[:upper:]' '[:lower:]' \
+  | sed 's/[^a-z0-9 ]/ /g' \
+  | tr ' ' '\n' \
+  | grep -E '^[a-z]{4,}$' \
+  | grep -vE '^(with|that|this|from|into|have|will|when|then|than|them|they|been|were|also|only|does|some|each|more|over|such|both|most|other|many|after|about|should|would|could|their|these|those|which|where|there|being|while|using|since|until|before|under|above)$' \
+  | sort -u | head -10 | tr '\n' ' ' | xargs)
+
+# Extract affected files from the issue body's ## Affected Files section
+ISSUE_BODY=$(gh issue view {NUMBER} {GH_FLAG} --json body --jq '.body' 2>/dev/null || echo '')
+AFFECTED_FILES_RAW=$(echo "$ISSUE_BODY" \
+  | sed -n '/^## Affected Files/,/^## /p' \
+  | grep -oE '`[^`]+\.(md|mjs|js|ts|py|sh|yaml|yml|json)`' \
+  | tr -d '`' | sort -u | head -5)
+
+# Extract symbols: backtick-quoted identifiers from the issue body (≥4 chars, camelCase or snake_case)
+SYMBOLS_RAW=$(echo "$ISSUE_BODY" \
+  | grep -oE '`[A-Za-z_][A-Za-z0-9_]{3,}`' \
+  | tr -d '`' | sort -u | head -5)
+
+# Build --file flags (one per affected file)
+FILE_FLAGS=""
+while IFS= read -r f; do
+  [ -n "$f" ] && FILE_FLAGS="$FILE_FLAGS --file $f"
+done <<< "$AFFECTED_FILES_RAW"
+
+# Build --symbol flag (first symbol only — recall supports one --symbol)
+SYMBOL_FLAG=""
+FIRST_SYMBOL=$(echo "$SYMBOLS_RAW" | head -1)
+[ -n "$FIRST_SYMBOL" ] && SYMBOL_FLAG="--symbol $FIRST_SYMBOL"
+```
+
+### Step 3: Run recall query and capture results
+
+```bash
+RECALL_RESULTS=""
+RECALL_ISSUE_CITATIONS=""
+
+if [ "$LEDGER_AVAILABLE" -eq 1 ] && [ -n "$TITLE_TERMS$FILE_FLAGS$SYMBOL_FLAG" ]; then
+  echo "[recall] Querying Forge Ledger: terms='${TITLE_TERMS}' files='${AFFECTED_FILES_RAW}' symbol='${FIRST_SYMBOL}'"
+
+  # Run combined query: title terms (free text) + file flags + symbol + min-score threshold
+  # --json for machine-readable output; --min-score 0.3 filters weak matches (noise gate)
+  RECALL_JSON=$(node "$RECALL_PATH" \
+    $TITLE_TERMS \
+    $FILE_FLAGS \
+    $SYMBOL_FLAG \
+    --k 5 \
+    --min-score 0.3 \
+    --json \
+    2>/dev/null || echo '[]')
+
+  # Count results
+  RECALL_COUNT=$(echo "$RECALL_JSON" | node -e "
+    let d = ''; process.stdin.on('data', c => d += c);
+    process.stdin.on('end', () => {
+      try { console.log(JSON.parse(d).length); } catch { console.log(0); }
+    });
+  " 2>/dev/null || echo "0")
+
+  if [ "${RECALL_COUNT:-0}" -gt 0 ]; then
+    echo "[recall] Found ${RECALL_COUNT} prior card(s) above threshold — injecting with delta-verification framing"
+
+    # Extract issue citations for the Prior Investigations field in the FORGE:INVESTIGATOR comment
+    RECALL_ISSUE_CITATIONS=$(echo "$RECALL_JSON" | node -e "
+      let d = ''; process.stdin.on('data', c => d += c);
+      process.stdin.on('end', () => {
+        try {
+          const cards = JSON.parse(d);
+          const seen = new Set();
+          const cites = cards
+            .filter(c => { if (seen.has(c.issue)) return false; seen.add(c.issue); return true; })
+            .map(c => '#' + c.issue)
+            .join(', ');
+          console.log(cites);
+        } catch { console.log(''); }
+      });
+    " 2>/dev/null || echo '')
+
+    # Format cards as human-readable text for injection (not raw JSON)
+    RECALL_FORMATTED=$(echo "$RECALL_JSON" | node -e "
+      let d = ''; process.stdin.on('data', c => d += c);
+      process.stdin.on('end', () => {
+        try {
+          const cards = JSON.parse(d);
+          const lines = [];
+          for (const c of cards) {
+            lines.push('── ' + c.kind.toUpperCase() + ' from #' + c.issue + ' (score: ' + c.score.toFixed(2) + ') ──');
+            if (c.rootCause)  lines.push('Root Cause: ' + c.rootCause);
+            if (c.prevention) lines.push('Fix/Prevention: ' + c.prevention);
+            if (c.pattern)    lines.push('Pattern: ' + c.pattern);
+            if (c.verdict)    lines.push('Verdict: ' + c.verdict + ' (' + (c.confidence || '?') + ')');
+            if (c.paths && c.paths.length) lines.push('Files: ' + c.paths.slice(0,3).join(', '));
+          }
+          console.log(lines.join('\n'));
+        } catch (e) { console.log(''); }
+      });
+    " 2>/dev/null || echo '')
+
+    # Cap at ≤ 2K chars (same budget as context C0 Gist summaries)
+    RECALL_RESULTS=$(echo "$RECALL_FORMATTED" | head -c 2048)
+  else
+    echo "[recall] No prior cards above threshold (min-score 0.3) — investigating from scratch"
+  fi
+fi
+```
+
+### Step 4: Inject recall results into investigation context
+
+If `RECALL_RESULTS` is non-empty, print the following block to stdout **before Phase 1A begins**. The investigation steps in Phase 1B MUST treat this as starting context — verify deltas against current code rather than re-deriving the prior model.
+
+**If `RECALL_RESULTS` is empty**: skip this step entirely and proceed to Phase 1A.
+
+```
+[FORGE:RECALL_PRIOR — Forge Ledger pre-recall results]
+Prior cards matched this issue above threshold (min-score 0.3).
+
+CRITICAL FRAMING: These cards describe prior findings on the same files/symbols.
+  → Verify the deltas against current code — do NOT re-derive the prior model.
+  → Stale cards (status: stale) are excluded by default — the query runs without
+     --include-stale. Do not treat any card as authoritative without confirming
+     the finding still exists in the current code.
+  → Cite confirmed priors in the FORGE:INVESTIGATOR "Prior Investigations" field.
+
+${RECALL_RESULTS}
+
+[END FORGE:RECALL_PRIOR]
+```
+
+Store `RECALL_ISSUE_CITATIONS` in a variable — it is used in Phase 1C to populate the `**Prior Investigations (via recall)**` field in the FORGE:INVESTIGATOR comment.
+
+---
+
 ## Phase 1A: Load Issue & Check Resume State
 
 ```bash
@@ -192,6 +357,20 @@ bash {REPO_PATH}/scripts/code-index.sh query --domain {DOMAIN_LABEL} --repo-path
 
 The comment MUST include `<!-- INVESTIGATION:COMPLETE -->` at the very end, AFTER all required sections are present. This marker signals the investigation finished successfully.
 
+**CODEC PATH (forge#1727)**: Construct the annotation body via the protocol codec — do NOT hand-roll the `<!-- FORGE:INVESTIGATOR -->` header. Use `forge-annotation.sh write INVESTIGATOR --field ...` or `node packages/protocol/src/cli.js emit INVESTIGATOR --field ...` to produce the opening tag and completion sentinel. Fill in the Markdown body sections below. The full pattern:
+
+```bash
+# Build the annotation body via codec (escaping and sentinel handled by codec)
+ANNOTATION_BODY=$(node packages/protocol/src/cli.js emit INVESTIGATOR \
+  --field "Verdict={VERDICT}" \
+  --field "Confidence={CONFIDENCE}" \
+  --field "Severity={SEVERITY}" \
+  --field "Task Type={TASK_TYPE}" \
+  --field "Decomposition Assessment={YES|NO} — {reason}")
+# ANNOTATION_BODY now has opening tag + required fields + INVESTIGATION:COMPLETE sentinel.
+# Append the Markdown body sections to it before posting.
+```
+
 Before posting, resolve the attribution annotation link from `forge.yaml`:
 
 ```bash
@@ -234,6 +413,7 @@ gh issue comment {NUMBER} {GH_FLAG} --body "<!-- FORGE:INVESTIGATOR -->
 **Last touched**: {hash — author — date — subject}
 **Pickaxe hits (prior fixes / regressions)**: {commit(s) found via \`git log -S\`/\`-G\`, or 'None found' — max 5}
 {This field is MANDATORY — populate from the git blame + pickaxe commands in step 4/5. If a file is newly created (no history), write 'New file — no history.'}
+**Prior Investigations (via recall)**: {Comma-separated issue citations from \`RECALL_ISSUE_CITATIONS\` (e.g. '#1172, #1243 — building on, not repeating'), or 'None — no Forge Ledger match above threshold' if \`RECALL_RESULTS\` was empty. Use the \`RECALL_ISSUE_CITATIONS\` variable populated in Phase 0.6.}
 
 ### Recommendation
 {what to build/fix, concrete and actionable}
@@ -541,6 +721,47 @@ fi
 
 ## Phase 1D: Update Labels & Return Verdict
 
+### 1D.0: Finding Lifecycle Label Transition (MANDATORY — run before workflow label update)
+
+**Purpose**: Wire the investigation verdict into the finding-validation lifecycle. If the issue under investigation is a review-finding (carries `needs-validation`), translate the verdict into `validated` or `false-positive` using `transition-label.sh --validate`. This is the primary mechanism that resolves the `needs-validation → validated/false-positive` lifecycle gap. <!-- Added: forge#1730 -->
+
+**Run this block regardless of verdict (CONFIRMED, PARTIAL, INVALID) — the verdict-to-label mapping handles all cases:**
+
+```bash
+# Check if this issue is a finding awaiting validation
+ISSUE_LABELS=$(gh issue view {NUMBER} {GH_FLAG} --json labels --jq '[.labels[].name] | join(",")' 2>/dev/null || echo "")
+
+if echo "$ISSUE_LABELS" | grep -q "needs-validation"; then
+  echo "Issue #{NUMBER} has needs-validation — applying verdict label transition..."
+  RESOLUTION=$(resolve_script 'transition-label')
+  TIER="${RESOLUTION%%:*}"
+  SCRIPT_PATH="${RESOLUTION#*:}"
+  case "$TIER" in
+    adaptive|universal)
+      bash "$SCRIPT_PATH" --validate {VERDICT} {NUMBER} {GH_FLAG} || true
+      ;;
+    prose)
+      # Prose fallback: apply label transition directly via gh
+      if [ "{VERDICT}" = "CONFIRMED" ]; then
+        gh issue edit {NUMBER} {GH_FLAG} --add-label "validated" --remove-label "needs-validation" 2>/dev/null || true
+        echo "Applied: needs-validation → validated (verdict: CONFIRMED)"
+      else
+        gh issue edit {NUMBER} {GH_FLAG} --add-label "false-positive" --remove-label "needs-validation" 2>/dev/null || true
+        echo "Applied: needs-validation → false-positive (verdict: {VERDICT})"
+      fi
+      ;;
+  esac
+else
+  echo "Issue #{NUMBER} does not have needs-validation — no finding lifecycle transition needed"
+fi
+```
+
+**Verdict → label mapping**: `CONFIRMED` → `validated`; `PARTIAL`, `NOT-CONFIRMED`, `INVALID` → `false-positive`.
+
+**Idempotency**: `transition-label.sh --validate` is a no-op if the issue already has `validated` or `false-positive`, or if it lacks `needs-validation`. Safe to call on any issue.
+
+---
+
 **CONFIRMED or PARTIAL with decompose: NO**:
 ```bash
 gh issue edit {NUMBER} {GH_FLAG} --add-label "workflow:ready-to-build" --remove-label "workflow:investigating"

package/commands/work-on.md

@@ -62,6 +62,7 @@ Orchestrator for the full issue lifecycle: investigate → decompose (if needed)
 - `workflow:merged` label is set
 - `workflow:invalid` label is set
 - `needs-human` label is set
+- `workflow:awaiting-merge` label is set (remediated + re-reviewed, awaiting a human merge decision — see #1810) <!-- Added: forge#1810 -->
 - `workflow:decomposed` label is set (sub-issues spawned)
 - Issue state is CLOSED with terminal label
 
@@ -216,7 +217,7 @@ fi
 Worktree/branch-already-exists and stale-label conditions are surfaced later (Phase 3E worktree creation and the `## Error Handling` section) with their own recovery guidance in `docs/site/troubleshooting.md`.
 
 ### 0A: Parse input
-Extract project prefix and issue number. If `next`/`pick`: list open issues sorted by priority, skip `needs-human` and `workflow:decomposed`, pick highest priority.
+Extract project prefix and issue number. If `next`/`pick`: list open issues sorted by priority, skip `needs-human`, `workflow:decomposed`, and `workflow:awaiting-merge`, pick highest priority.
 
 **Optional pre-flight**: Before committing to the full pipeline, run `/scope {NUMBER}` to get a complexity estimate (affected files, blast radius, risk flags, and decomposition recommendation). Especially useful for large or ambiguous issues.
 
@@ -234,7 +235,7 @@ gh issue comment {NUMBER} {GH_FLAG} --body "<!-- FORGE:HEARTBEAT -->
 
 **Also post at major phase entry points** (Phases 1, 3, and 5) — replace `Phase 0` with the correct phase name in each case. These mid-pipeline heartbeats ensure the stall detector sees recent activity during long phases (e.g., a build phase running for 20 minutes is not falsely classified as stalled). Inline snippets are embedded at Phase 1A, Phase 3A, and Phase 5A — agents resuming mid-pipeline encounter them without reading this section. <!-- Added: forge#740 -->
 
-**Skip if**: Issue already has a terminal label (`workflow:merged`, `workflow:invalid`, `needs-human`) — no heartbeat needed on a completed issue.
+**Skip if**: Issue already has a terminal label (`workflow:merged`, `workflow:invalid`, `needs-human`, `workflow:awaiting-merge`) — no heartbeat needed on a completed issue.
 
 ### 0B: Load issue + existing context
 ```bash
@@ -242,7 +243,7 @@ gh issue view {NUMBER} {GH_FLAG} --json number,title,body,labels,state,comments,
 gh api repos/{GH_REPO}/issues/{NUMBER}/comments --jq '.[] | {id: .id, author: .user.login, body: .body}'
 ```
 
-**Check**: state (closed → STOP), terminal labels (`workflow:merged`/`workflow:invalid` → STOP), existing agent comments (`FORGE:INVESTIGATOR`, `FORGE:DECOMPOSED`, `FORGE:CONTRACT`, `FORGE:BUILDER`, `FORGE:TRAJECTORY`, `FORGE:DECISION_RECORD`), parent tracker status, sub-issue status.
+**Check**: state (closed → STOP), terminal labels (`workflow:merged`/`workflow:invalid`/`workflow:awaiting-merge` → STOP), existing agent comments (`FORGE:INVESTIGATOR`, `FORGE:DECOMPOSED`, `FORGE:CONTRACT`, `FORGE:BUILDER`, `FORGE:TRAJECTORY`, `FORGE:DECISION_RECORD`), parent tracker status, sub-issue status.
 
 **Determine resume point**: No comments → Phase 1. Investigation exists + ready-to-build → Phase 3. Builder:COMPLETE + no PR → Phase 4. Builder without :COMPLETE (partial/interrupted build) + no PR → Phase 3 (partial-build cleanup). Builder + PR open → Phase 5. PR merged + issue open → Phase 6.
 
@@ -471,12 +472,12 @@ case "$TIER" in
   adaptive|universal) bash "$SCRIPT_PATH" {NUMBER} {GH_FLAG} investigating ;;
   prose)
     gh issue edit {NUMBER} {GH_FLAG} --add-label "workflow:investigating" \
-      --remove-label "workflow:ready-to-build,workflow:building,workflow:in-review,workflow:merged,workflow:invalid,workflow:decomposed" 2>/dev/null || true
+      --remove-label "workflow:ready-to-build,workflow:building,workflow:in-review,workflow:awaiting-merge,workflow:merged,workflow:invalid,workflow:decomposed" 2>/dev/null || true
     ;;
 esac
 ```
 
-**Post Phase 1 heartbeat** (skip if issue already has a terminal label — `workflow:merged`, `workflow:invalid`, `needs-human`):
+**Post Phase 1 heartbeat** (skip if issue already has a terminal label — `workflow:merged`, `workflow:invalid`, `needs-human`, `workflow:awaiting-merge`):
 ```bash
 PHASE_START_TIMESTAMP=$(date -u +%Y-%m-%dT%H:%M:%SZ)
 gh issue comment {NUMBER} {GH_FLAG} --body "<!-- FORGE:HEARTBEAT -->
@@ -748,7 +749,7 @@ case "$TIER" in
   adaptive|universal) bash "$SCRIPT_PATH" {NUMBER} {GH_FLAG} ready-to-build ;;
   prose)
     gh issue edit {NUMBER} {GH_FLAG} --add-label "workflow:ready-to-build" \
-      --remove-label "workflow:investigating,workflow:building,workflow:in-review,workflow:merged,workflow:invalid,workflow:decomposed" 2>/dev/null || true
+      --remove-label "workflow:investigating,workflow:building,workflow:in-review,workflow:awaiting-merge,workflow:merged,workflow:invalid,workflow:decomposed" 2>/dev/null || true
     ;;
 esac
 ```
@@ -797,7 +798,7 @@ case "$TIER" in
   adaptive|universal) bash "$SCRIPT_PATH" {NUMBER} {GH_FLAG} decomposed ;;
   prose)
     gh issue edit {NUMBER} {GH_FLAG} --add-label "workflow:decomposed" \
-      --remove-label "workflow:investigating,workflow:ready-to-build,workflow:building,workflow:in-review,workflow:merged,workflow:invalid" 2>/dev/null || true
+      --remove-label "workflow:investigating,workflow:ready-to-build,workflow:building,workflow:in-review,workflow:awaiting-merge,workflow:merged,workflow:invalid" 2>/dev/null || true
     ;;
 esac
 ```
@@ -821,7 +822,7 @@ case "$TIER" in
   adaptive|universal) bash "$SCRIPT_PATH" {NUMBER} {GH_FLAG} invalid ;;
   prose)
     gh issue edit {NUMBER} {GH_FLAG} --add-label "workflow:invalid" \
-      --remove-label "workflow:investigating,workflow:ready-to-build,workflow:building,workflow:in-review,workflow:merged,workflow:decomposed" 2>/dev/null || true
+      --remove-label "workflow:investigating,workflow:ready-to-build,workflow:building,workflow:in-review,workflow:awaiting-merge,workflow:merged,workflow:decomposed" 2>/dev/null || true
     ;;
 esac
 gh issue close {NUMBER} {GH_FLAG} --comment "Closing as invalid: {reason from investigation}"
@@ -927,7 +928,7 @@ case "$TIER" in
   adaptive|universal) bash "$SCRIPT_PATH" {NUMBER} {GH_FLAG} decomposed ;;
   prose)
     gh issue edit {NUMBER} {GH_FLAG} --add-label "workflow:decomposed" \
-      --remove-label "workflow:investigating,workflow:ready-to-build,workflow:building,workflow:in-review,workflow:merged,workflow:invalid" 2>/dev/null || true
+      --remove-label "workflow:investigating,workflow:ready-to-build,workflow:building,workflow:in-review,workflow:awaiting-merge,workflow:merged,workflow:invalid" 2>/dev/null || true
     ;;
 esac
 ```
@@ -958,7 +959,7 @@ fi
 
 ### 3A: Re-read state from GitHub (MANDATORY)
 
-**Post Phase 3 heartbeat** (skip if issue already has a terminal label — `workflow:merged`, `workflow:invalid`, `needs-human`):
+**Post Phase 3 heartbeat** (skip if issue already has a terminal label — `workflow:merged`, `workflow:invalid`, `needs-human`, `workflow:awaiting-merge`):
 ```bash
 PHASE_START_TIMESTAMP=$(date -u +%Y-%m-%dT%H:%M:%SZ)
 gh issue comment {NUMBER} {GH_FLAG} --body "<!-- FORGE:HEARTBEAT -->
@@ -1262,7 +1263,7 @@ case "$TIER" in
   adaptive|universal) bash "$SCRIPT_PATH" {NUMBER} {GH_FLAG} building ;;
   prose)
     gh issue edit {NUMBER} {GH_FLAG} --add-label "workflow:building" \
-      --remove-label "workflow:investigating,workflow:ready-to-build,workflow:in-review,workflow:merged,workflow:invalid,workflow:decomposed" 2>/dev/null || true
+      --remove-label "workflow:investigating,workflow:ready-to-build,workflow:in-review,workflow:awaiting-merge,workflow:merged,workflow:invalid,workflow:decomposed" 2>/dev/null || true
     ;;
 esac
 ```
@@ -1768,7 +1769,7 @@ case "$TIER" in
   adaptive|universal) bash "$SCRIPT_PATH" {NUMBER} {GH_FLAG} in-review ;;
   prose)
     gh issue edit {NUMBER} {GH_FLAG} --add-label "workflow:in-review" \
-      --remove-label "workflow:investigating,workflow:ready-to-build,workflow:building,workflow:merged,workflow:invalid,workflow:decomposed" 2>/dev/null || true
+      --remove-label "workflow:investigating,workflow:ready-to-build,workflow:building,workflow:awaiting-merge,workflow:merged,workflow:invalid,workflow:decomposed" 2>/dev/null || true
     ;;
 esac
 ```
@@ -1779,7 +1780,7 @@ esac
 
 ### 5A: Re-read state from GitHub (MANDATORY)
 
-**Post Phase 5 heartbeat** (skip if issue already has a terminal label — `workflow:merged`, `workflow:invalid`, `needs-human`):
+**Post Phase 5 heartbeat** (skip if issue already has a terminal label — `workflow:merged`, `workflow:invalid`, `needs-human`, `workflow:awaiting-merge`):
 ```bash
 PHASE_START_TIMESTAMP=$(date -u +%Y-%m-%dT%H:%M:%SZ)
 gh issue comment {NUMBER} {GH_FLAG} --body "<!-- FORGE:HEARTBEAT -->
@@ -1924,7 +1925,7 @@ case "$TIER" in
   adaptive|universal) bash "$SCRIPT_PATH" {NUMBER} {GH_FLAG} merged ;;
   prose)
     gh issue edit {NUMBER} {GH_FLAG} --add-label "workflow:merged" \
-      --remove-label "workflow:investigating,workflow:ready-to-build,workflow:building,workflow:in-review,workflow:invalid,workflow:decomposed" 2>/dev/null || true
+      --remove-label "workflow:investigating,workflow:ready-to-build,workflow:building,workflow:in-review,workflow:awaiting-merge,workflow:invalid,workflow:decomposed" 2>/dev/null || true
     ;;
 esac
 ```

package/docs/FORGE-PROTOCOL.md

@@ -13,3 +13,104 @@
 > and usable in any product with attribution. This older draft was mistakenly
 > marked AGPL-3.0; the protocol description itself has always been intended for
 > open, license-compatible adoption.
+
+---
+
+## Forge Ledger — Derived Artifact of the Protocol
+
+The **Forge Ledger** is the persistent, file/symbol-keyed knowledge index built from FORGE
+annotations. It is a _derived artifact_ of the protocol: the ledger is rebuilt by re-parsing
+the annotation corpus on GitHub (source of truth), not by maintaining separate authoritative
+state.
+
+### Architecture
+
+```
+GitHub Issues/PRs (annotation corpus, source of truth)
+          │
+          ▼
+scripts/build-knowledge-index.mjs   ← incremental indexer (watermarked by issue.updated_at)
+          │   uses packages/protocol/src/parse.js (FORGE annotation parser)
+          ▼
+~/.forge/index/
+  knowledge.jsonl    ← card records (one JSON per line, keyed by issue/kind/seq)
+  postings.json      ← BM25-lite inverted index (term → card IDs with per-field tf)
+  manifest.json      ← issue → content-hash map + watermark + card count
+  renames.jsonl      ← git rename log (old path → new path for query-time resolution)
+          │
+          ▼ (mirrored to orphan branch)
+forge-knowledge branch  ← versioned, diffable, hydratable by any clone or CI
+```
+
+### Card Schema
+
+Cards are keyed by provenance (`{issue}/{kind}/{seq}`), never by file path. Paths are
+attributes maintained by the indexer; renames are metadata updates, not re-keys.
+
+```json
+{
+  "schemaVersion": 1,
+  "id": "1370/pattern/0",
+  "kind": "pattern",
+  "issue": 1370,
+  "pattern": "...",
+  "rootCause": "...",
+  "prevention": "...",
+  "paths": ["bin/runner.mjs"],
+  "symbols": ["scrubEnv"],
+  "anchor": { "path": "bin/runner.mjs", "symbol": "scrubEnv" },
+  "status": "fresh",
+  "createdAt": "2026-07-04"
+}
+```
+
+### CLI
+
+```
+# Query by file path (exact lookup):
+forge recall --file bin/runner.mjs --json
+
+# Query by symbol:
+forge recall --symbol scrubEnv --json
+
+# Free-text BM25 search:
+forge recall "env scrub proc environ" --k 5
+
+# Index health:
+forge recall --doctor
+
+# Rebuild index from scratch:
+node scripts/build-knowledge-index.mjs --full-rebuild
+
+# Incremental update (used by close phase):
+node scripts/build-knowledge-index.mjs --issue {NUMBER}
+```
+
+### Invariants
+
+- **Full rebuild = incremental parity**: running a full rebuild produces byte-identical
+  card content to a sequence of incremental runs over the same issue range.
+- **Idempotency**: re-indexing the same issue twice produces the same card content (card IDs
+  are deterministic; content is a pure function of current annotation state).
+- **GitHub wins**: the index is always rebuildable from the annotation corpus alone. Deleting
+  `~/.forge/index/` loses nothing — a rebuild restores the same state.
+- **Non-blocking**: ledger indexing at close time never stalls the pipeline. Failure is logged
+  and the close phase continues.
+
+### Staleness Detection (tiered, cheapest first)
+
+1. Current blob sha of `anchor.path` matches stored blob sha → **FRESH**
+2. `anchor.symbol` is still defined in the current file → **FRESH**
+3. Rolling-hash scan finds `snippetHash` elsewhere in file → **MOVED** (re-anchor)
+4. `snippetHash` found in a file touched by rename log → **MOVED** (re-anchor path)
+5. Otherwise → **STALE** (excluded from binding injection; recallable with `--include-stale`)
+
+### Integration Points
+
+- **`commands/work-on/build/context.md` Phase C1**: uses `forge recall --file` for exact
+  file-path lookup; falls back to live `gh issue list --search` when index is absent.
+- **`commands/work-on/close.md` Phase C5.3**: calls `build-knowledge-index.mjs --issue`
+  after merge to index the just-closed issue; advances watermark.
+
+See issue [#1732](https://github.com/RapierCraftStudios/ForgeDock/issues/1732) for the
+implementation history and design decisions.

package/docs/design/awesome-list-submissions.md

@@ -0,0 +1,105 @@
+# Awesome List Submission Drafts
+
+Important: Have a contributor or community member submit these, not the repo owner's account. Many lists reject self-submissions.
+
+---
+
+## 1. hesreallyhim/awesome-claude-code (36.8K stars) — TOP PRIORITY
+
+### PR Title
+```
+Add ForgeDock — autonomous pipeline commands for Claude Code
+```
+
+### Entry (add under "Workflow & Automation" or "Agent Frameworks" section)
+
+```markdown
+- [ForgeDock](https://github.com/RapierCraftStudios/ForgeDock) - Structured autonomous development pipeline that adds investigate-build-review-merge workflow to Claude Code. Features 9-agent specialist PR review, 14-domain quality gate, and GitHub-native persistent memory via FORGE annotations. `npx forgedock`
+```
+
+### PR Description
+
+```markdown
+Adding ForgeDock, an open-source (AGPL) tool that adds structured pipeline commands to Claude Code.
+
+**What it does**: Turns Claude Code from a stateless chatbot into a multi-stage development pipeline. Each stage (investigate, build, review, merge) posts machine-readable annotations to GitHub issues/PRs, so agents reconstruct full context after compaction.
+
+**Key features**:
+- 20+ slash commands including `/work-on` (full pipeline), `/orchestrate` (parallel multi-issue), `/autopilot` (self-improvement cycle)
+- 9-agent specialist PR review (security, database, auth, concurrency, etc.)
+- 14-domain quality gate
+- GitHub labels as workflow state machine
+- `forge.yaml` per-repo configuration
+
+**Install**: `npx forgedock`
+
+**Why it belongs here**: It's the most comprehensive pipeline orchestration system in the Claude Code ecosystem — 35 command files totaling 800KB+ of structured prompt engineering.
+```
+
+---
+
+## 2. rohitg00/awesome-claude-code-toolkit
+
+### Entry
+
+```markdown
+### Pipeline Orchestration
+- [ForgeDock](https://github.com/RapierCraftStudios/ForgeDock) - Full SDLC pipeline for Claude Code: investigate → build → review → merge. 9-agent review, quality gate, GitHub-native memory via FORGE annotations. `npx forgedock`
+```
+
+---
+
+## 3. travisvn/awesome-claude-skills
+
+### Entry
+
+```markdown
+- [ForgeDock](https://github.com/RapierCraftStudios/ForgeDock) - 20+ pipeline commands: `/work-on` (full pipeline), `/orchestrate` (parallel issues), `/review-pr` (9-agent review), `/autopilot` (self-improvement), `/quality-gate` (14-domain checks). Uses GitHub as persistent knowledge graph.
+```
+
+---
+
+## 4. ComposioHQ/awesome-claude-skills
+
+### Entry
+
+```markdown
+- [ForgeDock](https://github.com/RapierCraftStudios/ForgeDock) - Autonomous development pipeline commands for Claude Code. Structured investigate-build-review-merge workflow with GitHub-native memory, multi-agent review, and quality gates.
+```
+
+---
+
+## 5. VoltAgent/awesome-agent-skills
+
+### Entry
+
+```markdown
+- [ForgeDock](https://github.com/RapierCraftStudios/ForgeDock) - Structured autonomous dev pipeline for Claude Code agents. Uses GitHub Issues/PRs as a knowledge graph with machine-readable FORGE annotations for inter-agent context passing. 35 command specs covering the full SDLC.
+```
+
+---
+
+## 6. Broader awesome lists
+
+### awesome-ai-agents
+
+```markdown
+- [ForgeDock](https://github.com/RapierCraftStudios/ForgeDock) - Open-source pipeline orchestrator for AI coding agents. Structures investigate → build → review → merge workflow using GitHub as a persistent knowledge graph. Currently supports Claude Code; multi-model planned.
+```
+
+### awesome-developer-tools
+
+```markdown
+- [ForgeDock](https://github.com/RapierCraftStudios/ForgeDock) - Autonomous development pipeline that adds structured workflow commands to Claude Code. 9-agent PR review, 14-domain quality gate, GitHub-native memory. `npx forgedock`
+```
+
+---
+
+## Submission Checklist
+
+- [ ] Check each list's CONTRIBUTING.md for formatting requirements
+- [ ] Ensure the entry follows the list's existing style (alphabetical? categorized?)
+- [ ] One PR per list
+- [ ] Submitter should have some GitHub activity (not a brand new account)
+- [ ] Don't submit all on the same day — space them out over 1-2 weeks
+- [ ] Priority order: awesome-claude-code first, then toolkit, then skills lists, then broader lists

package/docs/design/f5bot-monitoring-setup.md

@@ -0,0 +1,43 @@
+# F5Bot Mention Monitoring Setup
+
+F5Bot is a free service that sends email alerts when keywords appear on Reddit, Hacker News, or Lobsters.
+
+## Setup (5 minutes)
+
+1. Go to https://f5bot.com
+2. Create a free account (email only)
+3. Add these keyword alerts:
+
+| Keyword | Why |
+|---------|-----|
+| `forgedock` | Direct mentions |
+| `ForgeDock` | Case-sensitive variant |
+| `forge dock` | Common misspelling |
+| `"claude code commands"` | Users looking for what ForgeDock provides |
+| `"claude code workflow"` | High-intent search phrase |
+| `"autonomous development pipeline"` | Category-level interest |
+| `"FORGE annotation"` | Protocol mentions |
+
+4. Set email notifications to immediate (not digest)
+
+## Response Playbook
+
+When an alert fires:
+
+### Direct mention (someone talking about ForgeDock)
+- Read the full thread context
+- If positive: thank them, offer to help with any questions
+- If a question: answer thoroughly with code examples
+- If criticism: acknowledge, explain the reasoning, ask what they'd improve
+
+### Indirect mention (someone looking for what ForgeDock does)
+- Answer their question genuinely first
+- Mention ForgeDock naturally: "I've been using ForgeDock for this — it structures Claude Code into an investigate-build-review-merge pipeline"
+- Never just drop a link with no context
+
+### Rules
+- Always add genuine value to the conversation
+- Never post in threads where it would feel forced
+- On Reddit: post manually (never automate — ban risk)
+- On HN: only comment if you have genuine insight to add
+- Wait at least 10 minutes after the alert before responding (don't look like a bot)