Skip to content

AGENTS.md

Latest commit

 

History

History
262 lines (211 loc) · 14.2 KB

AGENTS.md

File metadata and controls

262 lines (211 loc) · 14.2 KB
Raw

AI SAFE² v3.1 Agent Entry Point

This file is the deterministic starting point for software agents, coding assistants, retrieval systems, compliance bots, and other automated consumers of this repository.

It has two jobs: preserve correct framework interpretation and define the minimum evidence-producing workflow for changes made in this repository or by agents reusing these instructions elsewhere.

Delivery workflow: isolate, build, prove, assess, ship

Use this workflow with any model, harness, or review provider. Repository facts and executable evidence take priority over model confidence or reviewer scores.

For material changes, classify delivery shape (spike, bounded, or architectural) separately from risk. Use .ai-safe2/development-policy.json and safe2 dev plan when the CLI is available. A generated plan or receipt is decision evidence, never merge, release, deployment, exception, policy-change, completion, or risk-acceptance authority. See docs/engineering/AI-SAFE2-DEVELOPMENT-METHOD.md.

1. Establish and isolate

  1. Read the nearest applicable AGENTS.md, repository manifest, contributing guidance, security policy, and relevant tests before changing files.
  2. Record the requested outcome, acceptance conditions, applicable controls, assumptions, exclusions, and evidence needed to call the work complete. Record the delivery shape and risk tier independently. Low- and medium-risk bounded work may proceed under existing authorization; architectural and high/critical work requires the explicit decisions named by policy.
  3. Inspect the working tree and preserve unrelated user changes. Never erase or rewrite work merely to obtain a clean checkout.
  4. For a new feature, use a dedicated branch or worktree based on the current trusted default branch. Confirm the base revision; do not assume a branch named main, a remote named origin, or network access.
  5. Parallel agents must use separate worktrees or non-overlapping task scopes. Shared-directory parallel editing is not isolation.

2. Build for the next maintainer

  1. Follow the architecture already established in the target repository. Add a service layer only when the design calls for one; do not impose a generic structure that increases coupling or hides control flow.
  2. Keep policy, evidence collection, decision logic, presentation, and external adapters separable where practical. Third-party outputs remain attributed evidence rather than native AI SAFE² decisions.
  3. Prefer strict, versioned contracts; bounded inputs; explicit unknown, partial, and not-applicable states; deterministic output; and fail-closed behavior at security or authorization boundaries.
  4. Preserve facts, declarations, assumptions, contradictions, and missing evidence as different states. Never manufacture a score, probability, successful execution, root cause, conformance claim, or human approval.
  5. Add or update documentation, examples, package data, navigation, and version references in the same change when users or agents need them to succeed.

3. Prove the change

  1. Capture the relevant before state before implementation when it can be reproduced safely. After implementation, capture the same measure or user journey under comparable conditions. For code, prefer an observed red/green cycle; use characterization-first, contract, schema, render, or approved-spike evidence when that is the more truthful falsification method.
  2. Use the evidence type appropriate to the claim:
    • UI or workflow: screenshots, video, or an accessibility/interaction trace.
    • Performance: repeatable measurements with environment and method.
    • CLI, API, contract, or security behavior: tests, exit codes, schemas, redacted output, hashes, and negative/adversarial cases.
    • Documentation: link, anchor, example-command, and rendering checks.
  3. A passing test proves only the behavior that test observed. A screenshot does not prove backend enforcement. A hash proves byte equality, not truth.
  4. Store only safe, minimal evidence. Redact credentials, personal data, private prompts, tokens, and unnecessary environment details.
  5. If the before state cannot be captured, say why and use a regression test or historical artifact without presenting it as direct before/after proof.

4. Assess and independently review

  1. Run the smallest relevant checks during development, then the repository's complete required quality, security, compatibility, packaging, and documentation gates before release.
  2. Use AI SAFE² against the changed system where applicable: identify the full model-plus-harness system, applicable enforcement planes and controls, evidence coverage, limitations, residual risks, decision owner, and next action. Self-assessment must be labeled as such.
  3. Inspect the final diff for unintended scope, unsafe defaults, secret or data exposure, dependency and supply-chain changes, compatibility breaks, misleading claims, and missing rollback or migration guidance.
  4. Independent human or machine review is valuable corroboration. Greptile, CodeRabbit, Macroscope, SkillSpector, and similar providers are optional attributed reviewers, not authorities. Preserve provider/version, scope, result, unresolved findings, and coverage gaps.
  5. Do not optimize for a vendor's numeric score or loop forever. Resolve valid findings, document accepted residual risk, and stop when defined acceptance gates pass or a decision owner must intervene.
  6. For GitHub changes, complete local pre-push gates, then open a draft pull request. Run check-pr, address valid findings, and rerun affected first-party checks. Select independent review according to the development policy and explicit owner instructions. Greptile is advisory and recommended for critical integration points; configuring it does not require invoking it on every PR. Use greploop only when the owner explicitly requests it, for no more than five review cycles. Honor owner instructions not to trigger a provider. Record skipped, absent, unavailable, or degraded review explicitly; never manufacture a confidence score or treat missing provider output as approval. Readiness depends on applicable first-party gates and required evidence, not a vendor score.

5. Ship with receipts

  1. The pull request must explain the problem, user value, scope, exclusions, before/after result, security and evidence boundaries, tests performed, compatibility, residual risks, and rollback or recovery path when relevant.
  2. Link durable evidence or provide reproducible commands. Distinguish local results from hosted CI and pending checks.
  3. Re-run affected checks after every material review-driven change. Never cite an earlier green run as evidence for changed code.
  4. Do not claim ready, complete, fixed, deployed, or released while required checks are failing, work remains uncommitted, the PR differs from the tested revision, or an external deployment has not been observed. For a material change using the development policy, produce and verify a safe2 dev receipt against the final revision before making a completion claim.
  5. Agents may prepare and update a PR when authorized. Human merge, release, production deployment, risk acceptance, and framework-conformance decisions remain with their named owners unless authority is explicitly delegated.

Portable completion record

For each material change, leave a concise record containing:

  • subject and exact revision assessed;
  • change scope and exclusions;
  • applicable system identity and trust boundaries;
  • before and after evidence, or the stated reason direct comparison is absent;
  • validation commands and outcomes by environment;
  • facts, assumptions, unknowns, conflicts, and residual risks;
  • independent-review attribution and unresolved findings;
  • recommendation, decision owner, rollback path, and next action.

This record can live in the pull request when no separate evidence artifact is required. It must remain understandable without access to an agent's chat log.

Start here

  1. Parse ai-safe2.manifest.json first.
  2. Parse repository-topics.manifest.json before placing or relocating documentation.
  3. Treat README.md and the framework control documents it links to as the human-readable framework entry point.
  4. Treat skills/mcp/data/ai-safe2-controls-v3.0.json as the stable machine-readable dataset for the unchanged 161-control core taxonomy.
  5. Treat skills/mcp/data/mcp-profile-v3.1.json as the machine-readable CP.5.MCP v3.1 overlay containing MCP-1 through MCP-19.
  6. Do not add the 19 MCP profile controls to the 161-control framework total.
  7. Treat 00-cross-pillar/unbiased-ai/uas-profile-v1.json as the UAS regulatory profile extension. Its 27 profile requirements do not add to the 161-control framework total and do not create CP.11 as a core Cross-Pillar control.

Version model

  • AI SAFE² Framework: v3.1.0
  • AI SAFE² CLI: v1.1.0 (1.0.0 was a GitHub-only release and never reached PyPI; verify with safe2 --version)
  • NEXUS: v0.6.0
  • Gateway: v3.0
  • MCP primary specification binding: 2026-07-28
  • MCP legacy compatibility binding: 2025-11-25
  • UAS regulatory profile extension: v1.0, 27 profile requirements

Component versions are independent. Do not rewrite NEXUS or Gateway evidence as framework v3.1 component evidence unless that component has separately changed version.

These are source identities, not publication receipts. Read .ai-safe2/component-versions.json and docs/COMPONENT-VERSIONS.md for the separate published package versions and compatibility minimums. Run python scripts/check_component_versions.py before submitting version changes; use --check-pypi to refresh live publication evidence. Do not publish a package or relabel historical evidence merely to eliminate a version difference.

Normative interpretation

AI SAFE² defines governance outcomes, controls, evidence expectations, and conformance requirements. NEXUS is Cyber Strategy Institute's first-party reference implementation. NEXUS is not required for framework conformance. An alternative implementation may conform if it demonstrably satisfies the applicable controls and evidence requirements.

For CP.5 profiles, apply this protocol-independence rule:

A CP.5 profile MUST NOT bind a control to a construct owned by the protocol it profiles.

Do not infer a governance boundary from protocol-owned correlation or session fields.

Enforcement planes

Classify requirements and evidence by plane before making a coverage claim:

  • north-south: agent to model provider
  • east-west: agent to agent
  • agent-to-tool: agent to MCP server or tool

Evidence from one plane does not automatically validate another plane.

Persistence vocabulary

Use these canonical persistence scopes in new evidence and integrations:

  • request
  • handle_scoped
  • durable
  • swarm_shared

Compatibility aliases may be accepted from older NEXUS data:

  • SESSION -> request
  • CROSS_SESSION -> handle_scoped
  • PERMANENT -> durable

A state handle or legacy Mcp-Session-Id is not identity and is not, by itself, an authorization boundary.

MCP v3.1 rules that agents must not infer incorrectly

  • server/discover is optional under the 2026-07-28 binding. Its absence is not a conformance failure.
  • MCP-19 requires intended-resource, audience, or equivalent evidenced binding.
  • Possession of an opaque bearer token does not by itself prove MCP-19 audience/resource validation.
  • The NEXUS MCP adapter in NEXUS/adapters/mcp/adapter.py is fail-closed scaffolding. Status: not production-ready.

Recommended machine workflow

For automated assessment or implementation guidance:

  1. Load ai-safe2.manifest.json.
  2. Load the 161-control core dataset.
  3. Determine the applicable enforcement plane and ACT context.
  4. If MCP applies, load the 19-control CP.5.MCP profile overlay.
  5. Resolve human-readable control detail through the paths identified in the manifest.
  6. Use scanner/ for static evidence where applicable, but do not equate scanner coverage with full framework conformance.
  7. Use challenges/ for falsification evidence and keep challenge maturity separate from framework/profile conformance.
  8. Preserve source version and implementation provenance in generated evidence.

Technology contribution and evidence interpretation

  • The current model name is AI Sovereign Maturity (AISM) Model. Use AISM or AISM Model after first mention; Sovereignty Score and Sovereignty Matrix remain distinct named instruments. Preserve historical wording and asset paths.

  • Organizational AISM maturity is separate from an artifact's scoped contribution.

  • Use AISM/TECHNOLOGY-CONTRIBUTION-PROFILE.md, AISM/EVIDENCE-ASSURANCE.md, and AISM/templates/TECHNOLOGY-CARD.md for the v1.0 assessment method.

  • Distinguish addresses, implements, enforces, validates, evidences, and challenges.

  • Keep assurance-v1.0 E0-E5 separate from the existing CLI numeric grade fields, verification caps, category completeness, and Challenge Lab C0-C5.

  • Do not infer a product's organizational maturity or promote candidate examples to independent validation. Missing evidence stays unassessed.

  • TCP schemas, commands, integrations, and dashboard views are not implemented. Read research/technology-contribution-examples.md for source limits and backlog.

  • Use AISM/TECHNOLOGY-VALIDATION.md and AISM/INCIDENT-EVIDENCE.md for test and incident-review practices; frozen Challenge 001 remains unchanged.

Useful entry points

  • Framework: README.md
  • Cross-Pillar Governance: 00-cross-pillar/README.md
  • MCP profile: 00-cross-pillar/cp5_mcp_server_security.md
  • AISM: AISM/README.md
  • NEXUS: NEXUS/README.md
  • Payment adapter usage: NEXUS/payments/ADAPTER-GUIDE.md
  • Sovereign Payment Gateway: NEXUS/payments/SOVEREIGN-GATEWAY.md
  • Scanner: scanner/README.md
  • Examples: examples/README.md
  • Research: research/README.md
  • Challenge Lab: challenges/README.md
  • Repository UX contract: docs/REPOSITORY-UX-STANDARD.md
  • Reusable GitHub release-note template: .github/RELEASE_TEMPLATE.md

When a machine-readable field and prose appear to conflict, do not silently guess. Preserve the conflict in the output and prefer the current v3.1 normative document identified by the manifest for interpretation.