gennady 0.8.3 → 0.8.4-draft.2

package/ai/kit/templates/sdd-v2/reconcile.directive.hbs

@@ -0,0 +1,183 @@
+<SddReconcile keywords="reconcile, fix, sync-from-code, drift, spec-probe, bug-vs-spec-defect, problem-class, blast-radius, back-sync, sdd-reconcile" type="directive" ver="2.1">
+  <Mission>
+    Restore the spec ⟷ code ⟷ task triangle after it desynced, then verify. A separate door
+    (`/sdd-reconcile`). Two auto-detected modes converge on the same tail:
+    - **fix** — a finding / bug / review drove it: the spec is (presumed) right, the code is wrong.
+    - **from-code** — freeform code ran ahead of the spec: the code is the new reality, the spec is stale.
+
+    The heart is not the patch — it is the probe (`AX_PROBLEM_PROBES_SPEC`): is this a bug or a
+    spec-defect, what is the problem's class, what is the blast radius. Both modes end with the SAME
+    tail: back-sync specs / tasks, then verify. Patching the symptom alone is not SDD.
+
+    Input — findings / a bug / a review, OR "I changed code, formalize it". Output — code and/or spec
+    moved to agreement, tasks reopened / created, trackers synced, gates green.
+  </Mission>
+
+  <BeliefState>
+    {{> "axiom/process/ax-operator-language"}}
+
+    {{> "axiom/process/ax-tool-invocation"}}
+
+    {{> "axiom/process/ax-operator-dialogue-style"}}
+
+    {{> "axiom/process/ax-dialogue-discipline"}}
+
+    {{> "axiom/process/ax-operator-safeguard"}}
+
+    {{> "axiom/process/ax-problem-probes-spec"}}
+
+    {{> "axiom/truth/ax-spec-is-sole-source"}}
+
+    {{> "axiom/scaffold/ax-mode-auto-detect-or-halt"}}
+
+    {{> "axiom/process/ax-task-resolution"}}
+
+    {{> "axiom/process/ax-fix-classification"}}
+
+    {{> "axiom/process/ax-grouping-reduces-noise"}}
+
+    {{> "axiom/audit/ax-finding-routing"}}
+
+    {{> "axiom/truth/ax-reuse-first"}}
+
+    {{> "axiom/spec/ax-pivot-requires-supersession"}}
+
+    {{> "axiom/process/ax-operator-agreement"}}
+
+    {{> "axiom/process/ax-execution-order"}}
+
+    {{> "axiom/process/ax-dispatch-via-batch"}}
+
+    {{> "axiom/process/ax-handoff-typed"}}
+
+    {{> "axiom/process/ax-reopen-format"}}
+
+    {{> "axiom/process/ax-verify-at-end"}}
+  </BeliefState>
+
+  <HaltConditions>
+    | 🛑 ID | Trigger |
+    |---|---|
+    | `H_NO_INPUT` | Neither findings / bug nor a code change to reconcile |
+    | `H_AMBIGUOUS_MODE` | Cannot tell fix from from-code — ask the operator |
+    | `H_OPERATOR_REJECT` | Operator rejected the reconcile plan |
+    | `H_TRIVIALITY_UNCONFIRMED` | Fix looks trivial but the probe leaves doubt, OR no critic was dispatched (a self-probe does not confirm triviality) — ask the operator: short-circuit or full path |
+    | `H_VERIFICATION_FAIL` | Gates still fail after the reconcile |
+  </HaltConditions>
+
+  <ExecutionPlan>
+    <Step id="STEP_0_INTAKE">
+      <Goal>Detect the mode.</Goal>
+      <Action>
+        Findings / bug / review present → `fix`. Code already changed / "formalize what I coded" / drift
+        → `from-code` (`AX_MODE_AUTO_DETECT_OR_HALT`; ambiguous → `H_AMBIGUOUS_MODE`).
+      </Action>
+    </Step>
+    <Step id="STEP_1_PICTURE">
+      <Goal>Map the affected area. (mechanical → tools)</Goal>
+      <Action>
+        Intent-search the specs for the area in play + read the git diff; map which specs / tasks own it
+        (`orient` for the entity / contract surface, `sdd-check` for the link / tracker state). This
+        is the bounded read — not the whole repo.
+      </Action>
+    </Step>
+    <Step id="STEP_2_PROBE">
+      <Goal>Probe the spec against the problem — the critical step (`AX_PROBLEM_PROBES_SPEC`).</Goal>
+      <Action>
+        Dispatch the critic on the affected spec, seeded with the problem, to judge: **bug or spec-defect**
+        (code violates a right spec, or the spec was wrong); **the class** (where
+        else the same class occurs, via `orient` over the closed-world); **the blast radius** (what
+        else the diff touches). MUST cover the full problem class and blast radius — the reported symptom is only the entry point. The critic MUST be an actually dispatched subagent — an
+        orchestrator self-probe never satisfies this step and never confirms triviality, no matter how
+        small the fix looks (mirrors `AX_FIX_CLASSIFICATION`: triviality is confirmed by the probe, never
+        by self-assessment). No dispatched verdict → `H_TRIVIALITY_UNCONFIRMED`. The probe verdict feeds STEP_2B.
+      </Action>
+    </Step>
+    <Step id="STEP_2B_CLASSIFY">
+      <Goal>Resolve ownership, classify every finding — BEFORE any edit (`AX_FIX_CLASSIFICATION`).</Goal>
+      <Action>
+        Build the ownership map first (`AX_TASK_RESOLUTION`): per finding located in a `.ts` / `.spec.md`
+        file — read the file header (first lines before `import` / first `#`), extract
+        `@tasks: <ACR>-<slug>[, ...]`, build file → [Task-IDs]. Header absent → classify anyway (the fix
+        IS adding the header), note "no task" for the plan.
+
+        Classify each finding into an action category:
+        - **direct-fix** — global / non-code artifact: tracker desync, execution-log placeholder, a
+          missing header with no other findings. Edit the file directly, verify.
+        - **spec-update** — spec gap: missing inventory entity, DbC contract gap, Decision Log gap,
+          stale pivot artifact. Edit the spec; a spec change that invalidates code escalates to task-reopen.
+        - **task-reopen** — ANY finding in a code file carrying `@tasks:`: bug, contract violation,
+          missing test, BDD mismatch, review finding. Reopen the owning task per `AX_REOPEN_FORMAT`;
+          pair every code-fix phase with a `test` phase (regression); multiple findings of one task go
+          into a single reopen Round.
+
+        <LogicSwitch on="fix class — confirmed by the dispatched critic's verdict from STEP_2, never by self-assessment (self-probe is void)">
+        - WHEN the class is trivial: a single site, blast radius confirmed empty by the dispatched critic's verdict, contracts / specs untouched -> patch the code TOGETHER WITH a regression test covering the fixed case in the same run (a task-reopen always pairs code-fix with a `test` phase — the trivial branch is not exempt from that pairing just because it skips the Round), back-sync the spec (`sdd-sync`), run the light gate (typecheck + tests of the touched files, including the new regression test).
+          - WHEN the light gate is green -> present `FIX_SUMMARY_FORMAT`. DONE — the full tail (STEP_3–7, epic audit + code-review) stays skipped.
+          - WHEN the light gate is red AND the failure reproduces on the pre-change baseline AND lies outside the blast radius confirmed by the critic -> record it in `FIX_SUMMARY_FORMAT` as pre-existing (not caused by this patch), propose a separate task to the operator for it, and do NOT head the summary with "✅ complete" — the gate is still red. DONE.
+          - OTHERWISE (the failure is caused by or overlaps the patch/blast radius) -> `H_VERIFICATION_FAIL`.
+        - WHEN triviality is plausible but the probe leaves doubt -> `H_TRIVIALITY_UNCONFIRMED`
+        - DEFAULT -> STEP_3_PLAN, the full path
+        </LogicSwitch>
+      </Action>
+    </Step>
+    <Step id="STEP_3_PLAN">
+      <Goal>Plan what moves.</Goal>
+      <Action>
+        From the probe + STEP_2B categories, decide per item what moves: code → spec (fix the code via
+        execution) or spec → code (`AX_PIVOT_REQUIRES_SUPERSESSION` + cascade downstream) or both;
+        reopen / create the affected tasks (`AX_REOPEN_FORMAT`), including the class siblings; group
+        scattered edits sharing one intent into a single task (`AX_GROUPING_REDUCES_NOISE`) — per-finding
+        tasks are noise; reconcile any new entity via `orient` (`AX_REUSE_FIRST`), filling the
+        "Reuse rationale" slot for anything that lands on JUSTIFY. If STEP_2B found a file with a
+        missing header, the plan MUST carry an explicit line to add it — the fix IS adding the header;
+        this is not deferred to `sdd-sync`, which does not write headers. Present the plan
+        (`PLAN_TABLE_FORMAT`).
+      </Action>
+    </Step>
+    <Step id="STEP_4_AGREE">
+      <Goal>Operator agreement (`AX_OPERATOR_AGREEMENT`).</Goal>
+      <Action>Ask via `QUESTION_FORMAT`; warn about the class / blast the operator may not have seen (`AX_OPERATOR_SAFEGUARD`). Rejected → `H_OPERATOR_REJECT`. STOP.</Action>
+    </Step>
+    <Step id="STEP_5_APPLY">
+      <Goal>Apply the changes.</Goal>
+      <Action>
+        Apply spec edits (defect / from-code); reopen / create tasks per the STEP_2B ownership map
+        (`AX_TASK_RESOLUTION`); dispatch the reopened tasks through execute as a BATCH with per-task
+        audit skipped (`AX_DISPATCH_VIA_BATCH`; the dispatched workers stay spec-bound per
+        `AX_SPEC_IS_SOLE_SOURCE`) — one reconcile-level verify runs at STEP_7 instead
+        (`AX_EXECUTION_ORDER`, `AX_HANDOFF_TYPED`, route per `AX_FINDING_ROUTING`).
+      </Action>
+    </Step>
+    <Step id="STEP_6_SYNC">
+      <Goal>Back-sync — mandatory in BOTH modes.</Goal>
+      <Action>`sdd-sync` brings specs / tasks / trackers into agreement with the final code. This tail is the same whether we entered as fix or from-code.</Action>
+    </Step>
+    <Step id="STEP_7_VERIFY">
+      <Goal>Verify mechanically AND semantically (`AX_VERIFY_AT_END`).</Goal>
+      <Action>
+        This full tail applies to the DEFAULT (non-trivial) path only — the trivial fix class already
+        exited at STEP_2B with its own light gate (typecheck + tests of the touched files). Reaching
+        STEP_7 means the path is non-trivial: run this full tail once here, never as an extra "to be
+        safe" pass layered on top of an already-closed trivial path.
+
+        `sdd-check` + `sdd-verify --profile full` must pass (else `H_VERIFICATION_FAIL`). Then — because
+        per-task audit was skipped in the batch (`AX_DISPATCH_VIA_BATCH`) — restore the safety net ONCE at
+        the reconcile level: dispatch a fresh-eyes epic audit
+        (`READ_AND_USE_DIRECTIVE("ai/directives/sdd-v2/audit.directive.xml")`, per-epic — drift code↔spec over
+        the reconciled set) and a code-review
+        (`READ_AND_USE_DIRECTIVE("ai/directives/sdd-v2/code-review.directive.xml")` — bugs in the reconciled
+        diff). A `BLOCKER` from either MUST pause and surface to the operator. Present the reconcile summary
+        (`FIX_SUMMARY_FORMAT`).
+      </Action>
+    </Step>
+  </ExecutionPlan>
+
+  <ChatOutput>
+    {{> "contract/process/question-format"}}
+
+    {{> "contract/process/plan-table-format"}}
+
+    {{> "contract/process/fix-summary-format"}}
+  </ChatOutput>
+</SddReconcile>

package/ai/kit/templates/sdd-v2/recover-from-code.directive.hbs

@@ -0,0 +1,153 @@
+<SddRecoverFromCode keywords="recover, from-code, restore-spec, path, brownfield, existing-scope, scope-fit, module-split, incremental, lazy, inventory-reverse, sdd-recover-from-code" type="directive" ver="1.1">
+  <Mission>
+    Recover a spec for ONE named path — a folder or a file the operator points at — from the code
+    that already lives there plus whatever sits next to it (README, ADR, old docs, tests). Entered
+    from the router when the portal is LIVE and the operator both asks to recover / recreate a spec
+    from code AND names a concrete path; the router-core beliefs it relies on are declared in
+    `BeliefState deps` (inherited, not repeated).
+
+    Distinct from the two neighboring recovery flows:
+    - `discover-from-code` recovers the WHOLE project's general picture and only enters from `root`
+      when the portal is absent. This flow is the opposite scale: one path, portal already live.
+    - `reconcile` mode=`from-code` formalizes ONE change against a spec that already exists. This
+      flow has no existing spec for the path yet — that is exactly the gap it fills.
+
+    The agent does the reading itself — `bash` / `grep` / `Read` over the path and its neighbors —
+    there is no dedicated recovery tool and none is being added (`AX_NO_NEW_TOOL`). It reuses the
+    existing branches to write anything: `scope` for the scope spec, `module` for module specs,
+    `scaffold` only if the operator wants alignment tasks. This flow owns none of that writing logic.
+
+    Input — a path (folder or file) + the operator's intent to recover its spec. Output — the path
+    lands in a confirmed scope (existing or new) with a confirmed module split, and the module specs
+    for it pass the same closed-world reverse check any hand-written module spec would.
+  </Mission>
+
+  <BeliefState deps="AX_OPERATOR_LANGUAGE, AX_TOOL_INVOCATION, AX_OPERATOR_DIALOGUE_STYLE, AX_DIALOGUE_DISCIPLINE, AX_OPERATOR_SAFEGUARD, AX_NO_PROCESS_NARRATION, AX_OPERATOR_OUTPUT_LIVE_TEXT, AX_STATELESS_ARTIFACT, AX_SCALE_PROPORTIONAL_DEPTH, AX_READER_WITHOUT_SESSION_CONTEXT, AX_DECISION_LOG_NON_OBVIOUS">
+    <Axiom id="AX_NO_NEW_TOOL">
+      This flow adds no CLI command and no shared-code helper. Surveying a path — what the code does,
+      who imports whom, which docs / tests sit beside it — is done live by the agent through `bash`
+      (`grep`, `find`, `ls`) and `Read`, the same way any engineer would open an unfamiliar folder.
+      Building a dedicated recovery tool here trades a rare, judgment-heavy task for permanent
+      maintenance weight — the operator has weighed that trade and rejected it. The ONLY mechanical
+      gate in this flow is the one that already exists: `gennady lint --spec=<module-spec>
+      --inventory-reverse <module-dir>` (`AX_REVERSE_INVENTORY_GATE`).
+    </Axiom>
+
+    <Axiom id="AX_EVIDENCE_HYGIENE">
+      Separate Facts / Assumptions / Hypotheses when presenting the survey and the proposal.
+      - **Facts** — directly read from the path: file layout, import edges, an existing test, a line
+        in a README that states purpose.
+      - **Assumptions** — a reasonable working read of code without a written purpose statement; mark
+        explicitly, invite correction.
+      - **Hypotheses** — guesses about intent that only the operator can confirm (why this exists,
+        who else depends on it).
+
+      Conflating the three lets a guess get written into the spec as if it were read from the code —
+      exactly the drift `--inventory-reverse` (`AX_REVERSE_INVENTORY_GATE`) later catches on the
+      inventory side, but the vision / purpose side has no mechanical check, so hygiene here is the
+      only guard.
+    </Axiom>
+
+    <Axiom id="AX_DOSED_SURVEY">
+      Read the path incrementally, cheapest signal first, and STOP once there is enough to propose a
+      scope fit + a module split — do not walk every file before saying anything. Cheap-to-expensive
+      order: directory listing and file names → package / workspace manifest (if any) → README / ADR
+      / doc files sitting beside the path → import graph of the path's own files (who it imports, who
+      imports it) → test files (what they exercise, which is often the best behavioral evidence) →
+      only then, if still unclear, a fuller read of the source. Present the coarse picture before
+      going deeper; the operator can always ask for more before confirming.
+    </Axiom>
+
+    <Axiom id="AX_REVERSE_INVENTORY_GATE">
+      A recovered module spec's Entity Inventory MUST be checked against the real code with
+      `gennady lint --spec=<module-spec> --inventory-reverse <module-dir>` before the flow closes.
+      This is what separates recovering a spec from paraphrasing the code into prose: an inventory
+      entry with no matching export, or an export with no inventory entry, is a finding to fix before
+      closing — never a note for later.
+    </Axiom>
+
+    {{> "axiom/process/ax-artifact-style-self-check"}}
+  </BeliefState>
+
+  <KernelGrammar>
+    {{> "definition/process/def-read-and-use-directive"}}
+  </KernelGrammar>
+
+  <ChatProtocol>
+    {{> "contract/process/halt-format"}}
+  </ChatProtocol>
+
+  <HaltConditions>
+    | 🛑 ID | Trigger |
+    |---|---|
+    | `H_PATH_NOT_FOUND` | The named path does not exist in the repo — ask the operator for the correct one |
+    | `H_PATH_EMPTY` | The path exists but holds no source (empty dir, docs only) — nothing to recover FROM code |
+    | `H_NO_PORTAL` | `specs/README.md` is absent — this is project-scale recovery, not one-path recovery; redirect to `ai/directives/sdd-v2/root.directive.xml` (which enters `discover-from-code` on an empty portal) |
+    | `H_SCOPE_NOT_CONFIRMED` | Operator rejects or leaves open the proposed scope fit / scope-type / module split — stop; nothing is written |
+  </HaltConditions>
+
+  <ExecutionPlan>
+    <Step id="STEP_0_INTAKE">
+      <Goal>Validate the path and the portal before spending any read.</Goal>
+      <Action>
+        Confirm the named path exists and contains source (`H_PATH_NOT_FOUND` / `H_PATH_EMPTY`
+        otherwise). Confirm the portal is live (`specs/README.md` present — `H_NO_PORTAL` otherwise,
+        which hands off to project-scale recovery instead). Both gates are cheap and mechanical; clear
+        them before STEP_1.
+      </Action>
+    </Step>
+    <Step id="STEP_1_SURVEY">
+      <Goal>Read the path and its neighbors — dosed, not exhaustive (`AX_DOSED_SURVEY`).</Goal>
+      <Action>
+        Walk the cheap-to-expensive order from `AX_DOSED_SURVEY`: layout → manifest → README / ADR /
+        docs beside the path → import edges in and out → tests → deeper source read only if still
+        unclear. Keep Facts / Assumptions / Hypotheses apart throughout (`AX_EVIDENCE_HYGIENE`). Also
+        read the current portal's Scope Graph + Scopes table (`sdd-state`) — the survey needs the
+        existing scopes to judge fit against.
+      </Action>
+    </Step>
+    <Step id="STEP_2_PROPOSE">
+      <Goal>Propose scope fit, scope-type, and a module split; let the operator steer.</Goal>
+      <Action>
+        Present the survey plain Russian, coarse first (`AX_EVIDENCE_HYGIENE` tri-split, confidence
+        marked per item): what the path does, which existing scope it fits OR that a new scope is
+        needed, the scope-type if new, and a first-cut module split. Where the fit or the split is a
+        genuine fork (new scope vs. folding into an existing one; where the module boundary falls) —
+        run it through `READ_AND_USE_DIRECTIVE("ai/directives/sdd-v2/interview-protocol.directive.xml")`
+        so each fork gets its own question, one at a time, rather than a single multi-part ask.
+        Outright rejection or an unresolved fork → `H_SCOPE_NOT_CONFIRMED`. STOP.
+      </Action>
+    </Step>
+    <Step id="STEP_3_RECOVER">
+      <Goal>Write the spec by reusing the existing authoring branches — no bespoke writing logic here.</Goal>
+      <Action>
+        Before handing off, run the self-check pass per `AX_ARTIFACT_STYLE_SELF_CHECK` on any prose
+        this flow writes itself (the survey, the proposal); each branch called below carries its own
+        copy of the same gate for the artifact it writes. On confirmation, hand off to the branches
+        that already know how to write a spec, in dependency order:
+        - `READ_AND_USE_DIRECTIVE("ai/directives/sdd-v2/scope.directive.xml")` — create the new scope
+          spec, or extend the existing one the path was folded into.
+        - `READ_AND_USE_DIRECTIVE("ai/directives/sdd-v2/module.directive.xml")` — write the module
+          spec(s) for the confirmed split, entity inventory sourced from what STEP_1 actually read.
+        - Optionally, if the operator wants the code brought in line with anything the recovery
+          surfaced (missing tests, a contract gap): `READ_AND_USE_DIRECTIVE("ai/directives/sdd-v2/scaffold.directive.xml")`.
+        This flow contributes none of the spec-writing rules — it only routes the confirmed picture
+        into the branch that owns each artifact.
+      </Action>
+    </Step>
+    <Step id="STEP_4_VERIFY">
+      <Goal>Prove the recovered spec matches the real code, not a paraphrase of it.</Goal>
+      <Action>
+        For every module spec produced: `gennady lint --spec=<module-spec> --inventory-reverse
+        <module-dir>` clean (`AX_REVERSE_INVENTORY_GATE`) — fix the inventory or the spec, not the
+        code, when it disagrees with reality. Then `sdd-check --all .` clean over the whole tree.
+        Return control.
+      </Action>
+    </Step>
+  </ExecutionPlan>
+
+  <ChatOutput>
+    Service line — dim, internal, never narrated (`AX_NO_PROCESS_NARRATION`):
+    `🧭 RFC_R<N> · path=<path> · scope=<scope-or-new> · step=<id>`.
+  </ChatOutput>
+</SddRecoverFromCode>

package/ai/kit/templates/sdd-v2/review-lifecycle.directive.hbs

@@ -0,0 +1,70 @@
+<SddReviewLifecycle keywords="review-lifecycle, master, review-state, compress, publish, MR, external-review, git, gh, sdd-review-lifecycle" type="directive" ver="2.2">
+  <Mission>
+    Drive a spec from review-state to merged master through EXTERNAL review. Loaded lazily by an authoring
+    flow (scope / infra / interface / module) AFTER it has written the spec in review-state. I do NOT author
+    spec content — the authoring flow did; I run the internal critic, publish the change for review, wait for
+    the operator's verdict, and ONLY on approval compress + merge.
+
+    Git is native `git` + `gh` via bash — no separate VCS client. Per `AX_SPEC_LIFECYCLE`: compress fires
+    only on external-review approval («no comments»), never on internal CLEAN, never on a timer.
+  </Mission>
+
+  <BeliefState deps="AX_OPERATOR_LANGUAGE, AX_OPERATOR_DIALOGUE_STYLE">
+    {{> "axiom/spec/ax-spec-lifecycle"}}
+
+    {{> "axiom/process/ax-permitted-bash-commands"}}
+  </BeliefState>
+
+  <HaltConditions>
+    | 🛑 ID | Trigger |
+    |---|---|
+    | `H_AWAITING_EXTERNAL_REVIEW` | Change published — session waits for the operator's verdict (feedback or «no comments»). A PAUSE, not a failure. |
+    | `H_DIRTY_TREE_NOT_THIS_CHANGE` | The git working tree carries changes unrelated to this spec change — operator resolves before publish |
+  </HaltConditions>
+
+  <ExecutionPlan>
+    <Step id="STEP_1_INTERNAL_CRITIC">
+      <Goal>Internal review until CLEAN — necessary, not sufficient.</Goal>
+      <Action>
+        Dispatch the critic (isolated), on a worker-tier model (`AX_CRITIC_MODEL_TIER`), on the review-state spec — `READ_AND_USE_DIRECTIVE("ai/directives/sdd-v2/critic.directive.xml")`
+        (product / design lenses: completeness · implementation-autonomy · understanding · product-value). Apply
+        its findings in place (still review-state — manifest + `✚`/`~`); loop until CLEAN.
+      </Action>
+    </Step>
+    <Step id="STEP_2_PUBLISH">
+      <Goal>Publish the change for external review.</Goal>
+      <Action>
+        Verify the working tree carries ONLY this spec change (`git status`; else `H_DIRTY_TREE_NOT_THIS_CHANGE`).
+        Commit the review-state spec on the working branch (`git add <spec>` → `git commit`), `git push`, open the
+        MR/PR (`gh pr create`) and capture its link — all via bash within `AX_PERMITTED_BASH_COMMANDS`. Present the MR link to the operator — the diff reads as a PR
+        (Change Manifest + `✚`/`~` marks make the delta legible).
+      </Action>
+    </Step>
+    <Step id="STEP_3_AWAIT">
+      <Goal>Wait for the external verdict.</Goal>
+      <Action>`H_AWAITING_EXTERNAL_REVIEW` — pause. The operator reviews the MR and returns with feedback or «no comments».</Action>
+    </Step>
+    <Step id="STEP_4_ON_RESUME">
+      <Goal>Branch on the verdict.</Goal>
+      <Action>
+        Feedback → apply edits in place (update the manifest + marks), `git push`, back to STEP_1 (re-critic →
+        re-publish → await again). «no comments» (approved) → STEP_5.
+      </Action>
+    </Step>
+    <Step id="STEP_5_COMPRESS">
+      <Goal>Compress to master and merge.</Goal>
+      <Action>
+        Compress per `AX_SPEC_LIFECYCLE`: remove the `CHANGE_MANIFEST` whole, strip the `✚`/`~` marks (lines stay),
+        resolve any ID collisions in one commit, `pivot` → mark superseded decisions. `git commit` → `gh pr merge`.
+        Then `sdd-check` on the spec MUST be clean of `SDD_REVIEW_STATE_STUCK` / `SDD_REVIEW_INCONSISTENT` (no
+        manifest or marks remain). The spec is now master; return to the authoring flow's downstream handoff.
+      </Action>
+    </Step>
+  </ExecutionPlan>
+
+  <HardForbidden>
+    - Compressing on internal-critic CLEAN — compress waits for external approval (`AX_SPEC_LIFECYCLE`).
+    - Authoring spec content — the loading flow owns that; I only run critic / publish / compress.
+    - Merging with the `CHANGE_MANIFEST` or `✚`/`~` marks still present — that is stuck review-state.
+  </HardForbidden>
+</SddReviewLifecycle>

package/ai/kit/templates/sdd-v2/root.directive.hbs

@@ -0,0 +1,133 @@
+<SddRoot keywords="root, portal, vision, scope-graph, idempotent, project-setup, infra-bootstrap" type="directive" ver="2.0">
+  <Mission>
+    Owner of `specs/README.md` — the Project Portal: Vision + Scope Graph + Scopes table.
+    Idempotent: runs any number of times to refine vision, extend the graph, or bootstrap the
+    first infra-base spec. Loaded lazily by the router; the router-core beliefs it relies on are
+    declared in `BeliefState deps` (inherited, not repeated).
+
+    Input — operator intent at project level. Output:
+    - `specs/README.md` with Vision + Scope Graph + Scopes table.
+    - Optional minimal `specs/infra-base/infra-base.spec.md` when the operator declared tooling.
+
+    When the portal is absent, root first probes the repo (`sdd-state --probe`): a greenfield repo (no
+    code) is initialized here; a repo that already holds code is handed to the from-code recovery branch
+    (`discover-from-code`) — root never invents a vision over code that already exists.
+
+    Out of scope: design of any individual scope (its vision, architecture, requirements,
+    modules) — that is the scope branch. Root writes only the project-level map.
+  </Mission>
+
+  <BeliefState deps="AX_OPERATOR_LANGUAGE, AX_TOOL_INVOCATION, AX_OPERATOR_DIALOGUE_STYLE, AX_DIALOGUE_DISCIPLINE, AX_OPERATOR_SAFEGUARD, AX_NO_PROCESS_NARRATION, AX_STATELESS_ARTIFACT">
+    {{> "axiom/spec/ax-portal-primary-owner"}}
+
+    {{> "axiom/scaffold/ax-idempotent-modes"}}
+
+    {{> "axiom/spec/ax-scope-graph-discipline"}}
+
+    {{> "axiom/infra/ax-infra-base-bootstrap"}}
+
+    {{> "axiom/spec/ax-scope-table-format"}}
+
+    {{> "axiom/spec/ax-vision-only-for-application"}}
+
+    {{> "axiom/process/ax-close-with-integrity-check"}}
+  </BeliefState>
+
+  <HaltConditions>
+    | 🛑 ID | Trigger |
+    |---|---|
+    | `H_NO_INTENT` | Operator invoked the root flow with empty intake against an existing Portal |
+    | `H_CYCLE_IN_GRAPH` | Scope Graph contains a cycle (detected by `sdd-check`) |
+    | `H_SCOPE_VS_MODULE_AMBIGUITY` | Operator labels as «scope» something that resembles a module |
+    | `H_OPERATOR_REJECT` | Operator rejected Vision, Scope Graph, or the final Portal |
+  </HaltConditions>
+
+  <ExecutionPlan>
+    <Step id="STEP_0_INTAKE">
+      <Goal>Determine today's change set from state.</Goal>
+      <Action>
+        State from the router (`sdd-state`) already reports whether `specs/README.md` exists.
+        - Absent → no portal yet: run `sdd-state --probe` to learn whether the repo is greenfield or
+          already holds code (`AX_TOOL_INVOCATION`; probe only now that it is needed — not at flow start).
+          - `CODE=absent` (empty / only package.json) → **greenfield init**. Ask (Russian): «Как называется
+            проект? Опиши в одном предложении его vision и первые scope'ы (infra-base, backend, web — на
+            черновую).»
+          - `CODE=present` → **from-code recovery** — do NOT invent a vision over existing code:
+            `READ_AND_USE_DIRECTIVE("ai/directives/sdd-v2/discover-from-code.directive.xml")`.
+        - Present → empty intake → `H_NO_INTENT`; otherwise classify the change:
+          vision / add scope / update graph / infra bootstrap. Root has no hard modes — create when
+          absent, propose intake-derived updates when present, per `AX_IDEMPOTENT_MODES`.
+      </Action>
+    </Step>
+    <Step id="STEP_1_VISION">
+      <Goal>Lock the project-level Vision.</Goal>
+      <Action>
+        No product / library scope → skip Vision (`AX_VISION_ONLY_FOR_APPLICATION`). Else propose
+        a one-sentence Vision: what we build and which problem it solves. Approval Check. STOP.
+      </Action>
+    </Step>
+    <Step id="STEP_2_SCOPE_GRAPH">
+      <Goal>Place each scope by its relationships first, then its edges.</Goal>
+      <Action>
+        For each scope the relationship question comes FIRST (`AX_OPERATOR_SAFEGUARD`): who will depend
+        on it, what it depends on, and whether it is cross-cutting (used by ≥2 scopes). Probe narrow
+        framing — «авторизация только для web? а API / будущие клиенты?». The answer drives three things:
+        the «scope vs module» test (a thing used inside one scope may be a module, not a scope →
+        `H_SCOPE_VS_MODULE_AMBIGUITY`); the `depends-on` edges; and, when it is cross-cutting, a note that
+        cross-scope scenarios or an interface scope may be needed. If the change REMOVES or RENAMES a
+        scope, first surface what it orphans — its `specs/<scope>/…` spec, tasks, and inbound references
+        — and resolve with the operator (move / delete / repoint); never silently leave orphans. Then
+        propose scope-type with rationale and render the Mermaid `graph TD` — edge semantics
+        (A→B = A depends-on B), acyclicity, and scope-type constraints per
+        `AX_SCOPE_GRAPH_DISCIPLINE` (a cycle → `H_CYCLE_IN_GRAPH`). Approval Check. STOP.
+      </Action>
+    </Step>
+    <Step id="STEP_3_INFRA_BOOTSTRAP">
+      <Goal>Materialize the minimal infra-base spec if tooling was declared.</Goal>
+      <Action>
+        No tooling declared → skip. Else, per `AX_INFRA_BASE_BOOTSTRAP`,
+        `READ_AND_USE_DIRECTIVE("ai/directives/sdd-v2/formats/infra-base-minimal-spec.xml")`
+        and write `specs/infra-base/infra-base.spec.md` to that format (scope-type infrastructure,
+        one-sentence Vision, Tool Stack table, note pointing to `discovery infra-base` for the full
+        Decision Log — the bootstrap only locks the tool choice, the full `infra` flow comes later).
+        Approval Check. STOP.
+      </Action>
+    </Step>
+    <Step id="STEP_4_PORTAL_WRITE">
+      <Goal>Write / update `specs/README.md`.</Goal>
+      <Action>
+        When `specs/README.md` does not exist yet, create its skeleton via `sdd-new portal` first —
+        it never overwrites and prints the section manifest (which sections are REQUIRED and what to
+        fill); when it already exists, edit it in place, skip `sdd-new`. Content guidance per
+        `READ_AND_USE_DIRECTIVE("ai/directives/sdd-v2/formats/portal-structure.xml")` and assemble the
+        Portal to that format. Scope status (✅ / 🚧) comes from `sdd-state` (presence of
+        `specs/<scope>/<scope>.spec.md`), not a manual stat — rows per `AX_SCOPE_TABLE_FORMAT`.
+        Reconcile any placeholder rows left by the scope flow into full rows — root is the primary
+        owner of `specs/README.md` and the only flow that rewrites it (`AX_PORTAL_PRIMARY_OWNER`).
+        Write the file. Then run `sdd-check --all .` to verify portal integrity —
+        graph acyclicity, graph↔table↔spec coherence, no orphan specs or dangling scope references — and
+        resolve any finding before finishing, per `AX_CLOSE_WITH_INTEGRITY_CHECK`. Approval Check. STOP.
+      </Action>
+    </Step>
+  </ExecutionPlan>
+
+  <ChatOutput>
+    Service line — dim, internal, never narrated (per `AX_NO_PROCESS_NARRATION`):
+    `🗺️ ROOT_R<N> · <project> · <mode> · conf=<LOW|MEDIUM|HIGH>`. Breadcrumb milestones for this
+    flow (per `BREADCRUMB_FORMAT`): Vision · Scope Graph · Infra · Portal.
+
+    {{> "contract/process/message-layout"}}
+
+    {{> "contract/process/breadcrumb-format"}}
+
+    {{> "contract/process/understanding-block-format"}}
+
+    {{> "contract/process/side-dive-format"}}
+
+    {{> "contract/process/flow-diagram-when"}}
+
+    {{> "axiom/process/ax-progressive-disclosure"}}
+  </ChatOutput>
+
+  <!-- Artifact formats (portal-structure, infra-base-minimal-spec) load lazily at their write step — see ExecutionPlan. -->
+</SddRoot>