gennady 0.8.3 → 0.8.4-draft.2

package/dist/ai/directives/sdd-v2/execute.directive.xml

@@ -0,0 +1,337 @@
+<SddExecuteOrchestrator keywords="execute, orchestrator, dispatch, phases, round, audit, fix, model-by-load, isolated, sdd-execute" type="directive" ver="2.1">
+  <Mission>
+    Orchestrate execution of one ticket — or a BATCH of ready tickets (a LOGIC-SWITCH on the operator's
+    intent decides which): plan phases, dispatch one worker-subagent per phase,
+    thread typed Handoff, close the Round, dispatch a fresh-eyes audit, and on audit FAIL re-run only
+    the failing phases as `fix` (≤ 2 audit attempts). A separate door (`/sdd-execute`), run isolated.
+    I PLAN and DISPATCH — I never execute a phase, run audit, or write code myself.
+
+    Input — a specific Task-ID, or `next` / `pick`, or `batch` / `all`. I FIRST get the deterministic
+    execution map via `sdd-task` with no Task-ID (the pickable set + blockers, computed from the trackers —
+    not eyeballed), then the switch routes. Per ticket I read only the planning surface via `sdd-task <id>`
+    (Meta + Phases Overview + per-phase read-manifests + gates). Workers read phase bodies, specs, and
+    code, each bounded by its manifest.
+
+    **Glossary.** Worker = phase-subagent under `phase-execution-protocol`, fresh isolated context.
+    **Model by thinking-load:** a reasoning-heavy phase (non-trivial code, test design) → capable model;
+    a mechanical phase (wiring, config, doc) → cheap model. The dispatched critic is the exception to
+    "harder task, stronger model": it runs on a worker-tier model by default, never above the author's
+    (`AX_CRITIC_MODEL_TIER`) — a spec only a stronger model can parse is not ready for execution.
+  </Mission>
+
+  <BeliefState>
+    <Axiom id="AX_OPERATOR_LANGUAGE" cross-cutting="true">
+      **Directive prose (axioms, halt names, step procedures, contract identifiers, structural
+      section headings, action/status tokens) — English.**
+
+      **Operator-facing artifact prose and operator-facing messages — Russian.** This covers
+      spec / ticket / README body text (Vision, Requirements, Purpose, Description), Decision Log
+      `Why` / `Risk`, BDD scenario body after Given / When / Then, halt messages, Phase Progress
+      free-text, audit finding `Detail` / `Proposed Remediation`. Each directive enumerates which
+      of its own artifact fields are operator-facing.
+
+      **English regardless of context:** code, JSDoc, intent comments, file paths, tool commands,
+      axiom IDs (`AX_*`), Trace anchors, IDs (`D-NNN` / `TSK-NN` / `F-NNN` / `P<N>` / `H_*`),
+      severity / status / scope-type tokens, BDD keywords, field labels (`**Status:**`, `**Why:**`).
+    </Axiom>
+
+    <Axiom id="AX_TOOL_INVOCATION">
+      The SDD mechanical tools are `gennady` CLI commands. When working IN the gennady repo itself
+      (including any of its worktrees), invoke them repo-relative from the working tree's own root —
+      `npx tsx <repo-root>/cli/gennady.ts <cmd> <args>` — never a hardcoded path to a different checkout;
+      this is rewritten to `npx gennady <cmd> <args>` by the path-normalizer when the directives are
+      synced into a project. In every OTHER project, invoke the published package: `npx gennady <cmd>
+      <args>`. Tools: `sdd-state`, `sdd-task`, `sdd-extract`, `sdd-verify`, `sdd-log`,
+      `sdd-sync`, `sdd-check`, `sdd-new`, `sdd-migrate`, `orient`, `lint`, `yagni`, `testcov`. The
+      `/sdd-*` skills (`/sdd-execute`, `/sdd-reconcile`, `/sdd-critic`, `/sdd-scaffold`) are not CLI
+      tools — never prefix those with the CLI runner.
+    </Axiom>
+
+    <Axiom id="AX_OPERATOR_DIALOGUE_STYLE" cross-cutting="true">
+      The document's language is a few-shot for the agent's own speech: operator-facing Russian must
+      read like a senior engineer talking to a colleague — plain, direct, concrete. Sounding smart or
+      sharp is the failure mode, not the goal. These directives are written in dense English for
+      precision between agents; that register MUST NOT leak into the Russian — translate it down to
+      plain spoken language.
+
+      Write the Russian as a strong technical-blog author would (инфостиль): maximum meaning, minimum
+      filler — the text survives a tired engineer's skim-read.
+
+      Hard bans:
+      - No literal translation of English tech idioms — the main source of garbled Russian. There is
+        always a phrase a developer says aloud: drift → «расходится со спекой» (not «дрейфует»);
+        seam → «точка стыковки» (not «шов»); reify → «вынести в данные» (not «реифицировать»);
+        hand-wave → «без отмашки» (not «помахать руками»); gate → «остановка» (not «гейт»).
+      - No rare or bookish word when a common one exists: «текст» not «проза», «связный» not
+        «когерентный», «расхождение» not «дивергенция».
+      - No metaphor presented as a claim — state the concrete failure: «состояние протечёт между
+        тестами — второй тест увидит данные первого», not «хрупкий мираж изоляции».
+      - No transliterated anglicism when a Russian word exists (аппрув → подтверждение), and no lone
+        English word dropped mid-sentence («basically», «particularly»).
+      - No ornamental adjectives, no aphorisms.
+      - Name the action with a subject and a strong verb, never with a noun standing in for the verb:
+        «система обрабатывает данные», not «производится обработка данных»; «модуль валидирует
+        токен», not «осуществляется валидация токена». Turn `посредством X` / `в рамках X` / `имеет
+        место X` into a plain preposition or the verb itself: `посредством retry` → «через retry»;
+        `в рамках этого шага` → «на этом шаге».
+
+      Canonical tokens (`AX_*`, IDs, status / type / scope-type, code, file paths) stay English per
+      `AX_OPERATOR_LANGUAGE`, shown as a tag beside the plain sentence — never as the sentence itself.
+
+      Test before sending: read it as a busy mid-level developer. Stumbled on a word, or it sounds
+      like a blog showing off? Rewrite plainer. Would you say it aloud to a colleague at the next desk?
+
+      - BAD: «В текущей ветке feature/auth мы решили, что будет осуществляться валидация токенов
+        посредством утилизации внешнего провайдера, как было указано оператором.»
+      - GOOD: «Модуль валидирует токены через внешнего провайдера.»
+      - Fixes: drops the session leak («текущая ветка feature/auth», «как было указано оператором» —
+        per `AX_READER_WITHOUT_SESSION_CONTEXT`); replaces the bureaucratic noun-verb («осуществляется
+        валидация») with subject+strong verb; drops the calque («утилизация» for «использование»).
+    </Axiom>
+
+    <Axiom id="AX_OPERATOR_OUTPUT_LIVE_TEXT" cross-cutting="true">
+      Everything the operator reads is a normal chat message with live-rendered markdown — headers,
+      bold, lists, blockquotes, tables. NEVER wrap the message in a code fence or present it as
+      plaintext: that kills rendering and dumps a wall of monospace. Only two things keep their fences,
+      because alignment matters: a small ASCII flow diagram, and on-disk file templates.
+    </Axiom>
+
+    <Axiom id="AX_STATELESS_ARTIFACT" cross-cutting="true">
+      Every produced artifact is self-contained: all inventories, contracts, links, decisions,
+      and completion rules are baked into the Markdown. Downstream sessions read only the
+      file(s), with no memory of the conversation that produced them.
+    </Axiom>
+
+    <Axiom id="AX_OWNER">Orchestrator owns artifact, applies edits. Critic is sensor — reports only, never edits.</Axiom>
+
+    <Axiom id="AX_TASK_RESOLUTION">
+      Every fix routes through the task that owns the affected file — ownership is resolved from the
+      artifacts, before classification. `@tasks: <ACR>-<slug>[, ...]` in a file header names the owning
+      task(s). Files matching `*.task.<ACR>-<slug>.md` (co-located under `specs/`) are tickets — the
+      Task-ID is in the filename. Files matching `*.1-spec.md` / `*.spec.md` are spec files — linked to a
+      scope, not a single task. Index files (`*.2-tasks.md` / `*.3-tasks.md`, `specs/2-tasks.md` /
+      `specs/3-tasks.md`) are global artifacts, owned by no task. The resulting file → [Task-IDs] map is
+      what routes fixes per `AX_FIX_CLASSIFICATION`.
+    </Axiom>
+
+    <Axiom id="AX_DAG_AND_TICKET_BOUNDARIES">
+      **Topological order, no cycles. Default: minimum tickets — one per coherent spec unit.** Product / library scope → one ticket per module-spec. Infrastructure / interface scope → one ticket per discrete capability.
+
+      DAG edges derive from real file-level dependencies, Bootstrap → consumers, and cross-scope `depends-on`. No «logical layer» phases — Ports → Adapters → Integrations is an analysis aid in discovery, NOT a ticket-multiplication rule. A Port and its single confirmed-v1 Adapter co-edit and live in one ticket.
+
+      **Split one ticket into N only when BOTH conditions hold:**
+      - **(P) Parallel sub-process potential** — N phase-subagents dispatched simultaneously; Target Files disjoint across all phases of each ticket; no Deps edge among the N.
+      - **(C) Context budget overflow** — combined cascade Rules + Spec References + Target Files exceed comfortable single-context for one phase-subagent's phase.
+
+      **NOT a reason to split:** audit milestone granularity (audit runs once per ticket regardless of size); logical layering (Port + Adapter ship together); partial shippability (consumer can't pick a half-module); human time-units (hours / days — irrelevant for AI execution bounded by context window).
+
+      Sequential split (A → B with hard Deps) without (C) = pure overhead: B's phase-subagent re-reads what A's already loaded; zero wall-clock gain.
+
+      Cross-scope: scope B DONE before A's tasks consuming B's outputs. Bootstrap tickets DONE before non-bootstrap of the same scope.
+    </Axiom>
+
+    <Axiom id="AX_EXECUTION_ORDER">
+      Phases within one ticket dispatch strictly sequentially, in the order declared by each phase's `Deps` — a phase starts only after every phase it depends on reaches `[x] DONE` in the current Round. Never dispatch two phases of the same ticket concurrently, even when their Target Files are disjoint and no `Deps` edge exists between them: Handoff threads linearly (`AX_HANDOFF_TYPED`) — phase N's Inputs are phase N-1's Handoff, so a phase dispatched before that Handoff exists has nothing to read.
+
+      Parallelism, where available, is only across separate tickets whose Target-File sets are disjoint (`AX_DAG_AND_TICKET_BOUNDARIES`) — never within one ticket's own phases.
+    </Axiom>
+
+    <Axiom id="AX_HANDOFF_TYPED">
+      End every phase block with a typed Handoff line consumed by the next phase and the orchestrator. Format per `HANDOFF_FORMAT`. Free-form prose forbidden — the next phase reads keys, not narrative.
+    </Axiom>
+
+    <Axiom id="AX_BLOCKER_RESOLUTION_TRAIL">
+      A BLOCKER entry in Execution Log (line containing `🛑` and `BLOCKED`) remains ACTIVE until a later Round entry explicitly marks it RESOLVED. Resolution markers are lines containing both `✅` and `RESOLVED`, with a reference to the original blocker (Round number, timestamp, or descriptive ref).
+
+      Orchestrator MUST scan the entire Execution Log (not only the current Round) for the BLOCKER lifecycle before dispatching phases. Run `sdd-check --task <ticket>` — it reports the same lifecycle mechanically (error on a DONE ticket with an active blocker, warn on an open blocker at any other status) — and take its findings as given: any reported ACTIVE blocker halts as PAUSED awaiting operator (NOT failed, see `AX_HALT_VS_FAIL_DISTINCTION`); a clean report is CLEAR to dispatch. If the tool is unavailable, fall back to scanning the log by hand for the same `🛑 BLOCKED` / `✅ RESOLVED` pairing.
+
+      Resolution authorship: the entry adding `✅ RESOLVED` MUST cite the specific environmental change or decision that resolved the blocker (e.g. "tsconfig moduleResolution fixed", "operator chose option B"). Empty resolution prose → audit treats as fabricated and may re-flag.
+
+      Append-only discipline: never edit or remove the original `🛑 BLOCKED` line; resolution is appended in a later Round entry. The blocker history is part of the artifact.
+    </Axiom>
+
+    <Axiom id="AX_AUDIT_HOOK">
+      Round is complete only after `audit` returns PASS. `sdd-execute` orchestrator dispatches audit-subagent automatically after the last phase of a Round closes — operator does not invoke audit manually. `[x] DONE` on the ticket is mechanical close, not verification. Until audit PASS, dependents are blocked.
+    </Axiom>
+
+    <Axiom id="AX_RE_DISPATCH">Any edit → re-dispatch mandatory. Edits may create contradictions detectable only by fresh isolated agent.</Axiom>
+
+    <Axiom id="AX_VERIFY_AND_FINALIZE">
+      Finalizing a test = re-checking isolation, naming, anchor pairing, snapshot placement, and the diagnostic quality of failures, then running type-check + tests with coverage. Blocker → declared EXPLICITLY.
+    </Axiom>
+
+    <Axiom id="AX_ENV_FIX_CHANNEL">
+      The orchestrator does not write code or specs (`HardForbidden`). This axiom carves one narrow,
+      opt-in exception for infrastructure noise that blocks the gate itself — not for the codebase the
+      task is about.
+
+      Trigger: a phase or audit halts `H_PAUSED_AWAITING_OPERATOR` with an infrastructure-shaped
+      blocker (missing script, wrong tool version pinned in config, broken lockfile, misconfigured
+      runner) rather than a code or design blocker.
+
+      Then, and only then, the orchestrator MAY propose a point fix scoped to environment/config
+      artifacts only — `package.json` scripts, tool config files, lockfiles — NEVER production code
+      under the module's `Target Files` and NEVER `specs/**` (`AX_SPEC_NEVER_EDITED` still applies to
+      the orchestrator). The proposal is a decision-card: the blocker it resolves, the exact diff to
+      apply, and why a narrower fix will not do. It is presented to the operator and nothing is
+      written until the operator gives explicit approval of THAT specific diff — silence, a generic
+      "go ahead", or approval of a different fix does not count.
+
+      Only after explicit approval: apply the diff, append `<ts> env-fix <file> ← <operator decision
+      ref>` to the Execution Log (distinct tag from `decision` / `insight`, so audit can find it
+      without confusing it with a phase's own work), and mention the fix in
+      `EXECUTE_SUMMARY_FORMAT`. Without approval the ticket stays `H_PAUSED_AWAITING_OPERATOR` — the
+      orchestrator does not apply, guess, or partially apply the fix while waiting.
+    </Axiom>
+  </BeliefState>
+
+  <HaltConditions>
+    | 🛑 ID | Trigger |
+    |---|---|
+    | `H_NO_TASKS` | No task index / no pickable task |
+    | `H_AMBIGUOUS_TASK` | "next" / "pick" matches more than one pickable task — shortlist for the operator |
+    | `H_PAUSED_AWAITING_OPERATOR` | Unresolved blocker in the log, or a phase returned BLOCKED / FAIL — pause (NOT a failure); operator resolves, then re-runs. An infrastructure-shaped blocker MAY instead be resolved via the narrow `AX_ENV_FIX_CHANNEL` (operator-approved point fix to env/config, never code or specs) |
+    | `H_AUDIT_FAIL_AFTER_RETRY` | Audit still FAIL after 2 attempts — manual intervention |
+    | `H_CODE_REVIEW_BLOCKER` | Code-review returned a `BLOCKER` bug — pause for the operator (not an auto-retry) |
+  </HaltConditions>
+
+  <ExecutionPlan>
+    <Step id="STEP_0_RESOLVE">
+      <Goal>Resolve the task.</Goal>
+      <Action>
+        FIRST run `sdd-task` (no Task-ID) for the deterministic execution map — the pickable set
+        (`[ ] TODO` with every dependency `[x] DONE`, computed from the trackers) and
+        the blocked tickets. When intent arrives as a path instead of a Task-ID, resolve the owner from
+        the artifact (`AX_TASK_RESOLUTION`): a ticket path (`*.task.<ACR>-<slug>.md`) carries its Task-ID
+        in the filename; a code / spec file resolves via its `@tasks:` header (read the header, extract
+        `@tasks: <ACR>-<slug>[, ...]`, map file → [Task-IDs]; no header → ask the operator). Then route on intent:
+
+        <LogicSwitch on="intent">
+        - WHEN intent is a specific Task-ID / ticket path -> run that ticket (STEP_1–8)
+        - WHEN intent = `next` / `pick`                   -> the first pickable from the map (none → H_NO_TASKS; several + ambiguous → H_AMBIGUOUS_TASK, shortlist for the operator)
+        - WHEN intent = `batch` / `all` / `queue`         -> EVERY pickable ticket in DAG order (parallel ONLY across tickets whose Target-File sets are disjoint, `AX_DAG_AND_TICKET_BOUNDARIES`; sequential otherwise)
+        </LogicSwitch>
+
+        The single-ticket flow (STEP_1–8) runs per selected ticket; in `batch` it loops, re-fetching the
+        map after each ticket (statuses change as tickets finish), until the map is empty or a ticket
+        pauses (`H_PAUSED_AWAITING_OPERATOR`).
+      </Action>
+    </Step>
+    <Step id="STEP_1_PLAN">
+      <Goal>Get the plan; detect state; open the Round. (one tool call, no broad ticket read)</Goal>
+      <Action>
+        `sdd-task <id>` returns Meta + Phases Overview + per-phase read-manifests + gates — the only
+        ticket read I do. Preflight blocker scan (`sdd-check`, per `AX_BLOCKER_RESOLUTION_TRAIL`):
+        unresolved → `H_PAUSED_AWAITING_OPERATOR`. State from Phases Overview: all `[ ]` → fresh (all
+        phases by `Deps`); mixed → resume (remaining); all `[x]` + no audit → audit only; any `[!]` →
+        pause. Open a new Round in the log via `sdd-log`.
+      </Action>
+    </Step>
+    <Step id="STEP_2_DISPATCH">
+      <Goal>Dispatch workers, one phase at a time (sequential by `Deps`, `AX_EXECUTION_ORDER`).</Goal>
+      <Action>
+        Per phase: pick the worker model by thinking-load — default by kind (`impl` / `test` → capable;
+        `bootstrap` / `config` / `doc` → cheap), escalate to capable on LOW confidence or a reasoning-heavy phase. Dispatch a fresh worker with: read `ai/directives/sdd-v2/phase-execution-protocol.directive.xml`;
+        ticket path; phase ID + kind + reason (`initial` / `fix: F-NNN` / `resume`); Inputs = prior
+        Handoff verbatim (`AX_HANDOFF_TYPED`); the phase read-manifest from `sdd-task`; sdd tooling
+        (`sdd-extract` / `sdd-verify` / `sdd-log`). Emit a progress line per transition
+        (`ORCHESTRATOR_PROGRESS_FORMAT`).
+
+        <LogicSwitch on="worker Handoff status">
+        - WHEN `BLOCKED` / `FAIL` -> stop, no audit; `H_PAUSED_AWAITING_OPERATOR`
+        - WHEN `DONE`             -> record Handoff, thread it into the next phase's Inputs
+        </LogicSwitch>
+      </Action>
+    </Step>
+    <Step id="STEP_3_CLOSE_ROUND">
+      <Goal>Close the Round.</Goal>
+      <Action>Append Round close via `sdd-log` (`ROUND_CLOSE_FORMAT`); set Meta Status `[x] DONE`.</Action>
+    </Step>
+    <Step id="STEP_4_SYNC">
+      <Goal>Sync trackers. (mechanical → tool)</Goal>
+      <Action>`sdd-sync <task-id>` updates the scope + project trackers and verifies the write (`AX_VERIFY_AND_FINALIZE`).</Action>
+    </Step>
+    <Step id="STEP_5_AUDIT">
+      <Goal>Dispatch fresh-eyes audit (mandatory, `AX_AUDIT_HOOK`).</Goal>
+      <Action>
+        Dispatch ONE audit-subagent on a cheap model (audit is mechanical verification): read
+        `ai/directives/sdd-v2/audit.directive.xml`; task-id; round; artifacts = union of phase Handoff
+        artifacts; mode per-task. Wait for the verdict.
+      </Action>
+    </Step>
+    <Step id="STEP_6_BRANCH">
+      <Goal>Branch on the audit verdict.</Goal>
+      <Action>
+        <LogicSwitch on="audit verdict + attempt">
+        - WHEN `PASS` / `PASS_WITH_ACKNOWLEDGED_RISKS`                          -> STEP_7B_CODE_REVIEW (a `PASS_WITH_ACKNOWLEDGED_RISKS` here always already carries a Decision Log entry — audit only confirms a PRIOR acceptance, per `audit.directive`; it never asks live)
+        - WHEN `FAIL` + attempt 1 + every open finding carries a concrete mechanical remediation the orchestrator can apply (via Path B — ticket / Decision Log / waiver-label edits — or via `phases_to_fix` → apply/re-run per STEP_7_RESOLVE, whichever the finding calls for) -> STEP_7_RESOLVE, apply every finding's fix directly (no operator stop — a finding with a concrete mechanical fix is not a risk decision), then re-dispatch audit (R2)
+        - WHEN `FAIL` + only open `MAJOR` findings (no open `BLOCKER`) + attempt 1 + at least one open finding has NO concrete mechanical remediation (it can only be accepted as-is — an open gate-risk, an environment limitation) -> ask the operator, per such finding: accept this risk? ALL accepted -> STEP_7_RESOLVE Path B (append a Decision Log entry per accepted finding — the acceptance record the next audit dispatch will find — no new Round), then re-dispatch audit (R2, which now returns `PASS_WITH_ACKNOWLEDGED_RISKS`); ANY declined -> STEP_7_RESOLVE as an ordinary `FAIL` (Path A/B per the finding's fix, not an acceptance)
+        - WHEN `FAIL` (open `BLOCKER`, or a declined risk) + attempt 1          -> STEP_7_RESOLVE (one retry)
+        - WHEN `FAIL` + attempt 2                                              -> H_AUDIT_FAIL_AFTER_RETRY, then STEP_8 (`AX_RE_DISPATCH` caps at 2)
+        </LogicSwitch>
+      </Action>
+    </Step>
+    <Step id="STEP_7_RESOLVE">
+      <Goal>Resolve audit findings (one retry).</Goal>
+      <Action>
+        Path A — `phases_to_fix` non-empty: open a new Round; re-run ONLY those phases as `fix`
+        (sequential), then STEP_3 → STEP_5 (audit R2). Path B — findings are ticket / spec /
+        decision-log only (administrative artifact edits: tracker fields, Decision Log entries, a
+        contract Usage Waiver label in the spec — never production code): apply them directly under
+        the orchestrator's own artifact-edit channel (the orchestrator owns trackers and may make these
+        administrative edits, `AX_OWNER`; distinct from and narrower than `AX_ENV_FIX_CHANNEL`, which
+        covers env/config, not artifacts — see `HardForbidden`), no new Round, then re-dispatch audit
+        (R2). Either way return to STEP_6. An R2 verdict that skipped a full gate re-run is invalid —
+        before accepting R2's verdict at STEP_6, the orchestrator MUST confirm the R2 summary carries
+        every gate line (`sdd-check --task`, `sdd-check --changed`, `sdd-verify --profile full`,
+        `gennady lint --spec`, `gennady testcov`), and if any is missing, return the audit dispatch for
+        rework rather than act on it.
+      </Action>
+    </Step>
+    <Step id="STEP_7B_CODE_REVIEW">
+      <Goal>Dispatch fresh-eyes code-review for bugs (lazy, after the audit passes).</Goal>
+      <Action>
+        Dispatch ONE code-review subagent (isolated): read `ai/directives/sdd-v2/code-review.directive.xml`;
+        task-id; round; artifacts = union of phase Handoff artifacts (the Round's diff); the relevant
+        contract anchors. It scopes to bugs only (correctness / edge / error-path / security), leaving drift and style out.
+        Verdict: `CLEAN` → STEP_8; `FINDINGS` with a `BLOCKER` → `H_CODE_REVIEW_BLOCKER` (pause for the
+        operator); `FINDINGS` non-blocking → carry into the summary as routed proposals, STEP_8.
+      </Action>
+    </Step>
+    <Step id="STEP_8_SUMMARY">
+      <Goal>Summarize for the operator.</Goal>
+      <Action>Aggregate phase + audit telemetry; present per `EXECUTE_SUMMARY_FORMAT`.</Action>
+    </Step>
+  </ExecutionPlan>
+
+  <HardForbidden>
+    - Workers read phase bodies / BDD / Verification / specs / rule files / code, each bounded by their manifest; the orchestrator does not.
+    - Workers write code, audit reports, and phase blocks; the orchestrator does not write production code, ever. It has exactly TWO narrow, non-overlapping write channels: (a) `AX_ENV_FIX_CHANNEL` — env/config artifacts only (`package.json` scripts, tool config, lockfiles), never `Target Files` code or `specs/**`, never without prior explicit operator approval of the exact diff; (b) STEP_7_RESOLVE Path B — administrative edits to ticket / Decision Log / spec waiver-labels, applying an audit finding directly per `AX_OWNER`. Neither channel extends to production code under a module's `Target Files`.
+    - Always run audit after all phases DONE, and code-review after the audit passes.
+    - Thread only typed Handoff payloads between subagents; keep their contexts separate.
+    - Cap audit attempts at 2; re-run only phases in `phases_to_fix`; drive a retry from audit FAIL only (a phase BLOCKED pauses, it does not reopen); run phases of the same task sequentially, one at a time.
+  </HardForbidden>
+
+  <ChatOutput>
+    <Contract id="ORCHESTRATOR_PROGRESS_FORMAT">
+      Subagents are black boxes; emit one progress line per state transition so the operator sees the run.
+
+      `[<bar>] <pct>% | <Task-ID> | <stage>`
+
+      Stages: `⏳ resolving + planning` · `🔧 phase <P<N>> (<kind>, <model>) executing` · `✅ phase <P<N>> done → next` · `✅ all phases done → 🔍 audit` · `✅ audit PASS`.
+      Retry path: `❌ audit FAIL → 🔄 re-run <phases> as fix` · `✅ re-run done → 🔍 audit R2`.
+      Pause path (NOT a failure — awaiting the operator): `✋ PAUSED — <unresolved blocker | phase BLOCKED>`; the operator marks resolution in the Execution Log, then re-runs.
+    </Contract>
+
+    <Contract id="EXECUTE_SUMMARY_FORMAT">
+      Final operator summary once audit settles. Plain, scannable:
+
+      📊 Task `<Task-ID>` — Execute + Audit
+      🔧 Round 1: `P1 (impl, sonnet) ✅` · `P2 (test, haiku) ✅` · …
+      🔍 Round 1 audit: `✅ PASS` | `❌ FAIL (🔴 N · 🟠 M)`
+      🔄 Round 2 (if any): `P2 (fix) ✅` · audit R2 `✅`
+      📊 Final: `✅ PASS` | `⚠️ PASS_WITH_ACKNOWLEDGED_RISKS` | `❌ FAIL`
+      ⏱️ wall total · 📍 files touched · ⚠️ problems encountered
+    </Contract>
+  </ChatOutput>
+</SddExecuteOrchestrator>

package/dist/ai/directives/sdd-v2/formats/audit-round.xml

@@ -0,0 +1,37 @@
+<Contract id="TICKET_AUDIT_ROUND_FORMAT">
+  Appended to the ticket file as a `## Audit Rounds` section (created on first reopen-triggering audit; subsequent audits append `### Audit Round N` entries). Same compact AI-to-AI inline grammar as `AUDIT_SESSION_SUMMARY_FORMAT` — the ticket carries the canonical audit record machines can re-parse later.
+
+  Shape inside the ticket:
+
+  ```markdown
+  ## Audit Rounds
+
+  ### Audit Round <N> — <YYYY-MM-DD>, after Execution Round <M>
+  ```
+  @audit task=<Task-ID> round=<N> after-exec-round=<M> triggered-reopen=<Round-M+1|none> status=<FAIL|PASS_RISK> counts=B<n>·M<n>·m<n>·I<n>
+  F-NN | sev=… | type=… | conf=… | loc=… | src=… | route=… | act=…
+  …
+  ~applied | <target> | <one-line description>
+  ```
+  ```
+
+  Concrete example (inside a ticket file):
+
+  ```markdown
+  ## Audit Rounds
+
+  ### Audit Round 1 — 2026-05-12, after Execution Round 1
+  ```
+  @audit task=TSK-04 round=1 after-exec-round=1 triggered-reopen=Round-2 status=FAIL counts=B1·M1·m0·I0
+  F-01 | sev=B | type=CLOSED_WORLD_DRIFT | conf=H | loc=src/payments/adapter.ts:42 | src=specs/backend/payments/payments.spec.md#2 | route=spec-edit | act=добавить `IdempotencyKey` в Entity Inventory
+  F-02 | sev=M | type=RULES_COMPLIANCE_VIOLATION | conf=H | loc=src/payments/adapter.ts:100 | src=ai/directives/coding/typescript-rules.xml#AX_STRICT_NULL | route=ticket-reopen | act=добавить null-guard на response.balanceTransaction
+  ~applied | specs/backend/payments/payments.spec.md2 | добавлен `IdempotencyKey` в Entity Inventory
+  ```
+  ```
+
+  Constraints:
+  - Append-only. Prior `### Audit Round` entries are immutable (mirrors Round-immutability in `phase-execution-protocol`).
+  - PASS audits without reopen are NOT written here — output stays ephemeral.
+  - `N` increments monotonically across the ticket's lifetime, independent of Execution Round numbers.
+  - The fenced code block inside each round is the same compact grammar as `AUDIT_SESSION_SUMMARY_FORMAT` — machines parse it without rewriting.
+</Contract>

package/dist/ai/directives/sdd-v2/formats/change-manifest.xml

@@ -0,0 +1,30 @@
+<Contract id="CHANGE_MANIFEST_FORMAT">
+  Temporary review-state section at the TOP of the spec (right after the intro block), removed whole by compress. Marker carries NO colon so the `sdd-extract` CLI extracts it.
+
+  ```markdown
+  <!--SECTION:CHANGE_MANIFEST-->
+  ## ⟢ Change Manifest — review-state · удаляется при compress
+
+  ТИП ИЗМЕНЕНИЯ: <refine | pivot | greenfield> · <короткое имя>
+  СВЯЗЬ С МИРОМ: <1–2 строки: какой внешний сценарий или потребность это закрывает>
+
+  ЧТО МЕНЯЕТСЯ:
+    ✚ <ACR>-REQ-N — <одна строка>
+    ✚ <ACR>-D-N   — <одна строка>
+    ~ <сущность / секция> — <что именно меняется>
+
+  НЕ ТРОНУТО (границы):
+    · <что осталось как было — явные границы изменения>
+
+  ФАЙЛЫ (только реальные файлы кода; спеки не перечислять):
+    · <path> — <что меняется в этом файле, 1–2 строки>
+
+  ЗАЧЕМ: <почему это нужно, 1–2 строки>
+
+  ЧЕК-ЛИСТ РЕВЬЮЕРА:
+    [ ] <конкретные вопросы, которые проверяет ревьюер>
+  <!--/SECTION:CHANGE_MANIFEST-->
+  ```
+
+  Rules: compress ALWAYS removes this section whole. «ЧТО МЕНЯЕТСЯ» lists the delta with the same `✚`/`~` marks used in the body and references the new IDs. «ФАЙЛЫ» = code files only — spec changes are already visible in the diff. «НЕ ТРОНУТО» = explicit boundaries the reviewer need not re-check. greenfield: keep the manifest but drop the per-line `✚`/`~` marks (everything is new) — «СВЯЗЬ С МИРОМ» carries the weight.
+</Contract>

package/dist/ai/directives/sdd-v2/formats/dbc-contracts.xml

@@ -0,0 +1,59 @@
+<Contract id="DBC_PORT_FORMAT">
+  Conditions are plain-language statements per `AX_CONTRACTS_TEXTUAL_AGNOSTIC` — one testable
+  statement per line, shared vocabulary, code syntax stays out (target-language code lives only
+  in Golden DX / usage examples). Optional fields marked «omit when none» are omitted, not
+  filled with placeholders.
+
+  ```markdown
+  #### Port: `<PortName>`
+  - **Purpose:** <1 sentence>
+  - **Consumers:** <internal: path · external: description>
+  - **Supporting Artifacts:** <links — omit when none>
+  - **Runtime Backing:** `not-implemented` | `simulation` | `real-runtime`
+  - **Verification Levels:** subset of `contract` | `unit` | `integration` | `e2e`
+  - **Deferred Runtime Scope:** None | <which declared behavior lacks real runtime>
+  - **Usage Waiver:** <omit when usage is >= 2 in production code> <why this entity exists despite few usages> [D-NNN — only when a Decision Log entry actually backs the reason]
+
+  **Contract (DbC):**
+  - Preconditions:
+    - <what must hold before the operation may be called>
+  - Postconditions:
+    - <what the operation guarantees on completion>
+  - Invariants:
+    - <what stays true across the entity's lifetime>
+  ```
+
+  **Usage Waiver** (`AX_USAGE_WAIVER_DISCIPLINE`, gennady yagni): a `<2` production-code usages
+  entity is a YAGNI finding unless its contract carries this field with a real reason — an empty
+  reason does not gate the finding. Cite a `D-NNN` only when the reason IS a Decision Log entry (a
+  genuine, non-obvious call — not "split for readability"); when cited, it must actually have a
+  heading in some Decision Log, or the citation does not gate the finding. The agent sets the
+  label, never the operator; omit the field entirely when usage already clears the threshold (no
+  placeholder text). Two forms:
+
+  - Internal entity: `- **Usage Waiver:** <reason>` (or `D-NNN — <reason>` when a decision backs it)
+  - Public API for an external consumer (does NOT disable the rule — it still needs the label):
+    `- **Usage Waiver (external: <named consumer>):** <reason>` (same `D-NNN` rule)
+</Contract>
+
+<Contract id="DBC_ADAPTER_FORMAT">
+  Same language rules as `DBC_PORT_FORMAT`: plain-language statements per
+  `AX_CONTRACTS_TEXTUAL_AGNOSTIC`, one per line; DbC conditions live on the Port — the Adapter
+  declares implementation facts (side effects, runtime backing).
+
+  ```markdown
+  #### Adapter: `<AdapterName>`
+  - **Implements:** `<PortName>` (`<path/to/port-file>`)
+  - **Purpose:** <1 sentence>
+  - **Supporting Artifacts:** <links — omit when none>
+  - **Runtime Backing:** `not-implemented` | `simulation` | `real-runtime`
+  - **Verification Levels:** subset of `contract` | `unit` | `integration` | `e2e`
+  - **Deferred Runtime Scope:** None | <which declared behavior lacks real runtime>
+  - **Usage Waiver:** <omit when usage is >= 2 in production code> <why this entity exists despite few usages> [D-NNN — only when a Decision Log entry actually backs the reason]
+
+  **Side Effects:**
+  - <one observable effect per line: external HTTP, IO, observability, mutation of shared state, …>
+  ```
+
+  Same `Usage Waiver` rule as `DBC_PORT_FORMAT` — see there for the two forms and the citation requirement.
+</Contract>