Skip to content

feat: add source-bound plan review feedback - #18

Merged
Deathcharge merged 2 commits into
mainfrom
codex/plan-review-records
Aug 11, 2026
Merged

feat: add source-bound plan review feedback#18
Deathcharge merged 2 commits into
mainfrom
codex/plan-review-records

Conversation

@Deathcharge

Copy link
Copy Markdown
Owner

Summary

  • add immutable comment, request-changes, and reject records bound to exact plan source
  • add deterministic review identity, bounded structured findings, optional exact-media binding, and stale/blocking verification
  • add CLI/API/schema/docs plus explicit fail-on-blocking CI behavior

Verification

  • 435 tests passed with 93.77% coverage
  • Black, Flake8, strict mypy, compileall, and git diff checks passed
  • 13 Draft 2020-12 schemas validated
  • wheel and sdist built; fresh Python 3.11 wheel journey passed with pip check

Trust boundary

Reviewer labels, decisions, hashes, and timestamps are unsigned local metadata. Positive authorization remains in the existing quality-gated plan approval workflow.

@coderabbitai

coderabbitai Bot commented Aug 8, 2026

Copy link
Copy Markdown

Review Change Stack

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: b51f9e39-45e1-41ab-867f-ca4f10930472

📥 Commits

Reviewing files that changed from the base of the PR and between 59beaf3 and 4803771.

📒 Files selected for processing (9)
  • README.md
  • docs/API.md
  • docs/PLAN_FEEDBACK.md
  • samsarix_creative_spirals/__init__.py
  • samsarix_creative_spirals/cli.py
  • samsarix_creative_spirals/plan_feedback.py
  • tests/test_cli.py
  • tests/test_plan_feedback.py
  • tests/test_public_api.py

Summary by CodeRabbit

  • New Features

    • Added immutable, source-bound plan reviews supporting comments, change requests, rejections, findings, suggestions, and optional media references.
    • Added CLI commands and public APIs to create, export, load, verify, and inspect plan-review schemas.
    • Added validation for tampering, stale sources, missing items, and blocking decisions.
  • Documentation

    • Updated guides, architecture, security notes, roadmap, examples, and changelog for version 0.16.0.
  • Tests

    • Added coverage for review creation, verification, schema validation, media binding, tamper detection, and CLI behavior.

Walkthrough

The PR adds immutable, source-bound plan-review records for campaign plans. It adds validated models, deterministic hashes and IDs, media binding, loading and verification APIs, CLI commands, a JSON Schema, tests, CI coverage, and 0.16 documentation.

Changes

Plan review workflow

Layer / File(s) Summary
Review contract and validation
samsarix_creative_spirals/plan-review.schema.json, samsarix_creative_spirals/plan_feedback.py, tests/test_plan_feedback.py
Defines validated review findings, decisions, metadata, media bindings, canonical hashes, and verification results.
Review lifecycle and public API
samsarix_creative_spirals/plan_feedback.py, samsarix_creative_spirals/schema.py, samsarix_creative_spirals/__init__.py, tests/test_plan_feedback.py, tests/test_public_api.py, docs/API.md
Creates, exports, loads, and verifies reviews against plan, source, and media state. Exposes the review models, functions, and schema loader.
CLI review commands
samsarix_creative_spirals/cli.py, tests/test_cli.py, .github/workflows/ci.yml, README.md, docs/QUICKSTART.md, examples/README.md
Adds plan review create, plan review verify, and plan-review schema output with blocking-result handling and validation coverage.
Release and workflow documentation
CHANGELOG.md, ROADMAP.md, SECURITY.md, docs/ARCHITECTURE.md, docs/PLAN_FEEDBACK.md, docs/PLAN_REVIEW.md, samsarix_creative_spirals/_version.py
Documents the 0.16 review artifact, supported workflow, trust boundaries, roadmap, and package version.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Reviewer
  participant CLI
  participant PlanFeedback
  participant ReviewFile
  participant CampaignPlan
  Reviewer->>CLI: create plan review
  CLI->>PlanFeedback: validate decision and findings
  PlanFeedback->>CampaignPlan: bind source and plan identity
  PlanFeedback->>ReviewFile: export immutable review
  Reviewer->>CLI: verify review
  CLI->>PlanFeedback: load and verify review
  PlanFeedback->>CampaignPlan: compare current state
  PlanFeedback-->>CLI: return validity and blocking status
Loading

Possibly related PRs

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 20.45% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (4 passed)
Check name Status Explanation
Title check ✅ Passed The title clearly and concisely summarizes the main change: source-bound plan review feedback.
Description check ✅ Passed The description directly explains the plan review records, verification behavior, interfaces, documentation, and validation results.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
✨ Finishing Touches 💡 1
📝 Generate docstrings 💡
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch codex/plan-review-records

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 4

🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/PLAN_FEEDBACK.md`:
- Around line 72-75: Update the exit-code description in the
“--fail-on-blocking” documentation to state that exit 4 also covers invalid
current bound-media state, including missing or changed media, alongside current
plan-state decisions. Preserve the distinction that stale negative decisions
from prior revisions are not blocking.

In `@README.md`:
- Around line 309-311: Update the media-binding documentation in README.md to
clarify that --include-media applies to both plan approval creation and plan
review artifacts, while preserving the existing distinction that positive
authorization remains in the quality-gated plan approval workflow.

In `@samsarix_creative_spirals/cli.py`:
- Line 547: Update the timestamp parsing in the plan review creation flow around
reviewed_at to use the review-specific parser that reports reviewedAt, rather
than parse_approval_timestamp(), while preserving the existing optional-argument
behavior.

In `@samsarix_creative_spirals/plan_feedback.py`:
- Around line 197-200: Update CampaignPlanReview validation at
samsarix_creative_spirals/plan_feedback.py#L197-L200 and
create_campaign_plan_review at
samsarix_creative_spirals/plan_feedback.py#L404-L408 to guard tuple conversion
for non-iterable findings values; catch the conversion failure, append the
validation message to issues, and continue through aggregated ConfigError
handling. Add coverage for findings=None at both public entry points.
🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 85976204-5ada-4f54-a23c-8756cbe3718c

📥 Commits

Reviewing files that changed from the base of the PR and between d4b9afb and 59beaf3.

📒 Files selected for processing (20)
  • .github/workflows/ci.yml
  • CHANGELOG.md
  • README.md
  • ROADMAP.md
  • SECURITY.md
  • docs/API.md
  • docs/ARCHITECTURE.md
  • docs/PLAN_FEEDBACK.md
  • docs/PLAN_REVIEW.md
  • docs/QUICKSTART.md
  • examples/README.md
  • samsarix_creative_spirals/__init__.py
  • samsarix_creative_spirals/_version.py
  • samsarix_creative_spirals/cli.py
  • samsarix_creative_spirals/plan-review.schema.json
  • samsarix_creative_spirals/plan_feedback.py
  • samsarix_creative_spirals/schema.py
  • tests/test_cli.py
  • tests/test_plan_feedback.py
  • tests/test_public_api.py

Comment thread docs/PLAN_FEEDBACK.md Outdated
Comment thread README.md
Comment thread samsarix_creative_spirals/cli.py Outdated
Comment thread samsarix_creative_spirals/plan_feedback.py Outdated
@Deathcharge
Deathcharge merged commit d81da9a into main Aug 11, 2026
5 checks passed
@Deathcharge
Deathcharge deleted the codex/plan-review-records branch August 11, 2026 00:49
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant