Add refresh decision prepare helper

[SoundBlaster]

Motivation

Maintainers can preflight an existing generated candidate refresh decision, but drafting that decision by hand is brittle. Package-set refresh review needs a repeatable read-only way to compare a fresh generated tree with current registry evidence and produce a machine-readable decision record.

Goals

• Add a helper that prepares draft SpecPMGeneratedCandidateRefreshDecision records from fresh/current generated artifacts.
• Preserve the authority boundary: prepare output is review evidence only, not registry acceptance or mutation.
• Cover no-op and generated contract-delta outcomes with regression tests and docs.

Changes

• Added specpm producer-bundle prepare-refresh-decision.
• Added SpecPMGeneratedCandidateRefreshDecisionPrepareReport.
• Compare contract-bearing generated files: specpm.yaml and specs/*.spec.yaml.
• Write optional decision JSON with --output and immediately validate it through existing refresh decision preflight rules.
• Updated refresh decision policy, producer bundle policy, operator guide, CLI DocC, roadmap, workplan, self-spec, and tests.

Validation

• PYTHONPATH=src pytest -q -> 259 passed
• PYTHONPATH=src ruff check .
• PYTHONPATH=src ruff format --check src tests
• git diff --check
• PYTHONPATH=src python3 -m specpm.cli validate .
• make docs-build
• make pages-smoke
• make public-index-generate PUBLIC_INDEX_OUTPUT=/tmp/specpm-p66-t20-public-index
• make dev-reload && make dev-smoke
• prepare/preflight smoke wrote /tmp/specpm-p66-t20-refresh-decision.json and verified digest count 8

Boundaries and Non-Goals

• Does not mutate public-index/curated, public-index/generated, accepted relations, or registry metadata.
• Does not accept producer output or decide package quality.
• Does not run SpecHarvester; it consumes a fresh generated artifact tree supplied by the maintainer/CI.

Notes

• This closes P66-T20 in specs/WORKPLAN.md.
• Next stacked task is P66-T21: CI/dry-run artifact for refresh decision preparation.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: d47d225ca4

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[Copilot]

Pull request overview

Adds a new, read-only “prepare” helper to draft SpecPMGeneratedCandidateRefreshDecision records by comparing a fresh generated artifact tree against the current registry’s generated/curated evidence, then immediately validating the draft via existing preflight rules. This supports repeatable refresh review without crossing into registry mutation/acceptance.

Changes:

• Introduces prepare_refresh_decision() and SpecPMGeneratedCandidateRefreshDecisionPrepareReport in the producer-bundle tooling.
• Adds CLI support for specpm producer-bundle prepare-refresh-decision, including optional --output decision JSON writing and --json stable report output.
• Adds regression tests and updates policies/operator docs/DocC/self-spec to document the new helper and non-authority boundary.

Reviewed changes

Copilot reviewed 15 out of 15 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
tests/test_core.py	Adds regression tests for prepare helper no-op, JSON output writing, and contract-delta detection.
src/specpm/producer_bundle.py	Implements prepare helper, report shape, contract-file comparison, and decision drafting + preflight validation.
src/specpm/cli.py	Adds producer-bundle prepare-refresh-decision subcommand, arguments, output handling, and text rendering.
specs/WORKPLAN.md	Marks P66-T20 complete and documents expected/result behavior for the new helper.
specs/specpm.spec.yaml	Updates self-spec capabilities/evidence to include the prepare helper.
specs/PUBLIC_INDEX_OPERATOR_GUIDE.md	Documents maintainer workflow for drafting refresh decisions from a fresh generated tree.
specs/PRODUCER_BUNDLE_PROPOSAL_POLICY.md	Documents prepare helper usage and reinforces read-only boundary.
specs/MULTI_PACKAGE_PRODUCER_INTAKE.md	References prepare helper as evidence-prep step before preflight.
specs/GENERATED_CANDIDATE_REFRESH_DECISION_POLICY.md	Adds “Prepare Helper” section and describes behavior/outcomes.
specpm.yaml	Registers new capability ID for the prepare helper.
Sources/SpecPM/Documentation.docc/Roadmap.md	Notes the new prepare helper in the DocC roadmap.
Sources/SpecPM/Documentation.docc/ProducerBundleProposalPolicy.md	DocC equivalent of producer bundle policy update.
Sources/SpecPM/Documentation.docc/GeneratedCandidateRefreshDecisionPolicy.md	DocC equivalent of refresh decision policy “Prepare Helper” addition.
Sources/SpecPM/Documentation.docc/CLIReference.md	Documents the new CLI subcommand in DocC CLI reference.
ROADMAP.md	Notes the new prepare helper in the repository roadmap.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.