WS6 — Guidance Maturity: CLI authoring, staleness findings, import/export

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

@@ -271,11 +271,11 @@ are for "hmm, this might be worth looking at" — the uncertain middle ground.
 
 Observations expire after 14 days. Triage them before they rot:
 
-1. **At session end:** run `list_observations` and quickly scan what's accumulated
+1. **At session end:** run `observation_list` and quickly scan what's accumulated
 2. **For each observation, decide:**
    - **Dismiss** — not actionable, already fixed, or not worth tracking. Use
-     `dismiss_observation` with a brief reason for the audit trail.
-   - **Promote** — deserves to be tracked as an issue. Use `promote_observation`
+     `observation_dismiss` with a brief reason for the audit trail.
+   - **Promote** — deserves to be tracked as an issue. Use `observation_promote`
      which atomically creates an issue and labels it `from-observation`. Choose
      the right issue type:
      - `type='bug'` — something is broken or produces wrong results
@@ -285,7 +285,7 @@ Observations expire after 14 days. Triage them before they rot:
    - **Leave it** — still uncertain. Let it age. If it survives a few sessions
      without being promoted, it's probably a dismiss.
 
-3. **Batch cleanup:** use the MCP tool `batch_dismiss_observations` when several observations
+3. **Batch cleanup:** use the MCP tool `observation_batch_dismiss` when several observations
    have gone stale together.
 
 ### Promote vs Dismiss
@@ -319,6 +319,6 @@ filigree search "from-observation"         # Search with context
 | "This task is bigger than expected" | Create sub-tasks, add deps |
 | "I'm done" | Comment, close with reason, check `ready` |
 | "Something changed while I worked" | `filigree changes --since <timestamp>` |
-| "I noticed something odd in a file I'm passing through" | `observe` with file_path and line — keep working |
+| "I noticed something odd in a file I'm passing through" | `observation_create` with file_path and line — keep working |
 | "I noticed a gap in the work I'm currently doing" | Fix it, expand the task, or file a proper issue — **do not** observe it |
-| "These observations are piling up" | `list_observations`, then dismiss or promote each |
+| "These observations are piling up" | `observation_list`, then dismiss or promote each |

.clarion/.gitignore

@@ -7,6 +7,7 @@
 # change on every analyze run, so they are NOT tracked (untracked 2026-06-02).
 clarion.db
 instance_id
+clarion.lock
 
 # SQLite write-ahead files never belong in the repo.
 *-wal

.github/workflows/docs.yml

@@ -27,10 +27,10 @@ jobs:
     name: Build + deploy
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
         with:
           fetch-depth: 0
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405
         with:
           python-version: "3.13"
           cache: pip

.github/workflows/release.yml

@@ -67,9 +67,29 @@ 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: rust clippy
         run: cargo clippy --workspace --all-targets --all-features -- -D warnings
 
@@ -133,20 +153,20 @@ jobs:
 
   release-governance:
     name: GitHub release governance
-    # Enforcement temporarily neutered: the repo's baseline governance is being
-    # rebaselined and release-control enforcement is moving to a separate app.
-    # The GOV-01/GOV-02 rulesets this job asserted are intentionally relaxed, so
-    # the live-ruleset check is replaced with a no-op notice. The job and its
-    # place in the build-rust / build-plugin `needs:` chain are retained so the
-    # static guard (check-github-release-governance.py --static-only) stays
-    # satisfied. Restore the enforcement step below — and the rulesets — when the
-    # new governance baseline lands (clarion-5d0bf8b51e).
     runs-on: ubuntu-latest
+    permissions:
+      contents: read
     steps:
-      - name: release governance (temporarily disabled)
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
+
+      - name: enforce repository release controls
+        env:
+          GH_TOKEN: ${{ secrets.RELEASE_GOVERNANCE_TOKEN }}
         run: |
-          echo "release-governance enforcement is temporarily disabled (clarion-5d0bf8b51e)."
-          echo "GOV-01/GOV-02 rulesets are intentionally relaxed during governance rebaselining."
+          set -euo pipefail
+          python scripts/check-github-release-governance.py \
+            --repository "${GITHUB_REPOSITORY}" \
+            --branch main
 
   build-rust:
     needs: [verify, release-governance]

AGENTS.md

@@ -231,7 +231,7 @@ When you are unsure, say what evidence is missing and go get it if it is cheap.
 When evidence is expensive or requires credentials, explain the limitation and
 the next command a maintainer can run.
 
-<!-- filigree:instructions:v2.2.0:9dff6e6d -->
+<!-- filigree:instructions:v2.3.0:108d0005 -->
 ## Filigree Issue Tracker
 
 `filigree` tracks tasks for this project. Data lives in `.filigree/`. Prefer
@@ -253,29 +253,29 @@ filigree start-work <id> --assignee <name>
 filigree close <id>
 ```
 
-Use the atomic claim+transition verbs — `start_work` / `start_next_work`
+Use the atomic claim+transition verbs — `work_start` / `work_start_next`
 (MCP) or `start-work` / `start-next-work` (CLI). Do **not** chain
-`claim_issue` (MCP) or `filigree claim` (CLI) with a subsequent status
+`work_claim` (MCP) or `filigree claim` (CLI) with a subsequent status
 update — the two-step form races against other agents; the combined verb is
 atomic.
 
 **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 (`triage → confirmed → fixing`), so a triage
-bug is *ready* but not directly *startable*: `start_work` on one returns
-`INVALID_TRANSITION` naming the next status, and `start_next_work` skips it.
-`get_ready` items carry a `startable` flag (plus a `next_action` hint when
+bug is *ready* but not directly *startable*: `work_start` on one returns
+`INVALID_TRANSITION` naming the next status, and `work_start_next` skips it.
+`work_ready` items carry a `startable` flag (plus a `next_action` hint when
 false). Pass `advance=true` (MCP) / `--advance` (CLI) to walk the soft
 transitions to the nearest working status automatically.
 
 ### Observations: when (and when not) to use them
 
-`observe` is a fire-and-forget scratchpad for *incidental* defects — things
+`observation_create` is a fire-and-forget scratchpad for *incidental* defects — things
 you notice *outside the scope of your current task* (a code smell in a
 neighbouring file, a stale TODO, a missing test for an edge case you happened
 to spot). Notes expire after 14 days unless promoted. Include `file_path` and
-`line` when relevant. At session end, skim `list_observations` and either
-`dismiss_observation` or `promote_observation` for what has accumulated.
+`line` when relevant. At session end, skim `observation_list` and either
+`observation_dismiss` or `observation_promote` for what has accumulated.
 
 **You fix bugs in your currently defined scope. You do NOT use observations
 to finish work prematurely.** If a defect, gap, or follow-up belongs to your
@@ -300,27 +300,27 @@ MCP tool schemas describe each tool; `filigree --help` and `filigree <verb>
 --help` are the authoritative CLI reference. You do not need to memorise
 either catalogue. The verbs you will reach for most:
 
-- **Find work:** `get_ready`, `get_blocked`, `list_issues`, `search_issues`
-- **Claim work:** `start_work`, `start_next_work`
-- **Update:** `add_comment`, `add_label`, `update_issue`, `close_issue`
-- **Admin (irreversible):** `delete_issue` (MCP) / `delete-issue` (CLI) —
-  hard-deletes a terminal issue and its rows; `undo_last` cannot reverse it.
-- **Scratchpad:** `observe`, `list_observations`, `promote_observation`, `dismiss_observation`
-- **Cross-product entity bindings (ADR-029):** `add_entity_association`,
-  `remove_entity_association`, `list_entity_associations`,
-  `list_associations_by_entity`. Used when a sibling tool (e.g.
+- **Find work:** `work_ready`, `work_blocked`, `issue_list`, `issue_search`
+- **Claim work:** `work_start`, `work_start_next`
+- **Update:** `comment_add`, `label_add`, `issue_update`, `issue_close`
+- **Admin (irreversible):** `issue_delete` (MCP) / `delete-issue` (CLI) —
+  hard-deletes a terminal issue and its rows; `admin_undo_last` cannot reverse it.
+- **Scratchpad:** `observation_create`, `observation_list`, `observation_promote`, `observation_dismiss`
+- **Cross-product entity bindings (ADR-029):** `entity_association_add`,
+  `entity_association_remove`, `entity_association_list`,
+  `entity_association_list_by_entity`. Used when a sibling tool (e.g.
   Clarion) needs to bind a Filigree issue to a function, class, or
   module identifier it owns. The `entity_id` is an opaque string
   from Filigree's perspective; the consumer (the sibling tool's read
   path) does drift detection against the stored
-  `content_hash_at_attach`. `list_associations_by_entity` is the
+  `content_hash_at_attach`. `entity_association_list_by_entity` is the
   reverse-lookup surface — given a Clarion entity ID, return every
   Filigree issue bound to it (project isolation is by DB file). Also
   reachable over HTTP as
   `GET/POST /api/issue/{issue_id}/entity-associations`,
   `DELETE /api/issue/{issue_id}/entity-associations?entity_id=…`,
   and `GET /api/entity-associations?entity_id=…`.
-- **Health:** `get_stats`, `get_metrics`, `get_mcp_status`
+- **Health:** `stats_get`, `metrics_get`, `mcp_status_get`
 
 Pass `--actor <name>` (CLI) so events attribute to your agent identity. It
 works in either position — before the verb (`filigree --actor X update …`) or
@@ -336,7 +336,7 @@ Errors return `{error: str, code: ErrorCode, details?: dict}`. Switch on
 `CLARION_REGISTRY_VERSION_MISMATCH`, `BRIEFING_BLOCKED`, `STOP_FAILED`,
 `SCHEMA_MISMATCH`, `INTERNAL`.
 
-On `INVALID_TRANSITION`, call `get_valid_transitions` (MCP) or
+On `INVALID_TRANSITION`, call `workflow_transition_list` (MCP) or
 `filigree transitions <id>` to see what the workflow allows from here.
 
 Two failure modes deserve a specific response:

CHANGELOG.md

@@ -12,8 +12,44 @@ only when an incompatible change is made to that surface. See
 
 ## [Unreleased]
 
+### Changed
+
+- Refreshed release-facing README/index documentation for the current 1.2.0
+  release line, including the 39-tool MCP surface, current install artifact
+  names, fixed ADR/docset links, current web/operator quick starts, and the full
+  end-to-end verification list.
+- Archived tracked architecture-analysis working notes out of live `temp/`
+  directories under `docs/archive/working-notes/`.
+
+## [1.2.0] — 2026-06-03
+
 ### Added
 
+- **Guidance maturity — WS6 (REQ-GUIDANCE-03/-05/-06; ADR-007, ADR-024).** The
+  guidance system moves from schema baseline to operator-usable.
+  - **`clarion guidance` CLI** — `create` / `edit` (`$EDITOR`) / `show` / `list`
+    / `delete` / `export` / `import`. Match-rule syntax (`path:` / `tag:` /
+    `kind:` / `subsystem:` / `entity:`), scope-levels (project→function), and
+    `--expires` normalisation to a full ISO-8601 instant. Sheets are written via a
+    new non-run-scoped `clarion-storage` guidance API, and the rule-matcher is
+    lifted into `clarion-storage` as the single source of truth shared by the CLI,
+    `analyze`, and the MCP read path.
+  - **Staleness findings (`analyze`).** `CLA-FACT-GUIDANCE-ORPHAN` (WARN) now also
+    fires for a `match_rules {entity:…}` rule pointing at a deleted entity (was
+    `guides`-edge only); new `CLA-FACT-GUIDANCE-EXPIRED` (INFO) and
+    `CLA-FACT-GUIDANCE-CHURN-STALE` (WARN, confidence 0.7 heuristic, asymmetric
+    threshold 50 / 20-pinned). Surfaced via `clarion guidance list --stale`
+    (review-cadence age) / `--expired`. CHURN-STALE is honest-empty until
+    `git_churn_count` population lands.
+  - **Team import/export.** `export --to <dir>` / `import <dir>` — deterministic
+    one-file-per-sheet sorted-key JSON, additive idempotent import, loud-fail on
+    malformed input.
+  - **Cache invalidation.** Authoring (create / edit / delete / import) eagerly
+    invalidates the summary cache of matched entities (ADR-007 churn-eager
+    invalidation).
+  - Deferred with tracking issues: the agent-mediated propose→promote lifecycle
+    (no observation-write transport), Wardline-derived generation, the in-browser
+    staleness-review UI, and guidance composition into summary generation.
 - **Git-rename provider seam now operative — WS9 / SEI §6 (REQ-C-05).** `analyze`
   drives the committed rename window so the `legis` `GitRenameSource` is actually
   consulted, closing the window gap previously surfaced in
@@ -107,6 +143,16 @@ only when an incompatible change is made to that surface. See
     adds no policy/attestation engine — Wardline analyses, `legis` governs,
     attestations key on Clarion's SEI.
 
+### Fixed
+
+- **`guidance_for` no longer drops expiry-bearing sheets in production.** The MCP
+  read path compared a sheet's ISO `expires` lexically against the server clock,
+  whose production default is a `unix:<seconds>` string — so every sheet carrying
+  any `expires` sorted as "expired" and was silently excluded from composition.
+  The comparison now parses both forms to seconds (fail-open on unparseable
+  input), guarded by a regression test that runs under the production clock
+  (clarion-3153e74f0b).
+
 ## [1.1.0] — 2026-05-31
 
 ### Added
@@ -420,7 +466,8 @@ normative.
 - Operator guides under [`docs/operator/`](docs/operator/) — getting-started,
   OpenRouter setup, HTTP read API.
 
-[Unreleased]: https://github.com/tachyon-beep/clarion/compare/v1.1.0...HEAD
+[Unreleased]: https://github.com/tachyon-beep/clarion/compare/v1.2.0...HEAD
+[1.2.0]: https://github.com/tachyon-beep/clarion/compare/v1.1.0...v1.2.0
 [1.1.0]: https://github.com/tachyon-beep/clarion/compare/v1.0.1...v1.1.0
 [1.0.1]: https://github.com/tachyon-beep/clarion/compare/v1.0.0...v1.0.1
 [1.0.0]: https://github.com/tachyon-beep/clarion/releases/tag/v1.0.0