Skip to content

docs(greenfield): remove per-story evidence pins - #109

Merged
aryeko merged 2 commits into
mainfrom
policy/drop-per-story-evidence
Jul 26, 2026
Merged

docs(greenfield): remove per-story evidence pins#109
aryeko merged 2 commits into
mainfrom
policy/drop-per-story-evidence

Conversation

@aryeko

@aryeko aryeko commented Jul 26, 2026

Copy link
Copy Markdown
Contributor

Summary

Unblocks: rework of #108 under the amended policy.

Verification

  • pnpm install --frozen-lockfile
  • pnpm delivery:check
  • pnpm check
  • git diff --check
  • grep -rn 'baseline_commit' docs/delivery/ scripts/ | wc -l0

The delivery validator passed for 48 stories and 7 phases and emitted an unpinned candidate-package manifest digest. The approved normative-corpus and story-authority-binding digest constants are unchanged.

Out of scope

  • Do not touch PR feat: complete greenfield phase 0 substrate #108, its branch feat/greenfield-phase-0-substrate, or its worktree at worktrees/jig/feat-greenfield-phase-0-substrate. A separate PR reworks it after this one merges.
  • Do not delete or rename scripts/run-gf-001-tests.mjs, scripts/write-gf-001-evidence.mjs, tests/gf-001/, or tests/fixtures/gf-001-workspace/. They are on main and are PR 2's job — removing them here would break pnpm check on this branch.
  • Do not change .github/workflows/check.yml. PR 2 owns it.
  • Do not add the generic evidence writer. PR 2 owns it.
  • Do not modify docs/product/, docs/redesign/, or anything else in the 67-file normative corpus — it would move an approved digest.
  • Do not renumber, reword, or restructure the 48 stories' outcomes, oracles, dependencies, or DR-* selections. Only baseline_commit leaves.

GF-001's existing per-story evidence machinery (scripts/run-gf-001-tests.mjs, scripts/write-gf-001-evidence.mjs, tests/gf-001/) stays on main until the follow-up rework of #108 removes it. main is transitionally non-compliant with the amended policy by design — removing it here would break pnpm check on this branch.

Summary by CodeRabbit

  • Documentation

    • Tightened greenfield delivery and reviewer semantics around how approved delivery packages, landing evidence, and reviewer records are captured and verified.
    • Clarified candidate-freeze and exact-subject evidence handling as generated CI artifacts (not committed assertions).
    • Removed baseline_commit from story documentation and updated related start-evidence explanations.
  • Validation

    • Updated track/story schema checks to the revised 15-field story contract.
    • Expanded/adjusted diagnostics for malformed story metadata (including blank titles).
    • Updated validation test expectations accordingly.

@coderabbitai

coderabbitai Bot commented Jul 26, 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: CHILL

Plan: Pro Plus

Run ID: be6f2d1b-aa1c-4ad0-9c08-0fd485e35386

📥 Commits

Reviewing files that changed from the base of the PR and between f2092ae and c4787fe.

📒 Files selected for processing (6)
  • docs/delivery/greenfield/delivery-policy.md
  • docs/delivery/greenfield/stories/GF-012.md
  • docs/delivery/greenfield/stories/GF-034.md
  • docs/delivery/greenfield/stories/GF-039.md
  • docs/delivery/greenfield/stories/GF-042.md
  • scripts/check-delivery-track.test.mjs
🚧 Files skipped from review as they are similar to previous changes (5)
  • docs/delivery/greenfield/stories/GF-039.md
  • docs/delivery/greenfield/stories/GF-012.md
  • docs/delivery/greenfield/stories/GF-034.md
  • docs/delivery/greenfield/stories/GF-042.md
  • docs/delivery/greenfield/delivery-policy.md

📝 Walkthrough

Walkthrough

The update removes per-story baseline_commit metadata, revises greenfield delivery and evidence-recording requirements, and changes track validation from 16 to 15 canonical story fields. Validator tests now use updated diagnostics and cover whitespace-only titles.

Changes

Greenfield delivery contract

Layer / File(s) Summary
External evidence and candidate review contract
docs/delivery/greenfield/delivery-policy.md, docs/delivery/greenfield/story-contract.md, docs/delivery/greenfield/reviewer/review-checklist.md, docs/delivery/greenfield/verification.md
Documentation requires external reviewer-record bindings, candidate-freeze verification, generated exact-subject evidence, and prohibits committed delivery-process constants.
Story metadata migration
docs/delivery/greenfield/stories/*.md
Story front matter removes baseline_commit; affected start-evidence text removes its planning/authority-provenance references.
15-field track schema validation
docs/delivery/greenfield/track.json, scripts/check-delivery-track.mjs, scripts/check-delivery-track.test.mjs
Track records and validation now use 15 canonical fields, remove the approved-hash check, update diagnostics, and reject whitespace-only titles.

Estimated code review effort: 3 (Moderate) | ~20 minutes

🚥 Pre-merge checks | ✅ 2 | ❌ 3

❌ Failed checks (3 warnings)

Check name Status Explanation Resolution
Linked Issues check ⚠️ Warning The PR removes baseline_commit pins in docs/scripts but does not implement Phase 9 records integrity required by #39. Add the integrity.json launch-header/snapshot/hash-chain work, additive run.started.binding.drivers binding, and fail-closed resume checks.
Out of Scope Changes check ⚠️ Warning The changes are about greenfield delivery documentation cleanup and baseline_commit removal, which is unrelated to the linked Phase 9 integrity work. Remove the unrelated greenfield docs/script changes or retarget the PR to the Phase 9 records integrity requirements.
Docstring Coverage ⚠️ Warning Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (2 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title clearly matches the main change: removing per-story evidence pins from greenfield docs.
✨ Finishing Touches
📝 Generate docstrings
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch policy/drop-per-story-evidence

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: 1

🧹 Nitpick comments (1)
scripts/check-delivery-track.mjs (1)

939-939: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Derive the diagnostic count from STORY_KEYS.

These messages repeat the literal 15; use STORY_KEYS.length instead so future schema changes cannot leave validation and diagnostics inconsistent.

Proposed refactor
-    if (!exactKeys(story, STORY_KEYS)) errors.push(`${story.id} must have exactly the 15 story fields`);
+    if (!exactKeys(story, STORY_KEYS))
+      errors.push(`${story.id} must have exactly the ${STORY_KEYS.length} story fields`);

-      errors.push(`${story.id} front matter must use exactly the 15 canonical fields`);
+      errors.push(`${story.id} front matter must use exactly the ${STORY_KEYS.length} canonical fields`);

-      errors.push(`${story.id} front matter must exactly match all 15 track fields`);
+      errors.push(`${story.id} front matter must exactly match all ${STORY_KEYS.length} track fields`);

Also applies to: 1044-1046

🤖 Prompt for 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.

In `@scripts/check-delivery-track.mjs` at line 939, Update the diagnostic messages
in the story validation logic, including the locations around the exact-key
check and lines 1044-1046, to derive the reported field count from
STORY_KEYS.length instead of the literal 15. Keep the existing validation
behavior and message context unchanged.
🤖 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/delivery/greenfield/delivery-policy.md`:
- Around line 136-143: Revise Rule 16 to prohibit only delivery-process
provenance/assertion state and generated evidence identifiers, not all story IDs
or branch references. Explicitly exempt canonical story paths such as the
story_file field and docs/delivery/greenfield/stories/GF-*.md, along with
ordinary repository and CI configuration, while preserving restrictions on
committed delivery state artifacts.

---

Nitpick comments:
In `@scripts/check-delivery-track.mjs`:
- Line 939: Update the diagnostic messages in the story validation logic,
including the locations around the exact-key check and lines 1044-1046, to
derive the reported field count from STORY_KEYS.length instead of the literal
15. Keep the existing validation behavior and message context unchanged.
🪄 Autofix (Beta)

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: CHILL

Plan: Pro Plus

Run ID: 717ca262-adfc-4973-9d48-c8ff9d9638d6

📥 Commits

Reviewing files that changed from the base of the PR and between 17eff4f and f2092ae.

📒 Files selected for processing (55)
  • docs/delivery/greenfield/delivery-policy.md
  • docs/delivery/greenfield/reviewer/review-checklist.md
  • docs/delivery/greenfield/stories/GF-001.md
  • docs/delivery/greenfield/stories/GF-002.md
  • docs/delivery/greenfield/stories/GF-003.md
  • docs/delivery/greenfield/stories/GF-004.md
  • docs/delivery/greenfield/stories/GF-005.md
  • docs/delivery/greenfield/stories/GF-010.md
  • docs/delivery/greenfield/stories/GF-011.md
  • docs/delivery/greenfield/stories/GF-012.md
  • docs/delivery/greenfield/stories/GF-013.md
  • docs/delivery/greenfield/stories/GF-014.md
  • docs/delivery/greenfield/stories/GF-015.md
  • docs/delivery/greenfield/stories/GF-019.md
  • docs/delivery/greenfield/stories/GF-020.md
  • docs/delivery/greenfield/stories/GF-021.md
  • docs/delivery/greenfield/stories/GF-022.md
  • docs/delivery/greenfield/stories/GF-023.md
  • docs/delivery/greenfield/stories/GF-024.md
  • docs/delivery/greenfield/stories/GF-025.md
  • docs/delivery/greenfield/stories/GF-026.md
  • docs/delivery/greenfield/stories/GF-030.md
  • docs/delivery/greenfield/stories/GF-031.md
  • docs/delivery/greenfield/stories/GF-032.md
  • docs/delivery/greenfield/stories/GF-033.md
  • docs/delivery/greenfield/stories/GF-034.md
  • docs/delivery/greenfield/stories/GF-035.md
  • docs/delivery/greenfield/stories/GF-036.md
  • docs/delivery/greenfield/stories/GF-037.md
  • docs/delivery/greenfield/stories/GF-038.md
  • docs/delivery/greenfield/stories/GF-039.md
  • docs/delivery/greenfield/stories/GF-040.md
  • docs/delivery/greenfield/stories/GF-041.md
  • docs/delivery/greenfield/stories/GF-042.md
  • docs/delivery/greenfield/stories/GF-043.md
  • docs/delivery/greenfield/stories/GF-044.md
  • docs/delivery/greenfield/stories/GF-045.md
  • docs/delivery/greenfield/stories/GF-046.md
  • docs/delivery/greenfield/stories/GF-047.md
  • docs/delivery/greenfield/stories/GF-050.md
  • docs/delivery/greenfield/stories/GF-051.md
  • docs/delivery/greenfield/stories/GF-052.md
  • docs/delivery/greenfield/stories/GF-053.md
  • docs/delivery/greenfield/stories/GF-054.md
  • docs/delivery/greenfield/stories/GF-055.md
  • docs/delivery/greenfield/stories/GF-056.md
  • docs/delivery/greenfield/stories/GF-057.md
  • docs/delivery/greenfield/stories/GF-060.md
  • docs/delivery/greenfield/stories/GF-061.md
  • docs/delivery/greenfield/stories/GF-062.md
  • docs/delivery/greenfield/story-contract.md
  • docs/delivery/greenfield/track.json
  • docs/delivery/greenfield/verification.md
  • scripts/check-delivery-track.mjs
  • scripts/check-delivery-track.test.mjs
💤 Files with no reviewable changes (32)
  • docs/delivery/greenfield/stories/GF-013.md
  • docs/delivery/greenfield/stories/GF-020.md
  • docs/delivery/greenfield/stories/GF-003.md
  • docs/delivery/greenfield/stories/GF-026.md
  • docs/delivery/greenfield/stories/GF-002.md
  • docs/delivery/greenfield/stories/GF-022.md
  • docs/delivery/greenfield/stories/GF-050.md
  • docs/delivery/greenfield/stories/GF-025.md
  • docs/delivery/greenfield/stories/GF-055.md
  • docs/delivery/greenfield/stories/GF-062.md
  • docs/delivery/greenfield/stories/GF-046.md
  • docs/delivery/greenfield/stories/GF-019.md
  • docs/delivery/greenfield/stories/GF-040.md
  • docs/delivery/greenfield/stories/GF-061.md
  • docs/delivery/greenfield/stories/GF-023.md
  • docs/delivery/greenfield/stories/GF-051.md
  • docs/delivery/greenfield/stories/GF-021.md
  • docs/delivery/greenfield/stories/GF-010.md
  • docs/delivery/greenfield/stories/GF-004.md
  • docs/delivery/greenfield/stories/GF-043.md
  • docs/delivery/greenfield/stories/GF-047.md
  • docs/delivery/greenfield/stories/GF-030.md
  • docs/delivery/greenfield/stories/GF-045.md
  • docs/delivery/greenfield/stories/GF-037.md
  • docs/delivery/greenfield/stories/GF-057.md
  • docs/delivery/greenfield/stories/GF-036.md
  • docs/delivery/greenfield/stories/GF-044.md
  • docs/delivery/greenfield/stories/GF-035.md
  • docs/delivery/greenfield/stories/GF-041.md
  • docs/delivery/greenfield/stories/GF-011.md
  • docs/delivery/greenfield/stories/GF-001.md
  • docs/delivery/greenfield/track.json

Comment thread docs/delivery/greenfield/delivery-policy.md Outdated
@aryeko
aryeko merged commit ef16251 into main Jul 26, 2026
2 checks passed
@aryeko
aryeko deleted the policy/drop-per-story-evidence branch July 26, 2026 22:56
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