Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions CODESTYLE.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,7 @@ Each language defines a **clean-compile** verification: the combination of build
### Operations and Failure Messages

- **Let the real operation be the check, not a prediction of it.** Attempt the read, the write, or the call itself, and turn its failure into a clean refusal. Do not probe first with an existence, type, or permission test. Where the operation could block or succeed on the wrong kind of target, judge what it opened instead. A probe is a second model of the operation. It misjudges each case its author did not foresee, such as a dangling link, a link loop, or a platform's own permission model. The operation cannot disagree with itself.
- **Classify a subprocess failure by which command failed and the status code it reports, never by the wording of its message.** That wording varies by tool version and locale, and a status code does not, even one printed inside the message. Where one command's status code cannot separate an expected failure from an unexpected one, split it into real operations, one per failure.
- **A failure message states the error, the path or other target, and the remedy, and claims nothing about the state the failure left.** The error the operation raised is the one fact the code holds at that point. A description of what the failure left behind is a prediction. It reads false once an unforeseen state reaches the message, such as a file written in full that then fails to close. A remedy such as "fix what it names, then re-run" needs no such claim.

### Command-Line Arguments
Expand Down
17 changes: 16 additions & 1 deletion host-setup/agent-safety/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -179,7 +179,22 @@ text says, because the harm it covers was never in the text.
A command naming git or gh that holds a carriage return is denied, since the shell reads one
as part of a word. So is one holding a word that a backslash-newline splits. So is one holding
an escaped backslash before a line break. The shell reads that as a line break where the hook
would join the lines, and as a continuation inside a double-quoted wrapper body. Two comments whose
would join the lines, and as a continuation inside a double-quoted wrapper body. Neither deny
reads a backslash-newline the outer shell keeps as text, where the hook can read it as a shell
running that text would. That is one inside single quotes in command text, including command
text in a `$(...)` substitution. It is also one ending a quoted heredoc's data line, unless the
delimiter line follows. It is not one inside `$'...'`, or single quotes within double quotes, a
backquote, or `${...}`. A Markdown hard line break in a quoted heredoc or a single-quoted body
is one. The single-quoted part must be its word's only quoted, escaped, or expanded part, with no
escaped word break just before it. Where the text names git, gh, or a push, it must also hold no
further quoting. Those names are read in the text as written, with its lines joined, and with
each one a line break. Each backslash-newline in that text must then sit in its command text or
end a comment there. The command is then read again as a shell running that text reads it,
joining the lines except where one ends a comment. It is also read with each one joined and with each one a line break, and denied where
any reading is. Every reading keeps each escaped backslash pair before a line break, which the
shell reads as one literal backslash. Nor does either read a single unquoted
backslash-newline between a command separator such as `&&` or `|` and a non-operator character,
which splits no word. Two comments whose
apostrophes pair up as one quoted span are read as the shell reads them, as comments. The
lines between them are then read as commands. Some words are read as they
stand. They are a directory option's literal or double-quoted value where the guard can read its quoting, a commit option's double-quoted value, a
Expand Down
Loading
Loading