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 24, 2026, 9:33 AM ET / 13:33 UTC.

Summary
Adds decision-packet JSON generation from report frontmatter and labels, syncs packet records through apply/replay/reconcile paths, renders a compact maintainer decision block, and documents/tests the new state output.

Reproducibility: not applicable. this is a feature PR rather than a current-main bug report. The PR body includes terminal output from a built apply-decisions run showing packet creation and cleanup.

Review metrics: 3 noteworthy metrics.

• Changed Surface: 5 files, +1097/-17. The patch adds a new module and tests while modifying central apply/replay/reconcile state writers.
• Generated-State Writers: 3 paths changed. apply-decisions, apply-artifacts, and reconcile now write or remove decision packet records.
• Proof Scope: 1 PR-visible CLI run. The body shows apply-decisions packet creation and cleanup; replay and reconcile are covered by source/tests and CI.

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:

• none.

Risk before merge

• [P1] The PR creates a new durable records//decision-packets/ directory and decision_packet_* report frontmatter that downstream state consumers need to accept as a generated-state contract.
• [P1] The PR-visible real behavior proof covers apply-decisions packet creation and cleanup; apply-artifacts and reconcile rely on source inspection, focused tests, and CI rather than separate real-run proof.
• [P1] The companion reports UI consumer is tracked outside this repository at https://github.com/openclaw/maintainers/issues/103, so maintainers should confirm the producer contract is ready before merge.

Maintainer options:

1. Accept Decision-Packet State Contract (recommended)
   A maintainer can merge once they agree that decision-packets and report pointer frontmatter are the right durable state surface.
2. Request Replay And Reconcile Proof
   A maintainer can ask for additional redacted terminal output covering apply-artifacts and reconcile before accepting the automation change.
3. Pause Until Consumer Contract Is Ready
   If the companion reporting consumer or state shape is not ready, leave this PR unmerged until that direction is settled.

Next step before merge

• [P2] Maintainer should decide whether to accept the new durable decision-packet state contract; no narrow automated repair is identified.

Security
Cleared: No concrete security or supply-chain concern was found; the patch adds no dependencies or workflow execution changes, and CodeQL is passing at the reviewed head.

Review details

Best possible solution:

Land after maintainer acceptance of the decision-packet state contract and exact-head checks, treating packet files as generated durable state derived from reports and labels.

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 includes terminal output from a built apply-decisions run showing packet creation and cleanup.

Is this the best way to solve the issue?

Unclear until maintainers accept the durable state contract; technically, the dedicated module plus apply/replay/reconcile hooks is coherent and I found no blocking patch defect. A safer alternative is to hold the packet output until the downstream maintainer UI contract is confirmed.

AGENTS.md: found and applied where relevant.

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

Label changes

Label justifications:

• P2: This is a normal-priority generated-state feature with bounded but maintainer-visible automation behavior.
• merge-risk: 🚨 automation: The diff changes ClawSweeper state-writing behavior in apply, artifact replay, reconcile, and review-comment rendering paths.
• 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 packet creation, report 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 packet creation, report pointer writing, stale packet removal, and pointer cleanup.

Evidence reviewed

What I checked:

• Repository policy: AGENTS.md was read fully; its generated-state layout and automation-safety guidance applies because this PR changes durable ClawSweeper state writers. (AGENTS.md:1, f92fbfebbe8f)
• Current main capability check: Current main has no decision-packet implementation, so the central feature is not already implemented or obsolete. (f92fbfebbe8f)
• Decision packet module: The PR adds buildDecisionPacketFromReport and syncDecisionPacketRecord to derive packet JSON, write the sidecar file, and update report pointer frontmatter. (src/decision-packets.ts:105, 347418dea66e)
• Apply path wiring: apply-decisions derives a decision-packets directory and routes report writes through packet sync before persisting updated reports. (src/clawsweeper.ts:16252, 347418dea66e)
• Replay and reconcile wiring: apply-artifacts and reconcile now sync decision packets when reports are written or moved between open and closed records. (src/clawsweeper.ts:18176, 347418dea66e)
• Documentation and focused coverage: README documents the new generated-state path and CLI override, and tests cover parsing, lane selection, pointer writing, and review-comment rendering. (README.md:90, 347418dea66e)

Likely related people:

• Peter Steinberger: Git blame on the existing apply-decisions, review-comment, reconcile, README, and test baselines points to the v0.3.0 release-era source this PR extends. (role: current apply/reconcile baseline contributor; confidence: medium; commits: dc824915bb6c; files: src/clawsweeper.ts, README.md, test/clawsweeper.test.ts)
• Vincent Koc: Recent current-main commits touched apply checkpoint behavior, CI/API pressure, CodeQL cleanup, and related automation surfaces near this change. (role: recent automation contributor; confidence: medium; commits: f94588d89c2f, 1566ad6a0a5b, babd6a435afb; files: src/clawsweeper.ts, .github/workflows/sweep.yml, test/clawsweeper.test.ts)
• Dallin Romney: Recent history shows adjacent work on advisory label sync, review comment rendering, proof policy tests, and test splitting around this review/apply surface. (role: recent review/comment-label contributor; confidence: medium; commits: b75626e4df03, 4e5c4d47c83f, 4cab87ce3d7f; files: src/clawsweeper.ts, test/clawsweeper.test.ts)
• brokemac79: The PR author also appears in prior merged current-main review/activity automation work, so they are relevant beyond only proposing this branch. (role: adjacent review automation contributor; confidence: medium; commits: 79e768844291, f2b07a7265fb, bb22ac97a417; files: src/clawsweeper.ts, test/clawsweeper.test.ts)

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.