wdi-method 0.6.18 → 0.6.24

package/kit/.constitution/method/README.md

@@ -43,6 +43,7 @@ Never a rule. When it disagrees with a guide, the guide wins and the disagreemen
 | [`language-guide.md`](language-guide.md) | Naming anything — a code identifier, a code file, a document file |
 | [`method-glossary.md`](method-glossary.md) | Unsure what a method term means — layer, wave, Product Component, ID code |
 | [`structure-guide.md`](structure-guide.md) | Writing or checking the two structure maps in `.control/` |
+| [`ci-guide.md`](ci-guide.md) | Writing or changing a CI workflow; when a push may start a cloud run, and what MUST NOT |
 
 ## `document/` — document rules
 

package/kit/.constitution/method/branch-guide.md

@@ -0,0 +1,87 @@
+---
+status: Accepted
+---
+
+# Branch Guide
+
+**Loaded when:** creating, switching, pushing, merging, or deleting git branches, creating task worktrees, targeting pull requests, or configuring repository branch policy
+
+This guide governs git branching conventions, protected branches, and pull request target policies across repositories using WDI Method.
+
+## Branch policy settings
+
+Branch settings live in `.control/registry/index.yaml` under `policy:`. Both default to `main`:
+
+| Setting | Governs | Default |
+|---|---|---|
+| `primary_branch` | Production / release trunk | `main` |
+| `development_branch` | Active development branch for specs, worktrees, and PR targets | `main` |
+
+Two workflows are supported:
+- **Single-branch workflow:** `primary_branch` and `development_branch` are identical (e.g. both `main`). Suitable for small tools and straightforward repositories.
+- **Two-branch workflow:** `primary_branch` is `main` (production-ready releases) and `development_branch` is `development` (ongoing feature integration).
+
+## Absolute branch immunity
+
+- An agent MUST NOT delete, rename, force-push, or overwrite `primary_branch` or `development_branch`, locally or on any remote.
+
+## Primary branch protection
+
+The `primary_branch` represents production stability:
+- An agent MUST NOT commit application code directly to `primary_branch`.
+- An agent MUST NOT force-push to `primary_branch`.
+- In single-branch mode (where `development_branch` equals `primary_branch`), the only exception to direct commits is non-code corpus planning: spec and ticket authoring in `.scratch/` and index updates in `.control/registry/specs.yaml`. All application code changes MUST go through isolated branches/worktrees and pull requests.
+- An agent MUST NOT merge into `primary_branch`, except in single-branch mode where `development_branch` equals `primary_branch`, and only when explicitly instructed by the repository maintainer.
+- Merges into `primary_branch` and release tagging belong exclusively to human maintainers or designated release workflows.
+
+## Development branch protection
+
+- An agent MUST NOT force-push to `development_branch`.
+- An agent MUST NOT commit application code directly to `development_branch`; code delivery MUST arrive via isolated task branches/worktrees and pull requests.
+- Direct commits to `development_branch` are permitted strictly for Phase 1 & 2 spec/ticket authoring in `.scratch/` and `.control/registry/specs.yaml`, with no application code changes.
+- Merging pull requests into `development_branch` requires explicit maintainer approval.
+
+## Active development target
+
+The `development_branch` is the sole base and landing target for active engineering work:
+- Feature specs, ticket authoring, and `.scratch/` planning documents are based on `development_branch`.
+- Task branches and implementation worktrees MUST branch from `development_branch`.
+- Pull requests opened by `wdi-build` or `wdi-autopilot` MUST target `development_branch`.
+
+## Fail-closed precheck
+
+Before running branch or worktree operations, an agent MUST verify that the configured `development_branch` exists locally or on the remote tracking ref:
+
+```bash
+git rev-parse --verify "refs/heads/<development_branch>" >/dev/null 2>&1 || git rev-parse --verify "refs/remotes/origin/<development_branch>" >/dev/null 2>&1
+```
+
+- If `development_branch` cannot be verified locally or on remote, the agent MUST STOP immediately and report the error to the maintainer.
+- An agent MUST NOT guess branch names or silently fall back to `main` when `development_branch` is missing.
+
+## Worktree and task branch lifecycle
+
+- Task branches and worktrees are temporary mechanisms for isolated implementation.
+- Once a task or run branch is merged into `development_branch`, the local task worktree and branch SHOULD be pruned.
+- Intermediate task branches MUST NOT be left lingering on the remote; only the designated run branch or PR branch reaches the remote.
+- When synchronizing `development_branch`, agents SHOULD run `git fetch --prune origin` to prune stale remote-tracking references of branches already deleted on the remote.
+- For method-owned run branches (e.g. `autopilot/<mandate-id>`), once the pull request is confirmed merged into `development_branch`, the remote branch SHOULD be pruned (`git push origin --delete <branch>`). If PR merge status cannot be verified, the remote branch MUST NOT be deleted and MUST be reported as a residual remote branch.
+- Absolute branch immunity strictly applies to remote operations: an agent MUST NEVER delete or prune `primary_branch` or `development_branch` on any remote.
+
+### Working tree isolation models
+
+Isolation protects branch integrity and build state during implementation:
+1. **Linked worktree (`git worktree add`):** An additional isolated checkout directory. Ideal for multi-task workflows and environments without toolchain file locks.
+2. **Exclusive primary working tree:** The root repository checkout temporarily dedicated exclusively to a task branch or autopilot run branch (`autopilot/<mandate-id>`). This model is permitted where linked worktrees encounter filesystem or toolchain locks (e.g. Windows file locking on compiler output or artifact build directories), provided all three conditions hold:
+   - The working tree is clean (`git status --porcelain` empty) before switching to the run branch.
+   - The checkout is dedicated exclusively to the active run (no parallel builders, concurrent human edits, or competing processes sharing the root tree).
+   - Only one active mandate or task run executes on the primary tree at any given time.
+3. **Shared checkout (PROHIBITED for code changes):** A working tree with dirty state, unstaged edits, or concurrent uncoordinated activities.
+
+## Red flags
+
+- Committing directly to `primary_branch` when `development_branch` differs
+- Deleting `primary_branch` or `development_branch` during worktree cleanup
+- Force-pushing to any protected branch
+- Falling back to `main` when `git rev-parse --verify <development_branch>` fails
+- Opening a pull request targeting `primary_branch` instead of `development_branch`

package/kit/.constitution/method/ci-guide.md

@@ -0,0 +1,169 @@
+---
+status: Accepted
+---
+
+# CI Guide
+
+**Loaded when:** writing or changing a GitHub Actions workflow, or deciding whether a push may start a
+cloud run
+
+Cloud runners are **metered**, and the meter is not flat: a Windows runner bills at **2×** the minutes it
+uses and macOS at **10×**, and on a private repository every one of those minutes comes out of a monthly
+allowance. One real run of `wdi-autopilot` over fifteen tickets pushed often enough to start CI dozens of
+times and spent most of a month's allowance in two days.
+
+**The fix is not fewer commits.** Commits stay granular — one per ticket, plus the memlog and registry
+writes — because that is what makes a run reviewable and resumable. What changes is **what a push
+triggers**.
+
+## One unit of work, one cloud run
+
+| | Runs where | When |
+|---|---|---|
+| Build, typecheck, the full suite **during** the work | **Locally**, on the machine doing the work | Every ticket — `wdi-build` Phase 3 Step 2 already requires it, and it is free |
+| The cloud workflow | GitHub Actions | **Once**, when the work is offered for review |
+
+- A workflow MUST be configured so that an intermediate push — a ticket commit, a memlog rewrite, a
+  registry catch-up, a spec close — starts **nothing**.
+- The cloud run MUST happen before the work is merged. Green CI on the **pushed head SHA** is still the
+  release evidence; what moves is how many times it is collected, not whether it is.
+- Under a mandate the unit of work is the whole run, so the one cloud run belongs at `wdi-autopilot`
+  § Finish. That skill owns the sequence and this guide MUST NOT restate it.
+- Where the repo's workflow cannot be changed — a shared org template, a workflow another team owns —
+  the run MUST keep intermediate work off the remote instead: hold the push, or make the pushed head
+  commit carry `[skip ci]`, which GitHub honours for `push` and `pull_request` events.
+
+### CI execution policy
+
+The product's CI execution policy is configured in `.control/registry/index.yaml` under `policy:`, defaulting to `cycle-end-cloud`:
+
+```yaml
+policy:
+  ci_execution: cycle-end-cloud # cycle-end-cloud (default)
+```
+
+- **`cycle-end-cloud` (default):** Intermediate pushes start nothing; exactly one cloud CI run is triggered at `wdi-autopilot` § Finish when the work is offered for review. Green CI on the pushed head SHA is required before marking the PR ready for review.
+- **Mandate CI override (signed bypass for constrained environments):** Where cloud runner allowances are strictly limited or emergency releases require local verification, an autonomous mandate MAY record a signed override on its decision block in `decisions.yaml`:
+  ```yaml
+  mandate:
+    ci_override: local-only-approved-by: "<Person, YYYY-MM-DD>"
+  ```
+  Under this signed override, the autopilot run MUST NOT call `gh pr ready`, the PR MUST remain as a Draft, no cloud runner is awaited, and the final release report MUST explicitly state: *"locally verified; cloud verification intentionally deferred by mandate"*. A global un-audited toggle MUST NOT be used to silently disable CI evidence.
+
+## Trigger shape
+
+| Event | Use it | Why |
+|---|---|---|
+| `workflow_dispatch` | **MUST** be present | The manual re-run. Without it, a red run can only be retried by pushing again |
+| `pull_request:` `types: [ready_for_review]` | The one automatic trigger | A draft PR is work in progress; marking it ready is the moment somebody is asking for the verdict. 100% branch-agnostic standard — triggers identically for `main`, `development`, or custom target branches |
+| `push:` `branches: [main, development]` | MAY | One run per merge, as the record of branch health. Note: GitHub Actions evaluates branch filters statically before checkout; if custom branch names are configured in `index.yaml` policy, update this list manually. Drop it where the allowance is tight |
+| bare `on: push` | **MUST NOT** | Every branch, every commit, no filter. This is the setting that spends an allowance |
+
+Two consequences worth stating, because both surprise people:
+
+- With `types: [ready_for_review]` and no `synchronize`, a push **after** the PR is ready does not
+  re-run CI. Re-run it with `workflow_dispatch`, or convert the PR back to draft and mark it ready
+  again. That is the intended trade: the re-run is a decision, not a reflex.
+- `concurrency` with `cancel-in-progress: true` stops two runs of the same ref from billing at once.
+  Every workflow below sets it.
+
+## What MUST NOT start a build
+
+A change that touches only prose or only the corpus cannot break the code, so it MUST NOT start the
+product's build. `paths-ignore` carries that: `**.md`, `.scratch/**`, and the method's own layers —
+`.control/**`, `.what/**`, `.how/**`, `.constitution/**`, `_bmad-output/**`, `.work/**`.
+
+The corpus workflow is the **mirror image** of that list and MUST stay a separate workflow: it runs the
+validators, on Ubuntu, only when the corpus changed. Keeping the two apart is what lets the expensive one
+be ignored while the cheap one still guards the registry.
+
+## Template — `.github/workflows/ci.yml`
+
+The product's build and test. This is the expensive one; the `runs-on` and the two `run:` lines are the
+product's, and they come from `.constitution/project/codebase-stack-guide.md`.
+
+```yaml
+name: ci
+
+on:
+  workflow_dispatch:
+  pull_request:
+    types: [ready_for_review]
+    paths-ignore:
+      - '**.md'
+      - '.scratch/**'
+      - '.control/**'
+      - '.what/**'
+      - '.how/**'
+      - '.constitution/**'
+      - '_bmad-output/**'
+      - '.work/**'
+  # One run per merge, as the record of branch health. GitHub Actions evaluates branch filters
+  # statically before checkout; if index.yaml policy configures custom branch names (e.g. trunk, dev),
+  # update this list manually. Delete this block where the allowance is tight.
+  push:
+    branches: [main, development]
+    paths-ignore:
+      - '**.md'
+      - '.scratch/**'
+      - '.control/**'
+      - '.what/**'
+      - '.how/**'
+      - '.constitution/**'
+      - '_bmad-output/**'
+      - '.work/**'
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    # A Windows runner bills 2× and macOS 10×. Name only the platforms the product actually ships on.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      # Replace both lines with this product's build and test commands.
+      - run: echo "build command from codebase-stack-guide.md"
+      - run: echo "test command from codebase-stack-guide.md"
+```
+
+## Template — `.github/workflows/korpus.yml`
+
+The corpus validators. Cheap, Ubuntu, and it runs only when the corpus moved — so it MAY keep the
+default `pull_request` trigger, which gives a verdict on the registry while the expensive workflow stays
+quiet. `korpus.yml` validates the corpus and **not** the code: a green run here is never build evidence.
+
+```yaml
+name: korpus
+
+on:
+  workflow_dispatch:
+  pull_request:
+    paths:
+      - '.control/**'
+      - '.what/**'
+      - '.how/**'
+      - '.constitution/**'
+
+concurrency:
+  group: korpus-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      # The three scripts declare their dependencies inline (PEP 723); uv is what runs them.
+      - uses: astral-sh/setup-uv@v5
+      - run: uv run .constitution/method/scripts/validate.py
+```
+
+## Red flags
+
+- `on: push` with no branch filter, in a repo whose runners are metered
+- The product's build and the corpus validators in one workflow — the cheap half then cannot run alone
+- A cloud run started to find out whether the code compiles, when the local suite answers that for free
+- CI watched per ticket under a mandate, instead of once at § Finish
+- A green `korpus.yml` read as a passing build

package/kit/.constitution/method/constitution.md

@@ -26,6 +26,7 @@ The repo layout is governed by `corpus-guide.md` and mapped by
 | `.what-rendered/` · `.how-rendered/` | The two above, assembled for a human to read — one page per gate, at the mirror path. Regenerated by `validate.py`, never edited, never read by a skill |
 | `_bmad-output/` | Run workspace; MUST be in git, not curated |
 | `.scratch/` | One directory per effort: a spec's `SPEC.md` and its ticket files, and ad hoc work that has no `FR` yet. MUST be in git — the corpus cites into it by path |
+| `.archive/` | Archived records — closed specs and historical provenance moved from `.scratch/`. MUST be in git |
 | `.work/` | Scratch; MUST be in git, emptied when a task closes |
 | *(application roots)* | Application code — named and mapped in `.control/structure-codebase.md` |