# Architecture Conformance Audit — 2026-06-14

Skill: `architecture-conformance-audit` (doc-vs-code). Trigger: post-`develop → main` release (3.0.0-beta.75)
after large cross-package work (preset system PRESET-001~017, CTX-001, HIST-001).

## Step 1 — Mechanical baseline (deterministic floor)

| Check                      | Result                                                                                                                                        |
| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `pnpm harness:conformance` | ✅ PASS — `dependencyDirection: pass`, `packageNameViolations: 0`, `conformant: true`                                                         |
| `pnpm harness:scan`        | ✅ PASS — all 25 scans (incl. `conformance`, `deps`, `interface-imports`, `capability-placement`, `sdk-public-surface`, `document-authority`) |

**No cycles, no dependency-direction violations, no capability-placement code violation.** The code graph is
clean. Every finding below is a **doc-vs-reality gap**, not a code defect.

## Step 2/3 — Findings (AF-NN)

Verdicts: HOLDS / DRIFT (doc stale/incomplete about correct code) / VIOLATION (doc factually wrong) /
STALE (claims something as future that already shipped). Severity: P0 build/release break or real cycle;
P1 materially misleading or a significant undocumented contract; P2 minor staleness/omission.

| AF    | Sev | Verdict     | Document(s)                                                                                                                                        | Finding                                                                                                                                                                                                                                                                                                                                                                                                                  | Code evidence                                                                                                                                               |
| ----- | --- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| AF-01 | P1  | DRIFT       | `agent-system.md`, `dependency-direction.md`, `repository-overview.md`, `ARCHITECTURE.md`, `capability-placement.md`, `cross-cutting-contracts.md` | The `@robota-sdk/agent-preset` package + preset feature is **entirely absent** from every architecture-map graph/ownership doc (no node, no edge, no ownership row). Systemic omission from one release.                                                                                                                                                                                                                 | `packages/agent-preset/package.json` (dep: agent-framework); consumed by `agent-command/package.json:40`, `agent-cli/package.json:57`                       |
| AF-02 | P1  | DRIFT       | `packages/agent-framework/docs/SPEC.md`                                                                                                            | The entire PRESET-011~017 command-api seam is exported but undocumented: `applyPresetToSession`, `IPresetApplicationOptions/Result`, `IModelReapplyOptions`, runtime `getActivePresetId/setActivePresetId/applyModelOptions/setParallelSubagentsEnabled`, host `applyPersona/applyCommandModuleSelection/applySelfVerification`, `createSelfVerificationSection` (`'self-verification'` source), `selectCommandModules`. | `src/command-api/preset/preset-application.ts:18,60`; `src/command-api/host-context.ts:87-112`; `src/context/system-prompt-section-providers.ts:43`         |
| AF-03 | P1  | VIOLATION   | `packages/agent-command/docs/SPEC.md`                                                                                                              | SPEC says "**19** standard command modules"; code assembles **21** (`preset` + `schedule` missing from the table). `@robota-sdk/agent-preset` dependency undocumented.                                                                                                                                                                                                                                                   | `src/default/default-command-modules.ts:74-94` (21 modules incl. `createPresetCommandModule():79`); `package.json:40`                                       |
| AF-04 | P1  | STALE+DRIFT | `packages/agent-preset/docs/SPEC.md`                                                                                                               | External-preset surface (9 exports: `loadExternalPresets`, `loadExternalPresetsFromDir`, `registerExternalPresets`, `clearExternalPresets`, `validateExternalPreset`, `defaultExternalPresetDir` + 3 types) is undocumented, and Extension Points still calls it "future work (PRESET-007)" — already shipped.                                                                                                           | `src/index.ts:21-44`; `src/load-external-presets.ts`; `src/preset-validation.ts`                                                                            |
| AF-05 | P1  | DRIFT       | `packages/agent-cli/docs/SPEC.md`, `agent-cli-composition.md`                                                                                      | `--preset` flag, `selectPresetId`/`resolveCliPreset`, the startup `loadExternalPresets()` call, and the `@robota-sdk/agent-preset` dependency are undocumented.                                                                                                                                                                                                                                                          | `src/cli.ts:26,140,146,154`; `src/startup/preset-selection.ts:13,34`; `src/utils/cli-args.ts:39`; `package.json:57`                                         |
| AF-06 | P1  | DRIFT       | `packages/agent-session/docs/SPEC.md`                                                                                                              | New public methods (`applyModelOptions`, `get/setActivePresetId`, `get/setParallelSubagentsEnabled`) and `ISessionOptions` fields (`activePresetId`, `enableParallelSubagents`) undocumented.                                                                                                                                                                                                                            | `src/session-base.ts:39-101`; `src/session-types.ts:57-62`                                                                                                  |
| AF-07 | P1  | DRIFT       | `packages/agent-core/docs/SPEC.md`                                                                                                                 | `TModelEffort` SSOT + the `effort` channel through `IModelConfig`/`setModel`/`IChatOptions` + `'high'` default is undocumented.                                                                                                                                                                                                                                                                                          | `src/interfaces/provider.ts:190,207`; `src/core/robota-types.ts:13`; `src/core/robota-config-manager.ts:184`; `src/services/execution-round-provider.ts:54` |
| AF-08 | P1  | VIOLATION   | `ARCHITECTURE.md`, `repository-overview.md`                                                                                                        | References a `agent-team` package that **does not exist** on disk.                                                                                                                                                                                                                                                                                                                                                       | `ls packages/agent-team` → absent                                                                                                                           |
| AF-09 | P2  | STALE       | `ARCHITECTURE.md`                                                                                                                                  | Root ASCII package box has 6 wrong/nonexistent names (`agent-sessions`, `agent-runtime`, `agent-sdk`, `agent-command-*`, `agent-event-service`, `agent-team`) and omits ~6 real packages incl. `agent-preset`.                                                                                                                                                                                                           | `packages/` listing (18 packages)                                                                                                                           |
| AF-10 | P2  | DRIFT       | `cross-cutting-contracts.md`                                                                                                                       | Indexes `host-context.ts` for FLOW wake bridges but has no row for the preset seams in the **same file** — internal inconsistency.                                                                                                                                                                                                                                                                                       | `src/command-api/host-context.ts:50` (wake) vs `:87-112` (preset)                                                                                           |
| AF-11 | P2  | STALE       | `agent-cli-composition.md`, `transport-architecture.md`                                                                                            | "Source-verified against develop on <date>" stamps predate the beta.75 preset/TUI-preset-display changes.                                                                                                                                                                                                                                                                                                                | dates 2026-05-11 / 2026-05-18 vs beta.75                                                                                                                    |
| AF-12 | P2  | DRIFT       | `dependency-direction.md`                                                                                                                          | Minor edge omissions: `agent-subagent-runner → agent-core` (prose lists 3 of 4 deps); `agent-web-ui → agent-transport` node/edge absent.                                                                                                                                                                                                                                                                                 | `agent-subagent-runner/package.json`; `agent-web-ui/package.json`                                                                                           |

### HOLDS (notable — verified correct, no change needed)

- **HIST-001 append-only history**: agent-core SPEC "append-only, never edited/deleted" HOLDS — `DEFAULT_MAX_MESSAGES_PER_CONVERSATION = 0` (unbounded). ✅
- **CTX-001 provider-based context estimate**: agent-core + agent-session SPEC HOLDS — `getContextState` uses `estimateContextTokensFromMessages`. ✅
- **agent-preset core contract** (`IPreset`/`resolvePreset`/precedence/built-in catalog): HOLDS.
- **project-structure.md Preset Package Rule** (`agent-preset → agent-framework`; reverse edges "must never exist"): HOLDS — the one doc that _was_ updated for the preset edge.
- **Capability placement**: `agent-cli` is a genuine thin shell (zero preset feature seams in `packages/agent-cli/src`); application logic in agent-framework, data in agent-preset. No code violation.

## Counts

| Verdict       | P0    | P1                    | P2    | Total  |
| ------------- | ----- | --------------------- | ----- | ------ |
| DRIFT         | 0     | 6                     | 3     | 9      |
| VIOLATION     | 0     | 2                     | 0     | 2      |
| STALE         | 0     | 1 (folded into AF-04) | 2     | 3      |
| CONTRADICTION | 0     | 0                     | 0     | 0      |
| **Findings**  | **0** | **8**                 | **4** | **12** |

## Step 5 — Gate verdict

- **Machine-readable (GATE-CONFORMANCE mechanical core): ✅ PASS** — `harness:conformance` `conformant: true`, `harness:scan` 25/25.
- **Analytic layer: 0 P0, 0 code violations, 8 P1 + 4 P2 doc-drift findings.** The 3.0.0-beta.75 preset
  system + CTX-001/HIST-001 are correctly architected and placed in code, but the architecture-map docs and
  6 package SPECs were not updated alongside (a `three_doc_layers_sync` lapse). No release blocker; the
  remediation is documentation-only.

## Coverage completion (post-initial-pass) + skill fix

**Coverage gap found in the initial pass.** The first run verified only 7 of the 10 top-level
architecture-map subdocs + 6 preset-touched SPECs, and **missed the entire `agent-cli/` subtree**
(`.agents/specs/architecture-map/agent-cli/*.md`, 7 docs) plus `apps-and-deployment.md`,
`architecture-lessons.md`, the architecture-map `README.md`, and 12 not-yet-audited package SPECs.

**Root cause — a skill bug (now fixed):** `doc-claim-verification` > Canonical Document Set used a
non-recursive glob `.agents/specs/architecture-map/*.md` which excludes nested subtrees like `agent-cli/`.
Fixed to `**/*.md` with an explicit "enumerate with `find`, do not hand-list, no silent scoping"
instruction; the `architecture-conformance-audit` orchestrator Step 2 now requires mechanical enumeration

- a coverage report. (Files: `.agents/skills/doc-claim-verification/SKILL.md`,
  `.agents/skills/architecture-conformance-audit/SKILL.md`.)

**Completion pass findings (AF-13 … AF-37):**

| Range              | Document(s)                                                                       | Headline                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| ------------------ | --------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| AF-13 … AF-31 (19) | `agent-cli/` subtree (7 docs)                                                     | The most-drifted area. Beyond preset gaps: phantom startup files (`composition-tree`), wrong `cli.ts` line count (196→316), stale ownership paths (`createProviderFromSettings` → agent-framework; `ManagedShellProcessRunner` → agent-executor; AF-22 VIOLATION), removed `useInteractiveSession` hook → `useTuiChannel`/`TuiInteractionChannel`, outdated print/interactive flow (`HeadlessInteractionChannel`/direct `renderApp`), web-sidecar CONTRADICTION. **All 7 docs fixed.** |
| AF-32 … AF-34 (3)  | `architecture-map/README.md`, `apps-and-deployment.md`, `architecture-lessons.md` | README missed `transport-architecture.md` row (fixed); other two HOLD.                                                                                                                                                                                                                                                                                                                                                                                                                 |
| AF-35 … AF-37 (3)  | `agent-transport`, `agent-interface-transport`, `agent-playground` SPECs          | AF-35 (beta.75 priority): TUI active-preset status display undocumented → added. AF-36: "zero deps" claim vs 3 type-only deps → reworded. AF-37: playground allowed-list under-enumerated → fixed.                                                                                                                                                                                                                                                                                     |
| (HOLD)             | 9 of 12 remaining SPECs                                                           | `agent-executor/provider/plugin/tools/tool-mcp/remote-client/interface-tui/subagent-runner/web-ui` — verified, all HOLD.                                                                                                                                                                                                                                                                                                                                                               |

**Final coverage: all canonical docs verified** (ARCHITECTURE.md, project-structure.md, ARCHITECTURE-MAP.md,
all 10 top-level architecture-map subdocs + the 7-doc `agent-cli/` subtree, all 18 package SPECs).
**Totals: AF-01 … AF-37 = 37 findings (0 P0, 1 hard VIOLATION [AF-22, doc owner-path wrong], rest P1/P2),
0 code violations.** All remediation applied to docs in the same change set; `harness:scan` 25/25 stays green.
