fix(template): rewrite session protocol to produce concrete orientation output

The previous template only defined a First Session Protocol (triggered when no
workstreams existed). When workstreams did exist, get_state_summary() was called
but no output was defined, causing registered-repo Claude sessions to produce
nothing useful.

New 3-step normal session protocol:
- Step 1: get_state_summary() + get_next_steps()
- Step 2: scan workplans/*.md for active tasks (todo/in_progress)
- Step 3: output orientation brief covering active workstreams, pending tasks
  for this repo (from workplans/ + [repo:<slug>] state hub tasks), suggested
  next action, and SBOM status

Also strengthens First Session Protocol, ADR-001 workplan convention section,
and SBOM ingest section (adds SCAN=1 REPO_PATH= flags).

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

scripts/project_claude_md.template

@@ -8,69 +8,84 @@ Hub topic ID: `{TOPIC_ID}`
 The State Hub runs locally at http://127.0.0.1:8000. The MCP server (`state-hub`)
 exposes tools for reading and writing state without touching the API directly.
 
+---
+
 ### Session Protocol
 
-**On receiving your first message — before writing any response text — call
+**On receiving your first message — before writing any response text — execute
-`get_state_summary()` immediately.** Do not greet, do not ask what to do.
+this orientation sequence. Do not greet, do not ask what to do first.**
-Call the tool first, then respond based on what you find.
 
-**At the start of every session:**
+**Step 1 — Call the State Hub**
-1. Call `get_state_summary()` — orients you to active workstreams, blocking decisions,
+```
-   and recent progress. If it fails, the API is likely offline:
+get_state_summary()   # orientation: workstreams, decisions, recent progress
-   ```
+get_next_steps()      # contextual suggestions from resolved decisions
-   cd ~/the-custodian/state-hub && make api
+```
-   ```
+If the call fails, the API is offline: `cd ~/the-custodian/state-hub && make api`
-2. Call `get_next_steps()` — surfaces contextual suggestions from recently resolved
+
-   decisions and cleared workstream dependencies. Act on these before starting new work.
+**Step 2 — Scan local workplans**
-3. Check whether this domain has any open workstreams in the summary.
+
-   - **If workstreams exist:** review blocking decisions before starting work.
+Read every file matching `workplans/*.md` in this repo. For each one with
-   - **If no workstreams exist:** follow the First Session Protocol below.
+`status: active`, extract and note:
+- The workplan title and ID
+- All tasks whose `status` is `todo` or `in_progress`
+
+**Step 3 — Present orientation to the user**
+
+Output a concise brief covering:
+1. **Active workstreams** (from state hub) for the `{DOMAIN}` domain — title,
+   task counts, any blocking decisions
+2. **Pending tasks for this repo** — from local `workplans/` files (Step 2)
+   plus any state hub tasks with `[repo:{REPO_SLUG}]` in their title
+3. **Suggested next action** — the highest-priority open item across both sources
+4. **SBOM status** — is `last_sbom_at` set for this repo? If not, note it as a gap
+
+If there are no workstreams at all: follow the First Session Protocol below.
 
 **During work:**
 - Use `record_decision()` for any decision that affects direction or dependencies.
 - Use `add_progress_event()` for notable events (milestones, blockers, insights).
-- Use `resolve_decision()` to close a decision once the choice is made — this is one
+- Use `resolve_decision()` to close a decision once the choice is made.
-  of the two sanctioned write operations in the hub.
 
 > **Design boundary:** The State Hub is a *read model*. Two write operations are
-> permanently sanctioned: **Resolving Decisions** and **Suggesting Next Steps** (v0.2).
+> permanently sanctioned: **Resolving Decisions** and **Suggesting Next Steps**.
-> The bootstrap tools (`create_workstream`, `create_task`, `update_task_status`) are
+> The bootstrap tools (`create_workstream`, `create_task`, `update_task_status`)
-> only for First Session Protocol. Formal work structure — requirements, workplans,
+> are only for First Session Protocol. Formal work structure — workplans, tasks —
-> milestones, tasks — belongs in the domain repo, not managed through the hub.
+> belongs in the domain repo as files (ADR-001), not managed through the hub alone.
 
 **At the end of every session:**
 - Call `add_progress_event()` with a summary of what was accomplished or decided.
   Include `topic_id: {TOPIC_ID}` and the relevant `workstream_id`.
 
+---
+
 ### First Session Protocol
 
-Triggered when `get_state_summary()` shows **no workstreams** for the `{DOMAIN}` topic.
+Triggered when `get_state_summary()` shows **no workstreams** for the `{DOMAIN}`
-This means the project is registered but work has not yet been structured.
+topic. The project is registered but work has not yet been structured.
 
 **Step 1 — Understand the project (read, don't write)**
-- `canon/projects/{DOMAIN}/project_charter_v0.1.md` — purpose, scope, success criteria
+- `~/the-custodian/canon/projects/{DOMAIN}/project_charter_v0.1.md` — purpose, scope
-- `canon/projects/{DOMAIN}/roadmap_v0.1.md` — planned phases
+- `~/the-custodian/canon/projects/{DOMAIN}/roadmap_v0.1.md` — planned phases
-- Scan the repo root: README, directory structure, any existing code or docs
+- Scan the repo root: README, directory structure, existing code or docs
 
 **Step 2 — Survey in-progress work**
-- Look for TODOs, open branches, half-finished files, or notes
+- Look for TODOs, open branches, half-finished files, notes
 - Note what is already done vs. what is clearly started but incomplete
 
 **Step 3 — Propose workstreams to Bernd**
-Based on what you found, propose 1–3 workstreams. Each workstream should be:
+Propose 1–3 workstreams — each a coherent strand of work lasting weeks to months,
-- A coherent strand of work lasting weeks to months (not a single task)
+named clearly, anchored to a roadmap phase. **Wait for approval before creating.**
-- Named clearly enough that its scope is obvious
-- Anchored to a phase in the roadmap if possible
 
-Present the proposals and **wait for approval before creating anything**.
+**Step 4 — Create workplan file first, then DB record**
-
+Per ADR-001, work items originate as files in the repo:
-**Step 4 — Create and populate (after approval)**
+```
+workplans/<DOMAIN>-WP-NNNN-<slug>.md   ← write this first
+```
+Then register in the hub:
 ```
 create_workstream(topic_id="{TOPIC_ID}", title="...", owner="...", description="...")
 create_task(workstream_id="<id>", title="...", priority="high|medium|low")
-# repeat for each task in the workstream
 ```
-Aim for 3–7 tasks per workstream at this stage. Tasks should be concrete and actionable.
 
 **Step 5 — Record the setup**
 ```
@@ -82,12 +97,28 @@ add_progress_event(
 )
 ```
 
+---
+
+### Workplan Convention (ADR-001)
+
+Work items MUST originate as files in this repo before being registered in the hub.
+
+**File location:** `workplans/<ID>-<slug>.md`
+**Frontmatter required:** `id`, `type: workplan`, `domain`, `repo`, `status`,
+`state_hub_workstream_id`, `state_hub_task_id` (per task)
+
+When the custodian creates a task targeting this repo from another session, it:
+1. Creates a state hub task with `[repo:{REPO_SLUG}]` in the title
+2. Creates a workplan file in this repo's `workplans/`
+3. You will see both at session start via the orientation sequence above
+
+---
+
 ### Contribution Tracking
 
-This project tracks upstream contributions in `contrib/` — bug reports, feature
+Track upstream contributions in `contrib/` — bug reports (BR), feature requests
-requests, extension-point proposals, and upstream PRs — as canonical Markdown files.
+(FR), extension-point proposals (EP), upstream PRs (UPR).
 
-**Directory layout:**
 ```
 contrib/
   bug-reports/       # br-YYYY-MM-DD--org--repo--slug.md
@@ -99,46 +130,27 @@ contrib/
 Templates: `~/the-custodian/canon/standards/contrib-templates/`
 Convention: `~/the-custodian/canon/standards/contribution-convention_v0.1.md`
 
-**Register a contribution in the State Hub:**
-```
-register_contribution(
-    type="upr",             # br | fr | ep | upr
-    title="Add injectTocTop to Observable Framework",
-    target_org="observablehq",
-    target_repo="framework",
-    body_path="contrib/upstream-prs/2026-02-26--observablehq--framework--inject.md",
-    related_workstream_id="<uuid>",
-)
-```
-
-**Update status when upstream responds:**
 ```
+register_contribution(type="br|fr|ep|upr", title="...", target_org="...",
+    target_repo="...", body_path="contrib/...", related_workstream_id="<uuid>")
 update_contribution_status(contribution_id="<uuid>", status="submitted")
-# then: acknowledged → accepted → merged
 ```
 
-**List all contributions for this domain:**
+---
-```
-get_contributions(target_repo="framework")
-```
 
 ### SBOM
 
-Software Bill of Materials for this repo is tracked in the State Hub.
+After updating dependencies, re-ingest the SBOM:
-
-**Ingest the current lockfile:**
 ```bash
 cd ~/the-custodian/state-hub
-make ingest-sbom REPO={REPO_SLUG}
+make ingest-sbom REPO={REPO_SLUG} SCAN=1 REPO_PATH=$(pwd)
 ```
 
-**Check licence risk:**
+Check compliance: `http://localhost:3000/repos`
-```
+Standard: `~/the-custodian/canon/standards/sbom-convention_v0.1.md`
-get_licence_report()
-```
 
-**View SBOM dashboard:** `http://localhost:3000/sbom`
+---
 
 ### Quick Reference
 
-See `~/the-custodian/state-hub/mcp_server/TOOLS.md` for a compact tool reference.
+`~/the-custodian/state-hub/mcp_server/TOOLS.md` — compact MCP tool reference