forgedock 1.0.21 → 1.1.1

package/bin/settings-hook.mjs

@@ -0,0 +1,112 @@
+/**
+ * bin/settings-hook.mjs — Idempotent SessionStart hook registration in
+ * ~/.claude/settings.json.
+ *
+ * Contract (spec: "Hook wiring"):
+ *   - Read-modify-write; unrelated keys and hooks preserved verbatim
+ *   - Our entry identified by HOOK_MARKER in its command string
+ *   - Malformed JSON → skip and report, NEVER overwrite the file
+ *   - Absolute hook script path baked in at install time
+ */
+
+import { existsSync, readFileSync, writeFileSync, renameSync, mkdirSync } from "fs";
+import { dirname } from "path";
+
+/** Substring identifying ForgeDock's own hook entry. */
+export const HOOK_MARKER = "session-start.mjs";
+
+function isOurs(entry) {
+  return JSON.stringify(entry).includes(HOOK_MARKER);
+}
+
+function readSettings(settingsPath) {
+  if (!existsSync(settingsPath)) return { settings: {}, fresh: true };
+  try {
+    const parsed = JSON.parse(readFileSync(settingsPath, "utf-8"));
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return null;
+    return { settings: parsed, fresh: false };
+  } catch {
+    return null; // malformed — caller must not write
+  }
+}
+
+function writeSettings(settingsPath, settings) {
+  mkdirSync(dirname(settingsPath), { recursive: true });
+  const tmp = settingsPath + ".tmp";
+  writeFileSync(tmp, JSON.stringify(settings, null, 2) + "\n", "utf-8");
+  renameSync(tmp, settingsPath);
+}
+
+/**
+ * Merge ForgeDock's SessionStart hook into settings.json.
+ * @param {string} settingsPath - Absolute path to ~/.claude/settings.json
+ * @param {string} hookScriptPath - Absolute path to bin/hooks/session-start.mjs
+ * @returns {{ status: 'installed'|'already'|'skipped-malformed' }}
+ */
+export function installSessionStartHook(settingsPath, hookScriptPath) {
+  const read = readSettings(settingsPath);
+  if (read === null) return { status: "skipped-malformed" };
+  const { settings } = read;
+
+  // Validate hooks shape: must be a plain object (not array, string, etc.)
+  if (settings.hooks !== undefined && settings.hooks !== null) {
+    if (Array.isArray(settings.hooks) || typeof settings.hooks !== "object") {
+      return { status: "skipped-malformed" };
+    }
+    // Validate SessionStart if present: must be an array
+    if (settings.hooks.SessionStart !== undefined && !Array.isArray(settings.hooks.SessionStart)) {
+      return { status: "skipped-malformed" };
+    }
+  } else {
+    // hooks missing or null → initialize to fresh object
+    settings.hooks = {};
+  }
+
+  const list = Array.isArray(settings.hooks.SessionStart) ? settings.hooks.SessionStart : [];
+  if (list.some(isOurs)) return { status: "already" };
+
+  list.push({
+    hooks: [
+      {
+        type: "command",
+        command: `node "${hookScriptPath}"`,
+      },
+    ],
+  });
+  settings.hooks.SessionStart = list;
+  writeSettings(settingsPath, settings);
+  return { status: "installed" };
+}
+
+/**
+ * Remove ForgeDock's SessionStart hook entry; leaves everything else alone.
+ * @returns {{ status: 'removed'|'absent'|'skipped-malformed' }}
+ */
+export function removeSessionStartHook(settingsPath) {
+  const read = readSettings(settingsPath);
+  if (read === null) return { status: "skipped-malformed" };
+  const { settings, fresh } = read;
+  if (fresh) return { status: "absent" };
+
+  // Validate hooks shape: must be a plain object (not array, string, etc.)
+  if (settings.hooks !== undefined && settings.hooks !== null) {
+    if (Array.isArray(settings.hooks) || typeof settings.hooks !== "object") {
+      return { status: "skipped-malformed" };
+    }
+  }
+
+  // Validate SessionStart shape if present: must be an array
+  if (settings.hooks && settings.hooks.SessionStart !== undefined && !Array.isArray(settings.hooks.SessionStart)) {
+    return { status: "skipped-malformed" };
+  }
+
+  const list = settings.hooks && Array.isArray(settings.hooks.SessionStart)
+    ? settings.hooks.SessionStart
+    : [];
+  const kept = list.filter((e) => !isOurs(e));
+  if (kept.length === list.length) return { status: "absent" };
+
+  settings.hooks.SessionStart = kept;
+  writeSettings(settingsPath, settings);
+  return { status: "removed" };
+}

package/bin/tui.mjs

@@ -837,7 +837,7 @@ const REVIEW_FIELDS = [
  */
 export async function annotatedReviewScreen(
   draft,
-  { hasExistingConfig = false, existingContent = "", showSources = false } = {},
+  { hasExistingConfig = false, existingContent = "", showSources = false, extraFields = {} } = {},
 ) {
   // Helper — pull a field from the draft by path, or return a low-confidence placeholder.
   function getField(draftPath) {
@@ -862,7 +862,10 @@ export async function annotatedReviewScreen(
   const whys = {};
 
   for (const fd of REVIEW_FIELDS) {
-    const field = getField(fd.draftPath);
+    const field =
+      fd.draftPath === null && extraFields[fd.key]
+        ? extraFields[fd.key]
+        : getField(fd.draftPath);
     values[fd.key] = field.value;
     confidences[fd.key] = field.confidence;
     sources[fd.key] = field.source;
@@ -987,7 +990,7 @@ export async function annotatedReviewScreen(
     }
 
     process.stdout.write(
-      `  ${dim("Press")} ${bold("Enter")} ${dim("to accept all values, or enter a field number to edit it.")}\n\n`,
+      `  ${dim("Press")} ${bold("Enter")} ${dim("to forge, or a number to edit a field")}\n\n`,
     );
   }
 

package/commands/autopilot.md

@@ -10,7 +10,7 @@ argument-hint: [--fix | --recon-only | --fix --limit 5 | --dry-run]
 **Config variables used by this command** (set in `forge.yaml`):
 - `{CREDENTIALS_FILE}` ← `paths.credentials.file` (optional) — path to credentials YAML for analytics APIs
 - `{SERVER_SSH}` ← `services.server_ssh` (optional) — SSH target for production server health checks (e.g., `ubuntu@1.2.3.4`)
-- `{EMEMO_PATH}` ← `services.ememo_path` (optional) — path on production server to open eMemo files
+- `{OPS_INBOX_PATH}` ← `services.ops_inbox_path` (optional) — path on production server to a directory of open work-item files (e.g. `/srv/ops/inbox`)
 - `{BILLING_ENABLED}` ← `billing.enabled` (optional, default `false`) — set to `true` to enable Stripe data collection in the Analytics Snapshot agent
 
 Resolve `{BILLING_ENABLED}` from `forge.yaml` before executing any phase:
@@ -112,7 +112,7 @@ Spawn these as **background agents** (all `run_in_background=true`, all `model="
 **Agent: Production Health**
 ```
 Check production system health:
-1. SSH to check for open eMemos: if {SERVER_SSH} is configured, run: ssh {SERVER_SSH} "ls {EMEMO_PATH}/*-open-* 2>/dev/null" — skip this step if SERVER_SSH or EMEMO_PATH is not set in forge.yaml
+1. SSH to check for open ops-inbox items: if {SERVER_SSH} is configured, run: ssh {SERVER_SSH} "ls {OPS_INBOX_PATH}/*-open-* 2>/dev/null" — skip this step if SERVER_SSH or OPS_INBOX_PATH is not set in forge.yaml
 2. If any exist, cat each one and summarize
 3. Check container health via MCP: get_production_status, run_production_health_check
 4. Check recent error logs: get_production_logs for api and worker (last 100 lines), grep for ERROR/CRITICAL
@@ -197,7 +197,7 @@ For each finding from RECON_DATA, assign:
 
 | Signal | Priority | Type |
 |--------|----------|------|
-| Production eMemo (open) | P1 | bug |
+| Open ops-inbox item | P1 | bug |
 | Container unhealthy | P0 | bug |
 | Error spike (>5x normal) | P1 | bug |
 | Tier degradation (>20% drop) | P2 | bug |
@@ -286,7 +286,7 @@ Print a structured report:
 
 ### Production Health
 - Containers: {all healthy / N unhealthy}
-- Open eMemos: {count}
+- Open ops-inbox items: {count}
 - Error patterns: {summary or "none"}
 
 ### Scraping Performance

package/commands/cleanup.md

@@ -47,7 +47,7 @@ All `{GH_REPO}`, `{GH_FLAG}`, `{REPO_PATH}`, `{STAGING_BRANCH}`, `{PROJECT_BOARD
 | `labels` or empty | Fix stale/missing workflow labels on closed issues |
 | `orphans` | Close open issues whose PRs are already merged |
 | `branches` | Prune worktrees and remote branches for merged PRs |
-| `milestones` | Close milestones with 0 open issues |
+| `milestones` | Report milestones with 0 open issues (advisory — never closes) |
 | `board` | Sync closed issues to Project board with correct terminal state |
 | `all` | All of the above, in order |
 
@@ -172,58 +172,109 @@ echo "Removed: $WORKTREE_PATH ($BRANCH_NAME)"
 
 ### 3C: Prune merged remote branches
 
-Delete remote `fix/` and `feat/` branches that are fully merged into `{STAGING_BRANCH}`:
+Delete remote `fix/` and `feat/` branches whose PR has merged — using **GitHub PR state as the source of truth**, not local git ancestry.
+
+**Why not `git branch -r --merged {STAGING_BRANCH}`**: an ancestry check only catches branches whose tip commit is reachable from `{STAGING_BRANCH}`. This misses two common cases:
+- **Feature-lane branches merged into a milestone branch.** Per `work-on.md` Phase 3E, milestone issues branch from and PR into `origin/milestone/{slug}`, not `{STAGING_BRANCH}`. Once such a branch's own PR merges into the milestone branch, it's fully absorbed and safe to delete — but it won't show up as "merged into staging" until the milestone itself ships (which may be days later, or never, if abandoned). This is the dominant cause of `feat/*` branches accumulating for a milestone/feature cluster.
+- **Squash merges.** If a branch was merged via squash (manual UI merge, or org/branch-protection settings that force squash-only), the resulting commit is a brand-new SHA that is never an ancestor of the original branch — so ancestry-based detection never matches it, even though the PR is clearly `MERGED` on GitHub.
+
+Both gaps disappear when merged-PR head-refs (regardless of base branch or merge strategy) are used directly as the deletion set:
+
+**Why also check `headRefOid`**: branch names are freely reusable in git. A name-only match cannot distinguish "this branch's current tip is the commit that merged" from "a branch with this name merged at some point in the past and has since been reused for new, unmerged work" (e.g. a second issue happens to slugify to the same `fix/*`/`feat/*` name). Comparing the branch's live remote tip SHA against the merged PR's `headRefOid` closes that gap — deletion only proceeds when the (name, SHA) pair matches a merged PR exactly, regardless of base branch or merge strategy.
+
+**Why `--force-with-lease` on the delete**: the `CURRENT_SHA` snapshot above is read from the local `origin/$branch` ref as of the `git fetch --prune` at the top of this phase. For large batches this loop can run for a while (one network call per branch), so a new commit can land on the remote branch between the fetch and that branch's turn in the loop — a TOCTOU window. A plain `git push origin --delete "$branch"` is unconditional: it deletes whatever the remote ref currently points to, even if that's no longer `$CURRENT_SHA`. Using `--force-with-lease=refs/heads/$branch:$CURRENT_SHA` makes the deletion a server-verified compare-and-swap — the remote rejects the update if `refs/heads/$branch` has moved since the snapshot, instead of silently deleting new work.
 
 ```bash
 cd {REPO_PATH}
 git fetch --prune origin
 
-# Count first
-MERGED_COUNT=$(git branch -r --merged origin/{STAGING_BRANCH} | grep -E "origin/(fix|feat)/" | wc -l)
-echo "Found $MERGED_COUNT merged remote branches to delete"
+# All remote fix/* and feat/* branches currently on origin
+REMOTE_BRANCHES=$(git branch -r | grep -E "origin/(fix|feat)/" | sed 's|origin/||' | tr -d ' ')
+
+# Head-ref name + head-ref SHA of every merged PR, regardless of base branch (staging,
+# milestone/*, main) or merge strategy (merge-commit vs. squash) — this is GitHub's own
+# merge bookkeeping, not local ref topology, so it's immune to both gaps above.
+# headRefOid is captured alongside headRefName so deletion can be gated on the branch's
+# CURRENT tip matching the commit that actually merged, not just a name match.
+# --limit is set high to avoid silent truncation; repos with more historical merged PRs
+# than this should re-run `/cleanup branches` incrementally to catch the remainder.
+MERGED_HEADS=$(gh pr list {GH_FLAG} --state merged --limit 1000 --json headRefName,headRefOid --jq '.[] | "\(.headRefName)\t\(.headRefOid)"')
+
+DELETE_COUNT=0
+SKIP_COUNT=0
+RACE_SKIP_COUNT=0
+for branch in $REMOTE_BRANCHES; do
+  CURRENT_SHA=$(git rev-parse "origin/$branch" 2>/dev/null)
+  if printf '%s\n' "$MERGED_HEADS" | grep -qxF "$(printf '%s\t%s' "$branch" "$CURRENT_SHA")"; then
+    # Name AND tip SHA match a merged PR's head-ref — safe to delete.
+    # Use --force-with-lease as a server-side compare-and-swap: the remote re-verifies
+    # refs/heads/$branch is still at $CURRENT_SHA at push time, closing the TOCTOU gap
+    # between this snapshot and the actual delete (see note above).
+    if git push origin --force-with-lease="refs/heads/$branch:$CURRENT_SHA" ":refs/heads/$branch" 2>&1; then
+      DELETE_COUNT=$((DELETE_COUNT + 1))
+      # Log the pre-deletion SHA so it's visible in run output/logs for recovery —
+      # see "Recovery: restoring an accidentally pruned branch" below.
+      echo "Deleted origin/$branch (was $CURRENT_SHA) — restorable via: git push origin $CURRENT_SHA:refs/heads/$branch"
+    else
+      # Lease rejected — the branch's remote tip moved since the snapshot (a new push
+      # landed mid-loop). Do NOT retry/force past this: skip and let the next cleanup
+      # run re-evaluate it against fresh state.
+      RACE_SKIP_COUNT=$((RACE_SKIP_COUNT + 1))
+      echo "RACE: origin/$branch tip changed since snapshot ($CURRENT_SHA) — lease rejected, not deleting. Will re-evaluate on next /cleanup run."
+    fi
+  elif printf '%s\n' "$MERGED_HEADS" | cut -f1 | grep -qxF "$branch"; then
+    # Name matches a merged PR's head-ref, but the branch's current tip does not match
+    # any merged commit recorded under that name — likely a reused branch name holding
+    # new, unmerged work. Skip deletion rather than risk destroying live commits.
+    SKIP_COUNT=$((SKIP_COUNT + 1))
+    echo "SKIP: origin/$branch name matches a merged PR head-ref but current tip ($CURRENT_SHA) does not match the merged commit — branch name likely reused for new work. Not deleting."
+  fi
+done
+echo "Deleted $DELETE_COUNT merged remote branches, skipped $SKIP_COUNT name-matched/SHA-mismatched branches, skipped $RACE_SKIP_COUNT raced branches (tip changed between snapshot and delete) (source of truth: gh pr list --state merged, verified against headRefOid, deletion gated by --force-with-lease)"
+```
 
-# Delete them
-if [ "$MERGED_COUNT" -gt 0 ]; then
-  git branch -r --merged origin/{STAGING_BRANCH} | grep -E "origin/(fix|feat)/" | sed 's|origin/||' | xargs -I{} git push origin --delete {} 2>&1
-fi
+**Note**: This can take a while for large batches (1 network call per deleted branch, plus one batched `gh pr list` call). Run in background if > 20 branches.
+
+**One-time backfill for existing stale branches**: repos that adopted this fix after already accumulating stale `feat/*`/`fix/*` branches (e.g. from milestones that shipped long ago) should run `/cleanup branches` once manually — the PR-state query above will catch the full backlog in a single pass since it isn't scoped to "this batch" or "this session," it queries all merged PRs on the repo.
+
+**Recovery: restoring an accidentally pruned branch**
+
+Phase 3C only ever deletes a branch whose (name, SHA) pair matched a merged PR's `headRefOid`, so the exact deleted commit is always recoverable: its SHA is echoed in the run log above (`Deleted origin/$branch (was $CURRENT_SHA) ...`), and the commit object survives in the remote's object store until garbage collection (for merge-commit merges it also remains reachable from the PR's merge commit; for squash merges the original tip becomes a dangling commit — not reachable by ancestry, but still restorable by SHA for as long as it hasn't been GC'd). If a branch is pruned in error (or needs to be recreated for any reason), restore it with:
+
+```bash
+# Using the SHA logged at deletion time (or from `gh pr view {PR_NUMBER} --json headRefOid`
+# if the run log is no longer available):
+git push origin <sha>:refs/heads/<branch>
 ```
 
-**Note**: This can take a while for large batches (1 network call per branch). Run in background if > 20 branches.
+Alternatively, GitHub itself offers a one-click **"Restore branch"** button on the merged PR's page (shown on the "<branch> was deleted" banner) for a limited window after deletion — typically available for as long as the underlying ref data hasn't been garbage-collected, often a few weeks. This is the fastest option when working from the GitHub UI rather than a local clone.
+
+Both options only apply to branches deleted by this phase (or by GitHub's own merge/delete UI) — a SHA is not captured for branches removed by other means (e.g. manual `git push origin --delete` run outside of `/cleanup`), so recovery there depends on `git reflog` on a clone that still has the ref, or GitHub's audit log.
 
 ---
 
-## Phase 4: Milestone Hygiene
+## Phase 4: Milestone Hygiene (Advisory Only)
+
+**NEVER close milestones in this phase.** Milestones are only closed by `/milestone ship` (human-gated) or `/milestone close` (explicit abandonment). Incorrect closure destroys milestone state that cannot be trivially recovered. <!-- fix: forge#1160 -->
 
-### 4A: Find completed milestones
+### 4A: Find milestones with 0 open issues
 
 ```bash
 # List open milestones with 0 remaining issues
 gh api repos/:owner/:repo/milestones --jq '.[] | select(.state == "open" and .open_issues == 0) | "\(.number) | \(.title) | open:\(.open_issues) closed:\(.closed_issues)"'
 ```
 
-### 4B: Close completed milestones (shipping-verified only)
+### 4B: Report findings (DO NOT close)
 
-For each milestone with 0 open issues, verify the milestone branch has been merged to staging or main before closing:
+For each milestone with 0 open issues, report it as a candidate for shipping or closing — but take no action:
 
 ```bash
-# Derive slug from milestone title (lowercase, spaces→hyphens, strip non-alphanumeric except hyphens)
-SLUG=$(echo "$MILESTONE_TITLE" | tr '[:upper:]' '[:lower:]' | tr ' ' '-' | tr -cd 'a-z0-9-')
-
-# Check if milestone branch was merged to staging or main
-SHIPPED_STAGING=$(gh pr list --base staging --head "milestone/$SLUG" --state merged --json number --jq '.[0].number' 2>/dev/null)
-SHIPPED_MAIN=$(gh pr list --base main --head "milestone/$SLUG" --state merged --json number --jq '.[0].number' 2>/dev/null)
-
-if [ -n "$SHIPPED_STAGING" ] || [ -n "$SHIPPED_MAIN" ]; then
-  # Safe to close — code has been shipped to staging or main
-  gh api repos/:owner/:repo/milestones/$MILESTONE_NUMBER -X PATCH -f state=closed
-  echo "CLOSED milestone: $MILESTONE_TITLE (shipped via PR #${SHIPPED_STAGING:-$SHIPPED_MAIN})"
-else
-  # DO NOT close — code is only on the milestone branch, not yet shipped
-  echo "SKIPPED: $MILESTONE_TITLE — issues done but milestone branch not merged to staging or main"
-fi
+echo "ADVISORY: $MILESTONE_TITLE — 0 open issues, $CLOSED_ISSUES closed"
+echo "  → To ship: /milestone ship $SLUG"
+echo "  → To abandon: /milestone close $SLUG"
 ```
 
-**Exception**: Don't close milestones that are intentionally kept open for future work (check if the milestone description says "ongoing" or "rolling"). If unsure, **SKIP it** — milestones are only closed by `/milestone ship` after code reaches staging. Incorrect closure destroys milestone state that cannot be trivially recovered.
+Do NOT call `gh api ... -X PATCH -f state=closed` on any milestone. This phase is informational only.
 
 ---
 
@@ -281,15 +332,10 @@ fi
 | Local branches deleted | {N} |
 | Remote branches deleted | {N} |
 
-### Milestones Closed
-| Milestone | Issues (closed) | Shipped via |
-|-----------|-----------------|-------------|
-| {title} | {N} | PR #{M} → staging/main |
-
-### Milestones Skipped (unshipped)
-| Milestone | Issues (closed) | Reason |
-|-----------|-----------------|--------|
-| {title} | {N} | No merged PR from milestone/{slug} → staging or main |
+### Milestones Ready to Ship (advisory — no action taken)
+| Milestone | Issues (closed) | Recommended Action |
+|-----------|-----------------|-------------------|
+| {title} | {N} | `/milestone ship {slug}` or `/milestone close {slug}` |
 
 ### Board Synced
 | Action | Count |

package/commands/deploy-info.md

@@ -156,7 +156,7 @@ done
 # Full file diff summary
 git diff --stat origin/$TARGET..origin/$SOURCE
 
-# Read layout paths from forge.yaml, fall back to AlterLab defaults
+# Read layout paths from forge.yaml, fall back to forge.yaml defaults
 LAYOUT_API=$(yq '.review.layout.api // "services/api"' forge.yaml 2>/dev/null || echo "services/api")
 LAYOUT_WORKER=$(yq '.review.layout.worker // "services/worker"' forge.yaml 2>/dev/null || echo "services/worker")
 LAYOUT_PAGES=$(yq '.review.layout.pages // "web/src/app"' forge.yaml 2>/dev/null || echo "web/src/app")
@@ -189,10 +189,14 @@ if [ -n "$MIGRATIONS" ]; then
   echo "⚠️ DATABASE MIGRATIONS INCLUDED:"
   echo "$MIGRATIONS"
   # Show migration content for review
-  for m in $MIGRATIONS; do
+  # $MIGRATIONS is one path per line (`git diff --name-only`) — herestring,
+  # not a piped `| while read`, for consistency with the newline-safe pattern
+  # used elsewhere in this sweep.
+  while IFS= read -r m; do
+    [ -z "$m" ] && continue
     echo "--- $m ---"
     git show origin/$SOURCE:$m 2>/dev/null | head -30
-  done
+  done <<< "$MIGRATIONS"
 fi
 ```
 
@@ -227,8 +231,10 @@ if [ -n "$NEW_ENV" ]; then
   # If your project uses a different backend, skip this block and verify manually.
   if [ "{DEPLOY_SECRETS_BACKEND}" = "sops" ]; then
     for var in $(echo "$NEW_ENV" | grep -oE '^\+[A-Z_]+' | sed 's/^\+//'); do
-      if ! grep -q "$var" scripts/decrypt-secrets.sh 2>/dev/null; then
-        echo "  ❌ $var NOT in decrypt-secrets.sh ENV_MAPPING"
+      if [ -f "{REPO_PATH}/scripts/decrypt-secrets.sh" ]; then
+        grep -q "$var" "{REPO_PATH}/scripts/decrypt-secrets.sh" 2>/dev/null || echo "  ❌ $var NOT in decrypt-secrets.sh ENV_MAPPING"
+      else
+        echo "  ℹ️  scripts/decrypt-secrets.sh not found — skipping ENV_MAPPING cross-check for $var. Verify manually in your SOPS chain."
       fi
     done
   else

package/commands/design-bench.md

@@ -1,6 +1,7 @@
 ---
 description: Run the ABC benchmark — reference URL → design-blind brief → render arms A/B/C → blind judge → scorecard with win-rates over n runs
 argument-hint: [<brief-name>|all] [--n <runs>] [--corpus-version <ver>]
+install: internal
 ---
 <!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
 <!-- SPDX-License-Identifier: AGPL-3.0-or-later -->

package/commands/design-render-critique-loop.md

@@ -1,6 +1,7 @@
 ---
 description: Render a design from its FORGE:DESIGN_SPEC, critique the rendered pixels against the perceptual negatives, and iterate until it passes or the budget is spent — the missing reward signal.
 argument-hint: [<issue-number>|<spec-path>] [--max-iters <n>] [--viewports desktop,mobile]
+install: internal
 ---
 <!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
 <!-- SPDX-License-Identifier: AGPL-3.0-or-later -->

package/commands/design.md

@@ -1,6 +1,7 @@
 ---
 description: Route a design GitHub issue through the UI Taste Harness — investigate → architect → implement → critique loop → user-feedback loop → close — accumulating FORGE:DESIGN_* annotations and driving the design:* label state machine to design:shipped.
 argument-hint: <issue-number> | <brief-name>
+install: internal
 ---
 <!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
 <!-- SPDX-License-Identifier: AGPL-3.0-or-later -->

package/commands/forge-stats.md

@@ -1,6 +1,7 @@
 ---
 description: Track command sizes, detect bloat, compare against baselines and thresholds
 argument-hint: [diff | baseline | full]
+install: internal
 ---
 <!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
 <!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
@@ -129,7 +130,7 @@ for cmd in commands/*.md; do
 done
 
 git add .baselines
-git commit -m "stats: update command baselines — $(date +%Y-%m-%d)"
+git commit -s -m "stats: update command baselines — $(date +%Y-%m-%d)"
 ```
 
 ---

package/commands/issue.md

@@ -495,7 +495,7 @@ Create all {N} issues? (yes / adjust #N / cancel)
 
 | Bad Issue | Why It Fails | Good Version |
 |-----------|-------------|-------------|
-| "Fix docker mount" | Which compose file? Which mount? | "fix: `.gemini` volume mount in docker-compose.prod.yml missing rw flag" |
+| "Fix docker mount" | Which compose file? Which mount? | "fix: `logs` volume in docker-compose.yml missing `rw` flag — container writes fail at runtime" |
 | "Update billing" | What about billing? What's broken? | "fix: payment_processor.charge() raises ZeroDivisionError when amount == 0" |
 | "Investigate performance" | Investigate what? Where? | "investigate: API p95 latency doubled since last deploy — trace hot paths in job processing routers" |
 | No affected files listed | Investigator guesses wrong files | List every file with what needs to change |

package/commands/optimize.md

@@ -382,7 +382,7 @@ Then:
 --- Next steps ---
   1. Review generated scripts in .forgedock/scripts/
   2. Run each script manually to verify output
-  3. If correct: git add .forgedock/scripts/ && git commit -m "feat(scripts): adaptive scripts from /optimize"
+  3. If correct: git add .forgedock/scripts/ && git commit -s -m "feat(scripts): adaptive scripts from /optimize"
   4. If not: edit scripts directly or update forge.yaml → learned: and re-run /optimize
 ```