v1.0: agent orientation — install --skills/--hooks/--all, hook session-start, MCP instructions/resources/prompt (PR 6/x)

.agents/skills/filigree-workflow/SKILL.md

@@ -23,12 +23,22 @@ Every task follows this lifecycle:
 filigree ready                                      → find available work (no blockers)
 filigree show <issue-id>                            → read requirements and context
 filigree transitions <issue-id>                     → check valid status transitions
-filigree start-work <issue-id> --assignee <name>    → atomically claim + transition to in_progress
+filigree start-work <issue-id> --assignee <name>    → atomically claim + transition into its working status
 [do the work, commit code]
 filigree close <issue-id> --reason="summary of what was done"
 ```
 
-Or skip steps 1–3 entirely with `filigree start-next-work --assignee <name>` to grab the highest-priority ready issue.
+Or skip steps 1–3 entirely with `filigree start-next-work --assignee <name>` to grab the highest-priority **startable** issue.
+
+> **Ready ≠ startable.** The working status is type-specific (tasks →
+> `in_progress`, features → `building`). Bugs start at `triage`, which has no
+> single-hop transition into work — they walk `triage → confirmed → fixing`. So
+> a triage bug is *ready* but not directly *startable*: `start-work` on one
+> returns `INVALID_TRANSITION` naming the next status to move through, and
+> `start-next-work` skips it. `ready` items carry a `startable` flag (and a
+> `next_action` hint when false). Pass `--advance` to either command to walk the
+> soft transitions automatically (`triage → confirmed → fixing`) instead of
+> being blocked or skipped.
 
 Always close with a `--reason` — it becomes audit trail for the next agent.
 
@@ -49,18 +59,26 @@ When triaging, use `filigree batch-update <ids...> --priority=N` for bulk change
 ### Solo or Swarm — Same Tool
 
 Use `start-work` (or `start-next-work`) for the usual case. Both atomically
-claim the issue *and* transition it to `in_progress` in one DB transaction —
-optimistic-locking on the assignee, so concurrent callers can't both think
-they own the issue.
+claim the issue *and* transition it into its working status in one DB
+transaction — optimistic-locking on the assignee, so concurrent callers can't
+both think they own the issue. The working status is type-specific (tasks →
+`in_progress`, features → `building`, bugs → `fixing`).
 
 ```bash
-filigree start-work <issue-id> --assignee <agent-name>     # specific issue
-filigree start-next-work --assignee <agent-name>           # highest-priority ready
+filigree start-work <issue-id> --assignee <agent-name>              # specific issue
+filigree start-next-work --assignee <agent-name>                    # highest-priority startable
+filigree start-work <bug-id> --assignee <agent-name> --advance      # walk triage → confirmed → fixing
 ```
 
 If another agent already owns the claim, the call fails with `code: CONFLICT`
 (CLI exit 4). Safe to retry against a different issue.
 
+`start-work` on a `triage` bug (or any type with no single-hop working status)
+returns `INVALID_TRANSITION` naming the intermediate status to move through
+first; `start-next-work` skips such issues. Pass `--advance` to walk the soft
+transitions to the nearest working status automatically (missing required
+fields become warnings, not blocks; hard edges are never auto-walked).
+
 ### Niche: Claim Without Transitioning
 
 `claim` and `claim-next` still exist for the rare case where you want to
@@ -170,13 +188,15 @@ When parsing `--json` output or MCP responses, expect these unified envelopes:
 
 - **Batch ops** → `{succeeded: [...], failed: [{id, error, code}, ...], newly_unblocked?: [...]}`.
   `failed` is always present (empty list if none); `newly_unblocked` is
-  omitted when the op cannot unblock. Pass `--detail=full` (CLI) or
+  present only when non-empty (omitted when the op unblocked nothing). Pass `--detail=full` (CLI) or
   `response_detail="full"` (MCP) to get full records back.
 - **List ops** → `{items: [...], has_more: bool, next_offset?: int}`.
   `next_offset` only appears when there is a next page.
 - **Errors** → `{error: str, code: ErrorCode, details?: dict}`. `code` is
   one of: `VALIDATION`, `NOT_FOUND`, `CONFLICT`, `INVALID_TRANSITION`,
-  `PERMISSION`, `NOT_INITIALIZED`, `IO`, `INVALID_API_URL`, `STOP_FAILED`,
+  `PERMISSION`, `NOT_INITIALIZED`, `IO`, `INVALID_API_URL`,
+  `FILE_REGISTRY_DISPLACED`, `REGISTRY_UNAVAILABLE`,
+  `CLARION_REGISTRY_VERSION_MISMATCH`, `BRIEFING_BLOCKED`, `STOP_FAILED`,
   `SCHEMA_MISMATCH`, `INTERNAL`. Branch on `code` for retry policy
   (`CONFLICT` → exit 4, retryable; everything at exit 1 needs operator
   intervention).

.agents/skills/filigree-workflow/references/team-coordination.md

@@ -7,10 +7,11 @@ work across multiple agents.
 
 ### The Race Condition Problem
 
-When multiple agents call `filigree update <issue-id> --status=in_progress`
+When multiple agents call `filigree update <issue-id> --status=<wip>`
 simultaneously, both think they own the issue. Filigree 2.0 solves this with
-`start-work`, which atomically claims the issue *and* transitions it to
-`in_progress` in a single DB transaction with optimistic locking on the
+`start-work`, which atomically claims the issue *and* transitions it to its
+type-specific working status (tasks → `in_progress`, features → `building`,
+bugs → `fixing`) in a single DB transaction with optimistic locking on the
 assignee.
 
 ### Start Protocol
@@ -27,9 +28,12 @@ If another agent already claimed the issue, the call fails with
 `code: CONFLICT` (CLI exit 4). No silent overwrite, no half-claimed state —
 either both the claim and the transition land, or neither does.
 
-`start-next-work` accepts the same filters as `claim-next`
-(`--type`, `--priority-min`, `--priority-max`, `--target-status`) so
-specialised agents can scope their work.
+`start-next-work` accepts the work-scoping filters `claim-next` also
+takes (`--type`, `--priority-min`, `--priority-max`) so specialised agents
+can scope their work. Because `start-next-work` *transitions* (not just
+reserves), it additionally accepts `--target-status` to override the wip
+target and `--advance` to walk soft transitions to wip — neither of which
+`claim-next` has, since `claim-next` only reserves and never changes status.
 
 ### Niche: Claim Without Transitioning
 
@@ -62,7 +66,8 @@ When passing work between agents, follow this sequence:
 
 1. **Document state**: Add a comment with current progress, decisions made,
    and remaining work
-2. **Update status**: Leave at `in_progress` if partially done, or close if complete
+2. **Update status**: Leave in its working status (`in_progress` / `building` /
+   `fixing`) if partially done, or close if complete
 3. **Flag blockers**: Create blocker issues and add dependencies if needed
 
 ```bash

.agents/skills/filigree-workflow/references/workflow-patterns.md

@@ -95,23 +95,33 @@ filigree remove-dep <blocked> <blocker>
 
 ### Standard Flow
 
+Bugs in the core pack do **not** start in a directly-startable state. They
+open at `triage` and walk soft transitions toward work (run
+`filigree type-info bug` for the authoritative graph):
+
 ```
-create (open) → in_progress → closed
+create (triage) → confirmed → fixing → verifying → closed
 ```
 
-Use `filigree start-work <issue-id> --assignee <name>` to make the
-`open → in_progress` transition atomically.
+`triage` has no single-hop transition into a `wip` status, so a fresh bug is
+*ready* but not *startable*. Pass `--advance` to walk the soft transitions to
+the nearest working status automatically:
 
-### With Verification
+```bash
+filigree start-work <bug-id> --assignee <name> --advance   # triage → confirmed → fixing
+```
 
-For types that support it (check `filigree type-info bug`):
+Without `--advance`, `start-work` on a `triage` bug returns
+`INVALID_TRANSITION` naming the next status (`confirmed`), and
+`start-next-work` skips it.
 
-```
-open → fixing → verifying → closed
-```
+### Disambiguating the wip target
 
-Pass `--target-status fixing` to `start-work` if the workflow has multiple
-`wip`-category targets and the resolver needs disambiguation.
+If the workflow has multiple `wip`-category targets reachable from the
+current status and the resolver needs disambiguation, pass
+`--target-status fixing` to `start-work` / `start-next-work`. (`claim` /
+`claim-next` only reserve and never transition, so they do not take
+`--target-status` or `--advance`.)
 
 ### Bug Report Template
 

.clarion/.gitignore

@@ -0,0 +1,22 @@
+# Clarion .gitignore — ADR-005 tracked-vs-excluded list.
+# Tracked (committed): clarion.db, config.json, .gitignore itself.
+# Excluded (ignored): WAL sidecars, shadow DB, per-run logs, tmp scratch.
+
+# SQLite write-ahead files never belong in the repo.
+*-wal
+*-shm
+*.db-wal
+*.db-shm
+
+# Shadow DB intermediate (ADR-011 --shadow-db).
+*.shadow.db
+*.db.new
+
+# Scratch / temp space.
+tmp/
+
+# Per-run log directories (see detailed-design §File layout). The run dir
+# metadata (config.yaml, stats.json, partial.json) is tracked; only the
+# raw LLM request/response log is excluded.
+logs/
+runs/*/log.jsonl

.clarion/config.json

@@ -0,0 +1,4 @@
+{
+    "schema_version": 1,
+    "last_run_id": null
+}

.clarion/instance_id

@@ -0,0 +1 @@
+07196666-c132-4bff-b9fb-1d0eeff64fdf

.codex/config.toml

@@ -0,0 +1,11 @@
+# Project-local Codex MCP configuration.
+# Codex does not read .mcp.json, so mirror this project's stdio MCP servers here.
+
+[mcp_servers.filigree]
+command = "/home/john/.local/bin/filigree-mcp"
+args = ["--project", "/home/john/clarion"]
+
+[mcp_servers.clarion-dogfood]
+command = "/home/john/clarion/target/release/clarion"
+args = ["serve", "--path", "/home/john/clarion"]
+env = { PATH = "/home/john/clarion/plugins/python/.venv/bin:/home/john/.local/bin:/home/john/elspeth/.venv/bin:/home/linuxbrew/.linuxbrew/bin:/home/linuxbrew/.linuxbrew/sbin:/home/john/.cargo/bin:/home/john/.nvm/versions/node/v20.19.3/bin:/home/john/miniconda/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin" }

.filigree.conf

@@ -0,0 +1,6 @@
+{
+  "version": 1,
+  "project_name": "clarion",
+  "prefix": "clarion",
+  "db": ".filigree/filigree.db"
+}

.github/dependabot.yml

@@ -1,5 +1,10 @@
 version: 2
 updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+
   - package-ecosystem: "pip"
     directory: "/plugins/python"
     schedule:

.github/workflows/ci.yml

@@ -11,20 +11,30 @@ concurrency:
 
 env:
   CARGO_TERM_COLOR: always
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
   RUSTFLAGS: "-D warnings"
 
 jobs:
   rust:
     name: Rust
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
 
-      - uses: dtolnay/rust-toolchain@stable
+      - uses: dtolnay/rust-toolchain@29eef336d9b2848a0b548edc03f92a220660cdb8
         with:
+          toolchain: stable
           components: clippy, rustfmt, llvm-tools-preview
 
-      - uses: Swatinem/rust-cache@v2
+      - uses: Swatinem/rust-cache@e18b497796c12c097a38f9edb9d0641fb99eee32
+
+      # Python is used by the migration-retirement guard and the
+      # workspace-version-lockstep guard below. Pin >= 3.11 explicitly so the
+      # stdlib `tomllib` is available regardless of which Python the runner
+      # image happens to preinstall.
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065
+        with:
+          python-version: "3.11"
 
       - name: fmt
         run: cargo fmt --all -- --check
@@ -34,11 +44,34 @@ jobs:
           python scripts/check-migration-retirement.py --self-test
           python scripts/check-migration-retirement.py
 
+      - name: release governance static guard
+        run: |
+          python scripts/check-github-release-governance.py --self-test
+          python scripts/check-github-release-governance.py --static-only
+
+      - name: cross-workspace version lockstep
+        run: python scripts/check-workspace-version-lockstep.py
+
+      - name: pyright pin lockstep
+        run: |
+          python scripts/check-pyright-pin-lockstep.py --self-test
+          python scripts/check-pyright-pin-lockstep.py
+
+      - name: wardline version bounds
+        run: |
+          python scripts/check-wardline-version-bounds.py --self-test
+          python scripts/check-wardline-version-bounds.py
+
+      - name: entity-cap ADR/code lockstep
+        run: |
+          python scripts/check-entity-cap-lockstep.py --self-test
+          python scripts/check-entity-cap-lockstep.py
+
       - name: clippy
         run: cargo clippy --workspace --all-targets --all-features -- -D warnings
 
       - name: install cargo-nextest
-        uses: taiki-e/install-action@cargo-nextest
+        uses: taiki-e/install-action@e310bff3ef77234d477d6bb655da153a5c49d1db
 
       # Ensure all workspace binaries (notably clarion-plugin-fixture) are built
       # before nextest runs. wp2_e2e tests need the fixture binary on disk and
@@ -52,9 +85,11 @@ jobs:
 
       - name: doc
         run: cargo doc --workspace --no-deps --all-features
+        env:
+          RUSTDOCFLAGS: "-D warnings"
 
       - name: install cargo-deny
-        uses: taiki-e/install-action@cargo-deny
+        uses: taiki-e/install-action@2e721ffcfc34740897fc3130e2dd782b1c136896
 
       - name: deny
         run: cargo deny check
@@ -63,16 +98,16 @@ jobs:
     name: Python plugin
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
 
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065
         with:
           python-version: "3.11"
           cache: pip
           cache-dependency-path: plugins/python/pyproject.toml
 
       - name: cache pyright runtime
-        uses: actions/cache@v4
+        uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830
         with:
           path: ~/.cache/pyright-python/
           key: pyright-python-1.1.409-${{ runner.os }}
@@ -105,20 +140,22 @@ jobs:
     runs-on: ubuntu-latest
     needs: [rust, python-plugin]
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
 
-      - uses: dtolnay/rust-toolchain@stable
+      - uses: dtolnay/rust-toolchain@29eef336d9b2848a0b548edc03f92a220660cdb8
+        with:
+          toolchain: stable
 
-      - uses: Swatinem/rust-cache@v2
+      - uses: Swatinem/rust-cache@e18b497796c12c097a38f9edb9d0641fb99eee32
 
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065
         with:
           python-version: "3.11"
           cache: pip
           cache-dependency-path: plugins/python/pyproject.toml
 
       - name: cache pyright runtime
-        uses: actions/cache@v4
+        uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830
         with:
           path: ~/.cache/pyright-python/
           key: pyright-python-1.1.409-${{ runner.os }}
@@ -128,3 +165,12 @@ jobs:
 
       - name: run walking skeleton
         run: bash tests/e2e/sprint_1_walking_skeleton.sh
+
+      - name: run WP5 secret scanner smoke
+        run: CARGO_BUILD=0 bash tests/e2e/wp5_secret_scan.sh
+
+      - name: Sprint 2 MCP surface
+        run: CARGO_BUILD=0 bash tests/e2e/sprint_2_mcp_surface.sh
+
+      - name: Phase 3 subsystems
+        run: CARGO_BUILD=0 bash tests/e2e/phase3_subsystems.sh