docs(xint): correct guide ingest activation contract

[Abiorh001]

Workstream PR Trust Bundle

Chunk

WS-XINT-002-04A planning correction - Correct guide-ingest activation contract

Goal

Make the 04A contract executable and fail-closed before implementation by restoring the canonical Project Manager policy surface and exact ART lineage-lock boundary omitted from the original contract.

Intent And Planning Context

• Intent: activate only artifact.guide_source.ingest through the canonical PREP seam after ART-03A.
• Chunk contract: .agent-loop/initiatives/WS-XINT-002-art-auth-end-to-end/chunks/WS-XINT-002-04A-guide-ingest-activation.md

What Changed

• Recorded merged ART-03A as entry evidence.
• Added the canonical Project Manager policy and ART lineage-lock files required by the acceptance criteria.
• Clarified covered Project Manager semantics: active system-scoped authority or active exact-project authority.
• Narrowly permitted the ART-owned draft-lineage lock correction and assigned custody to 04A.

Why It Changed

Pre-implementation architecture, security, product, QA, CI, and senior reviews found that the original allowed-file boundary could not safely satisfy its own authorization and stale-lineage acceptance criteria.

Design Chosen

Repair the planning contract first, in a planning-only PR, then stack the bounded implementation behind it.

Alternatives Rejected

• Implement outside the stated file boundary: rejected because it would violate the chunk contract.
• Skip the canonical policy update: rejected because the action would not be owned by the Project Manager role.
• Trust only snapshot/item locks: rejected because project and draft-guide lineage could become stale.

Scope Control

Allowed Files Changed

• .agent-loop/initiatives/WS-XINT-002-art-auth-end-to-end/PLAN.md
• .agent-loop/initiatives/WS-XINT-002-art-auth-end-to-end/STATUS.md
• .agent-loop/initiatives/WS-XINT-002-art-auth-end-to-end/chunks/WS-XINT-002-04A-guide-ingest-activation.md

Files Outside Stated Scope

• None

Product Behavior

• No Workstream product behavior changed.
• Product behavior changed and is explained here.

Evidence

Commands Run

• python scripts/check_stale_auth_docs.py
• python scripts/check_stale_artifact_contracts.py
• python scripts/check_markdown_links.py
• git diff --check

Result Summary

All planning-document checks passed. GitHub Agent Gates passed. CodeRabbit generated no actionable comments.

Acceptance Criteria Proof

• The contract now names the canonical Project Manager policy owner.
• The contract now permits exact project/draft-guide/snapshot/item locking.
• Covered system-scoped and exact-project grant behavior matches canonical policy.
• The correction remains planning-only.

Test Delta

Tests Added

• None; planning-only correction.

Tests Modified

• None.

Tests Removed Or Skipped

• None.

Internal Reviewer Results

Reviewed code SHA: 35b9bff

Reviewed at: 2026-07-28

Reviewer run IDs: pre-implementation 04A review fanout

Reviewer	Result	Blocking Findings	Notes
Senior engineering	PASS AFTER FIXES	None	Confirmed corrected boundary
QA/test	PASS AFTER FIXES	None	Acceptance criteria are now executable
Security/auth	PASS AFTER FIXES	None	Confirmed canonical covered-grant semantics
Product/ops	PASS AFTER FIXES	None	Confirmed Project Manager scope behavior
Architecture	PASS AFTER FIXES	None	Confirmed boundary correction
CI integrity	PASS	None	No gate changes
Docs	PASS	None	Planning documents are consistent
Reuse/dedup	PASS	None	No implementation duplication
Test delta	PASS	None	No tests changed

External Review

Source	Status	Notes
CodeRabbit	PASS	No actionable comments; description warning corrected
GitHub checks	IN PROGRESS	Agent Gates passed; hosted Backend suite running

CI And Gate Integrity

• No workflow weakening.
• No lint/test/docstring gate weakening.
• No coverage threshold weakening.
• No package script weakening.
• No unpinned new GitHub Action.
• Checkout credential persistence disabled where checkout is used.

Remaining Risks

The planning correction does not itself activate guide ingestion. Activation remains isolated in stacked PR #218 and requires its own exact-head CI and external review after retargeting to main.

Follow-Up Work

Merge this planning correction after hosted checks and human approval, retarget PR #218 to main, then rerun CodeRabbit and all hosted checks on the implementation head.

Human Review Focus

Please inspect:

• Canonical covered Project Manager semantics.
• The narrowly expanded allowed-file boundary.
• Exact project/draft-guide/snapshot/item lock requirements.

Human Merge Ownership

• I can explain what changed.
• I can explain why it changed.
• I know what could break.
• I accept the remaining risks.
• The user explicitly approved this specific PR for merge.

[coderabbitai]

📝 Walkthrough

Walkthrough

Updates WS-XINT-002 planning and status documentation for guide-ingest authorization, including covered Project Manager authority, activation scope and criteria, canonical permission ownership, and completed-state notes for the 04A/04B split.

Changes

Guide ingest authorization

Layer / File(s)	Summary
Guide-ingest activation contract .agent-loop/initiatives/WS-XINT-002-art-auth-end-to-end/PLAN.md, .agent-loop/initiatives/WS-XINT-002-art-auth-end-to-end/chunks/WS-XINT-002-04A-guide-ingest-activation.md	Authority wording now uses a covered Project Manager grant; the activation contract expands allowed files, narrows prohibited catalog changes to new identifiers, and requires canonical permission ownership with system-scoped or exact-project conditions.
Completion-state record .agent-loop/initiatives/WS-XINT-002-art-auth-end-to-end/STATUS.md	The 04B/04A status notes reference the merged PREP-compatible seam and identify the two corrections required before guide-ingest activation.

Estimated code review effort: 1 (Trivial) | ~5 minutes

Possibly related PRs

• Flow-Research/workstream#209: Updates the same guide-ingest permission and activation planning records.
• Flow-Research/workstream#213: Introduces the related 04A/04B split and activation contract.

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 is concise and accurately reflects the planning-only guide-ingest contract correction.
Description check	✅ Passed	The PR description follows the template and covers goal, context, scope, evidence, acceptance criteria, reviewers, and risks.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/ws-xint-002-04a-contract-repair

---

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

• X
• Mastodon
• Reddit
• LinkedIn

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

[Abiorh001]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.