Add maintainer decision packets

[brokemac79]

Summary

• writes maintainer decision packet JSON alongside ClawSweeper close/review records
• derives packet state from the current GitHub labels, review status, proof, and close report details
• updates packets during apply/replay/reconcile paths so skipped or drifted items keep the maintainer-facing data current
• keeps pure decision-packet parser/sync coverage in test/decision-packets.test.ts, with ClawSweeper integration coverage left in test/clawsweeper.test.ts

Companion reports UI

Companion maintainers report UI branch is ready locally at d081921d0a3f4baa3391bc0de3303955bc81c5fc (codex/decision-packets-reports-v1). Tracking issue: openclaw/maintainers#103. The PR link will be added once that branch can be published in openclaw/maintainers.

A local reports UI preview was generated from the maintainers branch. The screenshot assets are hosted on a separate preview-only branch in the author fork, not in this PR diff.

Reports UI Preview

Desktop overview:

Filtered view, showing persistent label/filter shape:

Mobile/narrow view:

GHAS / CodeQL Follow-Up

• Replaced the initially flagged report-heading regex with explicit line parsing in src/decision-packets.ts.
• CodeQL passed on the amended commit.

Real Behavior Proof

Ran the built CLI against temp items/, closed/, plans/, and decision-packets/ directories with a fake gh executable wired through GH_BIN, so the command exercised the real dist/clawsweeper.js apply-decisions path without mutating GitHub or repo state.

Command, with temp paths redacted:

node dist/clawsweeper.js apply-decisions --target-repo openclaw/clawsweeper --items-dir [temp]\items --closed-dir [temp]\closed --plans-dir [temp]\plans --decision-packets-dir [temp]\decision-packets --report-path [temp]\apply-report.json --limit 1 --processed-limit 1 --close-delay-ms 0 --item-numbers 321

Observed output and state:

{
  "firstRun": [
    {
      "number": 321,
      "action": "skipped_changed_since_review",
      "reason": "updated_at changed"
    }
  ],
  "packetProduced": true,
  "packetSummary": {
    "lane": "product_contract",
    "repo": "openclaw/clawsweeper",
    "number": 321,
    "state": "open"
  },
  "firstReportHasPointer": true,
  "secondRun": [
    {
      "number": 321,
      "action": "skipped_changed_since_review",
      "reason": "updated_at changed"
    }
  ],
  "stalePacketRemoved": true,
  "secondReportPointerCleared": true,
  "ghCalls": 4
}

The first run produced [temp]\decision-packets\321.json and wrote decision_packet_path / decision_packet_sha256 into the report. After removing the decision trigger from the temp report and rerunning the same CLI command, the stale packet was removed and the report pointers were cleared to none.

Validation

• pnpm run build:all
• pnpm run lint
• pnpm exec oxfmt --check README.md src/clawsweeper.ts src/decision-packets.ts test/clawsweeper.test.ts
• pnpm exec oxfmt --check src/decision-packets.ts
• pnpm exec oxfmt --check test/decision-packets.test.ts test/clawsweeper.test.ts
• node --test test/decision-packets.test.ts
• node --test --test-name-pattern "review comments include a compact maintainer decision packet block|apply-decisions skips advisory label sync when a close report changed since review" test/clawsweeper.test.ts
• node --test --test-name-pattern "decision packet|maintainer decision packet|apply-decisions skips advisory label sync when a close report changed since review" test/clawsweeper.test.ts before the test split
• git diff --check (CRLF warnings only)
• GitHub PR checks passed on the current commit, including CodeQL and pnpm check

Full test/clawsweeper.test.ts was not rerun in this final pass because the broader Windows lane previously hit an existing CRLF-sensitive workflow regex failure unrelated to this patch.

[clawsweeper]

Codex review: needs maintainer review before merge. Reviewed June 29, 2026, 3:24 PM ET / 19:24 UTC.

Summary
The PR adds decision-packet JSON generation, report frontmatter pointers, review-comment rendering, apply/replay/reconcile sync hooks, README docs, and focused tests.

Reproducibility: not applicable. this is a feature PR rather than a current-main bug report. The PR body provides terminal proof for the main apply-decisions packet creation and cleanup path.

Review metrics: 3 noteworthy metrics.

• Changed Surface: 5 files, +1097/-17. The PR adds a new module and tests while modifying central generated-state writers.
• Generated-State Writers: 3 paths changed. apply-decisions, apply-artifacts, and reconcile would start writing or removing decision packet records.
• Mergeability: CONFLICTING. The PR needs a refresh against current main before exact-head merge readiness can be trusted.

Merge readiness
Overall: 🐚 platinum hermit
Proof: 🦞 diamond lobster
Patch quality: 🐚 platinum hermit
Result: ready for maintainer review.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

• Refresh the branch against current main to resolve the reported merge conflict before exact-head merge review.

Risk before merge

• [P1] The PR creates a new durable records//decision-packets/ directory and decision_packet_* report frontmatter, so downstream state consumers need to accept the generated-state contract.
• [P1] The strongest real-run proof covers apply-decisions packet creation and cleanup; apply-artifacts and reconcile are supported by source inspection and tests rather than separate terminal proof.
• [P1] GitHub currently reports the PR as conflicting, so maintainers need a branch refresh and exact-head review before merge.

Maintainer options:

1. Refresh And Accept The State Contract (recommended)
   Refresh the branch against current main, then merge if maintainers accept decision packets as a durable generated-state surface.
2. Request Replay And Reconcile Runtime Proof
   Ask for additional redacted terminal output that exercises apply-artifacts and reconcile packet sync before accepting the automation change.
3. Pause For Consumer Contract Alignment
   Leave the PR open until the companion maintainer reports UI and generated-state schema expectations are confirmed.

Next step before merge

• [P2] Maintainers need to decide the generated-state contract and resolve the current merge conflict; there is no narrow automated code repair identified from this review.

Security
Cleared: No concrete security or supply-chain concern was found; the PR adds no dependencies or workflow execution changes, and the earlier CodeQL regex warning was addressed before the reviewed head.

Review details

Best possible solution:

Land the feature after maintainers accept the decision-packet state contract and the branch is refreshed cleanly against current main.

Do we have a high-confidence way to reproduce the issue?

Not applicable; this is a feature PR rather than a current-main bug report. The PR body provides terminal proof for the main apply-decisions packet creation and cleanup path.

Is this the best way to solve the issue?

Unclear until maintainers accept the durable state contract; the implementation shape is coherent and I found no line-level patch defect. The safer path is to refresh the branch and confirm the downstream consumer contract before merge.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against ae63b16d6c74.

Label changes

Label changes:

• add merge-risk: 🚨 compatibility: The diff adds durable decision-packet files and report frontmatter that downstream state consumers may need to understand or tolerate.

Label justifications:

• P2: This is a normal-priority generated-state feature with bounded but maintainer-visible automation impact.
• merge-risk: 🚨 automation: The diff changes ClawSweeper apply, artifact replay, reconcile, and review-comment state-output behavior.
• merge-risk: 🚨 compatibility: The diff adds durable decision-packet files and report frontmatter that downstream state consumers may need to understand or tolerate.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🦞 diamond lobster and patch quality is 🐚 platinum hermit.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (terminal): The PR body includes terminal output from a built CLI apply-decisions run showing after-change packet creation, pointer writing, stale packet removal, and pointer cleanup.
• proof: sufficient: Contributor real behavior proof is sufficient. The PR body includes terminal output from a built CLI apply-decisions run showing after-change packet creation, pointer writing, stale packet removal, and pointer cleanup.

Evidence reviewed

What I checked:

• Repository policy read: AGENTS.md was read fully; its generated-state and apply-lane guidance applies because this PR changes durable ClawSweeper state writers. (AGENTS.md:1, ae63b16d6c74)
• Current main capability check: Current main has existing needs-product-decision labels and comment text but no decision-packet generation or decision_packet frontmatter implementation, so the feature is not already implemented on main. (src/clawsweeper.ts:1491, ae63b16d6c74)
• Decision packet module: The PR adds buildDecisionPacketFromReport and syncDecisionPacketRecord to derive packet JSON, write sidecar files, remove stale packet files, and update report pointer frontmatter. (src/decision-packets.ts:105, 347418dea66e)
• Apply/replay/reconcile wiring: The PR routes apply-decisions, apply-artifacts, and reconcile report writes through decision-packet sync, so the change affects generated state maintenance paths. (src/clawsweeper.ts:16340, 347418dea66e)
• PR status and proof: GitHub reports the PR as CONFLICTING, while the PR body includes terminal proof from a built apply-decisions run that created packet files, wrote report pointers, removed a stale packet, and cleared pointers. (347418dea66e)
• Related PR check: fix: rotate apply queue batches #375 is adjacent apply-queue work and explicitly mentions this PR as a nearby overlap, but it does not implement decision packets or supersede this branch.

Likely related people:

• Dallin Romney: Recent current-main history introduced and split review-label, review-comment, maturity, and apply-decision paths that this PR extends. (role: recent review/comment-label contributor; confidence: high; commits: 4e5c4d47c83f, 4cab87ce3d7f, 323f7bdf7236; files: src/clawsweeper.ts, test/clawsweeper.test.ts, docs/triage-dashboard.md)
• Vincent Koc: Recent commits touched CI/API pressure, apply checkpointing, and CodeQL cleanup near the automation surfaces changed by this PR. (role: recent automation contributor; confidence: medium; commits: f94588d89c2f, 1566ad6a0a5b, babd6a435afb; files: src/clawsweeper.ts, .github/workflows/sweep.yml, test/clawsweeper.test.ts)
• brokemac79: The PR author also appears in prior merged current-main work on local-only issue and PR review mode, so they are relevant beyond only proposing this branch. (role: adjacent review automation contributor; confidence: medium; commits: 79e768844291, 84796f0c9b0c; files: src/clawsweeper.ts, README.md, test/clawsweeper.test.ts)
• Peter Steinberger: Recent current-main history includes repair intake and durable queue work adjacent to generated ClawSweeper state and automation policy. (role: adjacent repair/state contributor; confidence: medium; commits: be44378572ac, 59e2d4406ebb, 30163dfd667b; files: src/clawsweeper.ts, src/repair/, README.md)

What the crustacean ranks mean

• 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
• 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
• 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
• 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
• 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
• 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
• 🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

[brokemac79]

@clawsweeper re-review

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.