Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
93 lines (68 loc) · 4.8 KB

CONTRIBUTING.md

File metadata and controls

93 lines (68 loc) · 4.8 KB
Raw

Contributing

GuideCheck is a security-relevant standards project. Changes to the Human-Verifiable Assistant Guide profile are reviewed with that in mind.

What lives where

  • spec.md and verifier-conformance.md are normative. Changes to either are profile changes.
  • finding-ids.md is normative for the finding-id registry. Contract validation requires every finding id emitted by the verifier and hosted API to be documented there, so adding, renaming, or removing an id is a profile change.
  • design-rationale.md and threat-register.md are explanatory. They must stay consistent with the normative documents.
  • schemas/ is normative for the field sets it describes.
  • examples/ and fixtures/ must remain consistent with the current profile version.
  • archive/ is historical and is not edited.

Profile versioning

Profile versions follow Semantic Versioning as defined in spec.md section 11.

  • MAJOR: a change that removes a field, tightens a constraint, or invalidates previously conforming guides or verifiers
  • MINOR: an additive optional field, a relaxed constraint, or a new compatible check or fixture
  • PATCH: an editorial fix with no conformance effect

Every normative change updates CHANGELOG.md in the same commit.

Proposing a change

  1. Open an issue describing the problem, not just the proposed wording. Security standards fail most often from unstated assumptions.
  2. State the threat model impact. If the change weakens a defense, say so and justify it.
  3. For normative changes, identify every section, schema, example, and fixture affected. Spec and verifier-conformance must not drift apart.
  4. If the change affects the conformance ladder, the verifier output schema, or the action block shape, expect a longer review.
  5. Run make eval before submitting changes that affect fixtures, finding ids, verifier behavior, examples, or guide profile rules.

Review

Normative changes are reviewed by a maintainer with security ownership. A change that adds, removes, or reclassifies an attack mitigation is reviewed against threat-register.md and spec.md section 27.

Fixtures

A change to verifier behavior is incomplete without fixture coverage. The fixture suite under fixtures/ is the conformance target for verifier implementations. Add or update fixtures in the same change that alters a verifier requirement.

Fixture-suite releases will be signed and versioned once verifier-conformance.md reaches a stable conformance target, so verifier authors can pin a trusted corpus. See roadmap.md.

Evals

The local eval runner in scripts/eval_guidecheck.py checks static fixtures and generated edge cases. It is a regression harness for this repository, not a substitute for the normative text or static fixture suite. Generated eval cases that become conformance requirements should be promoted into static fixture directories.

Style

Documentation follows the repository markdown conventions: plain headings, no emphasis inside headings, triple-backtick code fences, no em dashes, bare https domains. Guide examples and fixtures must satisfy the byte profile they claim to demonstrate.

Security issues

Do not open a public issue for a vulnerability in the profile, a verifier, or a published guide. See SECURITY.md.

License

Contributions to specification text and documentation are accepted under CC-BY-4.0. Contributions to code and schemas are accepted under MIT. By contributing you agree your contribution is licensed under the applicable license.

Hosted-site Siteline assessment

For changes to the hosted site or its machine-readable surfaces, assess the canonical site at https://guidecheck.org/ with Siteline before delivery review and after an authorized deployment. Retrieve an existing result when appropriate; respect scan limits and cached-result timestamps.

  • Retain the result ID, scan timestamp, scanner and rubric versions, grade, score, findings, and repository commit. A shareable result requires confirmed storage.
  • Reconcile every finding against current source, generated output, and deployed evidence. Classify it as confirmed target work, scanner defect, deployment drift, stale or unreproduced, or informational. Record evidence and rationale for exceptions.
  • Resolve confirmed defects that affect the site's promised agent tasks before declaring acceptance. Do not add irrelevant APIs, feeds, contact forms, or commerce features merely to raise the grade.
  • Keep SNAP grades and passive standards panels separate from full GuideCheck, Graceful Boundaries, accessibility, or other applicable conformance checks. A high grade does not replace those checks.
  • Local candidate checks do not establish live acceptance. After deployment, verify the intended bytes and reconcile a scan of those deployed surfaces; a cached scan of earlier content remains historical evidence.