AAS Agent-First Control Plane Preview Profile

Status: approved intermediate release profile Date: 2026-07-17 Certified design: docs/maintainers/aas-agent-first-control-plane-v1-design.md

Purpose

This profile validates whether Codex, Claude Code, and comparable agents can use AAS to compose useful local skill stacks before AAS claims the stronger certified-v1 guarantees. It is additive: it does not change the frozen v1 design, benchmark, hostile corpus, verifier, or completion criteria. A passing preview does not complete the active v1 goal.

The permitted preview claim is:

AAS Agent-First Preview helps Codex and Claude compose a local, explainable, reproducible skill stack. Full-catalog recommendation quality and transactional apply/recovery safety are not yet certified.

Preview output must not use implementationVerified, releaseReady, released, certified, or an equivalent unqualified claim.

Included preview surfaces

Minimal, schema-validated aas-stack.json with pinned catalog identity, targets, approved intent and policy, and exact skill IDs.
CLI stack init, stack recommend, stack validate, stack plan, and stack doctor from the packed npm candidate.
The local stdio MCP with exactly search_skills, get_skill, recommend_stack, inspect_stack, diff_stack, and aas://skills/{id}.
Deterministic recommendation with structured factors, two visible lanes (recommended and discoveryCandidates), explicit unknowns, stable tie-breaking, and fail-closed policy decisions.
Functional Node 22/24 coverage on Linux, macOS, and Windows from one exact content-addressed tarball.
Workbench schema/import/render tests and a local production build. A live Pages deployment remains outside the preview until separately approved.

Experimental writes

stack apply and stack recover are present for controlled development but are not preview-supported safety claims. They are disabled by default:

apply requires the additional --experimental-apply flag and the existing exact plan-digest approval;
recovery requires --experimental-recovery and retains its existing recovery-plan approval;
successful experimental writes return releaseProfile: "preview" and certificationStatus: "experimental";
absence of the opt-in fails before runtime resolution or target writes with a structured policy error.

Internal transaction tests are development evidence only. Certification still requires the frozen production-binary crash, boundary, race, rollback, and recovery verifier.

Preview functional gate

Every matrix job must install the exact candidate tarball with lifecycle scripts disabled and run without checkout-only runtime dependencies. No job may be skipped or allowed to fail.

On Windows, the preview verifier may materialize its own isolated runtime-cache fixture and must then have the production core verify the complete identity and every cached byte before plan, doctor, or MCP use. This proves the read-only functional lifecycle without claiming that Windows cache-promotion durability is certified. Native directory-flush and interrupted-promotion evidence remains part of the certified-v1 transaction gate.

Windows preview creation of the regenerable manifest and immutable plan uses the explicit --preview-windows-output opt-in. The CLI fsyncs the file and returns outputDurability: "fileSyncedDirectoryUnverified" together with certificationStatus: "notCertified"; without that flag it remains fail-closed. This opt-in never applies to skill installation, host configuration, apply, or recovery.

Required functional suites are:

Package and entrypoints — allowlisted package contents; aas, aas-mcp, and the legacy alias exist; legacy invocation creates no stack state implicitly.
Stack lifecycle — init -> recommend -> validate -> plan -> doctor succeeds in isolated roots and does not materialize target skills or AAS managed state.
Determinism and explanation — repeated identical inputs produce the same canonical recommendation payload and expose factor, coverage, evidence, exclusion, and unknown fields.
Policy — proved incompatibility or forbidden risk is excluded; incomplete evidence remains visible; malformed or over-limit input fails closed.
MCP contract — the five tools and one resource template work over real stdio framing; project and cache snapshots remain unchanged by tool calls.
Write guard — apply and recovery without their experimental flags fail with structured policy codes and leave project, cache, and managed state unchanged.
Workbench — bounded text-only import/review tests and production build pass without ambient filesystem access.

The preview receipt must declare:

{
  "assuranceProfile": "agent-first-preview-1",
  "previewQualified": true,
  "certifiedV1": false,
  "notEvaluated": [
    "native-network-and-filesystem-attempt-observation",
    "transactional-crash-and-race-certification",
    "benchmark-80-90-100",
    "real-host-configuration-writes",
    "public-release"
  ]
}

Missing receipts, crashes, timeouts, canonical drift, or any failed functional suite make previewQualified false.

Explicitly not certified by preview

ETW, fs_usage, or strace proof of zero network attempts and zero persistent MCP writes.
Production-binary fault injection at every transaction boundary or every declared race class.
Full benchmark thresholds: at least 80% verified coverage, 90% inclusion precision, and 100% correct abstention for each supported intent and in macro-average.
Complete property/fuzz/hostile budgets required by certified v1.
Real Codex or Claude configuration writes, public Pages deployment, npm publication, GitHub release, or announcement.

These remain mandatory before AAS can call the recommendation system or transactional lifecycle certified v1.

Product-learning gate

After the functional matrix passes, preview evaluation should measure whether agents actually produce useful proposals:

task completion rate from a repository profile to a reviewable stack;
human accept/replace/remove rates for recommended skills;
uncovered goals and discovery-candidate promotions;
deterministic replay rate for the same normalized input and catalog digest;
time and interaction count from request to approved manifest.

No repository profile, source file, secret, or raw path is uploaded by default. Publishing or sharing any collected result requires a separate explicit decision and privacy review.

Relationship to certified v1

The certified verifier may remain red or unevaluated while the preview gate is green. That state must be reported as previewQualified: true and certifiedV1: false, never as a skipped certified pass. The frozen v1 design and goal remain the only completion criteria for certification and release.

6.8 KiB Raw Blame History