Rule Advice Supervision

---
name: "rule-advice-supervision"
description: "Contract governing the --advice flag: supervision checkpoints, caps, packets, dossier, receipts, and the boundary that keeps counsel from approving anything. Load only when --advice is present."
---

# Advice Supervision (`--advice`)

Not a workflow. This is the contract a wrapped skill loads **on demand** when the user
passed `--advice`, and it is inert otherwise. Do not invoke it as a task.

**Core rule:** when — and only when — the user passes `--advice`, a supporting skill may
call the `athena` agent at a small set of **named checkpoints** to get strategic
supervision over one delivery run. Athena assesses the situation, makes an evidence-backed
operational recommendation, guides before work, rescues a blocked run, reviews finished
work, and may return work for correction.

Supervision is **evidence a human reads**. It is never an approval, never a gate, never a
substitute for verification.

Athena is a workflow-level strategic intelligence agent with stronger reasoning and
cross-phase visibility — and **no mutation authority**. The parent owns execution, the
dossier, receipts and routing. Existing specialists keep their verdicts. Athena is
reachable through the `--advice` harness, and — where this runtime exposes direct
delegation by name — for a stateless strategy consult. It owns no lifecycle phase.

The mechanical half of this contract is enforced in code by the toolkit CLI — stage and
disposition legality, caps, packet size and content checks, dossier fields. Where this
prose and those checks disagree, the checks are authoritative and the prose is the bug.

## 1 — Activation

- Fires ONLY on an explicit `--advice` flag on a skill that documents support.
- NEVER from a session-start, session-end, or any other lifecycle hook. Hooks may not
  invoke agents.
- NEVER auto-enabled by a mode, tier, risk flag, score, or failure count.
- Delegated child jobs never self-supervise: a supervised parent does not hand `--advice`
  to the subagents it spawns.

Without the flag the checkpoint blocks are inert and cost nothing: the skill does not load
this file, makes zero calls, and writes no state or receipt.

## 2 — Cadence

```text
GUIDE → (executor works) → RESCUE* → REVIEW → RECHECK*
```

Checkpoints are **macro boundaries**, never per tool call, per file, or per loop
iteration.

| Stage | Purpose | Max per run |
|---|---|---:|
| GUIDE | Direction before work starts | 1 |
| RESCUE | Unblock a stalled or contradicted run | 2 (one per rework round) |
| REVIEW | Independent read of finished work, against evidence | 1 |
| RECHECK | Re-examine returned work | 1 |

Per-skill total ceiling:

| Skill | Cap |
|---|---:|
| `mk-brainstorming` | 4 |
| `mk-plan-creator` | 4 |
| `mk-cook` | 5 |
| `mk-fix` | 5 |
| `mk-autobuild` | 5 |
| `mk-ship` | 4 **per release stage** — `prepare`, `release` and `publish` each carry their own budget, charged by `--release-stage`. The flag is required for ship and refused for every other skill; it is fixed at `begin` and inherited by `commit`. |

Rules that keep the cadence bounded:

- A duplicate `checkpointId` is **idempotent** — it returns the prior result and does not
  consume a cap slot. That is what makes crash-and-resume safe. Ids are unique per RUN,
  not per partition: reusing one under a different stage or release stage is a naming
  collision and is refused, because returning another checkpoint's recorded result would
  silently skip the one the workflow believes it ran.
- `RECHECK` requires a prior `RETURN_TO_EXECUTOR`.
- A **second unresolved return escalates to a human.** There is no third opinion. Returns
  are counted within the budget that spent them, so on a partitioned skill a resolved
  return in one release stage and an unrelated one in another are two episodes, not one
  unresolved loop. The escalation flag itself stays run-wide: once a human has been asked,
  the whole run waits for them.
- Reaching a cap escalates; it never loops.
- A recorded call that names no partition, or names one the skill does not declare, counts
  against **every** partition. Skipping it would turn history written before the skill was
  partitioned — or a hand-edited value — into a free slot in each budget. Counting it
  everywhere can only under-permit, which is the direction this contract errs in.

**Rescue complements human stops; it never delays them.** The `mk-fix` rule — 3+ failed
attempts means stop and question the architecture with the user — fires on its own
schedule whether or not counsel was taken at two failures. The same holds for the Gate 1
question, the Gate 2 question, and any explicit business decision.

## 3 — Input packet (the parent supplies)

A fresh subagent inherits no conversation, so the packet is the supervisor's entire world.
Fields: `runId`, `skill`, `stage`, `checkpointId`, `mission`, `lockedDecisions`,
`currentState`, `workerSummary`, `evidenceRefs`, `priorDirective`, `question`,
`riskAndReversibility`.

- Serialized cap **12 KiB UTF-8** — fail visibly BEFORE delegation, never truncate. A
  truncated packet asks a different question than the one intended.
- At most **5 evidence pointers**, each carrying `path`, `relevance`, `provenance` and a
  short `summary`. Provenance is mandatory: an unattributed path cannot be weighed, and a
  fresh subagent cannot reconstruct it.
- **Never** a raw transcript, full diff or log, memory dump, secret or personal data, or
  unrelated project history. Pass a pointer, not the payload.
- Start with the map; Athena reads only the detail it selects.
- Locked decisions and the exact current question appear at both start and end as
  attention anchors.

## 4 — Output packet (Athena returns)

Fields: `disposition`, `strategicAssessment`, `decisionRecommendation`,
`strategicDirective`, `requiredCorrections`, `nextFalsifiableCheck`, `risksAndRollback`,
`rejectedAlternatives`, `assumptions`, `confidence`, `evidenceRead`.

Dispositions are **stage-specific**, and an illegal one is rejected before routing:

| Stage | Legal dispositions |
|---|---|
| GUIDE, RESCUE | `CONTINUE_WITH_DIRECTIVE`, `ESCALATE_TO_HUMAN`, `BLOCKED_MISSING_EVIDENCE` |
| REVIEW, RECHECK | `READY_FOR_EXISTING_GATE`, `RETURN_TO_EXECUTOR`, `ESCALATE_TO_HUMAN`, `BLOCKED_MISSING_EVIDENCE` |

`READY_FOR_EXISTING_GATE` means "the normal reviewer or gate is the correct next step". It
**never** means the gate is cleared.

- Output cap **600 words**. Volume is not rigor.
- `requiredCorrections`: max 5, ordered, each independently verifiable and each naming its
  `proofRequired`. `RETURN_TO_EXECUTOR` requires at least one.
- `decisionRecommendation` selects one operational path within the packet's locked scope
  and says why. It MUST escalate rather than override a locked business, security,
  compliance or gate decision.
- No `approve`, `clear`, `merge`, `deploy` or equivalent authority language, in any
  wording. Say "the evidence supports X".

### Transport status vs disposition

The subagent status block is **transport status only**: `DONE` means a valid packet
arrived; `BLOCKED` means no usable directive exists. The `disposition` field is the sole
workflow-routing signal. A `BLOCKED` transport may not carry a usable directive, and a
delivered packet must state a disposition — either mismatch is refused rather than guessed
at.

## 5 — Continuity dossier

One parent-owned file per run at the deterministic path
`tasks/reports/{supervisionRunId}-athena-supervision.md`.

Athena is a long-lived **lead**, never a long-lived **session**: every call is a fresh
isolated subagent. Continuity therefore comes from this compact record, NOT from a
transcript, an auto-memory, or a new supervisor store.

- Frontmatter and active summary stay under **2 KiB**, holding only run identity, current
  stage, locked-decision pointers, latest directive, correction count, receipt pointers,
  and next safe action.
- Historical receipts may sit below the active summary but are **never auto-loaded**.
  Never append full model output.
- The dossier **cannot** carry progress, verification, gate, approval, verdict or status
  fields. A candidate that does is refused, not stripped — silently dropping a field the
  caller believed it stored is worse than refusing.
- Two-step checkpoint marker: `pending` written BEFORE the call, `committed` after the
  result lands. A pending marker lets a resuming parent recognize an already-attempted
  checkpoint instead of spending another slot.
- Pointer placement: an active durable task gets an `evidenceRef`; a plan or run artifact
  gets a pointer; a one-off run keeps only the local dossier and has no automatic
  cross-session resume guarantee. Never invent an active task.

A state or write failure disables supervision for that run, emits the exact degraded
notice, and lets the ordinary unsupervised workflow continue — but no later Athena call may
run until durable state is recovered.

## 6 — Correction cycle

`RETURN_TO_EXECUTOR` routes work back to its **current owner** — planner, developer,
tester, whoever owns it — never to Athena.

1. The executor addresses each correction or records why it is rejected.
2. Source changes advance `evidenceRevision` and mark stale verification and review
   evidence **superseded**; normal checks re-run.
3. Plan or scope changes additionally invalidate Gate 1 and require a new human approval.
   In-scope source corrections keep Gate 1 but invalidate downstream evidence.
4. Athena rechecks once by default. A second unresolved return escalates.

Superseded evidence must never read as current at a later gate or ship preflight.

**A correction's only write target is an existing `workflow-evidence.json` inside the
project.** The index lives under several roots but always under that name, so the name is
the check; the CLI refuses any other path. Both the boundary check and the name check run
on the **resolved** path, because a textual check answers a question about the caller's
string rather than about the file that will be opened, and reads follow symlinks. A path
that does not resolve is absent, and a correction supersedes recorded evidence rather than
creating it, so it is refused.

## 6a — Composing with `--html`

`--advice` and `--html` are orthogonal. Neither implies the other, each is parsed
independently, and combining them changes no activation, approval, validation, export or
ownership. A run with both produces the same visual artifact, at the same path, validated
by the same validator, approved by the same human at the same gate, and exported by the
same owner as `--html` alone would for the same final Markdown.

They meet only in the correction loop, because a supervised correction edits Markdown and
the visual artifact pins hashes of it. The Markdown plan stays the source of truth; REVIEW
fires before the gate step where the visual preconditions are checked; and a returned
correction invalidates the artifact's pinned hashes exactly like any other Markdown edit —
rehash (which clears the prior visual approval), re-validate, re-review, re-approve, then
present the ordinary Gate 1. A stale artifact never reaches the gate beside a corrected
plan.

Athena approves no visual, edits no HTML, changes no filename or path, opens no browser,
and turns no dossier or receipt into a rendered artifact.

## 7 — Prohibitions

Athena MUST NOT:

- Mutate anything: no source, test, fixture, plan, verdict, status report, or memory
  write, and no command that alters the working tree. Only the parent writes the dossier
  and the receipt.

  Be precise about how that is enforced here: a Codex agent definition carries no
  per-agent tool or permission field, so on this runtime the ban is **behavioral —
  enforced by the agent's instructions, not by the sandbox**. The other two provider
  planes enforce it structurally (tool omission, read-only flag). Do not treat the
  behavioral ban as weaker for that reason, and do not describe this surface as
  structurally read-only.
- Interview the user. That is the `advisor` agent behind `mk-advise`, unchanged by this
  rule.
- Emit a verdict, score, grade, or security clearance. The `reviewer`, `evaluator` and
  `security` agents own those.
- Approve, clear, unblock, or advance Gate 1, Gate 2, a security review, CI, a merge, a
  deploy, or any user business decision.
- Change the executor's model, profile, or effort. `--advice` supervises the workflow, not
  the model running it.
- Spawn another Athena or any lifecycle agent.

**Gate authority invariant:** automation executes BETWEEN gates and never supplies the
authority OF a gate. An Athena directive is in exactly the same class as an evaluator
verdict or a green test suite — evidence presented to a human at the gate, never the
approval itself. Prose that lets supervision advance a gate, in any wording, is a
violation.

A directive is also **not verification**. Verification comes from tests, review verdicts
and validators. Supervision never counts toward it.

## 8 — Receipt

After each checkpoint the **parent** (never Athena) writes a receipt to
`tasks/reports/{YYMMDD}-{slug}-advice-{n}.md`:

```markdown
---
kind: advice-receipt
runId: <supervisionRunId>
stage: GUIDE | RESCUE | REVIEW | RECHECK
disposition: <the returned disposition, verbatim>
outcome: adopted | rejected | deferred
reason: <one line — required even when adopted>
taskId: <active task id, or "none">
provider: <runtime>
skill: <skill and workflow>
checkpointId: <named checkpoint>
---

This is a record of supervision, NEVER verification and never a gate approval.

**Question asked:** …
**Directive:** … (summary, not the full packet)
**Required corrections:** … (or "none")
**Evidence pointers:** …
**Next safe action:** …
```

`disposition` is Athena's returned routing signal; `outcome` is what the parent did with
it. They are separate fields because a parent may rightly reject a directive, and
collapsing them would hide that. The reason is required even when adopted — "why" is what
a later session cannot reconstruct.

A failed receipt write surfaces a one-line notice and never fails silently.

## 9 — Propagation

Only `supervisionRunId` crosses an approved top-level lifecycle handoff between skills that
both document `--advice`. Spawned workers receive a task-specific directive — never the
flag, never the dossier, never routing ability.

## 10 — Fallback

If the runtime cannot discover the agent or execute a foreground delegation, the skill
prints exactly:

```
advice checkpoint unavailable in this runtime: <reason>
```

then continues unsupervised.

**Inline self-advice impersonating Athena is forbidden.** A recommendation written by the
agent that is stuck is not an independent check, and labelling it as one corrupts the
receipt.

## 11 — Direct consult vs embedded supervision

Where this runtime exposes direct delegation to the agent by name, that is a **stateless
strategy consult**: Athena may assess a difficult situation, compare alternatives and make
a recommended operational decision, but creates no run receipt, correction routing or cap
accounting. It is NOT lifecycle supervision and must label itself accordingly. It escalates
rather than changing a locked business, security, compliance or gate decision. Embedded
supervision requires a valid `supervisionRunId`.

A direct consult returns a **strategy brief**, which is a different shape from a checkpoint
packet and deliberately cannot carry a `disposition`:

| Field | Required |
|---|---|
| `situation`, `decisionRecommendation`, `nextFalsifiableCheck`, `escalationPoint`, `confidence` | yes |
| `rejectedAlternatives`, `risksAndRollback`, `assumptions`, `evidenceRead` | no |

`disposition`, `requiredCorrections`, `strategicDirective`, `runId`, `stage`,
`checkpointId` and any receipt, dossier or correction field are **refused, not stripped**.
A disposition is a routing signal for a run; emitted without one it reads as a governed
decision that no run ever governed, and a later reader cannot tell the difference. That is
the impersonation this section exists to prevent, so the refusal lives in a schema rather
than in a reviewer's memory.

The two routes are distinct capabilities, and neither may impersonate the other:

| Route | Requires | Forbidden |
|---|---|---|
| `direct` | nothing — it is stateless | any `runId`, `stage` or `checkpointId`; any dossier, receipt or cap accounting |
| `embedded` | a valid `runId` **and** `stage` **and** `checkpointId` | — |

A call claiming `embedded` without a valid run id is refused rather than downgraded:
supervision with nothing to resume from and no cap to bound it is not supervision. A
`direct` consult that arrives carrying run state is refused rather than stripped, because
once that state is written down the consult is indistinguishable from a governed
checkpoint. Only `embedded` may produce durable supervision artifacts — structurally, not
by convention: a dossier path cannot be built without a run id, and a direct consult has
none.

## 12 — Model policy

`--advice` never changes the executor's model. Athena maps to the strongest advisory tier
declared in `.codex/agents/athena.toml` for this runtime. No model name or id belongs in
this contract or in any skill body.

## The call protocol

Identical at every checkpoint of every wrapped skill, so it lives here once. A wrapper
declares only WHERE its checkpoints fire and WHAT question each asks.

**1. Open the checkpoint.** This is what enforces the cap, stage legality and idempotency,
and writes the pending marker that makes a crash resumable:

```
mewkit advice begin --run <supervisionRunId> --skill mk-<skill> \
  --stage GUIDE|RESCUE|REVIEW|RECHECK --checkpoint <checkpointId>
```

`mk-ship` additionally passes `--release-stage prepare|release|publish`; every other skill
is refused if it passes one. A refusal is final for that checkpoint: continue unsupervised,
or escalate when the refusal says to. Re-running the same `--checkpoint` returns the
recorded result and spends no slot.

**2. Validate the packet, then delegate.** The caps, pointer budget, provenance requirement
and secret scan are enforced by the command, not by writing the packet carefully:

```
mewkit advice validate-packet --evidence <packet.json> --packet-kind input
```

Then delegate to the `athena` agent by name, with the packet inline — a fresh subagent
inherits no conversation. Validate the returned packet the same way with
`--packet-kind output` before acting on it or summarizing it into a receipt.

**3. Commit the result.** Render the returned packet to the user, then:

```
mewkit advice commit --run <runId> --checkpoint <checkpointId> \
  --disposition <returned disposition> --outcome adopted|rejected|deferred \
  --reason "<one line, required even when adopted>" \
  --directive "<summary>" --next "<next safe action>" \
  [--correction "<change>" ...] [--evidence-pointer <path> ...]
```

`commit` writes the receipt, records the call against the cap, and refuses a disposition
that is illegal for the stage. `disposition` is Athena's routing signal; `--outcome` is
what the wrapper decided to do with it — a rejected directive is a legitimate, recordable
outcome.

**4. Route on the disposition.**

- `CONTINUE_WITH_DIRECTIVE` — proceed; the directive is input, not instruction.
- `READY_FOR_EXISTING_GATE` — run the skill's normal next gate or review. It is NOT cleared.
- `RETURN_TO_EXECUTOR` — apply the corrections, then supersede the stale evidence:
  `mewkit advice commit … --disposition RETURN_TO_EXECUTOR --evidence <workflow-evidence.json> --correction-kind source|scope`.
  Re-run the skill's verification before its review. `scope` also returns Gate 1 to
  `required`.
- `ESCALATE_TO_HUMAN` — stop at the existing human touchpoint.
- `BLOCKED_MISSING_EVIDENCE` — supply the named evidence or continue unsupervised.

If an active durable task record exists, point at the receipt with
`mewkit task-state update <id> --evidence-ref <receipt path>`. With no active record, keep
the file and skip this step — never invent a record.

## Wiring status on this runtime

The adapter is authored: `.codex/agents/athena.toml` carries the full supervisor contract.

Six wrappers declare the flag and name their checkpoints: `mk-brainstorming` (deep
workflow only), `mk-plan-creator`, `mk-cook`, `mk-fix`, `mk-autobuild` and `mk-ship`. Each
fires at the stage boundaries in §2 and drives `mewkit advice begin|commit`, which is where
the caps, stage legality, idempotency, dossier and receipt are actually enforced.

`mk-workflow-orchestrator` exposes **no** flag and is not an entry point. When an
explicitly enabled run hands off, it carries `supervisionRunId` forward as an opaque value
at macro boundaries and nothing else.

Every other surface is excluded, and the exclusion is enforced in code rather than by
convention: `mewkit advice begin` refuses a skill absent from the cap table.

**Delegation on this runtime is authored but not yet live-verified.** No session has
exercised reaching the agent from a wrapper here. If the runtime cannot discover or
delegate to `athena`, print the fallback line in §10 and continue unsupervised. Never
improvise a checkpoint: writing a packet inline and presenting it as the agent's output is
not an independent check, and a receipt produced that way records supervision that never
happened.

### Parent-side commands

| Command | Enforces |
|---|---|
| `mewkit advice begin` | route contract, supervised-skill check, per-stage and per-skill caps, partition legality (`--release-stage`), idempotent `checkpointId`, pending marker |
| `mewkit advice commit` | stage and disposition legality, receipt validation (authority language, credentials, empty return), dossier commit, correction supersession |
| `mewkit advice status` | resume view: current stage, calls used, latest directive, next safe action |
| `mewkit advice validate-packet` | input packet, output packet, or direct-consult brief — `--packet-kind input\|output\|brief` |

A corrupt dossier is refused, never read as a fresh run — otherwise breaking the file that
counts the calls would be the cheapest way to buy unlimited ones.

## Gotchas

- Loading this file when `--advice` was not passed — it is inert then, and the load is pure
  context cost.
- Treating the behavioral write-ban as weaker because no sandbox enforces it on this
  runtime.
- Using a GUIDE disposition at REVIEW, or vice versa — the stage decides what is legal.
- Emitting a `disposition` from a direct consult — that shape is a checkpoint result and a
  consult has no run to govern.
- Reading `READY_FOR_EXISTING_GATE` as a cleared gate — it names the next step, nothing
  more.