design: per-driver context-management spec + role-aware three-tier (proactive/immediate/peripheral) context probe #372

New issue

Closed

opened 2026-06-26 07:21:13 +00:00 by coilysiren · 1 comment

coilysiren commented

2026-06-26 07:21:13 +00:00

Owner

Motivation

Low-capability drivers (the qwen trivial tier, any small local model, a degraded
remote) fail not only when context is missing but when it is too much.
Three tiers of context load a driver, and each drowns a weak model differently:

proactively presented - the eager bytes in the prompt at session start
(composed AGENTS/CLAUDE doctrine, every mounted skill's frontmatter, the
statusline, the issue-corpus index, the front-load seed block).
immediately available - the working-dir clone under /workspace/<name>,
one tool call away. A 3k-file repo is a real grep/attention surface even though
it is not in the prompt.
peripherally available - the /substrate/<name> reference repos (8 today)
the agent can grep without leaving its box. Cheap to provide, not free to a
small model that now has a much larger haystack to pick wrongly from.

The thesis: a low-capability warded driver is fundamentally incapable of its
task if any tier is too heavy, so each tier must be curated per driver. We want a
programmatic, agent-runnable probe that spins (or composes) a warded role and
reports all three tiers with numbers, plus a per-driver context-management
spec that declares and enforces the budget. This issue is design-first:
propose the probe architecture and the spec schema, do not lock a schema yet.

What already exists (do not rebuild)

check_context_budget (agentic-os, ward context-budget,
agentic_os/pre_commit/check_context_budget.py, docs/context-budget.md).
Measures the proactive axis only - composed doc + skill frontmatter + an
mcp server-count note - per harness (claude/codex/opencode), static,
host-side, chars/4 proxy, with --check for CI and per-harness budgets.
agent-adapters.yaml per-agent contextLevel: 2|1|0 (full/scoped/minimal),
the WARD_CONTEXT_LEVEL ladder the entrypoint composes against
(docs/agent-adapter-manifest.md). This is the only per-driver context
knob today: one integer, not a spec.
substrate manifest (preclone-repos.txt, 8 repos) - the peripheral tier.
agentic-os#269 - the open consult seed: "investigate how much surrounding
context commands like goose ask use." This issue is the per-role, three-tier
generalization of that seed.

The gap

Per-harness, not per-role. check_context_budget measures claude vs codex
vs opencode. It does not model the warded roles (engineer / advisor /
director / architect), which differ in WARD_CONTEXT_LEVEL composition and
in live container-only additions (the container doctrine overlay, the architect
read-only section, the issue-corpus index ward#367, the statusline ward#294,
the front-load seed block). The user explicitly wants engineer / consultant
(advisor) / director measured as they actually land in the container.
Proactive axis only. Nothing measures the immediately-available
(working-dir clone: file count, bytes, token-proxy) or peripherally-available
(substrate: repo count, total grep surface) tiers, which the thesis says matter
most for weak drivers.
contextLevel is one int, not a spec. There is no per-driver declaration
of a budget across the three tiers, and no enforcement.

Proposed shape (design these, do not lock yet)

Role-aware three-tier probe. For a given role+driver, compose (or spin) the
container and report: proactive (extend/reuse check_context_budget's doc+skill
accounting plus the container-only additions), immediately-available (walk
/workspace/<name>: tracked-file count, bytes, token-proxy), peripherally-
available (walk /substrate/<name>: per-repo and total). Programmatic,
--check-able, agent-runnable. Spin-real-container vs static-composition is an
open design fork - state the trade and pick.
Per-driver context-management spec. Propose extending agent-adapters.yaml
from a single contextLevel int to a per-tier budget block (proactive /
immediate / peripheral), so each driver declares its ceiling and the probe's
--check enforces it. The first schema instance sets the pattern everything
copies - propose it, surface it for Kai to shape, do not autonomously commit a
locked schema.
Authoring-vs-rollout split (per aos doctrine): the measurement is
authored in agentic-os (extend check_context_budget with the working-dir +
substrate tiers, measurement-only, reversible). The role-spin probe + the
spec schema live in ward, which owns roles, containers, substrate, and
WARD_CONTEXT_LEVEL. Cross-file an agentic-os companion for the measurement leg.

Acceptance (design-first)

A design proposal (comment or docs/<feature>.md) covering: the probe
architecture (real-spin vs compose), the per-tier accounting for each role, the
proposed per-driver spec schema, and the agentic-os/ward split.
The proposal names the open forks for Kai (spec schema shape, real-spin vs
static, where --check enforcement lives) rather than silently resolving them.
No locked schema committed to agent-adapters.yaml until Kai blesses it.

Non-goals

A real qwen tokenizer (the chars/4 proxy is fine for a zero-sum comparison).
Runtime/accumulated context (this measures init load, not sweep blow-out).

Filed from a read-only architect session (design walk on per-driver context
curation). Generalizes agentic-os#269; builds on docs/context-budget.md.

## Motivation Low-capability drivers (the qwen trivial tier, any small local model, a degraded remote) fail not only when context is **missing** but when it is **too much**. Three tiers of context load a driver, and each drowns a weak model differently: - **proactively presented** - the eager bytes in the prompt at session start (composed AGENTS/CLAUDE doctrine, every mounted skill's frontmatter, the statusline, the issue-corpus index, the front-load seed block). - **immediately available** - the working-dir clone under `/workspace/<name>`, one tool call away. A 3k-file repo is a real grep/attention surface even though it is not in the prompt. - **peripherally available** - the `/substrate/<name>` reference repos (8 today) the agent can grep without leaving its box. Cheap to provide, not free to a small model that now has a much larger haystack to pick wrongly from. The thesis: a low-capability warded driver is **fundamentally incapable** of its task if any tier is too heavy, so each tier must be curated per driver. We want a **programmatic, agent-runnable probe** that spins (or composes) a warded role and reports all three tiers with numbers, plus a **per-driver context-management spec** that declares and enforces the budget. This issue is **design-first**: propose the probe architecture and the spec schema, do not lock a schema yet. ## What already exists (do not rebuild) - **`check_context_budget`** (agentic-os, `ward context-budget`, `agentic_os/pre_commit/check_context_budget.py`, `docs/context-budget.md`). Measures the **proactive** axis only - composed doc + skill frontmatter + an mcp server-count note - **per harness** (claude/codex/opencode), static, host-side, chars/4 proxy, with `--check` for CI and per-harness budgets. - **`agent-adapters.yaml`** per-agent `contextLevel: 2|1|0` (full/scoped/minimal), the `WARD_CONTEXT_LEVEL` ladder the entrypoint composes against (`docs/agent-adapter-manifest.md`). This is the **only** per-driver context knob today: one integer, not a spec. - **substrate manifest** (`preclone-repos.txt`, 8 repos) - the peripheral tier. - **agentic-os#269** - the open consult seed: "investigate how much surrounding context commands like goose ask use." This issue is the per-role, three-tier generalization of that seed. ## The gap 1. **Per-harness, not per-role.** `check_context_budget` measures claude vs codex vs opencode. It does **not** model the warded **roles** (engineer / advisor / director / architect), which differ in `WARD_CONTEXT_LEVEL` composition **and** in live container-only additions (the container doctrine overlay, the architect read-only section, the issue-corpus index ward#367, the statusline ward#294, the front-load seed block). The user explicitly wants engineer / consultant (advisor) / director measured **as they actually land in the container**. 2. **Proactive axis only.** Nothing measures the **immediately-available** (working-dir clone: file count, bytes, token-proxy) or **peripherally-available** (substrate: repo count, total grep surface) tiers, which the thesis says matter most for weak drivers. 3. **`contextLevel` is one int, not a spec.** There is no per-driver declaration of a budget across the three tiers, and no enforcement. ## Proposed shape (design these, do not lock yet) - **Role-aware three-tier probe.** For a given role+driver, compose (or spin) the container and report: proactive (extend/reuse `check_context_budget`'s doc+skill accounting plus the container-only additions), immediately-available (walk `/workspace/<name>`: tracked-file count, bytes, token-proxy), peripherally- available (walk `/substrate/<name>`: per-repo and total). Programmatic, `--check`-able, agent-runnable. Spin-real-container vs static-composition is an open design fork - state the trade and pick. - **Per-driver context-management spec.** Propose extending `agent-adapters.yaml` from a single `contextLevel` int to a per-tier budget block (proactive / immediate / peripheral), so each driver declares its ceiling and the probe's `--check` enforces it. **The first schema instance sets the pattern everything copies - propose it, surface it for Kai to shape, do not autonomously commit a locked schema.** - **Authoring-vs-rollout split** (per aos doctrine): the **measurement** is authored in agentic-os (extend `check_context_budget` with the working-dir + substrate tiers, measurement-only, reversible). The **role-spin probe + the spec schema** live in ward, which owns roles, containers, substrate, and `WARD_CONTEXT_LEVEL`. Cross-file an agentic-os companion for the measurement leg. ## Acceptance (design-first) - A design proposal (comment or `docs/<feature>.md`) covering: the probe architecture (real-spin vs compose), the per-tier accounting for each role, the proposed per-driver spec schema, and the agentic-os/ward split. - The proposal names the open forks for Kai (spec schema shape, real-spin vs static, where `--check` enforcement lives) rather than silently resolving them. - No locked schema committed to `agent-adapters.yaml` until Kai blesses it. ## Non-goals - A real qwen tokenizer (the chars/4 proxy is fine for a zero-sum comparison). - Runtime/accumulated context (this measures **init** load, not sweep blow-out). Filed from a read-only architect session (design walk on per-driver context curation). Generalizes agentic-os#269; builds on `docs/context-budget.md`.

coilysiren added the

consult

labels

2026-07-01 04:29:35 +00:00

coilyco-ops commented

2026-07-02 00:17:40 +00:00

Member

Merged into #373 (identical design ticket filed twice; #373 is canonical at P3). Recorded by Claude Code (Fable) during the 2026-07-01 ward launch triage session with Kai.

coilyco-ops closed this issue

2026-07-02 00:17:42 +00:00

coilyco-ops referenced this issue

2026-07-02 00:21:47 +00:00

design: per-driver context-management spec + role-aware three-tier (proactive/immediate/peripheral) context probe #373