## [2026-05-02] orchestrator-owned-skill-override-enforcement
Context: `.agents/skill-overrides.md` carries per-skill mandates targeting orchestrator lifecycle (e.g. `mcp__personal-graph__session_start` before applying skill body, `write_state`/`write_episode` at end). The shared `orchestration/shell-content-contract/shell-ceremony.md` already had a `## Project Overrides` section telling skills to read the override file, but the rule was underspecified: it did not say the read is orchestrator-owned, did not require executing action mandates contained within, and did not name the lifecycle positions where mandates fire. Skills that delegated the read to a subagent (e.g. `bill-feature-implement` delegating to its pre-planning subagent) saw the action mandates paraphrased into a free-form `standards_notes` string and dropped in practice. Across four 2026-05-02 runs (SKILL-33 FU2/FU3/FU4 + SKILL-34) the personal-graph mandate was silently skipped on every run.
Decision: Override-section enforcement is fixed at the ceremony layer, not per-orchestrator. The `## Project Overrides` section in `orchestration/shell-content-contract/shell-ceremony.md` (consumed by 27 governed skills via sibling symlinks) now explicitly states that the read is orchestrator-owned and not delegable, names the two lifecycle positions where action mandates fire (preflight before skill body / postflight at end of skill before terminal `*_finished` telemetry), specifies the substring-match heuristic for detecting mandates (`mcp__*` tool calls, `read \`{path}\`` files, `write_state`/`write_episode` writes), and prescribes a structured result-recording shape. The pre-planning subagent's job is to surface override mandates (verbatim + structured `override_action_mandates` field in its RESULT JSON), never to execute them. This decision is repo-wide.
Reason: Subagent abstraction loss. Mandates aimed at the orchestrator's own lifecycle position cannot be fulfilled by a subagent that runs at a different lifecycle position. Fixing it once in the shared ceremony eliminates the abstraction layer where mandates get paraphrased away and propagates to every skill that links the canonical file — repo-wide enforcement at one edit cost.
Alternatives considered: (1) Add Step 0 / Step 9b prose to each orchestrator's `content.md` — rejected because `content.md` is the user-editable execution body, not the orchestration scaffold; the rule belongs at the ceremony layer where it can apply to every skill uniformly. (2) Tighten only the pre-planning briefing — rejected because it leaves the orchestrator-ownership question unsolved; mandates targeting before-skill-body and end-of-skill cannot be executed by a mid-flow pre-planner. (3) Add a runtime-level enforcement check that fails skills that skipped preflight — rejected as out of scope for SKILL-35; the static-string test asserts the prose says the right thing, which is sufficient for documented protocol. (4) Build a generic skill-override interpreter — rejected as premature; the substring-match heuristic is good enough until a mandate shape escapes it.
Revisit when: A new mandate shape escapes the substring-match heuristic (e.g. a mandate that doesn't name an `mcp__*` tool, a file path, or a write call). Or when ceremony enforcement needs to be machine-asserted at runtime rather than via static-string tests.

## [2026-04-21] top-level-orchestrators-use-workflow-contract
Context: Skill Bill already has multi-step orchestrators such as `bill-feature-implement`, but their step graph, retry rules, and artifact handoff mostly lived in skill prose and telemetry conventions.
Decision: Add a governed workflow contract under `orchestration/workflow-contract/PLAYBOOK.md` for top-level orchestrators only, starting with `bill-feature-implement`.
Reason: Durable workflow state belongs above reusable skills. This keeps stack routing and rubrics in standalone skills while giving long-running parent flows one authoritative place for step ids, artifacts, resume semantics, and parent-owned telemetry.
Alternatives considered: Turning every skill into a workflow was rejected because it would duplicate leaf-skill contracts and blur the stable user-facing command surface.
Revisit when: Skill Bill is ready to persist workflow state in runtime code or when a second top-level orchestrator adopts the contract.
