Skip to content

docs(rev): split guide chronology and task locking contracts#156

Merged
abiorh-claw merged 11 commits into
mainfrom
codex/ws-rev-001-02a-split-contracts
Jul 19, 2026
Merged

docs(rev): split guide chronology and task locking contracts#156
abiorh-claw merged 11 commits into
mainfrom
codex/ws-rev-001-02a-split-contracts

Conversation

@Abiorh001

@Abiorh001 Abiorh001 commented Jul 19, 2026

Copy link
Copy Markdown
Collaborator

PR Trust Bundle: WS-REV-001-02A

Chunk

WS-REV-001-02A - Guide Chronology And Task Locking Split.

Goal

Replace one oversized L1 runtime contract with three independently reviewable
and explicitly started children, without implementing runtime behavior.

Human-approved intent

Preserve one Project Guide pipeline, exact Task-bound guide context,
canonical-human approval provenance, immutable chronology, and the existing
separation between checker remediation and Review-rooted human revision. Do not
start any runtime child from this planning parent.

What changed

  • Converted parent 02A into a permanently non-executable planning split.
  • Added complete contracts for 02A1 Project/setup publication fencing, 02A3
    guide activation chronology, and 02A4 Task guide triplet screening.
  • Reconciled the initiative plan, decisions, risks, discovery, conformance,
    source manifest, test design, status, review log, and downstream gates.
  • Preserved the existing deferred 02A2 prepared-guide reactivation identity.
  • Added exactly one schema-v2 merge intent naming 02A1 with explicit start.

Why it changed

Required L1 preimplementation review found that the former contract crossed
three independent PostgreSQL concurrency and migration boundaries: the complete
Project/setup writer fence, canonical-human guide chronology, and Task guide
triplet screening. Those boundaries could not receive credible migration,
direct-SQL, race, rollback, downgrade, coverage, and human review proof in one
PR.

Design chosen

02A1 serializes every current setup writer through a Project-first publication
fence. 02A3 builds immutable per-Project activation chronology and canonical
human provenance on that fence. 02A4 then stamps and protects the exact Task
guide triplet after chronology exists. The later 02A2 remains separately gated
after chunk 08 for hidden prepared superseded-guide reactivation.

Alternatives rejected

  • No combined two-migration runtime PR crossing all three boundaries.
  • No guide activation before all setup writers share the publication fence.
  • No current/latest fallback for ambiguous guide or Task history.
  • No duplicated AUTH actor/profile lifecycle logic or ad hoc identity guards.
  • No public superseded-guide reactivation in 02A3.
  • No automatic start of 02A1 or any later child.

Scope control

The full PR changes 21 Markdown files under the REV initiative and one
merge-intent JSON file. This includes the internal evidence, trust bundle, and
external-review response added after the original 19-path planning candidate.
It changes no backend code, model, schema, migration, service, route, worker,
test, dependency, CI workflow, frozen reference specification, active product
document, or AUTH/ART/CON owner artifact.

Product behavior

This PR activates no product behavior. Current guide activation continues to
reject an already-active candidate. Task guide storage and screening remain
unchanged. Stored Review decisions remain only accept, needs_revision, and
reject, and adjudication remains deferred beyond v0.1.

Acceptance criteria proof

The parent records exact merged AUTH dependencies and the sole migration head.
Its historical start head was 0027_contributor_foundation; the conflict-free
publication rebase onto ART PR #154 advances the current sole head to
0028_artifact_admission without adding a Project/setup writer.
Every child specifies allowed and prohibited files, lock order, race and
rollback proof, coverage floors, required reviewers, human focus, and a stop
condition. Migration-owning children 02A3 and 02A4 additionally specify their
database objects, migration refusal, direct-SQL parity, and downgrade rules.
The merge intent names only same-initiative successor 02A1 and requires a
separate human start.

Tests/checks run

All four stale-contract scanners, Markdown links, loop-memory state, 88 agent
gate tests, docstring coverage at 90.5 percent, one-head Alembic verification,
schema-v2 merge-intent validation, scope checks, ancestry checks, and diff
integrity passed on the planning candidate.

Test delta

No executable test changed. No assertion, skip, xfail, test command, coverage
floor, or CI gate was removed or weakened.

CI integrity

No CI or package-script file changed. The repository-wide 78 percent baseline
and independent 90 percent minimum for future new or materially changed backend
subsystems remain explicit in the executable child contracts.

Reviewer results

Senior engineering, QA/test, security/auth, product/ops, architecture, docs,
reuse/dedup, test delta, and CI integrity all pass on rebased planning SHA
73a6c31ffb54a11cd22992dd3b6d0de5413d7e05 against ART-merged trusted base
44f2467cedc266d2efe261119cfff436ac6b7715. The circuit breaker approved the
planning-only size exception because every executable boundary is split and
separately gated.

External review

After the prior review cycle passed, ART PR #154 merged and PR #156 rebased
without conflict onto trusted main 44f2467c. This rewrote every branch SHA;
all prior GitHub/CodeRabbit results are historical. The rebased candidate has
now passed exact-SHA internal review and evidence rebinding; it must still be
force-pushed and pass fresh final-head external checks.

On prior pushed head 8f12f656, GitHub Backend and Agent Gates passed, and
CodeRabbit passed with one actionable source-manifest finding: a historical
PLAN2 AUTH-09D-A/0026 review-base sentence could be mistaken for the later
parent 02A start. The repair labels that snapshot as historical and restates the
full 02A trusted-main SHA, 0027_contributor_foundation head, and
then-current-head child allocation rule.
Fresh deterministic and internal review evidence passes for the repaired
candidate. At evidence head ebb8db88, Agent Gates passed, Backend remained
pending, and CodeRabbit's evidence-status comment required this repair. Merge is
blocked until all GitHub and CodeRabbit checks pass on the final pushed head with
no unresolved actionable comment. Human review remains pending.
On the ART-rebased head, CodeRabbit also found that the Revision-context
conformance row omitted deferred owner 02A2. The row now includes 02A2 and its
prepared If-Match-protected superseded-guide reactivation proof; runtime and
the explicit-start gate are unchanged. Exact-SHA internal review and evidence
rebinding pass for that repaired candidate.

Remaining risks

Historical chronology or Task context ambiguity must fail closed in future
migrations. ART's generic admission foundation is merged, while remaining ART
review capabilities and CON capabilities remain dependency-owned future work. All
24 planned REV action dependencies remain unavailable. Later duration and human
revision exhaustion semantics still require explicit human decisions.

Follow-up work

After merge, automated loop memory may name 02A1 with an explicit-start gate.
02A1 must refresh trusted main, the complete writer inventory, migration head,
plan review, and reviewer routing before any implementation. 02A3, 02A4, 02A2,
and 02B remain separately gated successors.

Human review focus

Review the split boundaries and order, complete writer-fence inventory,
canonical-human ownership, immutable chronology, migration refusal/downgrade
safety, Task triplet integrity, and the absence of runtime changes.

Human merge ownership

Only the user may approve and merge this specific PR. Merge does not authorize
02A1 or any other runtime implementation. Do not merge while any current-head
GitHub or CodeRabbit check is pending or failed, or while an actionable review
comment remains unresolved.

@coderabbitai

coderabbitai Bot commented Jul 19, 2026

Copy link
Copy Markdown

Review Change Stack

📝 Walkthrough

Walkthrough

WS-REV-001 parent 02A is now a planning-only split. Executable work is divided into 02A1, 02A3, and 02A4, while 02A2 remains deferred. Lifecycle documentation, dependency baselines, review evidence, downstream prerequisites, and explicit-start metadata were updated.

Changes

REV-02A lifecycle planning

Layer / File(s) Summary
Baseline and lifecycle gates
.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/{CHUNK_MAP.md,CONFORMANCE_MATRIX.md,DECISIONS.md,DISCOVERY.md,PLAN.md,REVIEW_LOG.md,RISKS.md,SOURCE_MANIFEST.md,STATUS.md,TEST_DESIGN_WS-REV-001-02.md}
Trusted-main facts, contributor-foundation provenance, child ordering, stop conditions, review outcomes, risks, and test ownership are updated for the revised 02A lifecycle.
Parent split contract and evidence
.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/chunks/WS-REV-001-02-review-policy-task-alignment.md, .agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/chunks/WS-REV-001-02A-guide-activation-sequence.md, .agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/reviews/*, .agent-loop/merge-intents/WS-REV-001-02A.json
Parent 02A is restricted to planning and dependency proof, with trust-bundle evidence and schema-v2 merge metadata defining separately gated child work.
Executable child specifications
.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/chunks/WS-REV-001-02A1-project-setup-publication-fence.md, .agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/chunks/WS-REV-001-02A3-guide-activation-chronology.md, .agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/chunks/WS-REV-001-02A4-task-guide-triplet-screening.md
02A1, 02A3, and 02A4 specify their fencing, chronology, triplet, migration, concurrency, acceptance, and verification contracts.
Deferred reactivation and downstream prerequisites
.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/chunks/WS-REV-001-02A2-prepared-guide-reactivation.md, .agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/chunks/WS-REV-001-02B-review-policy-task-lifecycle.md, .agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/chunks/WS-REV-001-02C-submission-attribution-lineage.md
02A2 now depends on the separated child set and chunk 08, while 02B and 02C consume the revised chronology and task-stamping boundaries.

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

Possibly related PRs

Suggested reviewers: abiorh-claw

🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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.
Title check ✅ Passed The title clearly matches the main change: splitting guide chronology and task locking contracts in REV docs.
Description check ✅ Passed The description is mostly complete and covers the required sections, with only minor template formatting differences.
✨ 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 codex/ws-rev-001-02a-split-contracts

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

🤖 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
@.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/SOURCE_MANIFEST.md:
- Around line 225-238: Update the 02A split review-base records to distinguish
the historical AUTH-09D-A/0026 review base from the actual trusted-main start at
migration 0027_contributor_foundation. Use the full 0027 commit SHA consistently
in the later post-rebase review-base section, ensuring child migration
allocation starts from that trusted head rather than the stale 0026 commit.
🪄 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: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: b53714e9-bfc4-4d28-b391-4fc296fdfe0d

📥 Commits

Reviewing files that changed from the base of the PR and between 8d5eb15 and 8f12f65.

📒 Files selected for processing (21)
  • .agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/CHUNK_MAP.md
  • .agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/CONFORMANCE_MATRIX.md
  • .agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/DECISIONS.md
  • .agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/DISCOVERY.md
  • .agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/PLAN.md
  • .agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/REVIEW_LOG.md
  • .agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/RISKS.md
  • .agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/SOURCE_MANIFEST.md
  • .agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/STATUS.md
  • .agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/TEST_DESIGN_WS-REV-001-02.md
  • .agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/chunks/WS-REV-001-02-review-policy-task-alignment.md
  • .agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/chunks/WS-REV-001-02A-guide-activation-sequence.md
  • .agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/chunks/WS-REV-001-02A1-project-setup-publication-fence.md
  • .agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/chunks/WS-REV-001-02A2-prepared-guide-reactivation.md
  • .agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/chunks/WS-REV-001-02A3-guide-activation-chronology.md
  • .agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/chunks/WS-REV-001-02A4-task-guide-triplet-screening.md
  • .agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/chunks/WS-REV-001-02B-review-policy-task-lifecycle.md
  • .agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/chunks/WS-REV-001-02C-submission-attribution-lineage.md
  • .agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/reviews/WS-REV-001-02A-internal-review-evidence.md
  • .agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/reviews/WS-REV-001-02A-pr-trust-bundle.md
  • .agent-loop/merge-intents/WS-REV-001-02A.json

@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

🤖 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
@.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/reviews/WS-REV-001-02A-external-review-response.md:
- Around line 48-49: The external-review response document must identify the
stale-SHA result as historical or replace it with final evidence for the
repaired candidate. In
.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/reviews/WS-REV-001-02A-external-review-response.md
lines 48-49, update the evidence status accordingly; in
.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/reviews/WS-REV-001-02A-pr-trust-bundle.md
lines 102-116, explicitly block merge until current-head GitHub/CodeRabbit
rechecks and evidence rebinding are complete, or record their completed results.
🪄 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: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 9cb87c74-33c7-4eb3-a55b-f02f2fc7bf96

📥 Commits

Reviewing files that changed from the base of the PR and between 8f12f65 and ebb8db8.

📒 Files selected for processing (5)
  • .agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/REVIEW_LOG.md
  • .agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/SOURCE_MANIFEST.md
  • .agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/reviews/WS-REV-001-02A-external-review-response.md
  • .agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/reviews/WS-REV-001-02A-internal-review-evidence.md
  • .agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/reviews/WS-REV-001-02A-pr-trust-bundle.md
🚧 Files skipped from review as they are similar to previous changes (3)
  • .agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/SOURCE_MANIFEST.md
  • .agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/REVIEW_LOG.md
  • .agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/reviews/WS-REV-001-02A-internal-review-evidence.md

@Abiorh001
Abiorh001 force-pushed the codex/ws-rev-001-02a-split-contracts branch from 1c2706a to b4a2b07 Compare July 19, 2026 17:02

@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

🤖 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
@.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/CONFORMANCE_MATRIX.md:
- Line 14: Update the “Revision context” entry in CONFORMANCE_MATRIX.md to
include deferred chunk 02A2, preserving the existing ownership and invariant
descriptions. Ensure prepared If-Match-protected superseded-guide reactivation
is explicitly owned by 02A2 or clearly reassigned to another chunk.
🪄 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: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: d1881882-4ae0-460d-b9ba-1b4bd1124dec

📥 Commits

Reviewing files that changed from the base of the PR and between ebb8db8 and b4a2b07.

📒 Files selected for processing (22)
  • .agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/CHUNK_MAP.md
  • .agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/CONFORMANCE_MATRIX.md
  • .agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/DECISIONS.md
  • .agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/DISCOVERY.md
  • .agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/PLAN.md
  • .agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/REVIEW_LOG.md
  • .agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/RISKS.md
  • .agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/SOURCE_MANIFEST.md
  • .agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/STATUS.md
  • .agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/TEST_DESIGN_WS-REV-001-02.md
  • .agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/chunks/WS-REV-001-02-review-policy-task-alignment.md
  • .agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/chunks/WS-REV-001-02A-guide-activation-sequence.md
  • .agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/chunks/WS-REV-001-02A1-project-setup-publication-fence.md
  • .agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/chunks/WS-REV-001-02A2-prepared-guide-reactivation.md
  • .agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/chunks/WS-REV-001-02A3-guide-activation-chronology.md
  • .agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/chunks/WS-REV-001-02A4-task-guide-triplet-screening.md
  • .agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/chunks/WS-REV-001-02B-review-policy-task-lifecycle.md
  • .agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/chunks/WS-REV-001-02C-submission-attribution-lineage.md
  • .agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/reviews/WS-REV-001-02A-external-review-response.md
  • .agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/reviews/WS-REV-001-02A-internal-review-evidence.md
  • .agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/reviews/WS-REV-001-02A-pr-trust-bundle.md
  • .agent-loop/merge-intents/WS-REV-001-02A.json
🚧 Files skipped from review as they are similar to previous changes (16)
  • .agent-loop/merge-intents/WS-REV-001-02A.json
  • .agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/chunks/WS-REV-001-02B-review-policy-task-lifecycle.md
  • .agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/chunks/WS-REV-001-02C-submission-attribution-lineage.md
  • .agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/RISKS.md
  • .agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/chunks/WS-REV-001-02A3-guide-activation-chronology.md
  • .agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/CHUNK_MAP.md
  • .agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/chunks/WS-REV-001-02-review-policy-task-alignment.md
  • .agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/chunks/WS-REV-001-02A4-task-guide-triplet-screening.md
  • .agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/reviews/WS-REV-001-02A-internal-review-evidence.md
  • .agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/DECISIONS.md
  • .agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/SOURCE_MANIFEST.md
  • .agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/PLAN.md
  • .agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/chunks/WS-REV-001-02A1-project-setup-publication-fence.md
  • .agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/TEST_DESIGN_WS-REV-001-02.md
  • .agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/REVIEW_LOG.md
  • .agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/chunks/WS-REV-001-02A-guide-activation-sequence.md

@abiorh-claw
abiorh-claw self-requested a review July 19, 2026 17:28
@abiorh-claw
abiorh-claw merged commit 3b1d637 into main Jul 19, 2026
4 checks passed
github-actions Bot pushed a commit that referenced this pull request Jul 19, 2026
@abiorh-claw
abiorh-claw deleted the codex/ws-rev-001-02a-split-contracts branch July 19, 2026 18:06
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.

2 participants