feat(skills): skill runtime, instruction resolver, capabilities and support bundle [SC-A0.1 + A0.2a]

[AetherAI3]

Problem

PR #71 ("Skills & Health") is CONFLICTING against main and cannot be rebased mechanically. It carries a large amount of genuinely new and valuable work — the skill runtime, the instruction resolver, the capability matrix, the support bundle — but it also carries a second, competing implementation of aether doctor v2.

Root cause

b98ef26d (2026-08-12) is the last commit main and PR #71 share.

• main then took PR feat: durable media output history, one safe opener, and aether doctor v2 #66 (27c100d8, 2026-08-14 14:42) — "durable media output history, one safe opener, and aether doctor v2".
• PR feat(skills): Skills & Health — skill runtime, instruction resolver, doctor v2, support bundle #71 branched at b98ef26d; its last commit a868f7d0 is 2026-08-14 22:49 — later on the clock, but authored against the 08-12 tree and therefore blind to PR feat: durable media output history, one safe opener, and aether doctor v2 #66.

Two independent "doctor v2"s were built in the same 48 hours. That is why only four files conflict textually while the semantic conflict is much larger.

Contract

The contested surface is the doctor report contract. Both sides declare schema version 2 with incompatible payloads:

	main — src/core/health.ts	PR #71 — src/core/diagnostics/contracts.ts
report	HealthReport, camelCase	DoctorReportV2, snake_case
configured / reachable / verified	Axis objects, state in {yes,no,unknown,na,not-checked}	plain boolean
mode	fast | live | fix	fast | network | live | fix
severity	info | warning | error	info | warning | critical

Decision: main's 3-axis model is canonical; PR #71's boolean triple is dropped, not merged.

A boolean verified cannot express not-checked. Fast mode performs no network I/O by contract, so every remote axis is unchecked — under PR #71's shape that must serialize as verified: false, which is indistinguishable from checked and failed. main's not-checked state keeps them distinct, and main's version is also the newer one. Shipping both would put two mutually incompatible payloads behind one schema_version: 2.

Two further decisions, recorded in full in the artifact:

• --deep stays read-only. PR feat(skills): Skills & Health — skill runtime, instruction resolver, doctor v2, support bundle #71 aliases it to --network, which silently adds network I/O to a flag that performs none today. --network will land as a new, explicitly named mode instead.
• main's engine content is kept. PR feat(skills): Skills & Health — skill runtime, instruction resolver, doctor v2, support bundle #71's dev_session_live.ts is 154 lines against main's doctor_live.ts at 991; a naive theirs resolution would have replaced the live engine with a 6x thinner one, and re-landed 9 checks main already has.

Full conflict matrix, per-surface decision record, and findings table: _loopstate/LOOP-01/sc-a0-2026-08-19/AUDIT-ARTIFACT.md

Implementation

This PR is A0.1 — the foundation only. It lands the part of PR #71 that main has no equivalent of. Notably, it applied to main unmodified: the port required zero source edits, which is itself evidence that the conflict was confined to the doctor engine.

src/core/skills/*        20 files — schema, digest, lock, trust, discovery, loader,
                         resolver, policy, bounds, eval, session, settings,
                         context packet, permission vocabulary
src/core/instructions/*   3 files — AGENTS.md discovery + resolution with provenance
src/core/why_log.ts       capability explanation log

Nothing is wired into the CLI yet, so this PR changes no user-visible behaviour. It is additive and inert until A0.3.

Tests

Run against this exact tree at d1b75ab:

command	result
npm ci --ignore-scripts	exit 0, 0 vulnerabilities
npm run typecheck	exit 0
npm test	1006 pass / 0 fail

Baseline re-measured on clean 41a7e261 in the same session: 922 pass / 0 fail. The 84 new tests are PR #71's skill and instruction suites, ported unchanged: trust/modify/re-trust lifecycle, lock drift, duplicate skill IDs across scopes, dependency cycles, lazy-loading token bounds, nested AGENTS.md precedence and provenance, conflicting-instruction detection.

No result here is inherited from PR #71's branch. PR #71 has no CI at all — gh pr view 71 --json statusCheckRollup returns an empty rollup — so nothing on it could have been inherited even if we wanted to.

Security notes

• No credential, token, or environment value is read, written, logged, or embedded by any file in this PR.
• Skill trust is digest-bound; a content change invalidates prior trust. Covered by test/skill_trust_lock.test.ts.
• Skill declarations restrict behaviour; they do not grant tools beyond the host's existing authority. Covered by test/skill_policy_packet.test.ts.
• Instruction resolution fails conservatively on unsupported syntax rather than guessing.

Known limits

• Skills are not reachable from the CLI in this PR. aether skills, /skills, aether capabilities, and the packaged built-in skill assets all land in A0.3.
• The skills and instructions doctor checks are not wired yet — they are the two checks from PR feat(skills): Skills & Health — skill runtime, instruction resolver, doctor v2, support bundle #71 that main has no equivalent of, and they need porting from PR feat(skills): Skills & Health — skill runtime, instruction resolver, doctor v2, support bundle #71's CheckSpec onto main's CheckOutcome. That is A0.2.
• --schema v2 JSON selection and the JUnit renderer from PR feat(skills): Skills & Health — skill runtime, instruction resolver, doctor v2, support bundle #71 are written against the dropped DoctorReportV2. They are deferred: either re-targeted at HealthReport in A0.3, or dropped.
• Out of scope but found during intake: package.json repository and bugs still point at DBarr3/aether-agent, not AetherAI3/aether-agent. Left for the integration lane rather than fixed opportunistically here.

Dependency and merge order

A0.1  this PR            skill + instruction foundation
A0.2  depends on A0.1    capabilities, support bundle, redaction/tar,
                         skills+instructions checks ported onto health.ts
A0.3  depends on A0.2    CLI wiring, packaged skill assets, docs

SC-A1 (tool runtime) and SC-A5 (usage continuity) both start from the accepted A0 head — PR #71 also modifies src/core/stream.ts, which both of those lanes own.

PR #71 should stay open until A0.3 merges, then be closed as superseded rather than merged. Its doctor engine is deliberately not carried forward.

---

Update — scope now covers A0.1 and the first half of A0.2

This branch has grown past the "foundation only" description above. Recording the
change rather than leaving a stale body.

Commits on this PR

commit	what
d1b75ab	A0.1 — skill runtime + instruction resolver foundation
1521199	CodeQL high-severity fix + mutation-checked regression test
ba7d041	A0.2 part 1 — capability matrix + redacted support bundle

Why one PR instead of the planned three. A0.1 is inert on its own and A0.2's
support bundle depends on it directly, so splitting them would produce a first PR
no reviewer can exercise and a second that cannot be reviewed without the first.
At ~37 files this is still well under PR #71's 100, and the module boundaries make
it readable. A0.3 (CLI wiring, packaged skill assets, docs) stays a separate PR.

CodeQL finding, fixed

CI flagged js/incomplete-sanitization (high) at instruction_resolver.ts:18 —
the glob metacharacter escape used a non-global regex, so only the first
metacharacter was escaped.

Not exploitable as written: char is glob[index], always a single code unit,
so a second occurrence cannot exist. But the escape's safety rested on an invariant
the function never stated, and a future change to a multi-character token would
silently widen every glob's match set. Fixed rather than dismissed.

The regression test pins the property, not the implementation: a glob containing
. + ( ) | { } [ ] $ ^ must match itself literally and must not match a decoy,
while ** and * keep working. Mutation-checked — replacing the escape with a
bare pattern += char fails the test (unescaped . would match axts); restoring
it passes.

This defect arrived from PR #71 untouched. PR #71 runs no CI, so on its own branch
it would have shipped unseen.

A0.2 part 1 — the one real port

capabilities.ts, redaction.ts, tar.ts and the generated capability snapshot
applied unmodified. support_bundle.ts needed two lines: it called PR #71's
doctorReportV2, which this rescue drops in favour of main's diagnosticReport.

The swap strictly improves the bundle. Under PR #71's boolean model a fast-mode
bundle — which performs no network I/O — had to serialize verified: false for
every remote axis, indistinguishable from checked and failed. main's
HealthReport carries per-axis not-checked, so an unexercised probe stays
visibly unexercised in the artifact a user hands to support.

Gates at ba7d041

command	result
npm run typecheck	exit 0
npm test	1017 pass / 0 fail
npm run smoke	3 pass / 3 skip / 1 fail

Test progression, each measured on the exact tree: 922 (clean 41a7e261) → 1006
(A0.1) → 1007 (CodeQL regression test) → 1017 (A0.2 part 1).

The smoke failure is operator-owned, not a regression. cloud turn returns
HTTP 401 "Invalid or expired session token". Verified by re-running smoke at
1521199 with this commit's changes stashed — identical failure. It needs
aether auth login. No file in this PR is on the cloud-turn path. Reported as a
fail, not rounded up to a pass.

Bundle safety suites pass: a seeded canary secret is rejected rather than shipped,
and an interrupted generation leaves no misleading "complete" artifact.

Still owed before this PR leaves draft

• A0.2 part 2 — port PR feat(skills): Skills & Health — skill runtime, instruction resolver, doctor v2, support bundle #71's skills and instructions doctor checks (the
  only two it has that main lacks) from its CheckSpec onto main's CheckOutcome,
  plus the safe-repair reconciliation.
• Re-run the full gate after that port.

A0.3 (CLI wiring, built-in skill assets, aether skills, /skills,
aether capabilities, docs) remains a separate follow-up PR. Until it lands, none
of this is reachable from the command line — it is additive and inert.