Adopt ten records for design rulings, with the four orders between them by HackingGate · Pull Request #451 · HackingGate/uphold

HackingGate · 2026-10-27T12:57:15Z

Adds [decide] to this repository's policy, so uphold's own design questions are ruled from adopted records and not from the whole catalog. Until now the rulings on #429 and #450 escalated every conflict, because nothing ranked the records.

Adopted (10). Seven of these are the records this repository's code and docs already cite by id as a reason:

explicit-unknown
parameterize-do-not-enumerate
enforcement-needs-a-trigger
psychological-acceptability
single-authoritative-source
mechanism-policy-separation
least-power

The other three decided the #429 and #450 rulings: complete-mediation, fail-safe-defaults and economy-of-mechanism. The rest of the review list in AGENTS.md is left out, because nothing in the design argues from those records.

Orders (4), one per adopted pair that conflicts, each taken from a choice this repository already made:

prefer	over	precedent
fail-safe-defaults	psychological-acceptability	`unresolved = "refuse"` is the shim's default; `"run"` is the opt-out (`docs/REFERENCE.md`, the shim table)
explicit-unknown	psychological-acceptability	a hook with no policy stands its guards down and says so on stderr (`docs/REFERENCE.md`, "What runs where there is no policy")
psychological-acceptability	complete-mediation	same section: refusing routine work gets the matcher deleted, "and the seam's real coverage goes to zero"
least-power	parameterize-do-not-enumerate	`[stop] run` is argv with no shell, and a pipeline names a script (`src/config.rs`, `Stop`)

Checks.

uphold check exits 0 and lists the 10 records and 4 orders.
The Python suite: 189 tests, OK.
Hooks: pre-commit, commit-msg and pre-push passed.

After merge. #429 Q5 and #450 Q1 and Q3 are ruled again from the adopted set.

https://claude.ai/code/session_01BHpLckRt4BNGCdFG9vLyEP

Summary by CodeRabbit

Documentation
- Added design principles and prioritized decision rules for handling uncertain shim scope, unread text, blocked routine work, and [stop] run commands.

coderabbitai · 2026-10-27T12:57:54Z

Important

Review skipped

Review was skipped as selected files did not have any reviewable changes.

Run configuration

Source mode: Auto
Repository: Unavailable
Branch: Unavailable
File: No configuration file from this repository applied
Commit: Unavailable
Layers: defaults
Review profile: CHILL
Plan: Advanced
Run ID: 8fce24f1-f5d3-4488-84b5-03401170bab3

Commits

Reviewing files that changed from the base of the PR and between 4149d58 and aabb562.

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

Source mode: Auto
Repository: Unavailable
Branch: Unavailable
File: No configuration file from this repository applied
Commit: Unavailable
Layers: defaults
Review profile: CHILL
Plan: Advanced
Run ID: aae4171e-d25c-4422-b471-8912f5712dd2

Commits

Reviewing files that changed from the base of the PR and between 907eb95 and 4149d58.

Files selected for processing: 1

policy/principles.toml

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

Walkthrough

The change adds a [decide] policy section with eleven adopted design principles and four ordered preference rules. Each principle and rule includes a stated rationale.

Changes: Decision policy

Layer / File(s)	Summary
Adopted principles and precedence `policy/principles.toml`	The `[decide]` section adds eleven adopted principles and four ordered preference rules. Each includes a stated rationale.

Priority: Low

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

Change: Other

Possibly related issues

HackingGate/uphold#429 — The policy adopts records used in the hook-matcher ruling and orders psychological acceptability over complete mediation. The PR states that Q5 will be ruled again.
HackingGate/uphold#450 — The adopted principles and precedence rules cover the unresolved hook questions about default refusal, standing down, and routine refusal. The PR states that Q1 and Q3 will be ruled again.

Merge Risk: Minimal · previous review 4149d

The decision policy is consistent with the inspected configuration contract and catalog conflicts. No merge-blocking issue was identified.

Pre-merge checks: 5

Check name	Status	Explanation
Description Check		Check skipped - CodeRabbit’s high-level summary is enabled.
Title check		The title clearly describes the main change: adopting design records and defining four precedence orders. It is specific and related to the policy update.
Docstring Coverage		No eligible functions found in the changed files. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Documentation-only edits and deletions within survi…
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.

Full details: Docstring Coverage

Explanation

No eligible functions found in the changed files. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Documentation-only edits and deletions within surviving functions are included; unchanged diff context and fully deleted functions are excluded. Analyzed 0 functions across 0 files. (1 skipped: 1 unsupported.)

Finishing Touches: 💡 1

🛠️ Fix failing CI checks: 💡

Commit to this branch
Create a new PR

🧪 Generate unit tests (beta)

Commit to this branch
Create a new PR

Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

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

uphold-review · 2026-10-27T12:58:19Z

uphold-review

Walkthrough

This pull request adds a [decide] table to the repository's own policy file, policy/principles.toml. The table adopts ten catalog records for design rulings: explicit-unknown, parameterize-do-not-enumerate, enforcement-needs-a-trigger, psychological-acceptability, single-authoritative-source, mechanism-policy-separation, least-power, complete-mediation, fail-safe-defaults and economy-of-mechanism. It also adds four [[decide.order]] entries, one for each adopted pair that names the other in conflicts_with:

fail-safe-defaults over psychological-acceptability
explicit-unknown over psychological-acceptability
psychological-acceptability over complete-mediation
least-power over parameterize-do-not-enumerate

Each order has a why naming the earlier choice it follows. A comment above the table says how the set was chosen.

I checked each why against the source it cites:

docs/REFERENCE.md makes unresolved = "refuse" the shim's default, with "run" as the opt-out.
The "What runs where there is no policy" section of the same file says the guards stand down and print that to stderr. It also gives the reason: refusing routine work leads people to delete the matcher.
src/config.rs Stop takes argv with no shell, cites least-power, and has a command that needs a pipeline name a script.

The four orders cover exactly the conflicting adopted pairs in the catalog's conflicts_with fields. No order is over a pair that does not conflict or a record that is not adopted. uphold check's decided() refuses both of those cases, and the gate's check passed.

Changes

File	Change
`policy/principles.toml`	Adds a `[decide]` table that adopts ten catalog records for this repository's design rulings. Adds four `[[decide.order]]` entries, each with a `why` naming the existing design choice it follows. A comment above the table says how the set was chosen.

❌ uphold rules: uphold's rules refuse this · this repository's policy at `ccb8795`

Rule output

$ uphold scan
policy check failed: no-running-os-identity-metadata (hostname)
Do not commit identity metadata from the running OS. The scan reads the current
username, home path, hostname and default route at runtime, then searches the
tracked files for what it read. Use neutral placeholders instead --
example-user, example-host, example.test, /srv/example.
.github/workflows/test.yml:127:          components: llvm-tools-preview
.github/workflows/test.yml:138:          tool: cargo-llvm-cov,nextest
docs/COVERAGE.md:73:| [Abstract syntax tree](https://en.wikipedia.org/wiki/Abstract_syntax_tree) | the program's structure without layout, so a rule matches a construct however it is spelled | [Clang AST](https://clang.llvm.org/docs/IntroductionToTheClangAST.html), [ast-grep](https://ast-grep.github.io/) |
docs/COVERAGE.md:79:| [High-level intermediate representation](https://en.wikipedia.org/wiki/Intermediate_representation) | names resolved and types assigned, so a check sees what an identifier refers to | [rustc HIR](https://rustc-dev-guide.rust-lang.org/hir.html), [MLIR](https://mlir.llvm.org/), [LLVM IR](https://llvm.org/docs/LangRef.html) |
docs/COVERAGE.md:80:| [Control-flow graph](https://en.wikipedia.org/wiki/Control-flow_graph) | every path a function can take, so a check can ask whether one statement is reached before another | [LLVM](https://llvm.org/), [Soot](https://soot-oss.github.io/soot/) |
docs/COVERAGE.md:81:| [Data-flow graph](https://en.wikipedia.org/wiki/Data_dependency) | which value flows into which operation | [Joern](https://joern.io/), [LLVM](https://llvm.org/) |
docs/COVERAGE.md:83:| [Static single-assignment form](https://en.wikipedia.org/wiki/Static_single-assignment_form) | each variable assigned once, so a value's definition is its name | [LLVM](https://llvm.org/), [GCC](https://gcc.gnu.org/) |
docs/COVERAGE.md:85:| [Def-use chains](https://en.wikipedia.org/wiki/Use-define_chain) | each definition linked to every use it reaches, and back | [LLVM](https://llvm.org/), [GCC](https://gcc.gnu.org/) |
docs/COVERAGE.md:86:| [Dominator tree](https://en.wikipedia.org/wiki/Dominator_(graph_theory)) | which statement runs before another on every path, so "checked before used" is decidable | [LLVM](https://llvm.org/), [GCC](https://gcc.gnu.org/) |
docs/COVERAGE.md:95:| [Dependency analysis](https://en.wikipedia.org/wiki/Dependence_analysis) | which statements must stay in order, the ground of loop transformation and slicing | [Polly](https://polly.llvm.org/), [isl](https://libisl.sourceforge.io/) |
docs/COVERAGE.md:96:| [Precision](https://en.wikipedia.org/wiki/Data-flow_analysis#Sensitivities): interprocedural, flow-, context- and path-sensitive | how much of the program an answer accounts for: across calls, in statement order, per call site, per branch; each costs time and removes false positives | [Infer](https://fbinfer.com/), [Clang Static Analyzer](https://clang-analyzer.llvm.org/), [SVF](https://github.com/SVF-tools/SVF) |
docs/COVERAGE.md:98:| [Interval](https://en.wikipedia.org/wiki/Interval_arithmetic), [octagon](https://doi.org/10.1007/s10990-006-8609-1) and [polyhedral](https://doi.org/10.1145/512760.512770) domains | bounds per variable; bounds on sums and differences of pairs; any linear relation: each more precise and more costly than the last | [APRON](https://github.com/antoinemine/apron), [Astree](https://www.absint.com/astree/), [Polly](https://polly.llvm.org/)/[isl](https://libisl.sourceforge.io/) |
docs/COVERAGE.md:149:| [Coverage-guided fuzzing](https://en.wikipedia.org/wiki/Fuzzing) | inputs mutated toward new code coverage until one fails | [AFL++](https://aflplus.plus/), [libFuzzer](https://llvm.org/docs/LibFuzzer.html), [honggfuzz](https://github.com/google/honggfuzz) |
docs/COVERAGE.md:158:| [Coverage analysis](https://en.wikipedia.org/wiki/Code_coverage) | which lines, branches or conditions a suite ran; a measure that stops measuring once it is a target, as [goodharts-law](../principles/goodharts-law.toml) says | [llvm-cov](https://llvm.org/docs/CommandGuide/llvm-cov.html), [gcov](https://gcc.gnu.org/onlinedocs/gcc/Gcov.html) |
docs/COVERAGE.md:166:| [Memory instrumentation](https://en.wikipedia.org/wiki/Instrumentation_(computer_programming)) | every access checked against allocation bounds and lifetimes | [AddressSanitizer](https://clang.llvm.org/docs/AddressSanitizer.html), [Valgrind](https://valgrind.org/) |
docs/COVERAGE.md:167:| [Race detection](https://en.wikipedia.org/wiki/Race_condition) | unsynchronized conflicting accesses found from the happens-before order of a run | [ThreadSanitizer](https://clang.llvm.org/docs/ThreadSanitizer.html), [Helgrind](https://valgrind.org/docs/manual/hg-manual.html) |
docs/COVERAGE.md:169:| [Deadlock analysis](https://en.wikipedia.org/wiki/Deadlock_(computer_science)) | lock-order cycles seen in one run, which can deadlock in another | [Helgrind](https://valgrind.org/docs/manual/hg-manual.html), [ThreadSanitizer](https://clang.llvm.org/docs/ThreadSanitizer.html) |
scripts/coverage.sh:49:for tool in llvm-cov nextest; do
scripts/coverage.sh:58:# this crate has no lib target -- and llvm-cov instruments that binary and
scripts/coverage.sh:73:echo "==> cargo llvm-cov ${args[*]}"
scripts/coverage.sh:74:cargo llvm-cov "${args[@]}"
toolchain.toml:87:# declared anyway because "cargo llvm-cov: no such subcommand" is not a message
toolchain.toml:90:name = "cargo-llvm-cov"
toolchain.toml:91:check = "cargo llvm-cov --version"
toolchain.toml:93:hint = "coverage-only; install: cargo install cargo-llvm-cov (or run: scripts/deps.sh install)"
toolchain.toml:186:check = "cargo llvm-cov --version >/dev/null 2>&1 && cargo nextest --version >/dev/null 2>&1"
toolchain.toml:188:cargo install --locked cargo-llvm-cov


$ uphold check
reconciled 19 enforcement claims:
  explicit-unknown <- catalog-tests  enforced by a hook installed here
  single-authoritative-source <- catalog-reference-current  enforced by a hook installed here
  make-illegal-states-unrepresentable <- catalog-validate  enforced by a hook installed here
  single-authoritative-source <- catalog-tests  enforced by a hook installed here
  explicit-unknown <- no-stale-hook-pins  enforced by uphold guard at manual
  single-authoritative-source <- no-stale-hook-pins  enforced by uphold guard at manual
  complete-mediation <- prevent-ai-author  enforced by uphold guard at commit-msg
  fail-safe-defaults <- prevent-public-push  enforced by uphold guard at pre-push
  observability <- removed-function-named  enforced by uphold guard at commit-msg
  least-privilege <- workflow-declares-permissions  enforced by uphold scan
  minimize-attack-surface <- workflow-declares-permissions  enforced by uphold scan
  compromise-recording <- no-local-merge  enforced by uphold guard at pre-merge-commit
  compromise-recording <- no-merge-commit  enforced by uphold guard at pre-commit
  data-minimization <- no-private-repo-names  enforced by uphold guard at commit-msg
  data-minimization <- no-running-os-identity-metadata  enforced by uphold scan
  chestertons-fence <- removed-function-named  enforced by uphold guard at commit-msg
  deprecation-discipline <- no-stale-hook-pins  enforced by uphold guard at manual
  reproducible-derived-state <- catalog-reference-current  enforced by a hook installed here
  reproducible-derived-state <- review-current  enforced by a hook installed here
  behavior  catalog-tests: unmeasured [not_requested] — no behavioral probe requested
  behavior  catalog-reference-current: unmeasured [not_requested] — no behavioral probe requested
  behavior  catalog-validate: unmeasured [not_requested] — no behavioral probe requested
  behavior  catalog-tests: unmeasured [not_requested] — no behavioral probe requested
  behavior  no-stale-hook-pins: unmeasured [not_requested] — no behavioral probe requested
  behavior  no-stale-hook-pins: unmeasured [not_requested] — no behavioral probe requested
  behavior  prevent-ai-author: unmeasured [not_requested] — no behavioral probe requested
  behavior  prevent-public-push: unmeasured [not_requested] — no behavioral probe requested
  behavior  removed-function-named: unmeasured [not_requested] — no behavioral probe requested
  behavior  workflow-declares-permissions: unmeasured [not_requested] — no behavioral probe requested
  behavior  workflow-declares-permissions: unmeasured [not_requested] — no behavioral probe requested
  behavior  no-local-merge: unmeasured [not_requested] — no behavioral probe requested
  behavior  no-merge-commit: unmeasured [not_requested] — no behavioral probe requested
  behavior  no-private-repo-names: unmeasured [not_requested] — no behavioral probe requested
  behavior  no-running-os-identity-metadata: unmeasured [not_requested] — no behavioral probe requested
  behavior  removed-function-named: unmeasured [not_requested] — no behavioral probe requested
  behavior  no-stale-hook-pins: unmeasured [not_requested] — no behavioral probe requested
  behavior  catalog-reference-current: unmeasured [not_requested] — no behavioral probe requested
  behavior  review-current: unmeasured [not_requested] — no behavioral probe requested
  note  lefthook.yml runs the binary
  note  lefthook.yml defines 20 command(s)
  note  .claude/settings.json runs `uphold hook`

✅ uphold review

The review document asked about 33 of uphold's records; this change violates none of them.

Reviewed with uphold 1.38.0 by uphold-review 0.3.1 · aabb562 · claude-opus-5-5 · 47 s · $0.19 list

codecov-commenter · 2026-10-27T13:04:47Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 94.95%. Comparing base (907eb95) to head (aabb562).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #451   +/-   ##
=======================================
  Coverage   94.95%   94.95%           
=======================================
  Files          55       55           
  Lines       28054    28054           
=======================================
  Hits        26640    26640           
  Misses       1414     1414

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

uphold's own design questions had nothing to be ruled from: `[decide]` was absent, so the rulings on #429 and #450 used the whole catalog and escalated every conflict. Adopt the records this repository's code and docs already argue from by id, plus the three those rulings turned on, and order the four adopted pairs that conflict, each by a choice this repository has already made. Claude-Session: https://claude.ai/code/session_01BHpLckRt4BNGCdFG9vLyEP

HackingGate mentioned this pull request Oct 27, 2026

Pin ruff-pre-commit at v0.17.3, its newest tag #452

Merged

HackingGate force-pushed the policy/adopt-decide branch from 4149d58 to aabb562 Compare October 27, 2026 14:01

HackingGate merged commit 59e4705 into main Oct 27, 2026
11 of 14 checks passed

HackingGate deleted the policy/adopt-decide branch October 27, 2026 14:15

This was referenced Oct 27, 2026

Design: the hook refuses only what the shim would, a publishing call to a destination where the rule's scope holds #450

Closed

Design: uphold ships its Claude Code hooks as a plugin from this repository #429

Open

coderabbitai Bot mentioned this pull request Oct 27, 2026

uphold hook judges a tool call where gh would judge the same act (#450) #453

Merged

Navigation Menu

Repository navigation

Adopt ten records for design rulings, with the four orders between them - #451

Adopt ten records for design rulings, with the four orders between them#451
HackingGate merged 1 commit into
mainfrom
policy/adopt-decide

HackingGate commented Oct 27, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

coderabbitai Bot commented Oct 27, 2026 •

edited

Loading

Review skipped

Uh oh!

uphold-review Bot commented Oct 27, 2026 •

edited

Loading

Uh oh!

codecov-commenter commented Oct 27, 2026 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

HackingGate commented Oct 27, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary by CodeRabbit

Uh oh!

coderabbitai Bot commented Oct 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review skipped

Uh oh!

uphold-review Bot commented Oct 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

uphold-review

Walkthrough

Changes

❌ uphold rules: uphold's rules refuse this · this repository's policy at ccb8795

✅ uphold review

Uh oh!

codecov-commenter commented Oct 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

HackingGate commented Oct 27, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented Oct 27, 2026 •

edited

Loading

uphold-review Bot commented Oct 27, 2026 •

edited

Loading

❌ uphold rules: uphold's rules refuse this · this repository's policy at `ccb8795`

codecov-commenter commented Oct 27, 2026 •

edited

Loading