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