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
8 changes: 7 additions & 1 deletion .github/workflows/test.yml
Original file line number Diff line number Diff line change
Expand Up @@ -12,16 +12,22 @@ permissions:
jobs:
test:
runs-on: ubuntu-latest
strategy:
fail-fast: false
matrix:
python: ["3.10", "3.12"]
steps:
- name: Check out repository
uses: actions/checkout@v4

- name: Set up Python
uses: actions/setup-python@v5
with:
python-version: "3.12"
python-version: ${{ matrix.python }}

- name: Run local verification suite
run: |
make test test-verify-ui
python3 scripts/build_public_contracts.py
- name: Verify installed wheel outside the checkout
run: python3 scripts/test_package_consumer.py
21 changes: 15 additions & 6 deletions ADOPTION.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,10 +2,11 @@

## Version-aware adoption

Existing supported legacy guides keep their current evaluation when checked by
the 1.0.0 dispatcher. No guide, manifest, DNS, or repository-anchor
rotation is required for that compatibility. The latest released profile is
[1.0.0](profiles/1.0.0/spec.md); legacy profiles remain supported.
Existing supported legacy guides keep their current evaluation under the 2.0.0
candidate dispatcher. No guide, manifest, DNS, or repository-anchor rotation
is required for that compatibility. The current candidate is
[2.0.0](profiles/2.0.0/spec.md) and is unpublished; [1.0.0](profiles/1.0.0/spec.md)
remains the last published profile, and legacy profiles remain supported.

Deliberately adopting 1.0.0 requires matching guide/manifest profile declarations
and another qualifying anchor when the repository was the only source of
Expand All @@ -15,9 +16,17 @@ Consumers that require 1.0.0 can use the `required_profile_version` API field or
`--require-profile-version` local CLI assertion. These reject an incompatible
guide rather than reinterpret its bytes. Local evaluation still caps at Level 3.

Deliberately adopting the 2.0.0 candidate requires matching guide and manifest
profile declarations. Its `corrected-content-1` policy is opt-in and its
`1.0.0-strict` anchor policy still excludes repository-file evidence from Level
4 qualification. It does not migrate existing reports. The experimental POSIX
CLI selector, `--contract posix-json-v1`, is independent of the guide-declared
profile selector; see [the CLI contract](docs/cli-contract.md).

The guidance below describes the published legacy profile. See the
[compatibility contract](docs/anchor-policy-compatibility.md) for version selection
and the [validation evidence](docs/anchor-dispatch-validation.md) for tested limits.
[compatibility contract](docs/anchor-policy-compatibility.md),
[corrected-content policy](docs/corrected-content-policy-2026-09-07.md), and
[candidate release notes](RELEASE_NOTES-2.0.0.md) for selection and status.

This is the practical on-ramp to GuideCheck. It explains what an
`assistant-guide.txt` artifact is, what the conformance ladder means in
Expand Down
17 changes: 16 additions & 1 deletion CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,22 @@

All notable changes to GuideCheck's Human-Verifiable Assistant Guide profile and its companion documents are recorded here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) conventions. Profile versions follow Semantic Versioning as defined in `spec.md` section 11.

## [Unreleased]
## [2.0.0] - 2026-09-07 (unreleased candidate)

- Include the corrected evaluator in the installable wheel and exercise legacy,
strict, corrected, and scanner dispatch from an isolated installed consumer in CI.
- Add the experimental `--contract posix-json-v1` verification adapter with one
terminal JSON record, separate operational and gate outcomes, and stable exit
categories. Existing CLI output and exit behavior remain the default.
- Freeze complete released 1.0.0 local and hosted reports in compatibility
replays alongside the existing legacy baseline.
- Add the root assistant-guide manifest and enforce byte equality with the
served copy, preserving published self-guide and manifest bytes.
- Add a local, unreleased 2.0.0 profile candidate selected only by guide bytes.
It corrects bounded negation and independent occurrence matching, blocks
unresolved execution targets, recognizes syntax-proven repository dispatch,
and inherits the released 1.0.0 strict anchor policy without changing legacy
or 1.0.0 reports.

## [1.0.0] - 2026-09-05

Expand Down
18 changes: 15 additions & 3 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -53,6 +53,7 @@ Canonical site: https://guidecheck.org/ · Verifier: https://guidecheck.org/veri
3ceb30a evaluator and 0.7.1 report contract; frozen artifact digests and full
report replays guard compatibility.
- `guidecheck_strict.py` implements the opt-in 1.0.0 provenance policy.
- `guidecheck_corrected.py` implements the opt-in 2.0.0 corrected-content policy.
- `guidecheck_verify.py` — local-file reference verifier CLI (Levels 1-3,
plus internal-consistency checks on Level 4 sidecar manifests/anchors).
- `guidecheck_scan.py` / `guidecheck_cli.py` — instruction-surface scanner
Expand Down Expand Up @@ -84,8 +85,9 @@ Canonical site: https://guidecheck.org/ · Verifier: https://guidecheck.org/veri
consistent with them, not the other way around.
- Software, engine, released-profile, and self-guide versions are separate in
`scripts/guidecheck_constants.py`. The legacy engine has frozen constants.
`scripts/check_version_sync.py` checks release surfaces against 1.0.0 and legacy/self-guide surfaces against 0.7.1;
package upgrades must not rewrite the published self-guide or its anchors.
`scripts/check_version_sync.py` checks the 2.0.0 candidate surfaces while
legacy/self-guide surfaces remain 0.7.1; candidate work must not rewrite the
published self-guide or its anchors.
- `finding-ids.md` is the normative registry for finding ids; new finding ids
used by fixtures or emitted by verifiers/scanner must be registered there
(see `CONTRIBUTING.md`).
Expand Down Expand Up @@ -129,7 +131,8 @@ builds and Sigstore-signs release + conformance-kit artifacts.

## Current state

- Released, profile version 1.0.0 (see `CHANGELOG.md`).
- The current candidate is 2.0.0 and is unpublished. Profile 1.0.0 remains the
last published profile (see `CHANGELOG.md`).
- Most recent work (2026-07-07): added `guidecheck scan`, a standalone
instruction-surface scanner for existing files (AGENTS.md/CLAUDE.md/
README/SKILL/llms.txt/assistant-guide.txt) that flags hidden-instruction
Expand Down Expand Up @@ -162,3 +165,12 @@ the deterministic DOM contract separately. CI runs both.
Local bounded-execution findings are implemented in the shared verifier. Pins
remain unverified, including through hosted callers. See roadmap.md for pending
hosted fetching and independence decisions. Legacy profile behavior remains pinned to the pre-dispatch baseline.

## Corrected-content candidate (2026-09-07)

The opt-in 2.0.0 candidate selects `corrected-content-1` while retaining the
`1.0.0-strict` anchor policy. See `docs/corrected-content-policy-2026-09-07.md`
and `RELEASE_NOTES-2.0.0.md`. It does not publish, migrate, or reinterpret
legacy, 1.0.0, or self-guide bytes. The experimental POSIX CLI selector
`--contract posix-json-v1` is independent of the guide-declared profile
selector; see `docs/cli-contract.md`.
20 changes: 19 additions & 1 deletion INTENT.md
Original file line number Diff line number Diff line change
Expand Up @@ -77,7 +77,23 @@ GuideCheck is a PAICE Foundation standard. It sits alongside the other open-spec

## Versioning and authority

The current profile is declared in `profiles/1.0.0/spec.md` and tracked in `CHANGELOG.md`. The current version is 1.0.0, released. Root normative documents preserve the legacy contract; the self-guide remains pinned to 0.7.1. The version is asserted by `scripts/check_version_sync.py` against `scripts/guidecheck_constants.py` against independently pinned release, engine, and self-guide identities, so the status here and the released tag cannot silently disagree. `spec.md` and `verifier-conformance.md` are normative. `design-rationale.md` and `threat-register.md` are explanatory and must stay consistent with the normative documents. `archive/` is historical and is not edited.
The current candidate version is 2.0.0, declared in `profiles/2.0.0/` and not
published. Profile 1.0.0 remains the last published profile and is tracked in
`CHANGELOG.md`. Root normative documents preserve the legacy contract; the
self-guide remains pinned to 0.7.1. `scripts/check_version_sync.py` asserts
candidate, engine, and self-guide identities without treating the candidate as
a published release. `spec.md` and `verifier-conformance.md` are normative.
`design-rationale.md` and `threat-register.md` are explanatory and must stay
consistent with the normative documents. `archive/` is historical and is not
edited.

## Corrected content checks

Decided by Sam on 2026-09-07: preserve frozen legacy reports and add an explicitly selected corrected evaluation path. The September 7 detector review reproduced negation false positives, affirmative-instruction false negatives, and unpinned script-dispatch gaps. These are maintenance of existing content-check obligations, not authority to silently alter a published evaluation contract.

Existing supported profile behavior, findings, levels, report identity, and exit semantics remain frozen. The corrected path has explicit 2.0.0 selection and `corrected-content-1` policy identity, as defined in `docs/corrected-content-policy-2026-09-07.md`. This does not revise the published strict 1.0.0 policy, which reuses legacy content checks. Publication and hosted acceptance are not completed by this candidate.

Sam also decided on 2026-09-07 that an unresolved execution target blocks Level 3 acceptance on the corrected path. The guide must establish the effective target and satisfy the applicable pinning contract. A declared hash alone cannot resolve an unidentified target. This requirement does not change any released legacy or 1.0.0 evaluation.

## Maintenance and demand gate

Expand All @@ -90,6 +106,8 @@ standard scope or authorize a cross-standard certification product. The Septembe

## Changelog

- 2026-09-07: Sam selected blocking unresolved execution targets for Level 3 on the opt-in corrected path; released evaluations remain frozen.
- 2026-09-07: Sam selected preservation of frozen legacy reports with opt-in corrected content checks. Recorded the decision and remaining selector/version design scope; evaluator and published profiles remain unchanged.
- 2026-09-05: Sam approved the version-aware anchor proposal with legacy compatibility required. The local 1.0.0 candidate excludes repository-file evidence from independent qualification, while the dispatcher preserves supported legacy evaluations and published self-guide bytes. Release and deployment remain separate. See `docs/anchor-policy-compatibility.md` and `docs/anchor-dispatch-validation.md`.

- 2026-07-31: Opened the canonical approval receipt as a live open question, prompted by an external question about binding approval to the exact executing action. Detail in `roadmap.md`; the identity fork (field in the record versus signer over it) is the first thing to resolve, gated behind Level 5 fixture-suite design.
Expand Down
15 changes: 13 additions & 2 deletions Makefile
Original file line number Diff line number Diff line change
@@ -1,7 +1,11 @@
.PHONY: test-verify-ui test-legacy-anchor-compatibility test-bounded-execution eval verify-fixtures validate-contracts test-contract-schema-validation test-parser-edge-cases check-guide-artifacts check-version-sync test-fetch-safety test-hosted-anchors test-hosted-api test-fetch-replay test-cli-contract test-scanner test release-archive conformance-kit
.PHONY: test-verify-ui test-legacy-anchor-compatibility test-bounded-execution test-corrected-content eval verify-fixtures validate-contracts test-contract-schema-validation test-parser-edge-cases check-guide-artifacts check-version-sync test-fetch-safety test-hosted-anchors test-hosted-api test-fetch-replay test-cli-contract test-scanner test release-archive conformance-kit

VERSION := $(shell python3 -c "import sys; sys.path.insert(0, 'scripts'); from guidecheck_constants import GUIDECHECK_VERSION; print(GUIDECHECK_VERSION)")

.PHONY: test-package-consumer test-posix-cli-contract
test-package-consumer:
python3 scripts/test_package_consumer.py

eval:
python3 scripts/eval_guidecheck.py

Expand Down Expand Up @@ -38,22 +42,29 @@ test-fetch-replay:
test-cli-contract:
python3 scripts/test_cli_contract.py

test-posix-cli-contract:
python3 scripts/test_posix_cli_contract.py

test-scanner:
python3 scripts/test_scanner.py

test-bounded-execution:
python3 scripts/test_bounded_execution.py

test-corrected-content:
python3 scripts/test_corrected_content.py

test-legacy-anchor-compatibility:
python3 scripts/test_legacy_anchor_compatibility.py
python3 scripts/test_dispatch_compatibility.py
python3 scripts/test_strict_compatibility.py
python3 scripts/test_profile_dispatch.py

# Keep the established Python-only test entry point usable without Node.
test-verify-ui:
node scripts/test_verify_ui.mjs

test: test-legacy-anchor-compatibility test-bounded-execution eval verify-fixtures validate-contracts test-contract-schema-validation test-parser-edge-cases check-guide-artifacts check-version-sync test-fetch-safety test-hosted-anchors test-hosted-api test-fetch-replay test-cli-contract test-scanner
test: test-legacy-anchor-compatibility test-bounded-execution test-corrected-content eval verify-fixtures validate-contracts test-contract-schema-validation test-parser-edge-cases check-guide-artifacts check-version-sync test-fetch-safety test-hosted-anchors test-hosted-api test-fetch-replay test-cli-contract test-posix-cli-contract test-scanner

# Full source archive for a GitHub release, matching prior build/ layout.
release-archive:
Expand Down
13 changes: 12 additions & 1 deletion PROJECT_CONTEXT.md
Original file line number Diff line number Diff line change
Expand Up @@ -64,7 +64,8 @@ notes), rather than a general PAICE-wide default.

## Current status

Released, profile version 1.0.0 (see `CHANGELOG.md`). Most recent shipped work:
The current candidate is 2.0.0 and is unpublished; 1.0.0 remains the last
published profile (see `CHANGELOG.md`). Most recent shipped work:
`guidecheck scan`, an instruction-surface scanner for pre-existing
AGENTS.md/CLAUDE.md/README/SKILL/llms.txt-style files (2026-07-07).
Undecided/open items live in
Expand All @@ -84,3 +85,13 @@ and delivery limits are in `docs/anchor-dispatch-validation.md`.
Local bounded-execution findings are implemented in the shared verifier. Pins
remain unverified, including through hosted callers. See roadmap.md for pending
hosted fetching and independence decisions. Legacy profile behavior remains pinned to the pre-dispatch baseline.

## Corrected-content candidate (2026-09-07)

The 2.0.0 candidate adds an explicitly selected `corrected-content-1` policy
while retaining the `1.0.0-strict` anchor policy. Legacy and 1.0.0 profiles,
their reports, and the 0.7.1 self-guide remain frozen. Candidate status and
scope are recorded in `RELEASE_NOTES-2.0.0.md` and
`docs/corrected-content-policy-2026-09-07.md`. The experimental POSIX CLI
selector `--contract posix-json-v1` is independent of the guide-declared
profile selector; see `docs/cli-contract.md`.
19 changes: 11 additions & 8 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,11 +1,11 @@
# GuideCheck

The 1.0.0 dispatcher preserves legacy
verification and selects stricter repository-anchor rules only for guides that
declare 1.0.0. See the [1.0.0 profile](profiles/1.0.0/spec.md),
[compatibility contract](docs/anchor-policy-compatibility.md), and
[validation evidence](docs/anchor-dispatch-validation.md). Published guide and
anchor bytes remain unchanged at 0.7.1; the latest released profile is 1.0.0.
The 2.0.0 candidate adds an opt-in corrected content policy while preserving
legacy and 1.0.0 evaluations. It is unpublished: 1.0.0 remains the last
published profile, and the self-guide and frozen legacy reports remain 0.7.1.
See the [2.0.0 candidate profile](profiles/2.0.0/spec.md),
[corrected-content policy](docs/corrected-content-policy-2026-09-07.md), and
[candidate release notes](RELEASE_NOTES-2.0.0.md). The current candidate is 2.0.0.

GuideCheck is a trust boundary protocol for agent instruction surfaces. It
ensures the instructions humans approve are the same instructions agents
Expand Down Expand Up @@ -98,7 +98,8 @@ agents may execute another.
## Documents

- `ADOPTION.md` - the practical on-ramp: conformance ladder, level-by-level path, guide-author checklist
- `profiles/1.0.0/spec.md` and `profiles/1.0.0/verifier-conformance.md` - the current normative guide and verifier profiles
- `profiles/2.0.0/spec.md` and `profiles/2.0.0/verifier-conformance.md` - the unpublished 2.0.0 candidate guide and verifier profiles
- `profiles/1.0.0/spec.md` and `profiles/1.0.0/verifier-conformance.md` - the last published guide and verifier profiles
- `spec.md` and `verifier-conformance.md` - preserved normative legacy profiles
- `design-rationale.md` - why the design choices were made
- `operator-guide.md` - non-normative defense-in-depth practices for operators
Expand Down Expand Up @@ -257,7 +258,9 @@ expectation contract by `scripts/check_reference_verifier.py`.

## Status

Released, profile version 1.0.0. Legacy profiles remain supported. See `CHANGELOG.md`.
The current candidate is 2.0.0 and is unpublished. Profile 1.0.0 remains the
last published profile; legacy profiles remain supported. See
`RELEASE_NOTES-2.0.0.md` and `CHANGELOG.md`.

This is an early-stage open standard. The most useful feedback right now is
whether the hidden-instruction problem maps to real operational risk in your
Expand Down
22 changes: 22 additions & 0 deletions RELEASE_NOTES-2.0.0.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
# GuideCheck 2.0.0 candidate release notes

Candidate version: 2.0.0

Status: Unpublished candidate. This file does not announce a tag, package,
GitHub Release, deployment, or hosted-service update.

GuideCheck 2.0.0 adds the opt-in `corrected-content-1` policy for guides that
explicitly declare profile 2.0.0. It retains the `1.0.0-strict` anchor policy:
repository-file evidence remains corroborating and cannot qualify a guide for
Level 4. An unresolved execution target blocks Level 3 under this policy.

The candidate preserves the isolated 0.7.1 legacy engine, the published 1.0.0
profile, the 0.7.1 self-guide, and all frozen reports. Existing guides are not
migrated or reinterpreted automatically.

The experimental POSIX JSON CLI contract, selected with
`--contract posix-json-v1`, is independent of the guide-declared profile
selector. See `docs/cli-contract.md`.

The normative corrected-content policy is
`docs/corrected-content-policy-2026-09-07.md`.
8 changes: 6 additions & 2 deletions api/verify.py
Original file line number Diff line number Diff line change
Expand Up @@ -43,6 +43,7 @@
import guidecheck_verify as gv # noqa: E402
from guidecheck_profiles import ProfileError, select_profile # noqa: E402
from guidecheck_strict import decorate_report # noqa: E402
from guidecheck_corrected import decorate_report as decorate_corrected_report # noqa: E402
from guidecheck_constants import GUIDECHECK_VERSION, HOSTED_VERIFIER_NAME, LEGACY_ENGINE_VERSION # noqa: E402
from guidecheck_fetch import FetchError, safe_fetch, variation_request_profile # noqa: E402
from guidecheck_hosted_anchors import ( # noqa: E402
Expand Down Expand Up @@ -738,10 +739,13 @@ def build_evaluated(
if note:
result["location_note"] = note
result["compact_report"] = _compact_report(result)
if selection is not None and selection.strict:
if selection is not None and selection.modern:
for anchor in result.get("cross_channel_anchors", []):
anchor.update((anchor_sources or {}).get(anchor["channel"] + " anchor", {}))
decorate_report(result, selection)
if selection.corrected:
decorate_corrected_report(result, selection)
else:
decorate_report(result, selection)
return result


Expand Down
11 changes: 11 additions & 0 deletions assistant-guide-manifest.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
guide-path: /.well-known/assistant-guide.txt
guide-version: 0.7.1
guide-sha256: 4b30202c809a3db037290371da8fed6a9681255199e0e19cfe1a0a7fc1d5df9e
guide-bytes: 8065
immutable-release-url: https://github.com/snapsynapse/guidecheck/releases/tag/v0.7.1
profile: human-verifiable-assistant-guide
profile-version: 0.7.1
canonical-url: https://guidecheck.org/.well-known/assistant-guide.txt
repository-url: https://github.com/snapsynapse/guidecheck
released-at: 2026-07-21T00:00:00Z
changelog-url: https://github.com/snapsynapse/guidecheck/blob/v0.7.1/CHANGELOG.md
Loading
Loading