forgedock 1.0.22 → 1.1.2

package/commands/orchestrate/phase-5-cleanup.md

@@ -0,0 +1,47 @@
+---
+install: internal
+---
+<!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
+<!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
+
+# /orchestrate — Phase 5: Post-Batch Cleanup
+
+## Phase 5: Post-Batch Cleanup
+
+**This phase is MANDATORY after every orchestration batch.** It prevents the rot that accumulates when multiple agents merge PRs in parallel — stale labels, orphaned worktrees, unclosed issues.
+
+### Step 5A: Run cleanup sweep
+
+Invoke the `/cleanup` skill with `all` to sweep everything:
+
+```
+Skill(skill="cleanup", args="all")
+```
+
+This will:
+- Fix stale workflow labels on any issues the agents left behind
+- Close orphaned open issues whose PRs were merged (common when merging to `staging`)
+- Remove worktrees created by agents in this batch
+- Delete local/remote `fix/*` and `feat/*` branches whose PR has merged — detection uses merged-PR state (`gh pr list --state merged`) as the source of truth, so it covers feature-lane branches merged into a milestone branch as well as squash-merged branches, not just branches merged directly to staging
+- Report milestones that hit 0 open issues — these are ready for `/milestone ship` (staging review + merge). Do NOT close them; closure happens after code reaches staging.
+- Sync Project board state
+
+### Step 5B: Run agent audit
+
+Invoke `/audit-agents` on this session to measure pipeline efficiency:
+
+```
+Skill(skill="audit-agents", args="latest")
+```
+
+Include the audit summary in the final report (Phase 6). Key metrics to surface:
+- **Avg idle%** — percentage of time agents spent stalled vs working
+- **Resume cycles** — how many times agents had to be resumed
+- **Stall boundaries** — which phase transitions cause the most stalls
+
+### Step 5C: Report cleanup results
+
+Include the cleanup summary in the final report (Phase 6). If cleanup found problems, call them out — they indicate agent pipeline failures that may need investigation.
+
+---
+

package/commands/orchestrate/phase-6-report.md

@@ -0,0 +1,198 @@
+---
+install: internal
+---
+<!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
+<!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
+
+# /orchestrate — Phase 6: Consolidated Report
+
+## Phase 6: Consolidated Report
+
+After ALL issues reach terminal state AND cleanup completes, present a final summary.
+
+### Step 6A: Collect trajectory data
+
+```bash
+for NUM in {all_completed_issue_numbers}; do
+  gh api repos/{GH_REPO}/issues/${NUM}/comments \
+    --jq '.[] | select(.body | contains("<!-- FORGE:TRAJECTORY -->")) | .body' 2>/dev/null
+done
+```
+
+Aggregate into the batch-level analytics for Step 6B.
+
+**Also collect the machine-readable summary cards** (`<!-- FORGE:CARD {json} -->`, embedded in
+each issue's `FORGE:TRAJECTORY` comment by `/work-on` close phase). These power the per-issue and
+batch cards in Step 6C:
+
+```bash
+CARDS=""
+for NUM in {all_completed_issue_numbers}; do
+  CARD=$(gh api repos/{GH_REPO}/issues/${NUM}/comments \
+    --jq '.[] | select(.body | contains("FORGE:CARD")) | .body' 2>/dev/null \
+    | sed -n 's/.*<!-- FORGE:CARD \(.*\) -->.*/\1/p' | head -1)
+  [ -n "$CARD" ] && CARDS="${CARDS}${CARD}"$'\n'
+done
+# CARDS is now a newline-delimited list of per-issue JSON objects (skip any issue whose
+# card is absent — pre-card runs or non-merged terminal states degrade gracefully).
+```
+
+### Step 6B: Present consolidated report
+
+```
+## Orchestration Complete
+
+**Scope**: {milestone / issue list}
+**Duration**: {approximate time}
+
+### Investigations (Phase 2)
+{IF investigations ran:}
+| # | Investigation | Issues Created | Result |
+|---|-------------|---------------|--------|
+| #{INV1} | {title} | #{N1}, #{N2}, #{N3} | ✓ Closed |
+{ELSE: "No investigations in this batch."}
+
+### Implementation Results
+
+| # | Issue | Source | Result | PR | Target |
+|---|-------|--------|--------|----|--------|
+| #{A} | {title} | original | ✓ Merged | #{PR} | staging |
+| #{B} | {title} | original | ✓ Merged | #{PR} | milestone/x |
+| #{N1} | {title} | from #{INV1} | ✓ Merged | #{PR} | staging |
+| #{C} | {title} | original | ✗ Invalid | — | — |
+| #{D} | {title} | original | ⚠ Blocked | — | — |
+| #{E} | {title} | original | ⏭ Skipped (dep) | — | — |
+
+### Review-Spawned Issues
+
+{IF review findings were created during any agent run:}
+| # | Finding | Source Issue | Source PR | Status |
+|---|---------|-------------|-----------|--------|
+| #{F1} | {title} | #{A} | PR #{PR} | ✓ Merged (in-batch) / ✓ Swept (completion sweep) / ⏳ Deferred (cosmetic) / ⛔ Deferred (gen2 cascade cap) |
+
+{ELSE: "No review findings created during this batch."}
+
+### Completion Sweep <!-- Added: forge#1105 -->
+- **Re-evaluated**: {N} deferred findings re-checked after DAG drain
+- **Dispatched**: {N} findings cleared and executed (file overlap resolved)
+- **Still deferred (cosmetic)**: {N} comment/typo findings (low-value, safe to leave)
+- **Permanently deferred (gen2)**: {N} generation >= 2 findings (cascade cap — requires manual `/work-on`)
+
+{IF permanently deferred > 0:}
+**Action required**: The following findings were permanently deferred due to the generation >= 2 cascade cap. They will NOT be picked up automatically — run `/work-on #{N}` manually or include them in the next `/orchestrate` batch:
+{list of permanently deferred issue numbers and titles}
+
+{IF cosmetic deferred > 0:}
+**Low-priority leftovers**: The following cosmetic findings remain open. They will be picked up by future runs or can be batched with `/orchestrate #{N1} #{N2}`:
+{list of cosmetic deferred issue numbers and titles}
+
+### Summary
+- **Investigations**: {N} completed, spawned {M} new issues
+- **Review findings**: {N} spawned, {M} resolved in-batch, {K} swept, {J} deferred (cosmetic), {L} deferred (gen2)
+- **Succeeded**: {N} issues resolved (implementation + sweep)
+- **Failed**: {N} issues need attention
+- **Skipped**: {N} issues (dependency failures)
+
+### Post-Batch Cleanup
+- Labels fixed: {N}
+- Orphaned issues closed: {N}
+- Worktrees removed: {N}
+- Branches pruned: {N}
+- Milestones closed: {N}
+
+### Agent Efficiency (from /audit-agents)
+
+| Agent | Issue | Total | Active | Idle% | Resumes | Stall Points |
+|-------|-------|-------|--------|-------|---------|--------------|
+{per-agent rows from audit}
+
+**Batch efficiency**: {avg_idle_pct}% idle time
+**Total resume cycles**: {sum_resumes} across {agent_count} agents
+**Clean agents** (no stalls): {clean_count}/{agent_count}
+
+### Batch Trajectory Analytics
+
+| Metric | Value |
+|--------|-------|
+| Issues attempted | {N} |
+| Investigation invalidation rate | {N_invalid}/{N_investigated} ({%}) |
+| Contracts posted | {N} |
+| Contract→code divergences | {N} (agents that updated contract mid-build) |
+| Review findings created | {N_total} |
+| Findings queued after cascade control | {N_queued}/{N_total} ({N_deferred} deferred — see Step 4C) |
+| Competing recommendations reconciled (Phase 2.5) | {RECONCILED_COUNT} (investigation plans arbitrated in place + serialized) |
+| Findings validated | {N} |
+| False positives | {N} ({%}) |
+| Anomalies flagged | {N} |
+
+**Domain breakdown**: {N} scraping, {N} frontend, {N} billing, ...
+**Routing**: {N} fast-lane, {N} feature-lane
+
+> `Findings queued after cascade control` reports Step 4C's defer/execute triage split (`QUEUED_FINDINGS` vs `DEFERRED_FINDINGS`) — it is NOT a dedup/arbitration computation; no such step exists for review findings. `Competing recommendations reconciled` is populated by Phase 2.5 (`RECONCILED_COUNT`), which reconciles investigation plans, not review findings. It is `0` when the batch had 0–1 investigations (synthesis is a no-op). <!-- Added: forge#1192, forge#1193 -->
+
+**Systematic issues** (flag if detected):
+- False positive rate > 30% → review agents may need tuning
+- Invalidation rate < 10% or > 35% → investigation calibration off
+- Same-domain merge conflicts between concurrent agents → domain serialization edges too loose
+- Contract divergences > 20% → investigation quality may need improvement
+- **Idle% > 50%** → agents stalling at phase boundaries; check work-on routing loop
+- **Avg resumes > 1** → orchestrator having to compensate for agent stops
+
+### Next Steps
+{If milestone and all issues done: "Milestone ready to ship. Run `/milestone ship {slug}` when ready. The ship command includes a pre-merge hunk-loss audit (Step 2.5) that detects staging-only hunks in milestone-modified files and rebases the milestone branch to absorb them before creating the PR — protecting against squash-merge regressions."}
+{If some failed: "Issues #{X}, #{Y} need manual attention. Re-run with `/work-on #{X}` after resolving blockers."}
+{If fast-lane: "All fixes merged to staging. Merge staging → main via GitHub web UI when ready to deploy."}
+```
+
+### Step 6C: Pipeline Summary Cards (the shareable moment)
+
+Render one compact summary card per completed issue (from the `CARDS` JSON collected in Step 6A),
+then a single batch-level summary card. These are the shareable artifacts a developer screenshots
+after an orchestration run. Print all cards to stdout.
+
+**Per-issue card** — emit one for each JSON object in `CARDS`. Use the same box-drawing style and
+51-column inner width as `work-on/close.md` Phase C4.5b. Read fields directly from the JSON
+(`issue`, `title`, `pipeline`, `commits`, `additions`, `deletions`, `pr`, `pr_target`, `review`,
+`elapsed_seconds`). Truncate long titles with `…`; render `null` numeric fields as `—`. The
+`pipeline`/`status` field already encodes skipped phases (decomposed/invalid/blocked), so reflect
+it verbatim. Skip issues with no card (graceful — pre-card or non-merged runs).
+
+**Batch summary card** — aggregate across all collected cards:
+
+```
+╔═══════════════════════════════════════════════════╗
+║  ForgeDock Orchestration Complete                 ║
+╠═══════════════════════════════════════════════════╣
+║                                                   ║
+║  Scope:    {milestone / issue list}               ║
+║  Issues:   {N} merged · {M} blocked · {K} invalid ║
+║  Commits:  {SUM_COMMITS} ({SUM_ADD} additions, {SUM_DEL} deletions) ║
+║  PRs:      {N} merged                             ║
+║  Findings: {N} spawned · {M} resolved             ║
+║  Time:     {BATCH_ELAPSED}                        ║
+║                                                   ║
+╚═══════════════════════════════════════════════════╝
+```
+
+Aggregate with `jq` over the collected cards (every sum degrades gracefully — `null`/missing
+fields are treated as 0; never fabricate):
+
+```bash
+echo "$CARDS" | grep -v '^$' | jq -s '{
+  merged:   (map(select(.status=="merged"))   | length),
+  blocked:  (map(select(.status=="blocked"))  | length),
+  invalid:  (map(select(.status=="invalid"))  | length),
+  commits:  (map(.commits   // 0) | add),
+  adds:     (map(.additions // 0) | add),
+  dels:     (map(.deletions // 0) | add),
+  prs:      (map(select(.pr != null)) | length),
+  elapsed:  (map(.elapsed_seconds // 0) | add)
+}'
+```
+
+The batch card's `Findings:` line is filled from the review-finding counts already computed in
+the Summary section above. `BATCH_ELAPSED` is the wall-clock duration of the orchestration run
+(Step 6B `Duration`), not the sum of per-issue elapsed times.
+
+---
+

package/commands/orchestrate/safety.md

@@ -0,0 +1,62 @@
+---
+install: internal
+---
+<!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
+<!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
+
+# /orchestrate — Safety Rules & Examples
+
+## Safety Rules
+
+1. **Every agent MUST invoke `/work-on` via the Skill tool.** No custom prompts. No manual implementation. Copy the Phase 4A template, fill in variables, done. (See HARD RULES at top of file.)
+2. **NEVER merge anything to `main`** — agents merge to `staging` or `milestone/{slug}` only
+3. **No artificial concurrency limit by default** — spawn as many agents as there are independent issues. Only file overlap and dependencies require sequencing. Set `forge.yaml → orchestration.max_concurrent` to cap in-flight workers and prevent rate-limit storms on large batches (see Engine mode § Concurrency model).
+4. **Always confirm with user before launching** — Step 3E is the mandatory checkpoint
+5. **No retries** — if an agent fails, report it and move on
+6. **Respect existing work** — skip issues already being worked on (`workflow:building`, `workflow:in-review`)
+7. **Dependency failures cascade** — if A fails and B depends on A, all transitive dependents of A are skipped (not attempted)
+8. **Always run post-batch cleanup** — Phase 5 is mandatory. Never skip `/cleanup all` after orchestration.
+9. **NEVER close/skip issues as duplicates** — only `/work-on` investigation agents can make that call after examining the actual code. The orchestrator delegates, it does not adjudicate. **This is distinct from Phase 2.5 plan reconciliation**: reconciling *competing recommendations* across investigation annotations (arbitrating incompatible plans, adding `Depends on #X` serialization edges) operates only on FORGE annotations and issue bodies — it never reads code and never closes/skips/merges an issue. Both issues in a reconciled conflict still run. Adjudicating *duplicate validity* (deciding two issues are the same bug and closing one) remains forbidden. <!-- Added: forge#1192 -->
+10. **Per-completion verification** — after each agent completes, check that it has `workflow:*` labels and structured comments. If an agent bypassed `/work-on`, report it as a pipeline failure.
+
+---
+
+## Examples
+
+### "orchestrate milestone api-expansion"
+→ Fetches all open issues in "API Expansion v1" milestone
+→ Builds DAG: #1526 → #1527 → #1528 → #1529 (chain), #1530 (no predecessors)
+→ Confirms with user, dispatches #1526 + #1530 immediately
+→ When #1526 completes, dispatches #1527 immediately (doesn't wait for #1530)
+→ Streaming continues until all issues reach terminal state
+
+### "orchestrate #1533 #1250"
+→ Fetches those 2 issues, no deps between them
+→ DAG: both have empty predecessor sets
+→ Confirms, dispatches both simultaneously
+
+### "orchestrate next 5"
+→ Gets top 5 priority issues, builds DAG
+→ Confirms, dispatches all ready issues immediately
+→ Dependent issues dispatch as predecessors complete
+
+### "orchestrate P0"
+→ Gets all P0 issues, runs them all (presumably urgent)
+→ DAG: likely all independent — dispatches simultaneously
+→ Confirms, executes
+
+### "orchestrate fast-lane"
+→ Gets all unmilestoned bugs/fixes
+→ Builds DAG from file-conflict and domain-serialization edges
+→ Dispatches all ready issues, streams dependent issues as predecessors complete
+
+### "orchestrate milestone user-auth-v2"
+→ Fetches all open issues in "User Auth v2" milestone
+→ Detects #42 is an investigation issue (title: "Investigate: session expiry race condition under high concurrency")
+→ Phase 2: Runs `/work-on 42` — investigation creates 3 new issues (#55-#57)
+→ Re-fetches milestone issues, now includes #55-#57
+→ Builds DAG: #38, #41, #55, #56 have no predecessors (ready); #39 depends on #38; #57 depends on #55
+→ Dispatches #38, #41, #55, #56 simultaneously
+→ When #38 completes, #39 dispatches immediately (doesn't wait for #41, #55, or #56)
+→ When #55 completes, #57 dispatches immediately (doesn't wait for others)
+→ Final report shows investigation spawned issues and streaming execution results