C1-A04 follow-up — Complete execution-boundary ref contract

[LogicDuke]

Purpose

Third-level quarantined validation repair for the CURRENT execution-boundary
contract findings discovered during post-Ready review of PR #35.

This PR is intentionally stacked directly on PR #35.

Required base:

repair/c1-a04-symref-claim

Required head:

repair/c1-a04-exec-boundary-contract

It MUST NOT target PR #21, PR #14, or main.

Verified root-cause set

A fresh closure audit classified the post-Ready finding cluster into three
CURRENT contract defects:

• R1 / P2 — validated ref operand is not necessarily the effective mutation
  target, and a resolve/check/mutate sequence is not an atomic security
  guarantee;
• R2 / P3 — the compared repository identity was ambiguous between effective
  ref-name/symbolic-referent identity and commit-object/OID identity;
• R3 / P3 — repository-resolution/effective-identity obligations were scoped
  too narrowly to ref-mutating operations and did not fully cover
  repair.change_request source/target direction.

Codex findings concerning TOCTOU and worktree HEAD binding collapse into R1.
The closure audit also identified push-destination/refspec binding as another
R1 surface.

Repair

This patch completes the future trusted repository/Git execution-boundary
contract.

It requires:

• repair.commit to bind the authorized worktree's effective HEAD referent to
  the authorized repair ref and fail closed on detached/wrong/indeterminate
  binding;
• repair.push to bind the effective destination to the authorized repair ref
  and prevent destination-refspec redirection;
• mutation/receiving-boundary enforcement that does not rely on a vulnerable
  resolve-then-use pre-check;
• the relevant repository identity to mean effective/terminal ref-name
  referent identity, not commit-object/OID equality;
• symbolic/effective aliases to the protected parent to fail closed;
• repair.change_request effective source to be the authorized repair ref and
  effective target to be the protected parent.

No implementation mechanism such as a specific Git command, lock, or
transaction API is prescribed.

Scope

Changed files exactly:

• docs/architecture/C1-repair-job-authority.md
• src/domain/repair-job.ts

src/domain/repair-job.ts changes are comments/TSDoc only.

No runtime behavior, type, API, operation, permit operand, or execution
authority changes.

C1 remains pure TypeScript.

Independent validation

Result:

PASS

Validated commit:

fc49e9aa81f949807dd9d5b2acc4afbd792032e1

Validated parent:

c743b65217cee372ba259cd4a1890469d529eed9

Validated binary patch SHA-256:

C1F34683764706F6257DD557B66B534554F85617617A841038B3CD3163E474E9

Validated patch bytes:

12891

Independent validation proved:

• exact changed files only;
• zero executable TypeScript token changes;
• 2939 executable tokens before / 2939 after;
• token diffs: 0;
• git diff --check PASS;
• typecheck PASS;
• lint PASS;
• full suite PASS: 882 tests / 15 files;
• build PASS;
• npm audit: 0 vulnerabilities;
• 10/10 adversarial contract cases PASS;
• validator made zero edits;
• patch fingerprint remained byte-identical before and after validation.

Preserved boundaries

• original C1-A04 textual alias protection remains intact;
• C1 remains pure TypeScript;
• no Git/filesystem/network/subprocess authority is added;
• no new execution authority is granted;
• force-push protection is unchanged;
• merge remains operator-only;
• auto-merge remains forbidden;
• PR C1-A04 follow-up — Clarify symbolic-ref resolution boundary #35 remains protected from direct AI repair;
• PR C1-A04 — Reject Git-equivalent protected/repair refs #21 remains untouched;
• PR Cockpit C1 — Repair Job Authority Envelope & Merge Barrier #14 remains untouched.

Quarantine

Required flow:

this DRAFT child
→ exact-head CI
→ independent GitHub reviews
→ classify every finding
→ policy/evidence gate
→ Ready
→ post-Ready observation
→ PASS: human CREATE A MERGE COMMIT upward into PR #35 branch
→ establish PR #35 NEW HEAD
→ fresh PR #35 audit

FAIL means this child remains quarantined/rejected and PR #35 stays untouched.

MERGE IS OPERATOR-ONLY.

No AI may merge this PR or enable auto-merge.

Maximum autonomous state:

READY_FOR_MERGE

Summary by CodeRabbit

• Documentation
  • Clarified branch and change-request safety requirements.
  • Documented validation of symbolic references, effective mutation targets, and change-request direction.
  • Expanded protected-parent safeguards to cover worktree heads, push destinations, unresolved targets, and concurrent changes.
  • Clarified that commit equality alone does not establish branch protection.
  • Documented role-specific reference requirements and fail-closed behavior for unstable or unauthorized targets.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 0e380fae-330a-4ece-a7c6-c3d84f7d0f2f

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

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: be7d6070-55e7-4309-ae89-99319334d4c4

📥 Commits

Reviewing files that changed from the base of the PR and between fc49e9a and c8fde78.

📒 Files selected for processing (2)

• docs/architecture/C1-repair-job-authority.md
• src/domain/repair-job.ts

Included review availability: Your plan provides up to 1 included review per hour; 0 remain after this review.

---

📝 Walkthrough

Walkthrough

The documentation defines trusted execution requirements for resolving symbolic refs, binding effective mutation targets, validating change-request direction, and enforcing protected-parent safeguards at mutation or receiving time.

Changes

Ref authority documentation

Layer / File(s)	Summary
Domain ref contract src/domain/repair-job.ts	The branch-reference documentation requires trusted resolution of symbolic refs and effective targets. It defines fail-closed behavior for protected, changed, or unresolved identities and limits mayDenoteSameBranchRef to canonical ref-name comparison.
Execution boundary and quarantine docs/architecture/C1-repair-job-authority.md	The architecture document covers commit and push target binding, change-request direction checks, atomic ref validation, canonical-ref limitations, and protected-parent quarantine rules.

Estimated code review effort: 2 (Simple) | ~10 minutes

Merge Risk: ⚪ Minimal · up to c8fde

This change clarifies the execution-boundary contract without changing runtime behavior or execution authority; no actionable merge-blocking risk remains after normal checks and review.

Poem

A rabbit checks each branch with care,
Resolves the paths through frosty air.
No hidden target slips from sight,
Protected roots stay locked up tight.
At mutation time, the rules hold bright.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the documentation changes that complete the execution-boundary ref contract.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
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

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch repair/c1-a04-exec-boundary-contract

---

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.}

[LogicDuke]

@codex review

[LogicDuke]

@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.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: fc49e9aa81

ℹ️ 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".

[LogicDuke]

@codex review

[LogicDuke]

@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.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: c8fde78b27

ℹ️ 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".

[LogicDuke]

@codex review

[LogicDuke]

@coderabbitai review

[coderabbitai]

⚠️ Action not completed

Review rate limited.

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.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 838d8edf31

ℹ️ 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".

[LogicDuke]

@codex review

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Can't wait for the next one!

Reviewed commit: 6fa3e95ff5

ℹ️ 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".

[LogicDuke]

@coderabbitai review

[coderabbitai]

❌ Action failed

Review failed.

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.

[LogicDuke]

@coderabbitai review

[coderabbitai]

⚠️ Action not completed

Review rate limited.

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.