# scaffold — baseline manifest + scaffold seeds

Machine-readable baselines that shape every fresh PA and every audit against a running one.

## `agent-baseline.json`

The list of capabilities every operator PA is expected to carry. Each entry is a mechanical presence-probe: `pa agent audit` (packages/cli/src/agent/) diffs an agent estate against this file and reports gaps.

Two failure classes it covers, in priority order:

1. **Drift** — the platform grows a capability, existing agents never adopt. This is the motivating case. Boot-slice shipped in core 0.1.7, one estate adopted, another never noticed for months. The audit turns adoption into a generated to-do instead of a memory test.
2. **Creation-time gaps** — a new agent scaffolded by `pa-init` boots missing standard kit. `packages/scaffold/test/manifest-coverage.test.mjs` runs the manifest against the pa-init plan and fails the build if any agents-local capability with a static-path probe is uncovered.

### Version-coupling convention

Every capability entry carries a `sinceVersion` (the `@stravica-ai/engineering-pa-core` release that introduced it) and the manifest as a whole carries a `manifestVersion` integer.

**When a new capability lands:**

1. Add the entry to `agent-baseline.json`.
2. Bump `manifestVersion` by 1.
3. Set the entry's `sinceVersion` to the core version the change ships in.
4. Note the manifest bump in `CHANGELOG.md` under the release (line pattern: `agent-baseline: added <capability-id> at manifestVersion N`).

**When a capability is removed** (rare — retired platform feature): bump `manifestVersion` and note the removal in the changelog. Never rename an `id` — retire and add.

### Probe types (v1)

Each probe carries a `type` and its own required fields (see `agent-baseline.schema.json`):

| Type | Purpose |
|---|---|
| `file-exists` | File at `path` exists. `{paName}` token substituted. |
| `directory-exists` | Directory at `path` exists (must be a dir, not a file). |
| `knowledge-doc-exists` | Semantic alias for `file-exists` on `operator/knowledge/**/*.md`. Kept as its own type so future extensions (graph presence, non-orphan) can enrich the check. |
| `staging-recent-write` | Directory exists AND has a non-hidden entry younger than `maxAgeDays`. Fails only if the newest entry is older than the window. Use with `severity: warn` — a quiet week is not a broken agent. |
| `schedule-defined` | A JSON file under `path` (typically `schedules/`) whose `command` includes ALL of `commandIncludes` and (if given) AT LEAST ONE of `commandIncludesAny`, and is not `enabled: false`. Host-pinned schedules produce `unverified-here` when the audited host doesn't match. Use with `hostDependent: true`. |
| `json-field-includes` | Open a JSON file at `path`, check that top-level `field` is an array containing `expectedValue` (token-substituted). Optional `requiredTool` gates the probe: absent tool = `unverified-here`. |

### Outcome ladder

| Rendered status | When |
|---|---|
| `pass` | Probe matched. |
| `warn` | Probe failed AND capability has `severity: warn` — informational, never gates `--strict`. |
| `fail` | Probe failed AND capability has `severity: fail` (default). Gates `--strict`. |
| `unverified-here` | Mechanically indeterminate on this host — host-pinned capability declared for another host, required tool absent from the estate, probe threw. Never a false pass, never a false fail. |

### Named defaults (ratified with the operator on approval)

- `pa agent audit` exit code default = 0 (informational tool). `--strict` opts into CI-gating exit 2 on any `fail`.
- `staging-recent-write` window = 7 days, severity `warn` (quiet-week tolerance).
- Host-dependent probes report `unverified-here`, never `fail`. Precision over noise.
- Manifest ships in `packages/core/knowledge/scaffold/` (single-bundled via `packages/engineering-pa/build.mjs`), not a separate schema package.
- Cache path `.session/agent-audit.json`, mirroring `pa environment`'s `.session/environment.json`.
- `sinceVersion` is the `@stravica-ai/engineering-pa-core` version, not the platform tarball version (manifest lives in core).

### Consumers

- **`pa agent audit`** — session-boot drift detection. Reads the cache; auto-refreshes on stale.
- **`pa-init`** (via `manifest-coverage.test.mjs`) — creation-time coverage guard. New capabilities that CAN be scaffolded MUST be scaffolded, or the test fails and forces the scaffold plan update at the same time as the manifest bump.
- **Future: `boot-context`** — the session-boot hook can surface a one-liner (`3/11 capabilities need adoption`) into the injected workState block.

## `domains.json`

The base set of knowledge domains seeded into every fresh PA — unchanged by this pass.