engagement-protocol

name	engagement-protocol
domain	meta
description	[PROTOCOL] Canonical contract for agency engagement lifecycle: artefact schemas, state files, iteration budget, escalation rules, cross-domain handoff, observability. Single source of truth referenced by agency-intake, leads, directors, and pipeline skills. Pure reference — no triggers, not invoked by the secretary as a router target.

engagement-protocol

This is the shared contract every agency role follows. The secretary captures intake, the lead orchestrates, the director accepts. All of them read from and write to the artefacts defined here.

Engagement = a directory

Every agency engagement lives in an engagement/ directory under the project working directory. Files in this directory are the engagement's state. Nothing about the engagement is conversational — if it matters, it's in a file.

Whitelist (allowed paths only)

The list below is closed. No files outside it may be created inside engagement/. Existing files outside this list are a protocol violation and the director MUST treat them as red flag (likely phantom-claims hideout).

engagement/
├── criteria.md                 # secretary, semi-immutable (additions/removals locked; rephrasing allowed via lead/secretary, see "Mutability rules")
├── scope-sync.md               # director, optional, append-only after create
├── plan.md                     # lead, mutable until first dispatch, then frozen
├── specs/                      # dev only — user-spec.md / tech-spec.md / research-verdict.md
├── tasks/*.md                  # ALL domains — atomic task files (mandatory L; recommended M with ≥2 specialists; skip S)
├── tasks/INDEX.md              # optional manifest; mandatory if size: L
├── brand/                      # design only — voice / tokens / guidelines
├── design-system/              # design only — components / tokens
├── ui/                         # design only — screens / flows
├── executor-reports/           # specialists, one file per specialist, append-only
│   └── {specialist}.md
├── validation-log.md           # lead, append-only — every validator run
├── validation-outputs/         # MANDATORY — JSON proof-of-run for each validator AND adversary role (incl. preliminary)
│   └── {validator|adversary-role}-iter-{N}[-preliminary]-{timestamp}.json
├── consilium-summary.md        # auto-written by consilium-synth.py (M/L only); aggregates adversary findings
├── human-directive.md          # MANDATORY on M/L between consilium and director verdict; human as supreme judge
├── codex-outputs/              # OPTIONAL — assets generated by Codex via mcp__codex__codex tool calls
│   └── {NN}-{slug}.{png|svg|jpg}
├── iteration                   # plain-text counter file (lead inc on handoff, director inc on reject)
├── screens/                    # MANDATORY for ux_heavy=true — Playwright captures
│   └── {iteration}/{theme}/    # e.g. iter-1/dark/dashboard.png
├── traces/                     # MANDATORY for ux_heavy=true — exercised flow logs
│   └── {iteration}/{flow}.json # network/console/dom snapshots
├── deploy-log.md               # dev only when deploy boundary crossed
├── docs-diff.md                # docs pipeline only
├── handoff.md                  # lead, REPLACED per iteration
└── acceptance-log.md           # director, append-only

Forbidden (do NOT create)

These names appear in past engagements as "supporting docs". They duplicate whitelist content, hide phantom claims, and bloat the bookkeeping. Forbidden:

• preview.md, compliance.md, review-log.md, visual-review.md, summary.md, notes.md, report.md, tldr.md
• rework-N-brief.md, iter-N-summary.md, wave-N-recap.md, anything resembling a per-iteration sidecar
• findings.md, issues.md, audit.md outside validation-log.md

If you feel pressure to create one of these — the content already belongs in an existing whitelist file:

• "compliance" / "audit" / "review" → validation-log.md
• "preview" / "summary" / "report" → handoff.md (it IS the summary)
• "rework brief" → new ## Iteration N section inside validation-log.md and rewritten handoff.md
• "exercised flow" / "smoke run" → traces/ directory + reference inside handoff.md §"Exercised"

Director's red-flag scan (per iteration): ls engagement/ — any file outside whitelist = REJECT with reason "out-of-whitelist artefact, content must move into canonical file".

Artefact schemas

criteria.md mutability rules (resolves the "immutable vs lead-sharpening" tension)

criteria.md is semi-immutable:

Action	Allowed by	When	Audit
Adding a new "Done when" / "Deliverables" bullet	user only	scope-sync with director	director records in scope-sync.md
Removing a bullet that has independent user value	user only	scope-sync with director	director records in scope-sync.md
Changing measurement bar (e.g. "tests green" → "tests + 90% coverage")	user only	scope-sync with director	director records in scope-sync.md
Rephrasing for clarity (no scope change)	lead OR secretary autonomously	Phase 1a sharpening, or loop-to-intake	scope-sync.md auto-edit log
Dropping no-value filler (would-always-be-zero metric, never-read deliverable)	lead OR secretary autonomously	Phase 1a sharpening	scope-sync.md auto-edit log
Splitting compound bullet into atoms	lead OR secretary autonomously	Phase 1a sharpening	scope-sync.md auto-edit log
Frontmatter size/ux_heavy promotion (S→M, false→minor→true)	lead	mid-engagement when scope grows	scope-sync.md note
Frontmatter demotion	NEVER (would discard accumulated rigour)	—	—

The directive resolves the apparent contradiction: criteria are immutable to scope, mutable for clarity. Lead does not need user touch to drop a "ошибки за период (always 0)" filler — that's not scope reduction, that's noise removal. Lead does need user touch to drop "тесты после миграции" — that has independent value.

criteria.md (secretary)

---
engagement: {engagement-name}
created: {YYYY-MM-DD}
domain: marketing | dev | design
size: S | M | L                                       # see Engagement size tier
ux_heavy: false | minor | true                        # see UX-heavy engagements
tools_required: [docker, playwright, postgres, ...]   # see Pre-flight check
# protocol_version: 4                                 # OPTIONAL — kept for future migration story; not required today
---

# Acceptance criteria — {engagement-name} — {YYYY-MM-DD}

## Scope
{one paragraph, verbatim-aligned with user brief}

## Deliverables expected
- {deliverable 1 with measurable bar}
- {deliverable 2 with measurable bar}

## Done when
- {observable condition 1}
- {observable condition 2}

## Explicitly out of scope
- {thing excluded with one-line justification}

## Review mode
`lean` | `full` | `solo`

## Iteration budget
Guidance: 2 rework cycles, then user escalation. Counter is informational — escalate immediately on repeating critique. Hard cap 4.

## Cross-domain dependency (optional)
- Primary domain: {marketing | dev | design}
- Secondary domain: {marketing | dev | design} — invoked at phase {N} by primary lead

Pre-flight check (intake-time, blocking)

Before secretary hands off to lead, verify every tool in tools_required is reachable:

Tool	Check	Action if missing
docker	docker info exits 0	Ask user to start Docker Desktop. Block until done.
playwright	playwright binary present (project or npx playwright --version)	Ask user / lead to install. Block until done.
postgres / db	connection string in .env and pg_isready (or equivalent) succeeds	Ask user to start DB. Block.
node, python, bun, etc.	--version succeeds	Ask user to install. Block.
Secrets (e.g. OPENAI_API_KEY)	env var or .env entry present (presence only — don't read value)	Ask user to add. Block.

Pre-flight failure → secretary records the blocking tool in criteria.md "out of scope" line "BLOCKED at intake until {tool} available", and pauses engagement until user resolves. Do NOT hand off to lead with known-broken validation environment — that is the root cause of CONDITIONAL accepts that never resolved.

scope-sync.md (director, optional)

# Scope sync — {engagement-name} — {YYYY-MM-DD HH:MM}

## Criteria frozen as of
{timestamp}

## Ambiguities resolved
- Q: {question raised by director or lead}
- A: {resolution}

## Criteria locked by
{director-name}

plan.md (lead)

# Engagement plan — {engagement-name}

## Shape
{engagement-type classification + rationale}

## Phases
1. Phase name — owner (mid-lead / specialist) — deliverable — dependencies
2. ...

## Validators planned
- {validator-name} on {artefact} — triggered by {rule}

## Cross-domain handoff (if applicable)
- Trigger: {condition}
- Secondary lead: {lead-agent-name}
- Artefact passed: {path}

validation-log.md (lead, append-only)

Schema defined in validation-pipeline. Append one section per validator run.

handoff.md (lead, replaced per iteration)

The first section is ALWAYS the diff. The rest is supporting evidence. If a director reads only section 1, they should already know roughly what happened — prose is for context, not for the primary source of truth.

# Handoff — iteration {N} — {engagement-name} — {YYYY-MM-DD HH:MM}

## 1. Diff summary (PRIMARY)
For dev engagements, paste raw output:
- `git diff --stat {base}..HEAD` (file-level changes)
- `git log --oneline {base}..HEAD` (commit list)

For marketing/design engagements (no git diff available):
- Created files: list with sizes (`wc -l` or byte count)
- Modified files: before/after delta (lines added/removed or visual diff)
- Removed files: list with reason

This section is the **source of truth** for what changed. All other sections describe WHY and HOW WELL — they do not redefine what changed.

## 2. Deliverable manifest
- {artefact path 1} — {short description}
- {artefact path 2} — ...

## 3. Criteria trace
| # | Criterion | Status | Evidence (path + line/section) |
|---|---|---|---|
| 1 | {criterion text} | ✅ / ⚠️ / ❌ | {pointer} |

## 4. Executor reports
- {specialist-name} — `executor-reports/{specialist}.md`

### 4-pre. Specialist contract enforcement (lead duty)

Before composing §4 and §4a, lead verifies every dispatched specialist wrote to the canonical place:

```bash
# For each specialist dispatched:
ls engagement/executor-reports/{specialist-name}.md     # must exist
ls engagement/                                          # no rogue files

If a specialist:

• Wrote nothing → re-dispatch with reminder, do NOT pretend they reported.
• Wrote to wrong path (/tmp/, engagement/notes.md, project-root report.md) → re-dispatch + delete wrong file.
• Created a rogue file in engagement/ (e.g. findings-frontend.md) → consolidate into their canonical executor-report, delete rogue.

This enforcement is the lead's job, not the director's. Director treats engagement/ as authoritative — anything outside whitelist locations doesn't exist for acceptance purposes (and is a REJECT trigger).

4-iter. Iteration structure inside executor-reports

When the same specialist is re-dispatched on iter N+1 to address director feedback, they MUST append to their existing executor-report — NOT overwrite it. Each iteration in the report is structurally separated:

# {specialist-name} executor report

## Iteration 1 — 2026-05-06 14:30
### Criteria acknowledgement
- Addresses crit-1 (foo.py exports add)

### What was done
- Implemented add() at src/foo.py L4
- Added unit test in tests/test_foo.py L12-L20

### Cross-contract claims
- Returns int, not None on edge cases (frontend should expect int)

### Anti-pattern self-disclosure
- None

## Iteration 2 — 2026-05-07 11:15
### What changed since iter-1
- Director rejected: edge-case test for negative inputs missing.
- Added negative-input test at tests/test_foo.py L22-L30.

### Anti-pattern self-disclosure
- None

Lead enforces the format on dispatch: include in Task prompt explicit reminder to append ## Iteration {N} heading. Without iteration headings on iter ≥ 2, handoff-precheck flags executor-report-iteration-missing as REJECT trigger — earlier work would be silently overwritten and audit trail lost.

4a. Cross-validation table (REQUIRED if ≥2 specialists touched shared contracts)

Free-form "all match" claims are not accepted — director cannot verify them. Use this table with verbatim quotes from each specialist's executor report; without the table the cross-validation is presumed unrun and director treats it as such (REJECT).

Contract	Specialist A — claim (verbatim)	Specialist B — claim (verbatim)	Verdict
POST /api/items	dev-backend-engineer.md L42: "returns 201 + {id, name}"	dev-frontend-engineer.md L18: "expects 201, body {id, name}"	MATCH
User.email field type	dev-backend-engineer.md L67: "VARCHAR(254) NOT NULL"	dev-tech-architect.md L23: "string, max 320"	DIVERGE

DIVERGE = blocker. Resolve (re-dispatch the wrong specialist for fix, re-run code-reviewer) BEFORE handoff. Submitting with unresolved DIVERGE = REJECT.

If no shared contracts in this engagement, write: "N/A — no specialists overlap on shared contracts (only single-domain artefacts produced)." This explicit N/A is required — silence is not an answer.

5. Validation log

Summary — see validation-log.md for full entries.

• {validator}: {verdict}, {N findings resolved / N deferred}

6. Exercised (MANDATORY for ux_heavy, optional otherwise)

Narrative of what happened when the lead actually used each touched control. Each bullet must reference a verifiable artefact (Playwright trace, network log, screenshot, DOM snapshot path) — prose alone is reject-worthy because it can be hallucinated.

Format per bullet:

• Action → observed result → evidence path
• Example: "Clicked 'Квартал' preset at 14:32 → date popover set 2026-04-01 → 2026-04-24 (24 days). Evidence: traces/iter-2/quarter-preset.json line 45-52, screens/iter-2/dark/dashboard-quarter.png."

If section absent on a ux_heavy: true engagement → handoff INCOMPLETE (returned unread, no iteration burned).

7. Self-acceptance rehearsal (MANDATORY — structural gate, not prose)

Lead simulates director's acceptance sweep before handoff. This section is REQUIRED to be non-empty in a structured way:

7a. Mechanical pre-check (paste verbatim JSON output)

$ python ~/.claude/scripts/handoff-precheck.py engagement/ --json
{
  "engagement": "...",
  "fail_count": 0,
  "skip_count": 0,
  "status": "pass",
  "checks": [...]
}

status MUST be "pass". If any check failed, STOP — fix the underlying issue and re-run. Do NOT submit handoff with a red exit code; the director's first action will be running the same script and seeing the same red.

7b. Honest concerns list (concerns must bind to criteria)

The point of this section is to catch the LLM-honesty hole: if you write "no concerns" you are signalling either dishonesty or absence of thought. Force yourself to find real concerns — and tag each one with the criterion it relates to, so vague "naming could be better" filler can be detected:

Format:

1. [crit-{N} | non-criteria | scope-creep] {concern}: {what I'd push back on if I were the director} — {why I'm submitting anyway: in-scope deferral / pre-discussed waiver / honest gap disclosed in §11 deferrals}
2. [crit-{N} | non-criteria | scope-creep] {second concern, real one}
3. (optional more)

Tag meanings:

• crit-{N} — concern about how this engagement covers criterion N (the strongest tag, hardest to fake).
• non-criteria — concern about something orthogonal to criteria.md (allowed but capped: at most 1 of N).
• scope-creep — concern that something done isn't strictly required by criteria (warning of over-engineering).

Threshold by engagement size:

• Size S: ≥1 concern, at least one tagged crit-{N} OR scope-creep.
• Size M: ≥2 concerns, at least one tagged crit-{N}.
• Size L: ≥2 concerns, plus delta from prior iteration ("what's new vs iter-{N-1}").

A rehearsal section that fails the tag-distribution check is structurally invalid — director rejects with self-acceptance concerns ducked criteria.md, bad-faith pattern. The tagging makes "naming could be better" / "docstring short" filler harder, because those are non-criteria and only one is allowed.

7c. ux_heavy auto-promote check

If your work touched any of *.tsx, *.jsx, *.vue, *.svelte, *.html, or styling (*.css, *.scss, Tailwind classes in JSX), AND criteria.md has ux_heavy: false:

• Either ux_heavy was misclassified at intake → state explicitly "AUTO-PROMOTE: ux_heavy → true (UI files touched in diff §1)" and produce screens/traces accordingly.
• OR your work is genuinely non-UX (tooling on UI infra without visible change) → state explicitly why ux_heavy stays false.

Don't quietly skip screens just because intake said ux_heavy: false. This auto-promote keeps a misclassification at intake from disabling all UX defences downstream.

8. Deploy log

• See deploy-log.md OR "N/A — no deploy in this engagement"

9. Docs diff

• See docs-diff.md OR "N/A — no docs change"

10. Iteration counter

Current round: {N}. Prior round(s): {1, 2, ...}. (informational — escalation triggered by repeating critique, not by counter)

Source of truth: engagement/iteration plain-text file (single integer). Lead increments it before submitting handoff; director increments on REJECT. handoff-precheck verifies the counter agrees with ## Iteration N headings in acceptance-log.md. Mismatch = REJECT (someone falsified the count).

11. Known deferrals

• {deferred item}: justified by {criteria.md out-of-scope | explicit user waiver | director-approved scope note}

### `acceptance-log.md` (director, append-only)

Schema defined in `director-acceptance-protocol`. One section per iteration.

## Protocol versioning

`protocol_version` in `criteria.md` frontmatter pins the engagement to the protocol version it was created under. handoff-precheck reads this field and:

- If version equals current (4) — proceed normally.
- If version is older than `MIN_SUPPORTED` (currently 3) — REJECT with `engagement uses obsolete protocol; run engagement-migrate.py`.
- If version is older but ≥ `MIN_SUPPORTED` — WARN; engagement continues with old rules where they differ. Migration recommended at next safe break.
- If version is newer than current script — REJECT; scripts are out of date.

Current version log:

| Version | Introduced | Major changes |
|---|---|---|
| 1 | 2026-04-20 | initial agency model |
| 2 | 2026-04-24 | post-Wave-2 fixes (binary verdict, whitelist, ux_heavy, screens/traces) |
| 3 | 2026-05-05 | machine-checked gates (preflight, paths-check, danger-scan, validator-outputs) |
| 4 | 2026-05-06 | engagement size tier (S/M/L), ux_heavy gradient, structured trace schema, abort workflow, cross-domain secondary, protocol versioning, error budget gradient |

Version bumps happen when handoff-schema sections change OR new mandatory sub-checks are added. Backward compatibility is preserved as long as old engagements declare their version explicitly.

## Engagement size tier (S / M / L)

Different engagements need different rigour. Forcing a 30-line CSS tweak through the same 11-section handoff as a multi-wave refactor invites corner-cutting. Size is set by the secretary at intake and recorded in `criteria.md` frontmatter as `size: S | M | L`.

### Sizing rules (mechanical)

| Tier | Diff size | Specialists | UI scope | Deploy |
|---|---|---|---|---|
| **S** | ≤2 changed files OR ≤50 LOC | 1 | none / `ux_heavy: false` | none |
| **M** | 3–10 files OR 50–500 LOC | 2–3 | `ux_heavy: false` or `minor` | preview/staging only |
| **L** | >10 files OR >500 LOC, OR multi-wave | ≥4, OR cross-domain | `ux_heavy: true`, OR new design system | production deploy |

If the engagement crosses thresholds during execution, lead promotes the size in `scope-sync.md` (S→M→L only, never demote). Promotion = additional rigour applies retroactively from next handoff.

### Schema relaxations by tier

| Section / gate | S | M | L |
|---|---|---|---|
| Handoff §1 Diff summary | **single line OK** ("+/- N files") | required (full git stat) | required (full git stat + commits) |
| Handoff §2 Deliverable manifest | required | required | required |
| Handoff §3 Criteria trace | **inline** (1 line per crit, no table needed) | required (table) | required (table) |
| Handoff §4 Executor reports | merged into §2 if 1 specialist | required | required |
| §4a Cross-validation table | N/A (1 specialist) | required if ≥2 specialists touch shared contract | required |
| Handoff §5 Validation log | brief summary line OK | full | full |
| Validator output JSON files | required | required | required |
| Handoff §6 Exercised | only if `ux_heavy: minor \| true` | only if `ux_heavy: minor \| true` | required if `ux_heavy: minor \| true` |
| Handoff §7 Self-acceptance | **abbreviated: ≥1 concern** | full: ≥2 concerns | full: ≥2 concerns + delta-from-iter-N-1 |
| Handoff §8 Deploy log | N/A | only if deploy crossed | required |
| Handoff §9 Docs diff | optional | mandatory if `src/` touched | mandatory if `src/` touched |
| Handoff §10 Iteration counter | optional (informational) | optional | optional |
| Handoff §11 Known deferrals | optional | required (or "None") | required (or "None") |
| Director scope sync | optional | optional | mandatory if `ux_heavy: true` or weak criteria |
| Director phase | **NONE** (producer self-attest + mechanical + human) | lightweight (judge between producer + 1 adversary) | full (judge between producer + 5-reviewer consilium) |
| Adversary pass | none | Opus adversary in fresh subprocess (`adversary.py --consilium M`) | Consilium: peer-Opus + 2× Codex + Sonnet + Haiku (`adversary.py --consilium L`) |
| Iteration budget | 1 (one shot expected) | 2 | 3 |
| Iteration budget on auto-promote | n/a | +1 (so promoted-S becomes M with 3 max) | +1 (so promoted-M becomes L with 4 max) |

### S-tier minimum-viable handoff template

For `size: S` engagements, this 5-line shape is acceptable as `handoff.md`:

```markdown
# Handoff — iter 1 — {engagement-name}

## 1. Diff summary
+/- {N} files: {paths}; {one-line of what changed}

## 2. Deliverables + criteria trace
- crit-1: {bullet text} ✅ {evidence path}
- crit-2: {bullet text} ✅ {evidence path}

## 5. Validation log
{validator}: {verdict} — see validation-outputs/

## 7. Self-acceptance
1. [crit-N|scope-creep] {one honest concern} — {justification}

That's it. No §3 table when 2-3 criteria fit inline. No §4 separate reports section when one specialist's work is in §2 already. No §6 unless UI. No §11 if there are no deferrals. The point: small engagement = small handoff. Director still runs handoff-precheck.py — schema-aware checks know about size: S and don't demand the larger-tier sections. | tasks/*.md atomic decomposition | N/A (skip) | recommended if ≥2 specialists OR ≥3 distinct deliverables | required (tasks/INDEX.md mandatory) |

Tier-relaxations are the ONLY allowed deviation from the canonical schema. Any other deviation = whitelist violation = REJECT. The point: small engagements feel small, large engagements stay rigorous, and corner-cutting goes from individual lead choice to protocol-recognised path.

Task decomposition rule (cross-domain)

tasks/*.md files are atomic deliverable units that let lead re-dispatch a single broken atom on iter-2 instead of re-running the whole phase. Each domain has its own decomposition methodology:

• dev — task-decomposition (tech-spec → atomic tasks with TDD anchors). Existing.
• marketing — marketing-task-decomposition (criteria + plan → atomic tasks: keyword-cluster, ad-group, landing-block, metric-pull, banner-variant, etc.). New.
• design — design-task-decomposition (criteria + plan → atomic tasks: voice-axis, logo-direction, token-group, component-spec, screen-variant, etc.). New.

Authority and timing:

• Lead invokes the matching skill at Phase 2.5 (after plan.md is frozen, before any specialist dispatch).
• Skip permitted only on size: S engagements OR size: M with a single specialist.
• Director will REJECT a size: L handoff with no tasks/ directory or with empty tasks/INDEX.md. Same gate as missing validation-log.md.

On REJECT loop: lead identifies failing crit-N from director verdict, finds tasks where crit_refs includes those crit values, re-dispatches ONLY those tasks. Specialist appends ## Iteration {N} to their executor-report (per §4-iter rules). The whole-phase re-run is the failure mode this exists to prevent.

How handoff-precheck.py adapts

The script reads size from criteria.md frontmatter and skips checks not applicable to that tier (e.g. for size: S with 1 specialist, cross-val table check is automatically skipped — not because of bypass, but because the schema declares it N/A at this size). Same logic gates the tasks/ requirement: the precheck tolerates an empty tasks/ on S, warns on M without it, and FAILs on L without it.

Iteration budget

The counter is informational, not a quota. Do not use language like "slot 1/2 used" or "last attempt" — it creates psychological pressure to accept marginal work. Escalation triggers are root-cause based, not slot-based:

• Iteration 1 — lead's first handoff. Director writes ACCEPT or REJECT (binary, see "Verdict is binary" below).
• Iteration 2 — lead's revision. Director reviews again.
• Repeating-critique trigger (highest priority): if the same blocking item from iteration N appears again in iteration N+1 — escalate to user IMMEDIATELY, regardless of which iteration this is. The loop is the signal, not the count.
• Pre-final-iteration trigger: before starting the last allowed iteration, escalate to user with current blockers. Wait for explicit "продолжаем" or "пересматриваем scope".
• Hard limit by tier (tiered acceptance refactor):
  • S: 1 iteration. REJECT → human directive (rework / abandon), no auto-loop.
  • M: 2 iterations. After round 2, escalate.
  • L: 3 iterations. After round 3, escalate.
  • Auto-promoted engagements: budget +1 (promoted-S becomes M with 3 max; promoted-M becomes L with 4 max).
• Never start an iteration beyond the hard limit without user authorisation.

Mechanical loop-to-intake trigger

"Criteria are wrong, not the work" is a real failure mode but agents miss it without an explicit rule. Trigger:

If acceptance-log.md shows iter-N REJECT and iter-(N+1) REJECT with the same blocker (matched by criterion ID OR by reject-reason text-similarity ≥ 70%), the lead is OBLIGATED to:

1. STOP rework. Do not start iter-(N+2) on this criterion.
2. Dispatch agency-intake via Task tool with payload:
   • Path to engagement/criteria.md.
   • Path to engagement/acceptance-log.md.
   • The repeating blocker text.
   • Lead's diagnosis: "criterion {id} is unbuildable as written because {reason}; suggest revision to {proposed-rewording}".
3. Wait for secretary to either:
   • Edit criteria.md (touching only the broken criterion, keeping rest intact, recording change in scope-sync.md with director's signature) and unblock.
   • Escalate to user: "criterion {id} cannot be met as stated, revise scope or close engagement".
4. Resume from current iteration with revised criteria.

If lead skips this and just keeps reworking → director rejects with loop-to-intake skipped — repeating blocker not escalated. The mechanical trigger (same blocker twice) is the signal, regardless of how confident the lead feels about a fix.

Secretary's authority during loop-to-intake

When dispatched mid-engagement to fix criteria, secretary has authority for non-scope edits without user touch (matching lead's Phase 1a sharpening rules):

• Rephrasing a vague bullet to a measurable one (no value change).
• Dropping a redundant / no-value filler bullet that the lead's experience reveals.
• Splitting a compound bullet into testable atoms.

These are recorded in scope-sync.md as "secretary auto-edit during loop-to-intake" with diff. User sees them at ACCEPT.

User touch required only when:

• The criterion is unbuildable for principled reasons (not just "lead struggled twice").
• Removing a deliverable that has independent user value.
• Major scope change that shifts the engagement to a different domain.

In those cases, secretary escalates with the standard Russian template:

Critеrии для engagement {name} нуждаются в существенной правке. {N} итерация(и) rework не закрыли блокер:
- {blocker text}

Предложение: {proposed-rewording or scope reduction}.
Альтернатива: закрыть engagement как unresolvable.

Выбери: подтвердить правку / переформулировать / закрыть engagement.

When the loop is "criteria are wrong, not the work", route back to agency-intake for new/updated criteria.md instead of throwing more rework at the lead.

Verdict is binary

The director's verdict is exactly ACCEPT or REJECT. Conditional accepts are forbidden — they defeat the agency model's purpose of reducing user QA burden:

• No ACCEPT CONDITIONAL, no ACCEPT pending X, no ACCEPT with TODO, no ACCEPT — user to verify Y.
• If any acceptance bar cannot be verified by the director with available tools (Docker not running, Playwright not installed, BD not reachable, secrets missing): the verdict is REJECT with reason validation incomplete: <what was unverifiable>. Do NOT defer the verification to the user.
• Tooling unavailability is itself a blocker. The lead and the director coordinate to make the validation environment work (escalate to user once if a manual step is required, e.g. "запусти Docker Desktop"), then continue. They do NOT submit work for user-side validation.

The only acceptable form of "deferral" is something already listed in criteria.md "Explicitly out of scope" or in a director-approved scope-sync.md waiver.

UX-heavy engagements

ux_heavy is a 3-level gradient, not boolean — small UI tweaks should not pay full L-engagement overhead:

Value	When	Mandatory artefacts
false	Backend, brand voice, SEO, copy without UI surface, infra	none
minor	CSS tweak, copy edit on existing surface, padding/color/font change, single-state visual fix	ONE screen per touched surface, single theme; NO traces required
true	New UI surface, new interactive flow, behaviour-changing UI, multi-screen design	Screens both themes + traces with structured verdict field per flow

Set by secretary at intake based on signals (visual hierarchy / layout / typography / color / spacing / words of taste / mockup references). Lead can promote during execution (false → minor → true) with scope-sync.md entry; never demote.

ux_heavy: minor — relaxed rules

For a small CSS-class adjustment or copy tweak, full screens-light+dark + traces is overkill and pushes leads toward corner-cutting. minor keeps the visible-state guarantee without overhead:

• ONE screenshot per touched surface in engagement/screens/{iteration}/{theme}/{surface}.png. Single theme acceptable (whichever was visually changed); both themes only if both were modified.
• traces/ is optional — required only if the change has interactive behaviour (rare for CSS).
• handoff.md §6 Exercised is required but each bullet may reference just a screen, no trace.
• ux-review validator runs in lightweight mode (skips trace verification).

ux_heavy: true — full rules

1. engagement/screens/{iteration}/{theme}/ MUST contain Playwright captures of every touched UI surface, BOTH light and dark themes (if dark mode exists in the project).
2. engagement/traces/{iteration}/{flow}.json MUST contain structured exercised-flow records (schema below) for every exercised flow listed in handoff §6.
3. handoff.md §6 "Exercised" is mandatory and must reference real paths in screens/ and traces/.
4. ux-review validator MUST be in lead's validation-log before handoff (mandatory per director-acceptance-protocol's validator selection on ux_heavy: true). On L-tier, director MAY request a single re-run of ux-review on screens + traces if adversary findings identify a coverage gap (per director-acceptance-protocol §"When you MAY request specific validator re-run").
5. Docker / Playwright unavailability is a blocker, never a deferral. Lead escalates to user once ("start Docker Desktop"), then proceeds. screens/ cannot be left for the user to capture.

If ux_heavy: true and any of (1)–(3) absent on submission → handoff is INCOMPLETE (returned unread, doesn't burn iteration budget).

Trace JSON schema (mandatory structured fields)

Free-form trace dumps let the lead write "result was correct" without comparing claim to reality. Forcing structure makes the lead compare numerically before submission:

{
  "flow": "quarter-preset-click",
  "iteration": 2,
  "captured_at": "2026-04-24T14:32:11Z",
  "steps": [
    {
      "action": "click",
      "selector": "[data-test=preset-quarter]",
      "expected": "period.endDate - period.startDate >= 80 days (rolling 90-day window)",
      "observed": {
        "period.startDate": "2026-04-01",
        "period.endDate": "2026-04-24",
        "diff_days": 24
      },
      "verdict": "FAIL",
      "notes": "Math.floor(month/3) returns calendar quarter start, degrades to 1-3 days at month boundaries"
    }
  ],
  "network": [{"url": "...", "status": 200, "request_body": "...", "response_body": "..."}],
  "console": [{"level": "warn", "message": "..."}],
  "dom_snapshot": "engagement/traces/iter-2/quarter-preset.html"
}

Required fields per step:

• action — what user did (click / type / select / navigate).
• selector — DOM selector or trace anchor.
• expected — what SHOULD happen, written from criteria.md or user-spec language. Plain English allowed but must be falsifiable.
• observed — what actually happened, structured as object with concrete values.
• verdict — "PASS" or "FAIL". Lead computes this themselves.

Lead-side gate: if any step has "verdict": "FAIL", the lead does NOT submit handoff with this trace as evidence. Either fix the underlying behaviour, or surface as a known-issue deferral with explicit out-of-scope justification in §11. Submitting with FAIL verdicts attached = REJECT submitted FAIL trace as evidence.

Director-side gate: ux-review validator and director both look at verdict field. Missing verdict field → REJECT unstructured trace cannot be verified. Free-form prose traces that don't parse as JSON → REJECT.

Dangerous operations registry

Some operations have heavy / irreversible consequences (data loss, history rewrite, production damage, infra teardown). Validators check correctness, not authorisation. Authorisation is a separate axis: the user must explicitly OK these ops, even if they are technically clean.

Operations requiring explicit user OK (always)

Class	Examples	Why user-OK required
Schema destruction	DROP TABLE, DROP COLUMN, TRUNCATE, lossy ALTER COLUMN TYPE	Data lost cannot be reconstituted from code.
Bulk row deletion	DELETE FROM x without WHERE, deletes affecting >25 files	Reversal needs backup recovery.
History rewrite	git push --force, git reset --hard origin/...	Teammates' work / audit trail destroyed.
Filesystem recursive delete	rm -rf on parents, ~, $HOME, root paths	Path mistakes are catastrophic.
Migration without rollback	down() empty / raise NotImplementedError	ACCEPT becomes irreversible.
Production deploy	vercel --prod, fly deploy, gh release create, manual kubectl apply -f prod	Live impact, customer-visible.
Infrastructure teardown	terraform destroy, kubectl delete -n prod	State loss + customer impact.
Secret rotation/deletion	rotate-secret, delete-secret, gh secret remove	Downstream consumers may break silently.
Public publish	npm publish, pip upload (real index, not test)	Cannot fully unpublish.

Detection

Lead runs ~/.claude/scripts/danger-scan.py --engagement engagement/ (or --diff-file ...) before handoff. The script covers the patterns above plus bulk-delete heuristic. JSON output lists every match with severity (critical/high) and rationale.

handoff-precheck.py calls danger-scan.py automatically as one of its sub-checks. Non-empty findings → handoff blocked until either (a) each finding has a paired user-OK entry in scope-sync.md, OR (b) the operation is removed from the diff.

User-OK protocol

When danger-scan finds a dangerous op, the lead surfaces it to the user via director-mediated escalation BEFORE merging / applying:

Опасная операция в этом engagement:
- {operation kind}: {snippet}
- Последствия: {msg from danger-scan}

Подтверждаешь? (y / n / разъяснить)

Lead waits for explicit "y" / "да" / "ок" — silence is NOT consent. On "y": lead writes a confirmation entry in scope-sync.md:

## Dangerous-op user OK — {YYYY-MM-DD HH:MM}
- {operation id}: {snippet} — user OK on {timestamp} via {user-message reference}
- Backup verified before apply: {yes/no/N-A — backup not applicable for this op}

Without this entry, director rejects with dangerous operation submitted without user-OK in scope-sync.md.

Backups

For schema destruction and bulk delete: lead must verify a recent backup exists BEFORE applying. Mechanical check goes in scope-sync.md "Backup verified" line: timestamp + backup location. No backup → operation cannot proceed even with user OK; lead asks user to create backup first.

What does NOT count as dangerous

• Adding columns / tables / indexes (forward-compatible).
• Test fixture changes.
• Editing source files in any quantity (revertible by git).
• Local rm of build artefacts inside project dir (dist/, node_modules/).
• Deploys to staging / preview environments.
• Engagement archival (mv engagement engagement-archived/...).

These do not require user touch and stay autonomous.

Engagement abort (user pulls the plug mid-engagement)

When the user says "стоп / забей / закрой" mid-engagement (any iteration, even before iter 1 handoff):

1. The role currently holding the floor (lead, secretary, or director) writes a stub acceptance-log.md:

   ## Iteration {current} — {YYYY-MM-DD HH:MM}
   
   ### Verdict: ABORTED
   
   Reason: user requested abort.
   User message reference: "{verbatim quote of user's stop directive}"
   
   State at abort:
   - Iteration: {N}
   - Last director verdict (if any): {ACCEPT / REJECT / none}
   - Specialists dispatched: {list}
   - Artefacts produced: {list}
   

2. Run archival with abort flag:

   python ~/.claude/scripts/engagement-archive.py --reason aborted
   

   This moves engagement/ → engagement-archived/{date}-{name}-aborted/primary/. Sanity checks (criteria.md exists, ACCEPT verdict present) are skipped under --reason aborted.

3. Print one user-facing line confirming archive:

   Engagement {name} прерван и заархивирован: engagement-archived/{date}-{name}-aborted/
   

4. No further iteration/handoff/director action. Engagement is closed.

When NOT to abort

If user says "не уверен / подожди / давай по-другому" — that is NOT an abort. That's a scope clarification, route to:

• secretary if criteria are wrong (loop-to-intake protocol)
• lead if approach is wrong (request fresh dispatch with new constraints)

Abort is reserved for explicit termination: "стоп", "забей", "закрой engagement", "не делай это", "отменяю".

Engagement archival (after ACCEPT)

After the director writes ACCEPT in acceptance-log.md, the engagement directory is archived to free the slot for the next engagement. Without archival, leftover artefacts pollute whitelist scans and create cross-engagement confusion (old screens look like current ones, stale plan.md misleads new lead).

Director performs archival via the canonical script — never by hand-rolling mv. Script handles name extraction, collision-suffix, sanity checks (criteria.md exists + ACCEPT verdict present):

python ~/.claude/scripts/engagement-archive.py

Order matters: the verdict and user-facing summary go FIRST, archival LAST. If archival fails (permissions, collision unresolvable), it never affects the user-delivery message — they already got the verdict. Director retries archival or surfaces the failure as an internal note.

For aborted / rejected engagements (rare — only when user closes engagement without ACCEPT), use --force. Default refuses to archive without an ACCEPT verdict to prevent accidental loss of in-progress state.

Order of operations on ACCEPT (and what to do if archival fails)

Strictly: verdict → user-facing summary → archival. Archival is the LAST action, not the first. If archival fails, the user has already received the verdict and the deliverables — no rollback needed; the engagement is logically closed.

1. Director writes ACCEPT verdict in engagement/acceptance-log.md with criteria trace.
2. Director runs python ~/.claude/scripts/handoff-paths-check.py engagement/acceptance-log.md — if any phantom path in evidence column, fix verdict before proceeding.
3. Director composes user-facing summary (Russian, lists deliverables verbatim).
4. Director runs python ~/.claude/scripts/engagement-archive.py.
5. If archival succeeds: print archived-to path, done.
6. If archival fails (collision unresolvable, permissions, disk full):
   • Do NOT undo the verdict. The user has the deliverables; engagement is closed.
   • Log the archival error in a new section ## Archival pending — {timestamp} at the end of acceptance-log.md.
   • User is notified once: "Engagement принят, артефакты доставлены. Архивация не сработала: {error}. Повторю после {fix}."
   • Director (or any later session) retries engagement-archive.py once the blocker is cleared. Script is idempotent — re-running on already-archived state is a no-op.

Archival never blocks user delivery

The user-facing message goes BEFORE archival. If you swap the order, an archival hiccup becomes a perceived failure of the engagement itself. The agency-model contract is: deliverables + verdict are user-visible artefacts; archive is internal bookkeeping.

Archive directory:

• engagement-archived/ lives in the project working directory.
• One subdirectory per completed engagement: {YYYY-MM-DD}-{engagement-name}/.
• Contents preserved as-is (criteria.md, handoff.md, acceptance-log.md, executor-reports/, validation-log.md, screens/, traces/) — kept for audit-trail and future cross-reference.
• Never delete archives without user instruction.

If a new engagement starts in the same project: agency-intake creates a fresh engagement/ directory; archival happened on the previous one already, so there are no collisions.

Pre-archival sanity check (director runs before mv):

• criteria.md exists (we're archiving a real engagement, not random folder).
• acceptance-log.md exists with at least one ACCEPT verdict (don't archive engagements that never reached accept).
• No new engagement is mid-flight in this directory (no engagement/ already exists at target archive path).

If the user asks to re-open / reference an archived engagement: read engagement-archived/{date}-{name}/ directly. Do not unarchive (move back) — that would make the new engagement collide with the old.

Task-tool prompts: minimum viable content

Long Task-tool prompts (200+ lines) duplicate what the dispatched agent already knows from its skills frontmatter (engagement-protocol, domain methodology, Engagement-mode contract). Verbose prompts:

• inflate token usage with no signal gain
• delay agent's first action (more tokens to parse before responding)
• look like "stalled" to operators waiting for first heartbeat

Minimum-viable Task prompt (canonical)

Engagement: {engagement-name}
Iteration: {N}
Criteria: {absolute path to engagement/criteria.md}
Review mode: {lean | full | solo}

Read criteria.md first. Engagement context, source paths, and constraints
are inside it — do not re-paste here.

Begin {phase-name}. Heartbeat per phase per protocol.

Return summary on completion (or escalation).

That's it. 5–8 lines.

What NOT to include in Task prompts

• Full criteria text — agent reads criteria.md itself.
• Source artefact paths — listed in criteria.md.
• Protocol reminders ("don't create files outside whitelist", "use heartbeat", "11-section handoff") — those are in engagement-protocol skill which the agent loads via frontmatter. Re-pasting them in prompts is noise.
• Anti-pattern lists — already in agent's ## Anti-patterns section.
• Backstory about why the engagement exists — irrelevant to execution.

When MORE prompt content IS justified

• Specific phase-only constraint (e.g. "this iteration is rework — focus only on F-02 token mismatch from previous reject").
• One-off override that contradicts protocol default (e.g. "skip docs-pipeline for this engagement — out of scope per scope-sync").
• New convention the agent's skills don't yet teach (very rare; if it recurs, document in skill instead).

Even in these cases, additional content stays under 30 lines.

Why this matters

In the actual landing-hybrid-header-hero test we ran: a 200-line dispatch prompt to design-lead caused the agent to spend its first 20-40 seconds parsing instead of acting. Operator interpreted this as a stall and interrupted. Friction was self-inflicted by verbose prompt, not by agent behaviour.

Resume policy (interrupted iterations)

If a lead's previous session was interrupted mid-iteration (Task tool cancelled, context compaction, manual user stop) and a new dispatch resumes the same iteration N:

1. Inspect existing engagement state first. Files from prior session may include partial executor-reports, traces, screens, partial hybrid build, etc. They are not invalid by virtue of being from an interrupted session — but they are not automatically valid either.

2. Decide per-artefact: reuse or regenerate. Heartbeat at the resume point MUST list which artefacts you reuse vs regenerate:

   ## Heartbeat — Phase Resume — completed {ts}
   - iteration: {N} (resumed)
   - artefacts reused-from-prior-session: traces/iter-N/nav-anchor-click.json (validated still represents current code), executor-reports/X.md (Phase 3 work intact)
   - artefacts regenerated: screens/iter-N/light/*.png (re-captured against latest code), validation-outputs/* (validators re-run on resume)
   - artefacts deleted: scope-sync.md (legacy from prior intent that was superseded)
   - next phase: {name}
   

3. Reuse criteria:

   • Trace JSON is reusable IFF its captured_at is newer than the most recent code change AND the artefact under test is unchanged.
   • Screens are reusable IFF the surface they capture is unchanged since they were taken.
   • Validator outputs are reusable IFF the artefact they validated is unchanged.
   • Executor reports are reusable IFF the specialist's work isn't being redone.

4. Stale = regenerate, no shortcut. Reusing a trace or screen that doesn't represent current state is the silent-failure mode this rule prevents. If unsure → regenerate.

5. Trace captured_at: validators (ux-review) and trace-schema-check.py warn if captured_at is older than the file mtime of any artefact the trace references. Lead must regenerate or update the trace.

Lead heartbeat (mandatory — every lead, every phase)

Long-running orchestrator-agents (top-leads, mid-leads) dispatched via Task tool can stop streaming tokens for many minutes while doing internal planning, file edits, or sub-dispatches. The user/operator has no signal whether the agent is alive or stuck.

To prevent silent stalls: every lead appends one heartbeat line to engagement/validation-log.md after each completed phase. The presence + recency of these lines is the heartbeat.

Heartbeat entry format

## Heartbeat — Phase {phase-name} — completed {YYYY-MM-DD HH:MM:SS}
- iteration: {N}
- artefacts updated: {list of paths touched in this phase}
- next phase: {name | "handoff" | "done"}

Inserted at the top of validation-log.md (newest first), so observers tail validation-log.md get latest signal.

Cadence

• Top-lead phases: intake-understanding, plan, dispatch (per mid-lead), cross-cutting validation, docs-pipeline, self-acceptance, handoff. → 6-8 heartbeats per iteration.
• Mid-lead phases: intake-from-top, plan, dispatch (per specialist), aggregate, return-up. → 4-5 heartbeats per dispatch.
• Specialists do NOT heartbeat — they are short-lived and return synchronously to mid-lead.

Heartbeats are append-only, never modified. They are NOT validation findings — validation-log.md retains its existing role as validator output index, the Heartbeat sections live alongside the per-validator sections.

When user / operator can confirm "stuck"

If validation-log.md's most recent Heartbeat is older than:

• 5 minutes for an S engagement
• 15 minutes for M
• 30 minutes for L (mid-lead may legitimately spend ≥30min in a single complex phase)

→ engagement is presumed stalled. Recommended action: open the engagement directory, check git status / file mtimes for any artefact created since last heartbeat. If lead made progress without writing heartbeat — that's a protocol violation (REJECT trigger). If no progress visible — abort and re-dispatch from last completed phase.

engagement-doctor.py --check stalled automates this signal (Tier 11.6).

Anti-patterns

• Don't backfill heartbeats — write them when the phase actually completes, not in handoff.md after the fact.
• Don't heartbeat mid-phase — only at phase boundaries.
• Don't heartbeat from specialists — they have no phases.

Token budget guard (Tier 14)

Each tier has an empirical token envelope (lead + director combined per iteration):

size	budget per iter	trigger
S	100,000	one-shot, abnormal if more than 1 iter
M	500,000	M baseline; 500k×2 = 1M is the realistic cap before user-touch
L	1,500,000	L baseline; rare engagement should exceed cumulative 4-5M before scope-sync escalation

Lead runs after every heartbeat from Phase 4 onward (when costly subagent waves happen):

python ~/.claude/scripts/token-budget.py engagement/ --json

Exit codes:

• 0: usage ≤ 80% × cumulative_budget — on track.
• 0 with status: warn: 80% < usage ≤ 100% — finishing strategy, no panic.
• 1 with status: fail: usage > 100% — over budget. Lead chooses one:
  1. Auto-promote tier (S→M, M→L) via size-detect.py --auto-promote if scope grew naturally.
  2. Scope-sync escalation with the user via director (per criteria.md mutability rules) — propose deferrals.
  3. Accept partial: ship completed atoms, list rest in handoff §11 Known deferrals.

The guard reads ~/.claude/projects/{project}/metrics.jsonl for tokens_used per iteration. When that field is absent (older director runs), the script falls back to duration_s × 800 token proxy. Director must start including tokens_used field per the per-iter metric line.

The guard is a budget signal, not a hard kill switch. Lead can override one iteration with explicit user-touch authorisation in scope-sync.md. Demoting tier or under-reporting tokens to dodge the guard = protocol violation; director rejects on next sweep.

Size auto-promote check (every heartbeat after Phase 2)

After Phase 2 (plan.md frozen) and on every heartbeat thereafter, lead runs:

python ~/.claude/scripts/size-detect.py engagement/ --mode runtime --auto-promote --json

The script measures the engagement against tier thresholds (executor-reports count, tasks count, ui_surfaces, diff files/LOC, deploy crossed) and:

• Exit 0: observed ≤ current tier. No action — heartbeat as usual.
• Exit 1: observed > current tier. With --auto-promote, the script:
  1. Rewrites criteria.md frontmatter size: to the new tier (S→M, M→L; demotion forbidden).
  2. Appends a ## Auto-promote — size X → Y — {ts} block to scope-sync.md documenting the trigger measurements.

Lead acks the promote in the same heartbeat: next phase: {name}; auto-promoted: {old}→{new} and adjusts subsequent rigour to match the new tier (e.g. tasks/ now mandatory if promoted to L, §11 now required if promoted to M).

The check is cheap (~50ms, no subprocess fork-out beyond directory scan + handoff.md grep). Skipping it once is fine; never running it across an engagement is the failure mode where lead silently treats an L engagement as M and gets REJECTed by director's handoff-precheck.py --mode ready.

director-sweep.py re-runs the same check during acceptance — if it sees current still S/M but observations are clearly L, that's a REJECT with reason "size drift, lead failed to promote".

Retroactive consequences of auto-promote

Promotion shifts the acceptance protocol to the new tier retroactively. Specifically:

1. Iteration budget bumps +1 on the promoted engagement (S→M makes M-budget 3 instead of 2; M→L makes L-budget 4 instead of 3). One extra round absorbs the adversary findings on work that was produced under lighter-tier mode.
2. Adversary pass is required at handoff regardless of when promotion occurred. S engagements that auto-promote to M will receive Opus adversary review; M engagements promoted to L will receive full consilium. Producer cannot skip adversary by claiming "the work was done under S/M mode".
3. scope-sync.md documents the budget revision:

   ## Auto-promote S → M @ 2026-05-09T14:23:00Z
   Trigger metrics: 3 specialists invoked, 8 diff_files, ux_surfaces=2
   New acceptance protocol: M-tier (Opus adversary required at handoff)
   Iteration budget revised: 2 → 3 (one extra round budgeted for adversary findings)
   

4. Validators applicable to the new tier must run before handoff — if M-tier requires accessibility-validator on ux_heavy and the engagement was produced as S without it, lead must run validator now and fix gaps before submitting.

Lead must address gaps that the new tier requires before handoff, not at acceptance. Auto-promote should not surprise the director at acceptance time — heartbeat-driven detection means there is always at least one phase between promote and handoff for the lead to catch up. If lead submits an auto-promoted engagement without addressing the new tier's requirements, handoff-precheck.py for the new tier will FAIL on missing artefacts (e.g. tasks-decomposition check fails on M→L without tasks/INDEX.md).

Machine-checked gates

Two distinct points where machine checks fire. Both use scripts at ~/.claude/scripts/:

At intake (secretary, BEFORE handoff to lead)

python ~/.claude/scripts/preflight.py --criteria engagement/criteria.md --json --auto-fix

Purpose: ensure validation environment is ready before the engagement starts. Wave-2-style "Docker missing for the whole engagement, then user is asked to validate by hand" is what this prevents.

Before handoff (lead, then director on receipt)

python ~/.claude/scripts/handoff-precheck.py engagement/ --json

Purpose: ensure the engagement state itself is ready for review — whitelist clean, paths exist, validators ran, no banned language, no undisclosed dangerous ops, etc. Includes a re-run of preflight (environment may have degraded mid-engagement: Docker crashed, secret rotated, package broke).

Hard-gate tier dispatch (tiered acceptance refactor):

• S-tier: 6 critical checks (criteria-frontmatter, whitelist, preflight, handoff-paths, danger-scan, verdict-canonical)
• M-tier: 11 checks (S + handoff-sections, self-acceptance-thinness, iteration-counter, validator-outputs, size-drift)
• L-tier: 19 checks (all)

The script reads size: from criteria.md frontmatter and runs only the tier-applicable checks (no soft-skip overhead). Use --all-checks for debug or --override-checks NAME1,NAME2 for ad-hoc additional checks.

At acceptance (M/L tiers only — S has no director phase)

# M-tier: single Opus adversary
python ~/.claude/scripts/adversary.py engagement/ --consilium M

# L-tier: 5-reviewer consilium (peer-Opus + 2× Codex + Sonnet + Haiku)
python ~/.claude/scripts/adversary.py engagement/ --consilium L

# Aggregate:
python ~/.claude/scripts/consilium-synth.py engagement/

# Human reads consilium-summary.md as supreme judge, writes human-directive.md.
# THEN director acts per directive (PROCEED_TO_VERDICT | REJECT_NOW | DIRECTED_VERDICT).

# After director writes verdict, mechanical post-check:
python ~/.claude/scripts/handoff-precheck.py engagement/
# (M/L tier sets include `human-directive` and `director-verdict` checks.)

Two-pass adversary protocol (filesystem-isolated): each role runs Pass 1 in subprocess on a CURATED copy of engagement/ that physically excludes handoff.md, acceptance-log.md, consilium-summary.md, human-directive.md, and validation-outputs/. Pass 1 writes preliminary findings. Pass 2 runs on full engagement with preliminary findings injected; reads handoff and finalizes verdict. Outputs:

• engagement/validation-outputs/{role}-iter-N-preliminary-{ts}.json (Pass 1)
• engagement/validation-outputs/{role}-iter-N-{ts}.json (Pass 2 final)

consilium-synth.py aggregates Pass 2 outputs into engagement/consilium-summary.md with two-stage dedup (cluster by evidence_path first, then issue similarity), convergent findings, cross-family disagreements, naive-layer catches, similarity matrix.

Human-as-supreme-judge step: human reads consilium-summary.md, writes engagement/human-directive.md with Decision: PROCEED_TO_VERDICT | REJECT_NOW | DIRECTED_VERDICT. This filters adversary noise (false positives, filler) before director processes. Director then acts per directive — adjudicating remaining signals with explicit markers (SUSTAINED/OVERRULED, SIDED WITH X, REAL/FALSE_POSITIVE, ACKNOWLEDGED). director-verdict-check.py mechanically verifies markers exist for every consilium signal.

See director-acceptance-protocol skill for full per-tier procedure.

One canonical entry point bundles every handoff machine check

python ~/.claude/scripts/handoff-precheck.py engagement/ --json

The wrapper runs:

1. whitelist — ls engagement/ against the closed allowed list (no rogue preview.md / compliance.md).
2. criteria-frontmatter — criteria.md has engagement, domain, ux_heavy, tools_required.
3. preflight — every tool in tools_required is reachable (delegates to preflight.py).
4. handoff-paths — every path cited in handoff.md exists on disk (delegates to handoff-paths-check.py).
5. handoff-sections — required sections §1–§5, §7, §8, §11 present; §6 present if ux_heavy: true.
6. self-acceptance-thinness — §7 concerns sublist has ≥2 real items (catches LLM "no concerns" bad-faith).

Non-zero exit = INCOMPLETE handoff. Never submit / accept with red exit codes — these checks exist precisely because the underlying bug classes (broken tooling, phantom paths, rogue files, thin rehearsal) cannot be reliably caught by reading prose.

The individual sub-scripts (preflight.py, handoff-paths-check.py) can also be run directly if you want a focused check (e.g. mid-engagement Docker sanity), but at gate time always go through the wrapper.

Escalation template (director → user, Russian)

После двух кругов правок директор не принимает работу. Текущая блокировка:
- {blocking item 1}
- {blocking item 2}

Продолжать ещё круг или пересмотреть scope / criteria?

Cross-domain handoff

Two-domain engagements only. Secretary classifies the primary domain and declares secondary as a downstream dependency in criteria.md. Three-domain engagements are rejected at intake — user must split them.

State location (collision-free)

Primary engagement uses engagement/ (the canonical path). Secondary engagement uses engagement-secondary/{domain}/ to avoid overwriting primary state.

project-root/
├── engagement/                      # primary (e.g. design)
│   ├── criteria.md
│   ├── handoff.md
│   └── ...
└── engagement-secondary/
    └── marketing/                   # secondary (e.g. marketing)
        ├── criteria.md              # derived from primary's accepted output
        ├── handoff.md
        └── ...

handoff-precheck.py engagement-secondary/{domain} works on the secondary the same way as on primary. All scripts (preflight, paths-check, danger-scan, archive) accept any directory — they don't hardcode engagement/.

Workflow

1. Secretary writes engagement/criteria.md with primary domain + cross-domain.secondary: <domain> note.

2. Primary lead completes phases.

3. Primary director ACCEPTs.

4. Primary lead (NOT director) initiates secondary using secondary-init.py (deterministic, scripted):

   python ~/.claude/scripts/secondary-init.py \
     --domain marketing \
     --primary engagement/ \
     --scope "Запустить кампанию на лендинге, созданном в primary engagement"
   

   The script:

   • Creates engagement-secondary/marketing/
   • Reads primary's criteria.md to inherit engagement name, project metadata
   • Writes a fresh criteria.md with frontmatter (domain: marketing, parent_engagement: ../engagement/, fresh size, ux_heavy, tools_required defaults)
   • Initialises iteration file at 1
   • Creates executor-reports/, validation-outputs/ directories
   • Writes a <!-- inherits from {primary path} --> audit comment

5. Primary lead dispatches secondary lead via Task tool with the new engagement-secondary/{domain}/criteria.md path.

6. Secondary lead runs its own full engagement cycle in engagement-secondary/{domain}/.

7. Secondary director ACCEPTs (or REJECTs into secondary's own iter loop — primary is already done).

8. After secondary ACCEPT, primary director composes unified user message referencing both engagements.

Archival

On final user delivery (after both ACCEPT'ed):

python ~/.claude/scripts/engagement-archive.py             # archives primary
python ~/.claude/scripts/engagement-archive.py --root . --secondary marketing   # archives secondary

Both end up under one dated archive folder:

engagement-archived/
└── 2026-05-06-acme-launch/
    ├── primary/             # mv of engagement/
    └── secondary-marketing/ # mv of engagement-secondary/marketing/

Anti-patterns

• Don't write secondary state into engagement/ — collision with primary, irrecoverable.
• Don't dispatch secondary lead before primary director ACCEPTs — the secondary depends on primary's accepted output, not work-in-progress.
• Don't archive primary while secondary is still iterating — final unified message comes after both ACCEPT.

Observability

Every director iteration appends one JSON line to ~/.claude/projects/{project}/metrics.jsonl:

{
  "ts": "2026-04-20T15:30:00Z",
  "engagement": "{engagement-name}",
  "domain": "marketing|dev|design",
  "director": "{director-agent}",
  "iter": 2,
  "verdict": "accept|reject",
  "blocking_count": 3,
  "reran_validators": ["reality-checker", "skeptic"],
  "duration_s": 180
}

No live dashboard. Raw JSONL for retrospective analysis.

Role boundaries (authoritative)

Stage	Secretary	Lead	Director	User
Intake capture	✓	—	—	source
criteria.md draft	✓	—	reads	approves
Scope sync (optional)	—	raises Q	writes Q/A + freeze	—
Planning	—	✓	—	—
Specialist dispatch	—	✓	—	—
Cross-cutting pipelines	—	✓	re-runs on sweep	—
Handoff package	—	✓	—	—
Accept/reject verdict	—	—	✓	—
User-facing delivery	—	—	✓ (on accept)	receives
Escalation	—	—	✓ (at round 3)	decides

Anti-patterns

• Don't invent new artefact sections. Schemas are fixed. Add fields via this skill's next revision, not per-engagement.
• Don't create files outside the whitelist. Forbidden list (preview/compliance/review-log/etc.) is closed. Wanting one of those = signal that content belongs in an existing whitelist file. Director treats out-of-whitelist files as REJECT.
• Don't skip criteria.md. Directors cannot accept against fuzzy intent.
• Don't let the lead write acceptance-log.md. That's self-acceptance.
• Don't let the director write handoff.md. That's author-as-reviewer.
• Don't talk to the user mid-engagement (lead / director) — lead surfaces via director; director surfaces only on accept or escalation. Pre-flight tooling unavailability is the only mid-engagement user touch allowed (and it's blocker disclosure, not work consultation).
• Don't issue ACCEPT CONDITIONAL. Verdict is binary. Tool unavailability = REJECT with reason validation incomplete, not a deferral to user.
• Don't defer Playwright capture / exercised flow logs to the user. UX validation artefacts are part of hand-off. If they're missing, hand-off is incomplete.
• Don't silently exceed iteration budget. Escalate before round 3, OR earlier on repeating critique.
• Don't use slot language. "Slot 1/2 used", "last attempt", "final round" — banned. Escalation is root-cause based.