yadflow 1.0.1

package/skills/sdlc-author-architecture/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: sdlc-author-architecture
+description: 'Front state 3 of the gated SDLC. With the architect, author architecture.md and the locked contract.md (the shared cross-repo surface), then hash-lock the contract surface into .sdlc/contract-lock.json. Reads epic.md as input. Never auto-advances — hands off to the team review gate (which escalates on the contract risk tag). Use when the user says "author the architecture" or after the epic gate passes.'
+---
+
+# SDLC — Author Architecture + Contract (front state 3)
+
+**Goal:** Produce a human-authored, AI-assisted `architecture.md` and the **locked** `contract.md`
+for an approved epic, then record a hash-lock of the contract surface so a later contract-check can
+detect drift. This is a **front state**: human-authored with AI assist, **never auto-advances**.
+When both artifacts are drafted, control passes to `sdlc-review-gate`, which **escalates** this review
+by default (the architecture step carries `risk_tags: ["contract"]`).
+
+This skill enforces the build plan's core rules: all state lives in files; the contract holds only the
+shared cross-repo surface at charter altitude; front steps stay locked to `human_approve`.
+
+## Conventions
+
+- `{project-root}` resolves from the project working directory.
+- Artifacts live under `{project-root}/epics/EP-<slug>/` (build plan §6).
+- Speak in the configured `communication_language`; write documents in `document_output_language`.
+
+## On Activation
+
+### Step 1 — Resolve the epic and check the gate
+Resolve the `EP-<slug>` (ask if not provided). Read `{project-root}/epics/EP-<slug>/.sdlc/state.json`.
+Only proceed when `currentStep == "architecture"` and that step's `status == "in_progress"` (the epic
+review must already have passed). If not, stop and point the user at `sdlc-status` / the gate.
+
+### Step 1b — Open the authoring branch
+Open the architecture authoring branch `architecture/EP-<slug>` per the shared procedure
+(`../sdlc-author-epic/references/state-schema.md` → "Authoring branches"): git-safe (skip with a note
+if `{project-root}` is not a git work tree), check out the branch if it exists, else create it from the
+hub's default branch. Author and commit `architecture.md` / `contract.md` / `contract-lock.json` on it.
+This is **distinct** from the bridge's `review/…` branch.
+
+### Step 2 — Read the epic as input context
+Read `epic.md`. Note `repos` (the touched domains), the goal, scope, and acceptance signals. The
+architecture must serve every repo listed in `repos`.
+
+### Step 2b — Load existing-code context (make the brain code-aware)
+Read the registry `{project-root}/.sdlc/repos.json` (`config.yaml` `code_context`). For **each repo in
+`epic.repos`**, load the lightweight code-map `{project-root}/.sdlc/code-context/<repo>/code-map.md`
+**and**, because this phase locks the contract, the full pack `.../pack.md` when you need depth on the
+existing **endpoints, events, and data models**. This is the context that stops the architecture from
+re-defining or contradicting what is already built. (`pack.md` is **not committed** — if it is absent
+locally, regenerate it with `sdlc repo refresh <repo>`; the committed `code-map.md`
+is always present.)
+
+- **Greenfield-safe:** if `repos.json` is absent/empty, note "no repos connected" and proceed — design
+  from scratch as before.
+- **Staleness:** if a repo's current HEAD ≠ its registry `syncedHead`, warn and suggest
+  `sdlc repo refresh <repo>` (a human decision — flag and stop, never auto-refresh); stamp
+  `code-context: stale` in the frontmatter.
+- **Traceability:** record the loaded maps in the `code-context:` frontmatter of both `architecture.md`
+  and `contract.md`.
+- For an area not in the code-map, do a live on-demand read (`sdlc-connect-repos`
+  `references/code-context.md`).
+
+### Step 3 — Author the architecture (assist: architect)
+Adopt the **architect** lens (`bmad-agent-architect`, Winston) and write
+`{project-root}/epics/EP-<slug>/architecture.md` using EXACTLY this template:
+
+```markdown
+---
+id: EP-<slug>
+artifact: architecture
+status: draft
+owner: <inherit from epic.md owner>   # the epic owner carries through; not retyped
+repos: [<inherit from epic>]
+code-context: { repos: [], loaded: <YYYY-MM-DD or none> }   # code-maps cross-checked (Step 2b/4b)
+---
+
+## Overview
+<!-- the shape of the solution across repos, 2-4 sentences -->
+
+## Components by repo
+<!-- one subsection per repo in `repos`; responsibilities at charter altitude -->
+
+## Cross-repo flows
+<!-- the key request/event flows that span repos -->
+
+## Data ownership
+<!-- which repo owns which entity/store -->
+
+## Risks & decisions
+<!-- notable trade-offs; anything that drove the contract surface -->
+```
+
+Keep per-repo detail at responsibility altitude — implementation detail belongs in stories/specs, not
+here.
+
+### Step 4 — Author the locked contract (assist: architect)
+Write `{project-root}/epics/EP-<slug>/contract.md`. The contract holds **only the shared cross-repo
+surface**: API shape, events, and data model — at charter altitude, **no per-repo implementation
+detail**. Wrap that surface in a single delimited block bounded by the exact markers
+`<!-- CONTRACT-SURFACE:BEGIN -->` and `<!-- CONTRACT-SURFACE:END -->` so the hash-lock and the later
+contract-check operate on a stable, unambiguous region. Use EXACTLY this template:
+
+```markdown
+---
+id: EP-<slug>
+artifact: contract
+status: locked
+repos: [<inherit from epic>]
+code-context: { repos: [], loaded: <YYYY-MM-DD or none> }   # not hashed — frontmatter sits outside CONTRACT-SURFACE
+---
+
+# Contract — EP-<slug>
+
+> Shared cross-repo surface only. Charter altitude. Changing anything inside the
+> CONTRACT-SURFACE block re-locks the hash and invalidates prior approvals.
+
+<!-- CONTRACT-SURFACE:BEGIN -->
+## API
+<!-- endpoints: method + path + purpose; request/response shape at field level, no impl -->
+
+## Events
+<!-- event name + payload shape + producer/consumer repos -->
+
+## Data model
+<!-- shared entities + fields that cross a repo boundary -->
+<!-- CONTRACT-SURFACE:END -->
+
+## Notes
+<!-- anything outside the surface: rationale, open questions (not hashed) -->
+```
+
+### Step 4b — Cross-check the surface against existing code (BEFORE locking)
+Using the code-context loaded in Step 2b, compare the proposed `CONTRACT-SURFACE` against what the
+connected repos **already expose** (their code-maps' endpoints / events / data models):
+
+- If a proposed endpoint, event, or entity **collides with or duplicates** an existing one, do not
+  silently re-define it — either **reuse** the existing surface, or record the deliberate change in
+  `architecture.md` "Risks & decisions" (it will likely need a `Contract-Change` later).
+- If the new surface **depends on** existing behaviour, name that dependency in "Cross-repo flows" /
+  "Risks & decisions" so stories build on it rather than rebuilding it.
+- Reconcile every conflict **before** Step 5 — the hash locks whatever you settle on, so the surface
+  must already be consistent with the code when it is locked.
+
+If no repos are connected (greenfield), skip this step.
+
+### Step 5 — Lock the contract surface (hash)
+Compute the SHA-256 of the **exact bytes between** the `CONTRACT-SURFACE:BEGIN` and
+`CONTRACT-SURFACE:END` markers (the content between the markers, excluding the marker lines
+themselves) and write `{project-root}/epics/EP-<slug>/.sdlc/contract-lock.json`:
+
+```json
+{ "artifact": "contract.md", "hash": "sha256:<hex>", "lockedAt": "<YYYY-MM-DD>" }
+```
+
+Canonicalization (so the hash round-trips): hash the surface region as written between the markers,
+LF line endings, no leading/trailing blank-line normalization beyond what is in the file. Recompute
+the same way later; if it differs, the contract surface changed. The reference command:
+
+```bash
+awk '/CONTRACT-SURFACE:BEGIN/{f=1;next} /CONTRACT-SURFACE:END/{f=0} f' \
+  epics/EP-<slug>/contract.md | shasum -a 256
+```
+
+(See `references/contract-format.md` for the altitude rule and the exact hashing recipe.)
+
+### Step 6 — Advance the authoring step (NOT the gate)
+In `state.json`: set `architecture.status: "done"`, set `architecture-review.status: "in_review"`, and
+set `currentStep: "architecture-review"`. Write `state.json`. Do **not** touch `approvals.json` — only
+real reviewers approve, through the gate.
+
+### Step 7 — Stop at the gate (do NOT advance)
+Report: the paths to `architecture.md`, `contract.md`, and `contract-lock.json`; the contract hash;
+and that the next action is **review** via `sdlc-review-gate`. Note that this review **escalates**
+(risk tag `contract`): it needs owner + 1 reviewer **plus a domain owner for each touched repo**.
+**Never record approval here.** Front states do not auto-advance. When the hub has a platform, the gate
+opens a review PR on the hub (via `sdlc-hub-bridge`, labelled per touched repo) and
+`sdlc-review-gate action: sync` pulls platform approvals/comments into the ledger; a contract re-lock
+invalidates prior platform approvals too. Otherwise the review is recorded file-only.
+
+## Reference
+- Contract surface, altitude rule, and hashing recipe: `references/contract-format.md`.
+- State schema and field meanings: `../sdlc-author-epic/references/state-schema.md`.
+- Connecting code repos + the code-context cross-checked here: `../sdlc-connect-repos/SKILL.md`.

package/skills/sdlc-author-architecture/references/contract-format.md

@@ -0,0 +1,72 @@
+# Contract surface — format, altitude, and hash-lock
+
+The `contract.md` produced at front state 3 is the **single source of truth for the shared cross-repo
+surface** of an epic. Phase 3's contract-check (not built yet) fails a PR when a repo drifts from this
+surface. To make that check possible, the surface is delimited and hash-locked now.
+
+## What goes in the surface (altitude rule)
+
+Inside the `CONTRACT-SURFACE` block, and nowhere else:
+
+- **API** — the endpoints that cross a repo boundary: method, path, purpose, and the request/response
+  shape at the field level. No handler logic, no per-repo framework detail.
+- **Events** — event name, payload shape, and which repos produce/consume it.
+- **Data model** — only entities/fields that cross a repo boundary (shared identifiers, shared
+  enums/status values). A field private to one repo does not belong here.
+
+Charter altitude: describe the *shape of the agreement between repos*, not how any repo implements it.
+Implementation detail belongs in stories and (Phase 3) Spec Kit specs, not in the contract.
+
+Anything that is rationale, open questions, or non-binding notes goes **outside** the block (under
+`## Notes`) so it can change without re-locking the hash.
+
+## The delimited block
+
+Exactly two marker lines bound the hashed region:
+
+```
+<!-- CONTRACT-SURFACE:BEGIN -->
+... hashed content ...
+<!-- CONTRACT-SURFACE:END -->
+```
+
+Only the content **between** the markers is hashed — the marker lines themselves are excluded. This
+keeps the hash stable against edits to the surrounding prose, frontmatter, or notes.
+
+## The hash-lock
+
+Stored at `epics/EP-<slug>/.sdlc/contract-lock.json`:
+
+```json
+{ "artifact": "contract.md", "hash": "sha256:<hex>", "lockedAt": "<YYYY-MM-DD>" }
+```
+
+### Recipe (must round-trip)
+
+```bash
+awk '/CONTRACT-SURFACE:BEGIN/{f=1;next} /CONTRACT-SURFACE:END/{f=0} f' \
+  epics/EP-<slug>/contract.md | tr -d '\r' | shasum -a 256
+```
+
+- `awk` emits every line strictly between the two markers (the `next` after BEGIN skips the BEGIN
+  line; setting `f=0` on END stops before printing END).
+- `tr -d '\r'` normalizes CRLF line endings to LF before hashing — the same surface must hash
+  identically no matter which platform last saved the file (the CLI normalizes the same way).
+- `shasum -a 256` (BSD/macOS) or `sha256sum` (GNU/Linux) produce the same hex digest for identical
+  bytes. Prefix the digest with `sha256:` when writing the lock file.
+- Round-trip property: hashing unchanged content twice yields the same digest; any edit inside the
+  block changes it. That is exactly the drift signal the Phase 3 check needs.
+
+## Interaction with the review gate
+
+- The `architecture-review` step carries `risk_tags: ["contract"]`, so `sdlc-review-gate` **escalates**
+  it: owner + 1 reviewer **plus** one `domain-owner` approval per repo in the epic's `repos`.
+- **Staleness:** if the surface block is edited after approvals are recorded, the recomputed hash will
+  not match the lock — approvals are stale and the gate drops back to `comment`. Re-lock (Step 5 of the
+  skill) and re-approve.
+
+## Why a hash (vs structured diff)
+
+A hash is the smallest representation that proves "did the agreed surface change?" — which is all the
+front half needs. A field-by-field structured diff is a Phase 3 concern (it tells you *what* drifted in
+a failing PR); the lock established here is what that future check compares against.

package/skills/sdlc-author-epic/SKILL.md

@@ -0,0 +1,154 @@
+---
+name: sdlc-author-epic
+description: 'Front state for the epic in the gated SDLC. Shape a feature idea with the analyst (or read analysis.md when the optional analysis step already ran), then write the epic with the pm, into epic.md. The entry point when analysis is skipped: assigns the EP-<slug> ID and seeds .sdlc/ state. Never auto-advances — hands off to the team review gate. Use when the user says "start a new feature/epic" or "author an epic".'
+---
+
+# SDLC — Author Epic (front state)
+
+**Goal:** Produce a human-authored, AI-assisted `epic.md` for a new feature, and — when the epic is the
+entry point — assign its stable `EP-<slug>` ID and initialise the per-epic state machine in `.sdlc/`.
+This is a **front state**: human-authored with AI assist and **never auto-advances**. When the epic is
+drafted, control passes to `sdlc-review-gate`.
+
+**Two entry modes** (the optional `sdlc-author-analysis` step decides which):
+- **Analysis ran** — `.sdlc/state.json` already exists with `currentStep == "epic"`. The epic **reads
+  `analysis.md`** as its shaped input and does not re-seed state.
+- **Analysis skipped** (the default) — no `state.json` yet. The epic is the entry point: it shapes the
+  idea inline with the analyst, assigns `EP-<slug>`, and seeds the **8-step** chain.
+
+This skill enforces the build plan's core rules: all state lives in files; IDs are generated by the
+engine (never typed by hand); front steps are locked to `human_approve`.
+
+## Conventions
+
+- `{project-root}` resolves from the project working directory.
+- Epic artifacts live under `{project-root}/epics/EP-<slug>/` (build plan §6).
+- Speak in the configured `communication_language`; write documents in `document_output_language`.
+
+## On Activation
+
+### Step 1 — Determine the entry mode
+Read `{project-root}/epics/EP-<slug>/.sdlc/state.json` if an epic is named, otherwise check whether one
+exists for the idea.
+
+- **Analysis ran** — `state.json` exists with `currentStep == "epic"` and the `epic` step
+  `status == "in_progress"` (the analysis review already passed). Skip **Step 3** (the ID is already
+  assigned) and **Step 5** (state is already seeded); take the *analysis-ran* branch of Step 2 (read
+  `analysis.md`) and run Step 5b to advance the authoring step.
+- **Analysis skipped** (the default) — no `state.json`. The epic is the entry point: run Steps 2–5
+  (inline analyst shaping + ID assignment + seed) and **skip Step 5b**.
+
+Either mode runs Step 3b (branch), Step 4 (write the epic), and Step 6 (stop at the gate).
+
+If `state.json` exists but `currentStep != "epic"`, stop and point the user at `sdlc-status` / the gate.
+
+### Step 2 — Shape the idea (assist: analyst) — or read the analysis
+- **Analysis skipped:** ask the user for a one-line feature idea if not provided, then adopt the
+  **analyst** lens (`bmad-agent-analyst`, Mary) to pressure-test it: who is the user, what problem, what
+  signals success, what is out of scope. Keep it brief — this is shaping, not a PRD.
+- **Analysis ran:** read `{project-root}/epics/EP-<slug>/analysis.md` (the analyst's discovery brief)
+  and carry its Recommendation / Scope framing forward — do not re-shape from scratch.
+
+### Step 2b — Load existing-code context (make the brain code-aware)
+Read the registry `{project-root}/.sdlc/repos.json` (`config.yaml` `code_context`). For **every
+connected repo** (the epic's `repos` are not chosen yet at this point), load the lightweight code-map
+`{project-root}/.sdlc/code-context/<repo>/code-map.md`. Use it so the epic's **Scope / Out of scope /
+Context** reflect what is **already built** — reference existing behaviour rather than re-proposing it,
+and let it inform which `repos` the epic should touch.
+
+- **Greenfield-safe:** if `repos.json` is absent or empty, note "no repos connected" and proceed — no
+  behaviour change for a project with no code yet.
+- **Staleness:** if a repo's current HEAD (`git -C <path> rev-parse HEAD`) ≠ its registry `syncedHead`,
+  warn and suggest `sdlc repo refresh <repo>` (a human decision — flag and stop, never auto-refresh);
+  stamp `code-context: stale` in the frontmatter.
+- **Traceability:** record which maps you loaded in the epic frontmatter `code-context:` field.
+- For depth on a specific area not in the map, do a live on-demand read (see `sdlc-connect-repos`
+  `references/code-context.md`) — do not block on it.
+
+### Step 3 — Generate the Epic ID (engine-assigned, never by hand) — analysis-skipped only
+*(Skip when analysis ran — the ID was already assigned by `sdlc-author-analysis`.)*
+Derive `EP-<slug>` where `slug` is **2–4 lowercase words joined by hyphens**, drawn from the idea
+(e.g. `EP-istifta-inquiries`). Lowercase except the fixed `EP` prefix. **The ID is assigned once and
+never renamed** — renaming breaks every downstream link (build plan §6b).
+Check `{project-root}/epics/` for collisions; if the slug exists, append a distinguishing word.
+
+### Step 3b — Open the authoring branch
+Open the epic authoring branch `epic/EP-<slug>` per the shared procedure
+(`references/state-schema.md` → "Authoring branches"): git-safe (skip with a note if `{project-root}`
+is not a git work tree), check out the branch if it exists, else create it from the hub's default
+branch. Author and commit `epic.md` on it. This is **distinct** from the bridge's `review/…` branch.
+
+### Step 4 — Write the epic (assist: pm)
+Adopt the **pm** lens (`bmad-agent-pm`, John) and write `{project-root}/epics/EP-<slug>/epic.md`
+using EXACTLY this template (build plan §6b):
+
+```markdown
+---
+id: EP-<slug>
+status: draft
+owner:
+technical_product_owner:
+repos: [backend, mobile, dashboard]
+code-context: { repos: [], loaded: <YYYY-MM-DD or none> }   # which code-maps informed this epic (Step 2b)
+---
+
+## Goal
+<!-- why this feature exists, 1-2 sentences -->
+
+## Scope
+## Out of scope
+## Context / background
+## Acceptance signals (user-level)
+```
+
+Fill the body with the user; leave `owner` / `technical_product_owner` for the user to set. Set
+`repos` to the repos this epic will touch.
+
+### Step 5 — Seed the state machine — analysis-skipped only
+*(Skip when analysis ran — `sdlc-author-analysis` already seeded the 10-step chain. Go to Step 5b.)*
+Create `{project-root}/epics/EP-<slug>/.sdlc/state.json` describing the full **8-step** front-state
+sequence (no analysis), all steps defaulting to `automation: human_approve`, with the four authoring
+steps **locked**. Use this exact shape (see `references/state-schema.md`):
+
+```json
+{
+  "epicId": "EP-<slug>",
+  "createdAt": "<YYYY-MM-DD>",
+  "currentStep": "epic-review",
+  "steps": [
+    { "id": "epic",               "type": "author",         "artifact": "epic.md",          "assistance": "review", "automation": "human_approve", "locked": true,  "status": "done",        "risk_tags": [] },
+    { "id": "epic-review",        "type": "review+approve", "artifact": "epic.md",          "assistance": "review", "automation": "human_approve", "locked": true,  "status": "in_review",   "risk_tags": [] },
+    { "id": "architecture",       "type": "author",         "artifact": "architecture.md",  "assistance": "review", "automation": "human_approve", "locked": true,  "status": "blocked",     "risk_tags": [] },
+    { "id": "architecture-review","type": "review+approve", "artifact": "architecture.md",  "assistance": "review", "automation": "human_approve", "locked": true,  "status": "blocked",     "risk_tags": ["contract"] },
+    { "id": "ui-design",          "type": "author",         "artifact": "ui-design.md",     "assistance": "review", "automation": "human_approve", "locked": true,  "status": "blocked",     "risk_tags": [] },
+    { "id": "ui-design-review",   "type": "review+approve", "artifact": "ui-design.md",     "assistance": "review", "automation": "human_approve", "locked": true,  "status": "blocked",     "risk_tags": [] },
+    { "id": "stories",            "type": "author",         "artifact": "stories/",         "assistance": "review", "automation": "human_approve", "locked": true,  "status": "blocked",     "risk_tags": [] },
+    { "id": "stories-review",     "type": "review+approve", "artifact": "stories/",         "assistance": "review", "automation": "human_approve", "locked": true,  "status": "blocked",     "risk_tags": [] }
+  ]
+}
+```
+
+Notes:
+- `architecture-review` carries `risk_tags: ["contract"]` so the gate escalates it by default
+  (build plan §4): the contract review needs domain owners, not just owner + 1.
+- Also create an empty approvals ledger `{project-root}/epics/EP-<slug>/.sdlc/approvals.json`
+  and an empty comments ledger `{project-root}/epics/EP-<slug>/.sdlc/comments.json`, each containing
+  `[]`, and the `reviews/` directory. (`comments.json` is the machine-readable counterpart to the
+  `reviews/*--comments.md` markdown — `sdlc-review-gate` appends to it on every `comment`.)
+
+### Step 5b — Advance the authoring step — analysis-ran only
+*(Only when analysis ran — `state.json` already exists from `sdlc-author-analysis`.)*
+In `state.json`: set `epic.status: "done"`, set `epic-review.status: "in_review"`, and set
+`currentStep: "epic-review"`. Write `state.json`. Do **not** re-seed and do **not** touch
+`approvals.json` — only real reviewers approve, through the gate.
+
+### Step 6 — Stop at the gate (do NOT advance)
+Report: epic ID, the path to `epic.md`, and that the next action is **review** via
+`sdlc-review-gate`. **Never mark the epic-review step approved here** — only real reviewers do that
+through the gate. Front states do not auto-advance. When the hub has a platform, the gate opens a review
+PR on the hub (via `sdlc-hub-bridge`) and `sdlc-review-gate action: sync` pulls platform approvals/
+comments into the ledger; otherwise the review is recorded file-only.
+
+## Reference
+- State schema and field meanings: `references/state-schema.md`.
+- Connecting code repos + the code-context the brain reads: `../sdlc-connect-repos/SKILL.md`.

package/skills/sdlc-author-epic/references/state-schema.md

@@ -0,0 +1,187 @@
+# `.sdlc/` state schema
+
+All SDLC state lives in plain files under `epics/EP-<slug>/.sdlc/` (build plan §1: "All state lives
+in files on disk. Nothing hidden."). No database, no browser storage.
+
+## `state.json`
+The per-epic state machine.
+
+| Field | Meaning |
+|-------|---------|
+| `epicId` | The stable `EP-<slug>` ID. Never renamed. |
+| `createdAt` | ISO date the epic was created. |
+| `currentStep` | `id` of the step the workflow is waiting on right now. |
+| `steps[]` | Ordered list of every front-state step. |
+
+Each `steps[]` entry:
+
+| Field | Values | Meaning |
+|-------|--------|---------|
+| `id` | `analysis`, `analysis-review`, `epic`, `epic-review`, `architecture`, `architecture-review`, `ui-design`, `ui-design-review`, `stories`, `stories-review` | Step identity. |
+
+### Two valid chain shapes (analysis is optional)
+
+The `analysis` step (and its `analysis-review` gate) is **optional** — it exists only when the team
+ran `sdlc-author-analysis` before the epic. The entry-point skill (whichever runs first) is the one
+that assigns `EP-<slug>` and seeds `state.json` + the empty ledgers; the other skill detects an
+existing `state.json` and does **not** re-seed.
+
+- **With analysis** (10 steps — `sdlc-author-analysis` seeded the chain):
+  `analysis → analysis-review → epic → epic-review → architecture → architecture-review → ui-design →
+  ui-design-review → stories → stories-review`. Seeded `currentStep` is `analysis-review`; `epic`
+  starts `blocked`.
+- **Without analysis** (8 steps — `sdlc-author-epic` is the entry point, the default):
+  `epic → epic-review → … → stories-review`. Seeded `currentStep` is `epic-review`.
+
+After `stories-review` passes, `currentStep` becomes the `ready-for-build` sentinel either way.
+`analysis-review` carries no `risk_tags` (base rule: owner + 1 reviewer).
+
+### Authoring branches
+
+Each front **authoring** step opens its own git branch at the start of the step, named
+`<step>/EP-<slug>` where `<step>` ∈ `analysis | epic | architecture | ui-design | stories`
+(`config.yaml` `defaults.front_authoring_branch`). This is **distinct** from the review branch
+`review/EP-<slug>/<artifact-base>` that `sdlc-hub-bridge` opens later for the review PR/MR.
+
+The shared procedure (run once the `EP-<slug>` is known):
+1. **Git-safe / greenfield-safe:** if `{project-root}` is not a git work tree
+   (`git rev-parse --is-inside-work-tree` fails), skip branching with a note and author on the current
+   tree — no error.
+2. Branch name = `<step>/EP-<slug>`. If it already exists, check it out; otherwise create it from the
+   hub's default branch (`git checkout -b <step>/EP-<slug>`).
+3. Author and commit the step's artifact(s) on that branch. The bridge's `review/…` branch is created
+   separately at review time and is untouched by this step.
+| `type` | `author` \| `review+approve` | Authoring step or a team review gate. |
+| `artifact` | filename or folder | The file/folder this step produces or gates. |
+| `assistance` | `none` \| `review` \| `heavy` | Dial 1 — how much AI helps (build plan §2). |
+| `automation` | `human_approve` \| `machine_advance` | Dial 2 — who advances (build plan §2). |
+| `locked` | `true` \| `false` | Front steps are `true`: may NOT be set to `machine_advance` in this version. |
+| `status` | `blocked` \| `in_progress` \| `in_review` \| `done` | Lifecycle. `blocked` = upstream step not yet approved. |
+| `risk_tags` | subset of `contract`, `auth`, `payments` | Drives review escalation (build plan §4). |
+
+## `approvals.json`
+Append-only ledger (an array). Each entry:
+
+```json
+{ "artifact": "epic.md", "step": "epic-review", "approver": "<name>", "role": "owner|reviewer|domain-owner", "domain": "<repo-or-area, optional>", "status": "approved", "date": "<YYYY-MM-DD>", "source": "<bridge, optional>" }
+```
+
+`source: "bridge"` marks an approval synced from a hub review PR/MR by `sdlc-review-gate action: sync`
+(via `sdlc-hub-bridge`). Manual approvals omit `source` and are never altered by `sync`.
+
+## `comments.json`
+Append-only ledger (an array), the machine-readable counterpart to the `reviews/*--comments.md` markdown
+("who reviewed/commented", as `approvals.json` is "who approved"). Written by `sdlc-review-gate`'s
+`comment` action; feeds the `approved.md` participation roster, not the gate predicate. Each entry:
+
+```json
+{ "artifact": "epic.md", "step": "epic-review", "commenter": "<name>", "role": "owner|reviewer|domain-owner", "domain": "<optional>", "round": <n>, "count": <comments this round>, "date": "<YYYY-MM-DD>" }
+```
+
+## `hub-prs.json`
+Present only when the front-half review runs through the platform bridge. Per review step, the review
+PR/MR opened on the hub (sibling of `approvals.json`, so the locked `state.json` step shape is untouched):
+
+```json
+{ "step": "<review step id>", "artifact": "<artifact>", "platform": "github|gitlab", "number": <n>, "url": "<pr/mr url>", "branch": "review/EP-<slug>/<artifact-base>", "lastSyncedAt": "<YYYY-MM-DD or null>" }
+```
+
+## `reviews/`
+Human-readable review records, one file per round:
+`reviews/<artifact-base>--<YYYY-MM-DD>--<status>.md` where `status` ∈ `comments` | `approved`
+and `<artifact-base>` is the artifact without extension (e.g. `epic`, `architecture`, `stories-S01`).
+
+## Dial defaults & locks
+- Every step defaults to `automation: human_approve` (build plan §2).
+- The four authoring front steps and their reviews are `locked: true` — the engine refuses to set
+  them to `machine_advance` in this version (build plan §1, §8.7). Only back states (build pipeline,
+  steps 9–14) may move toward machine-advance in a later iteration.
+
+---
+
+# Phase 4 build-half state (the back half made dial-bearing)
+
+Phase 3 recorded build progress only *after the fact* in `build-log.json`. Phase 4 needs the back
+steps to carry their own `automation` dial so the orchestrator (`sdlc-run`) can read it and decide
+whether to advance on its own. Two new files under `.sdlc/` do this.
+
+## `build-state/<story-id>.json`
+One file per story that has entered the build half. The build half is **per-story, per-repo**, so the
+steps live under each repo (mirrors the per-repo shape of `build-log.json`).
+
+```json
+{
+  "story": "EP-<slug>-S0N",
+  "repos": {
+    "backend": {
+      "currentStep": "checks",
+      "steps": [
+        { "id": "spec",            "automation": "human_approve",  "locked": false, "status": "done" },
+        { "id": "tasks",           "automation": "human_approve",  "locked": false, "status": "done" },
+        { "id": "implement",       "automation": "human_approve",  "locked": false, "status": "done" },
+        { "id": "checks",          "automation": "machine_advance","locked": false, "status": "in_progress" },
+        { "id": "engineer-review", "automation": "human_approve",  "locked": true,  "status": "blocked" }
+      ]
+    }
+  }
+}
+```
+
+Each `steps[]` entry:
+
+| Field | Values | Meaning |
+|-------|--------|---------|
+| `id` | `spec`, `tasks`, `implement`, `checks`, `engineer-review` | Back-half step identity (the `back_steps` from `config.yaml` + the human merge gate). |
+| `automation` | `human_approve` \| `machine_advance` | Dial 2. Defaults to `human_approve`; flipped to `machine_advance` only after the trust threshold is met (and never for `locked` steps). |
+| `locked` | `true` \| `false` | `engineer-review` is `true` — it never auto-advances (build plan §E). |
+| `status` | `blocked` \| `in_progress` \| `in_review` \| `done` | Lifecycle. `sdlc-run` advances `done` steps and `blocked`s on a halt. |
+
+`currentStep` is the `id` the orchestrator is waiting on / about to run for that repo. The file is
+created when a story enters the build half; all dials start `human_approve` (the `config.yaml`
+`automation.default`).
+
+## `trust-log.json`
+Append-only ledger (an array), the back-half analogue of `approvals.json`. **This is the evidence
+base** that decides when a step is safe to automate (build plan Step A). One entry per step run:
+
+```json
+{
+  "story": "EP-<slug>-S0N",
+  "repo": "backend",
+  "step": "checks",
+  "automation": "human_approve",
+  "verdict": "approved-unchanged",
+  "signals": { "checks": "pass", "human_edited_diff": false, "scope_overrun": false, "contract_touch": false },
+  "ranBy": "machine",
+  "date": "<YYYY-MM-DD>",
+  "note": "<optional>"
+}
+```
+
+| Field | Values | Meaning |
+|-------|--------|---------|
+| `step` | a `back_steps` id | Which step this run is recorded against. |
+| `automation` | dial in force at run time | So the log shows whether the run was a manual or an automated advance. |
+| `verdict` | `approved-unchanged` \| `approved-with-edits` \| `rejected` | The trust signal. **Provisional verdict is derived** (below); the human gate for that step confirms or overrides it and finalizes the entry. |
+| `signals` | object | The raw inputs the provisional verdict was derived from. The fields present depend on the step (table below). |
+| `ranBy` | `machine` \| `human` | Whether the orchestrator advanced it or a human did. |
+
+**Per-step `signals` fields** (only the relevant ones are set; others may be omitted or `n/a`):
+
+| Step | Signals | Finalized at (the human gate) |
+|------|---------|-------------------------------|
+| `spec` | `human_edited_spec` | the human who accepts `specs/<story>/` (`sdlc-spec` Step 8) |
+| `tasks` | `task_rescoped` | first consume by `sdlc-implement` (Step 8) |
+| `implement` | `human_edited_diff`, `scope_overrun`, `contract_touch` | engineer review at `sdlc-ship` |
+| `checks` | `checks` (`pass`\|`fail`) | the gate run itself (objective) |
+
+**Deriving the provisional verdict** (build plan Step A; extended for `spec`/`tasks` in Phase 4b — the
+same three-way shape, anchored to each step's human gate, never self-graded):
+- any check FAIL, scope overrun, contract-surface touch, or a discarded/regenerated artifact → `rejected`;
+- accepted after a human edited the output (`human_edited_diff` / `human_edited_spec` / `task_rescoped`) → `approved-with-edits`;
+- accepted as produced → `approved-unchanged`.
+
+**Trust threshold** (from `config.yaml` `automation.trust_threshold`): a step is a candidate for
+`machine_advance` only when its slice of `trust-log.json` (same `step`, this story's repo or the
+project) has `>= min_runs` entries AND the fraction with `verdict == "approved-unchanged"` is
+`>= min_approved_unchanged`. The dial-setter in `sdlc-run` enforces this; `sdlc-status` surfaces it.