Fix three documentation defects found by the final release audit - #5
Merged
Merged
Conversation
- README: the local control plane paragraph and the execution mode table claimed the user always performs the local switch, with no exception. The normative source (references/control-channel-safety.md rule 1) and the Chinese README both allow the agent to perform it on explicit request, one action at a time, after the recovery card. The English text now says the same instead of contradicting the contract it documents. - README: the suite is 414 tests, not 412; the two consent path tests added late in 0.4.0 were not reflected. - CHANGELOG: the 0.4.0 and 0.3.2 compare links pointed at a v0.3.2 tag that was never created, so both returned 404. 0.4.0 now compares from v0.3.1, and 0.3.2 links to the pull request that carried it, with a sentence explaining why it has no tag of its own. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 67b00c3672
ℹ️ 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".
| 1. **Risk resolved** (`decision: allow`). The target is proven independent of the agent's current path, or a complete automatic rollback contract covers every declared target. Proceed under normal authorisation: show impact, backup, verification, and rollback, then get an explicit yes. | ||
| 2. **Risk unresolved on a remote target** (`decision: warn`, `can_apply_with_acknowledgment: true`). The gate does not refuse. It presents a risk card: what breaks, the recovery path, the residual risks, and the safer alternatives. The change proceeds only after the user explicitly accepts the residual risk for that specific operation, via `--accept-residual-risk`, and the accepted risks are written into the receipt as `acknowledged_risks`. | ||
| 3. **Local control plane** (`execution_mode: manual-local-control-plane`, `can_apply_with_acknowledgment: false`). Switching local TUN, the system proxy, an active proxy process, DNS, routes, or the firewall stays outside the remote executor no matter what the user consents to, because consent cannot keep a socket open. The user performs that one switch; the agent confirms it is still online and then continues the remote work itself. | ||
| 3. **Local control plane** (`execution_mode: manual-local-control-plane`, `can_apply_with_acknowledgment: false`). Switching local TUN, the system proxy, an active proxy process, DNS, routes, or the firewall stays outside the remote executor no matter what the user consents to, because consent cannot keep a socket open. By default the user performs that one switch. If the user explicitly asks the agent to perform it and accepts the disconnection risk after seeing the recovery card, the agent may execute it locally, one action at a time; either way the agent confirms it is still online and then continues the remote work itself. |
There was a problem hiding this comment.
Replace this newly added local-delegation procedure with a pointer to the canonical reference rather than repeating the exception here and again in the execution-mode table. The repository requires control-channel and informed-consent rules to live only in references/control-channel-safety.md; duplicating the exact authorization and sequencing requirements in the README allows a future safety update to leave this user-facing copy stale.
AGENTS.md reference: AGENTS.md:L18-L22
Useful? React with 👍 / 👎.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Final audit findings, all documentation:
English README contradicted the safety contract it documents. The local control plane paragraph and the
execution_modetable said the user always performs the local switch, no exception. The normative source (references/control-channel-safety.md, hard rule 1) and the Chinese README both allow the agent to perform it on explicit request after the recovery card, one action at a time. An English reader would have concluded delegation is impossible, which is wrong. Now aligned with the single source.Test count drift: 412 → 414 (the two consent path tests landed after the sentence was written).
CHANGELOG compare links 404ed: both referenced a
v0.3.2tag that was never created.[0.4.0]now compares fromv0.3.1;[0.3.2]links to PR Release 0.4.0: informed-consent gate, independence protocol, publication assets #2 with a sentence explaining why it has no tag.Verified locally: docs contract and skill contract suites pass, secret scan clean.
🤖 Generated with Claude Code