Skip to content

fix(trust): treat manifest-declared policy packs as trust roots (#1075) - #1127

Merged
pengfei-threemoonslab merged 4 commits into
mainfrom
claude/issue-1075-manifest-policy-trust-roots
Nov 8, 2026
Merged

pengfei-threemoonslab merged 4 commits into
mainfrom
claude/issue-1075-manifest-policy-trust-roots

Conversation

@pengfei-threemoonslab

Copy link
Copy Markdown
Contributor

Summary

Closes #1075

  • A manifest-declared policy pack is a trust root wherever it lives. SHIP-VERIFY-TRUST-ROOT-TOUCHED classified a pack only by **/policies/**, while checks.policy_packs[].path may name any file under the manifest's directory. A PR that edited only a pack declared elsewhere, such as the vendor/shipgate-policies/org-release.yaml layout docs/organization.md recommends, raised no finding and came back mergeable / complete. verify now classifies every pack the base or head manifest declares as trust_root_class: policy, with matched_glob set to the repository-relative path. The same edit now returns human_review_required.
  • Judged against the base declaration. The base manifest is read once from the base commit. That is the same regular_file_at_ref read verify: read an in-repo --diff-from and ci.mode from the base, never from the PR head #1024 makes for the ci exit floor; _base_ci_policy is now a projection of that one read, and its note text is unchanged. A PR that removes the declaration and edits the pack in the same diff therefore still gets the policy finding beside the manifest one. The head manifest the run loads also contributes, so a --no-base worktree run is covered too.
  • Same path as fix(verify): read in-repo --diff-from and ci policy from the base #1074, not a parallel one. The paths go into the existing internal VerificationContext.configured_trust_root_inputs map, via the existing _configured_input_trust_roots, which now takes the manifests. checks/verify.py and core/trust_roots.py are unchanged. Command-line inputs come first, so they keep verify: read an in-repo --diff-from and ci.mode from the base, never from the PR head #1024's classes. A path the glob table already classifies keeps its class and glob, so its fingerprint does not move.
  • The other manifest-declared baseline path. The issue asks for "any other manifest-declared policy or baseline path". The only other one is baseline.audit_log, the log that vouches for an in-repository --baseline. It defaults to baseline-audit.log beside the baseline and resolves through the scan's own _resolve_audit_log_path. It is now shipgate_state, the class fix(verify): read in-repo --diff-from and ci policy from the base #1074 gave the baseline, except when baseline.integrity_mode: off, because the scan does not read it then.
  • Paths resolve lexically, as the scan resolves them: packs against the manifest's directory (a scoped services/mailer/shipgate.yaml binds services/mailer/rules/org.yaml, not a root rules/org.yaml), and the audit log against the baseline's. A path outside the repository is not classified.
  • CHANGELOG ## Unreleased bullet (placed after verify: read an in-repo --diff-from and ci.mode from the base, never from the PR head #1024's). The STABILITY migration note verify-manifest-bound-trust-roots-1075 says the trust-root set is broader: newly covered paths get new fingerprints, and existing ones do not move. The § Verify Orchestrator sentence is extended. docs/checks.md, docs/organization.md and docs/baseline.md say the same; llms-full.txt is rebuilt from docs/checks.md.

Surface discipline: no new surface. No CLI flag, schema, contract, check ID, severity or trust_root_class value is added, and the context map is internal and never serialized. Headline metric: blocked-recall. A PR that weakens the gate through a vendored pack no longer reads mergeable.

Type

  • Check or risk-model change
  • Input adapter change
  • CLI or GitHub Action behavior
  • Report, schema, or SARIF output
  • Documentation only

Authorship

  • A coding agent wrote some or all of this change. Agent: Claude Code (claude-opus-5-5)
  • A person read the whole diff before opening this pull request.

No person has read this diff yet. It needs the owner's review before merge.

Verification

CI is authoritative for python -m ruff check ., python -m compileall -q src tests, and python -m pytest.

Additional local checks run (Python 3.12, macOS):

  • Reproduction on origin/main (2cb8f4f), ./shipgate verify --base main --head HEAD on a scratch repo whose manifest declares vendor/shipgate-policies/org-release.yaml, with a PR that edits only that file: mergeable, control.state: complete, can_merge_without_human: true, no findings. The same holds for a scoped services/mailer/shipgate.yaml and for a --no-base worktree edit. With this change all three return human_review_required with SHIP-VERIFY-TRUST-ROOT-TOUCHED (policy, matched_glob = the pack path). The remove-the-declaration case adds the policy finding beside the manifest one. In the policies/org.yaml control, the finding's fingerprint (fp_e48e0cb023cc0e6c) and the manifest finding's (fp_bfe9966d650e948e) are identical before and after.
  • python -m pytest tests/test_verify_pr_controlled_inputs.py: 37 passed. The 11 new cases were also run inside an unpatched HEAD export. 9 fail with the missing-trust-root assertion (one with a TypeError on the new signature). The 2 that pass there are the integrity-off negative and the fingerprint-stability guard, which are meant to hold on both.
  • Full suite, -n auto -m "not perf and not slow" --ignore=tests/test_adapter_static_only.py (22,327 tests): 5 failures, all environmental. Two are test_check_unmodelled_host_config_keys.py[local_settings_enabled_plugins-*]: this machine's global gitignore hides .claude/settings.local.json, and they pass with an empty XDG_CONFIG_HOME. Three are test_schema_roundtrip.py: the local venv has pydantic 2.13.4 while constraints/dev.txt pins 2.14.3, and they fail identically on an unpatched HEAD export. After merging main (fix(schemas): freeze published schema bytes; the generator refuses to rewrite one (#1044 slice A) #1116), test_published_schema_freeze.py's version-bump test fails for the same reason, and fails on an origin/main export too. CI's locked closure is authoritative for those.
  • tests/test_adapter_static_only.py: pass. tests/test_latency_budget.py -m perf: pass. python -m ruff check .: pass. python -m compileall -q src tests: ok.
  • python scripts/regenerate_goldens.py --check: Checked 24 sample artifacts; 0 changed.
  • python scripts/build-llms-full.py re-run; the 20 test files that read the edited docs pass (test_public_surface_contract.py included).
  • tests/shard_seconds.json: test_verify_pr_controlled_inputs.py re-measured serially at ea14fe2 (53.6s, 37 cases) and recorded as a supplemental increment, as verify: read an in-repo --diff-from and ci.mode from the base, never from the PR head #1024 did. tests/test_shard_partition.py passes.
  • Branch synced with main (fix(schemas): freeze published schema bytes; the generator refuses to rewrite one (#1044 slice A) #1116) as fc1d34b, with no conflicts. The merged tree equals the trial merge, and focused suites pass on it, apart from the pydantic-version schema tests above.

Release-readiness notes

  • No user-code import added to default scan paths
  • No network access added to default scan paths
  • New or changed check IDs are documented in docs/checks.md (none added or changed; the check's docs section now names the configured inputs)
  • Report/schema changes are additive or documented in STABILITY.md

Decisions taken

  • Base ∪ head, not base only. The base's declarations are what close the remove-and-edit case. The head's are what this run loads, and they cover --no-base runs, where no base manifest is read. Without them, a worktree --no-base edit of a declared pack still read mergeable. A head-only declaration always comes with a manifest edit, which is itself a trust root, so adding it never creates a lone new review.
  • First adoption. When the base has no manifest, the introduced manifest's packs are classified too. So an adoption PR that also adds a pack outside policies/** gets the same extra policy finding a pack under policies/** already gets. The verdict was already human_review_required.
  • Repository containment, not manifest-directory containment. A declared path that escapes the manifest directory but stays in the repository fails the scan anyway (resolve_input_path). Classifying it is harmless, and it matches fix(verify): read in-repo --diff-from and ci policy from the base #1074's _repository_relative_input rule.
  • Audit-log class shipgate_state, not policy. The issue's sketch says policy for every path. The audit log is baseline state, though, so it takes the class fix(verify): read in-repo --diff-from and ci policy from the base #1074 gives the baseline. Both classes are in BAND_EXCLUDED_TRUST_ROOT_CLASSES.
  • Check metadata untouched. docs/checks/verify.yaml's fires_when already omits the verify: read an in-repo --diff-from and ci.mode from the base, never from the PR head #1024 inputs and the configured manifest. Editing it would churn docs/checks.json and the catalog, so the prose section in docs/checks.md carries the update instead.

Protected paths touched

none

Follow-up candidates (not in this PR)

  • check and the installed hooks still classify by the static table. shipgate check --base main --head HEAD on a PR that edits only vendor/shipgate-policies/org-release.yaml returns allow. The pretooluse hook's PROTECTED_SURFACES is rendered from TRUST_ROOT_SURFACES at install time, so it cannot know manifest-declared paths. PR-time verify is now the backstop. Making the local boundary evaluator read the manifest's declarations is a separate surface (core/agent_boundary.py).
  • SHIP-VERIFY-POLICY-BASE-ABSENT's fail-safe surface set (_POLICY_SURFACES) also stops at **/policies/**. With no base snapshot, a declared pack edit now raises the trust-root finding but not that fail-safe. The verdict needs a human either way.

🤖 Generated with Claude Code

SHIP-VERIFY-TRUST-ROOT-TOUCHED classified a policy pack only by
`**/policies/**`, while `checks.policy_packs[].path` may name any file
under the manifest's directory. A pull request that edited only a pack
declared elsewhere, such as the vendor/shipgate-policies/org-release.yaml
layout docs/organization.md recommends, raised no finding and came back
mergeable. #1024 classified a --policy-pack named on the command line,
not one the manifest declares.

verify now feeds the paths a manifest binds into the same internal
VerificationContext.configured_trust_root_inputs map #1024 added:

- each checks.policy_packs[].path, class `policy`, resolved against the
  manifest's directory as the scan resolves it;
- the audit log that vouches for an in-repository --baseline
  (baseline.audit_log, or baseline-audit.log beside the baseline, via the
  scan's own _resolve_audit_log_path), class `shipgate_state` like the
  baseline, unless baseline.integrity_mode is off.

The declarations come from the base manifest, read once from the base
commit (the read #1024 makes for the ci exit floor, now shared), and from
the head manifest the run loads. A change that removes a declaration and
edits the pack in one diff is still a `policy` trust root beside the
edited manifest, and a --no-base worktree run is covered by the head's.
Command-line inputs keep their classes, and a path the glob table already
classifies keeps its class, glob and fingerprint; newly covered paths get
new fingerprints. No schema, contract or check ID moves.

CHANGELOG, a STABILITY migration note, docs/checks.md (llms-full.txt
rebuilt), docs/organization.md and docs/baseline.md say the trust-root set
is broader.
…1075 cases

The file grew from 25 to 37 cases. Record the serial JUnit measurement
(53.6s) as a supplemental increment, as #1024 did for the same file.
The configured manifest is classified before the glob list, so the claim
that a classified path keeps its glob holds for the configured inputs only.
STABILITY also says when the head's declarations apply alone and that
scan --changed-files carries no configured inputs.
@pengfei-threemoonslab
pengfei-threemoonslab merged commit b581c39 into main Nov 8, 2026
16 checks passed
pengfei-threemoonslab added a commit that referenced this pull request Nov 8, 2026
Brings in #1127 (the #1075 trust-root fix), which 1.3.0 must carry.
CHANGELOG.md conflicted because this branch promoted the Unreleased
section #1127 added a line to; both files are regenerated from main's
Unreleased by the same cut script, so #1127's entry is a one-liner in
"Verification, attestation and control", joins the verify highlight,
and its full prose is in docs/changelog/1.3.0.md. Its STABILITY
migration note is stamped 1.3.0, and llms-full.txt rebuilds identical.
pengfei-threemoonslab added a commit that referenced this pull request Nov 8, 2026
The development corpus ran on 04fc9ce (this preparation with #1127):
39 partial, 6 not_established and 4 timeouts; no added, removed or
changed row; 415 not_established candidates. All 49 answers equal those
of main at 952a74c, which the release record's regression figures
come from. Q0 37/49 (retained), Q1 0/49, Q2 0/49, down from 4/49 and
3/49 at the 2026-10-05 ledger. run.py exited 1 on the four timeouts;
that is recorded, not a blocker. The holdout has no pinned members.

The ledger test now accepts a null answer_id for a member whose row says
it has no answer (timeout, refused, unavailable), never with Q1: the
first ledger with timeouts. The release record links the ledger, and the
release heading is dated 2026-11-08, the day the cut was finalised.
pengfei-threemoonslab added a commit that referenced this pull request Nov 8, 2026
* release: prepare 1.3.0 on the advisory channel

- Version 1.3.0 in pyproject.toml and __version__, the plugin and
  marketplace manifests, .well-known, the in-tree runtime lines, the
  capability-lock example, the determinism boundary and llms-full.txt.
- CHANGELOG: Unreleased promoted to "1.3.0 - 2026-11-07", one line per
  change, with the application regression and the Q2 line stated
  plainly; the full prose moves to docs/changelog/1.3.0.md. Every PR
  merged since v1.2.0 is cited: #962, #987, #995, #1088 and #1123/#1124
  gained citations, and the CI- and lock-only PRs share one line.
- STABILITY.md: title, intro paragraphs and 22 migration notes stamped
  1.3.0.
- Schemas: generated, then pinned (15 documents new since 1.2.0). The
  host-grants 0.9 inventory and baseline documents no longer say "0.9
  has not shipped in a tagged release", which the tag would freeze false.
- .github/release-channels.json declares 1.3.0 advisory.

* release: codex boundary goldens name 1.3.0; tighten two release-note lines

The codex boundary-result goldens pin tool.version, which the full suite enumerated after the bump. The release note's opening says "several ways", not "most of it", and the control-completion line names the MCP input it means.

* benchmark(application-q2): ledger for the 1.3.0 release build; Q2 0/49

The development corpus ran on 04fc9ce (this preparation with #1127):
39 partial, 6 not_established and 4 timeouts; no added, removed or
changed row; 415 not_established candidates. All 49 answers equal those
of main at 952a74c, which the release record's regression figures
come from. Q0 37/49 (retained), Q1 0/49, Q2 0/49, down from 4/49 and
3/49 at the 2026-10-05 ledger. run.py exited 1 on the four timeouts;
that is recorded, not a blocker. The holdout has no pinned members.

The ledger test now accepts a null answer_id for a member whose row says
it has no answer (timeout, refused, unavailable), never with Q1: the
first ledger with timeouts. The release record links the ledger, and the
release heading is dated 2026-11-08, the day the cut was finalised.
pengfei-threemoonslab added a commit that referenced this pull request Nov 11, 2026
…pack (#1128) (#1130)

After #1075 only PR-time verify knew the packs a manifest declares.
`check --base main --head HEAD` answered `allow` for a change that edited
only `vendor/shipgate-policies/org-release.yaml`, while the same edit to
`policies/org.yaml` got `require_review`. The installed PreToolUse hook let
the edit land without asking. And verify's boundary assessment published
SHIP-AGENT-BOUNDARY-PROTECTED-SURFACE-UNCLASSIFIED for the policies/ file but
not for the vendored one.

- core/trust_roots: manifest_policy_pack_paths, #1127's lexical resolution
  moved to core, and is_manifest_policy_pack, the normalized casefold match
  configured_input_trust_root uses. verify's _configured_input_trust_roots
  calls the resolver; its output is unchanged.
- check: the base manifest as committed at the base ref, plus the head
  manifest, declare the packs. A provided diff, and the MCP tool, read the
  working tree only and run no Git. evaluate_agent_boundary routes each pack
  as policies/** is routed. It records trust_root_class: policy only where
  the trust-root table does not classify the path, so it never takes the
  graded agent route, and no structural shortcut clears it.
- verify: the same packs reach assessment_for_scan_context through a
  run-private VerificationContext field, so verify publishes the boundary
  row that check publishes.
- hook: _ConfiguredSurfaces replaces the static lookup in PreToolUse, the
  approval memory, the PostToolUse nudge and the Stop hook. It reads the
  manifest in the working tree and at --base. It parses a manifest only when
  the text can name a pack, through `agents-shipgate org policy-packs --json`
  on a private copy, once per version (kept in the hook state).

policies/** rows and fingerprints are byte-identical. No schema, contract,
rule ID, check ID, severity or trust_root_class value moves.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

trust roots: a manifest-declared policy pack outside policies/** must be a trust root

1 participant