From 2b36fc187d070ead8d509a7a6b5d0885dee15ec3 Mon Sep 17 00:00:00 2001
From: tegwick <bernd.worsch@gmail.com>
Date: Sat, 5 Sep 2026 20:38:30 +0200
Subject: [PATCH] Complete PQRST-WP-0001: bootstrap State Hub integration
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

T01 — Reviewed the generated integration files. Resolved the
{CREDENTIAL_ROUTING} placeholder in AGENTS.md from the fleet canon, refreshed
the SCOPE.md repository layout (stale after registration), and replaced the
README stub with orientation and entry points.

T02 — Documented the developer workflow in AGENTS.md. This is a Markdown-only
spec repository: nothing to install, build, or run, and no test suite. In place
of a toolchain, added a six-point verification checklist covering prompt/spec
coupling, the closed 5-tuple, example-record arithmetic, cross-references,
version discipline, and the append-only rule for history/. The signature
validation command is verified working — all nine example signatures sum to 100.

T03 — Seeded PQRST-WP-0002 "Validate spec v0.1 against real sessions and cut
v0.2": pilot the closing prompt unassisted on at least eight real sessions,
decide the record-storage boundary SCOPE.md leaves open, then revise. v0.1 was
consolidated from two drafts neither of which had been applied to a session, so
the open questions are empirical rather than editorial.

WP-0001 marked finished with DoR/DoD assessments (clears C-34). No open
residuals — the follow-on work is carried by PQRST-WP-0002.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SQ6oF1DtVDKcD1FCpvRVLx

Assistant: claude-code
Assistant-Model: opus
Assistant-Process: 272883@bnt-lap001
Assistant-Session: f40c8f53-fb65-4980-9d29-bcdb3dd946f7
---
 AGENTS.md                                     | 129 +++++++++++++++++-
 README.md                                     |  48 ++++++-
 SCOPE.md                                      |  12 +-
 workplans/PQRST-WP-0001-statehub-bootstrap.md |  26 +++-
 ...0002-validate-v01-against-real-sessions.md | 125 +++++++++++++++++
 5 files changed, 333 insertions(+), 7 deletions(-)
 create mode 100644 workplans/PQRST-WP-0002-validate-v01-against-real-sessions.md

diff --git a/AGENTS.md b/AGENTS.md
index 39b89d7..c2df2d8 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -123,7 +123,56 @@ curl -s -X PATCH "http://127.0.0.1:8000/tasks/<task_id>" \
 
 ---
 
-{CREDENTIAL_ROUTING}
+## Credential and access routing
+
+**Audience:** Codex, Claude Code, Grok, and custodian agents that call **llm-connect**
+for inference. Run this check **before** requesting secrets, API keys, SSH access,
+login tokens, or database passwords — in any repo, not only `ops-warden`.
+
+ops-warden **issues SSH certificates only** (`warden sign`, `cert_command`). Every
+other credential need belongs to another subsystem. **Do not** message
+`ops-warden` on State Hub expecting a secret value; the reply is a pointer, not a key.
+
+### Lookup (do this first)
+
+```bash
+warden route find "<describe your need>" --json
+warden route show <catalog-id> --json
+```
+
+Requires the `warden` CLI from `~/ops-warden` (`uv tool install .` or `uv run warden`).
+
+| Agent runtime | How to orient |
+| --- | --- |
+| **Codex / Grok** (shell, HTTP State Hub) | `warden route` commands above; inbox `to_agent=pqrst-practice` is for coordination, not secret vending |
+| **Claude Code** (MCP when available) | `get_domain_summary("custodian")` for workplans; **still** use `warden route` for credential ownership |
+| **llm-connect** (inference service) | Never put secret retrieval in prompts; route custody to OpenBao/operator paths surfaced by `warden route` |
+
+### Quick routing table
+
+| I need… | Owner | ops-warden executes? |
+| --- | --- | --- |
+| SSH cert (`adm`/`agt`/`atm`) | ops-warden | **Yes** — `warden sign` |
+| API key, DB password, provider token | OpenBao (`railiance-platform`) | No — route only |
+| Login / OIDC / MFA | key-cape / Keycloak | No — route only |
+| Authorization decision | flex-auth | No — route only |
+| activity-core → issue-core emission | activity-core + issue-core | No — `warden route show activity-core-issue-sink` |
+| SSH tunnel | ops-bridge (+ `cert_command` from warden) | No — route only |
+
+### Anti-patterns (do not do these)
+
+- `POST /messages/` to `ops-warden` asking for `ISSUE_CORE_API_KEY`, `OPENROUTER_API_KEY`, etc.
+- Inventing `warden secret`, `warden login`, `warden bao`, `warden tunnel` — they do not exist
+- Pasting secrets into Git, State Hub, workplans, logs, or chat
+
+### Other capabilities (reuse-surface)
+
+Non-credential capabilities are usually discovered through **reuse-surface** federation
+(`reuse-surface` registry / `capability.*` indexes). Credential routing is inlined in
+every repo's agent instructions because it is high-frequency, high-risk, and easy to
+get wrong.
+
+**Canon:** `~/ops-warden/wiki/CredentialRouting.md` · catalog `~/ops-warden/registry/routing/catalog.yaml`
 
 <!-- REPO-AGENTS-EXTENSIONS -->
 <!-- Append repo-specific agent instructions below this marker.
@@ -203,3 +252,81 @@ To create a new workplan:
 1. Write the file following the format above
 2. Run `uv run --project ~/repo-manager rmgr sync --path . --push`.
 3. Run `statehub fix-consistency` only when a separate deep audit is needed.
+
+---
+
+## Repo-Specific Working Notes
+
+### What this repo is
+
+A **specification-and-prompt repository**. Every tracked file is Markdown except
+`.repo-classification.yaml`. There is no application code, no package manifest,
+and no runtime. Read [`INTENT.md`](INTENT.md) and [`SCOPE.md`](SCOPE.md) before
+changing anything — SCOPE.md is normative about what must *not* be added here.
+
+The deliverables are:
+
+| File | Role |
+| --- | --- |
+| `spec/PqrstEstimationPractice.md` | The normative specification. Versioned. |
+| `PqrstPrompt.md` | The canonical end-of-session prompt operators paste. |
+| `INTENT.md` / `SCOPE.md` | Why the practice exists; what belongs here. |
+| `history/` | Source drafts. **Append-only — never edit an existing file.** |
+
+### Developer workflow
+
+There is nothing to install, build, or run.
+
+| Step | Command | Notes |
+| --- | --- | --- |
+| Install | — | No dependencies. |
+| Build | — | No build step. |
+| Run | — | Nothing executes; the prompt is pasted into a session by an operator. |
+| Test | — | No test suite. Verification is the checklist below. |
+| Lint | — | No linter is configured. Match surrounding Markdown style. |
+| Sync | `uv run --project ~/repo-manager rmgr sync --path . --push` | After workplan file changes. |
+| Audit | `statehub fix-consistency` | Deep audit; also regenerates `WORK-RECORDS.md`. |
+
+Do not add a toolchain to make this table look fuller. A validator, collector,
+or CI harness for PQRST records is explicitly out of scope (`SCOPE.md`) and
+belongs in a consuming repository.
+
+### Verification checklist
+
+Run this before committing a change to the spec or the prompt. It is a reading
+task, not a command — the coupling between the two files is the thing that
+breaks.
+
+1. **Prompt matches spec.** Every rule in the prompt's `Rules:` list has a
+   corresponding rule in spec §3, and the prompt's output block matches the
+   stored-record format in spec §5.1 field for field.
+2. **The 5-tuple is closed.** No change introduces a sixth dimension, and
+   confidence stays outside P/Q/R/S/T (spec R9, R10).
+3. **Examples validate.** Every example record in the repo satisfies spec §5.5.
+   The arithmetic can be checked mechanically:
+
+   ```bash
+   grep -rhoE 'P[0-9]+ Q[0-9]+ R[0-9]+ S[0-9]+ T[0-9]+' --include='*.md' . \
+     | sort -u \
+     | awk '{sig=$0; s=0; for(i=1;i<=NF;i++){gsub(/[PQRST]/,"",$i); s+=$i}
+            printf "%-28s %s\n", sig, (s==100 ? "ok" : "SUM=" s)}'
+   ```
+
+   Every line must report `ok`.
+4. **Cross-references resolve.** Relative links between `INTENT.md`,
+   `SCOPE.md`, `PqrstPrompt.md`, and `spec/` still point at existing files and
+   sections.
+5. **Version discipline.** A change to a dimension's meaning, the validation
+   rules, or the stored record format is **breaking**: bump the spec version,
+   add a row to its Appendix B, and say plainly that older records are less
+   comparable. Editorial changes need no bump.
+6. **`history/` untouched.** `git diff --stat history/` is empty.
+
+### Conventions
+
+- The specification is the source of truth; `PqrstPrompt.md` follows it, never
+  the reverse.
+- Prefer prose the operator can act on at 11pm at the end of a long session.
+  Terse beats thorough in `PqrstPrompt.md`; thorough beats terse in `spec/`.
+- Keep the anti-goals in `INTENT.md` intact when editing. They are the load-
+  bearing part of the practice, not framing.
diff --git a/README.md b/README.md
index e78c702..f1bb60f 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,49 @@
 # pqrst-practice
 
-lightweight retrospective audit for agentic coding sessions on problem/quality/research/security/task-organization
\ No newline at end of file
+A lightweight retrospective audit for closing agentic coding sessions: a forced
+100% allocation of a session's effective engineering effort across five stable
+dimensions — **P**roblem, **Q**uality, **R**esearch, **S**ecurity, **T**ask
+organization.
+
+> Where did the effective engineering effort of this session actually go?
+
+## Start here
+
+| I want to… | Read |
+| --- | --- |
+| Close a session right now | [`PqrstPrompt.md`](PqrstPrompt.md) — paste it, done |
+| Understand the model | [`spec/PqrstEstimationPractice.md`](spec/PqrstEstimationPractice.md) (v0.1) |
+| Know why it exists, and what it must not become | [`INTENT.md`](INTENT.md) |
+| Know what belongs in this repo | [`SCOPE.md`](SCOPE.md) |
+| Work in this repo as an agent | [`AGENTS.md`](AGENTS.md) |
+
+## What a record looks like
+
+```text
+PQRST-Estimate
+P: 25%
+Q: 15%
+R: 45%
+S: 0%
+T: 15%
+Sum: 100%
+Confidence: medium
+Signature: P25 Q15 R45 S0 T15
+Dominant factors: Existing auth middleware was undocumented and contradicted the
+README, so most attention went to reconstructing the request path before
+changing behavior.
+```
+
+The numbers are the index. The `Dominant factors` sentence is the content — a
+signature stored without it is not auditable.
+
+## What this is not
+
+Not a productivity score, not telemetry, not a planning target. There is no good
+profile: an exploration session is R-heavy, a hardening session Q-heavy, a
+credential integration S-heavy. The practice fails the moment anyone tries to
+score well on it.
+
+This repository defines the practice and supplies the prompt. Collectors,
+validators, dashboards, and record storage belong elsewhere — see
+[`SCOPE.md`](SCOPE.md).
diff --git a/SCOPE.md b/SCOPE.md
index a510223..0e6fb62 100644
--- a/SCOPE.md
+++ b/SCOPE.md
@@ -80,14 +80,24 @@ These hold across all versions:
 INTENT.md                        why this practice exists and what it must not become
 SCOPE.md                         this file
 PqrstPrompt.md                   the canonical end-of-session prompt
-README.md                        one-line orientation
+README.md                        orientation and entry points
+AGENTS.md                        agent instructions, developer workflow, verification checklist
 spec/
   PqrstEstimationPractice.md     the specification (v0.1)
 history/
   20260905-*_chatgpt.md          source draft, retained unmodified
   20260905-*_grok.md             source draft, retained unmodified
+workplans/                       work records for this repo (State Hub convention)
 ```
 
+State Hub integration files — `.custodian-brief.md`, `.repo-classification.yaml`,
+and `WORK-RECORDS.md` — are generated and kept in sync by `statehub` /
+`repo-manager`. They are not edited by hand.
+
+The repo is registered in the Custodian State Hub under domain `agents`, topic
+`practice` ("prestructured actions that are less complex than a process but more
+ambitious and structured than a task"), with workplan prefix `PQRST-WP`.
+
 ---
 
 ## Change process
diff --git a/workplans/PQRST-WP-0001-statehub-bootstrap.md b/workplans/PQRST-WP-0001-statehub-bootstrap.md
index 2bfa6e3..cea9eba 100644
--- a/workplans/PQRST-WP-0001-statehub-bootstrap.md
+++ b/workplans/PQRST-WP-0001-statehub-bootstrap.md
@@ -4,11 +4,21 @@ type: workplan
 title: "Bootstrap State Hub integration"
 domain: agents
 repo: pqrst-practice
-status: ready
+status: finished
 owner: codex
 topic_slug: practice
 created: "2026-09-05"
 updated: "2026-09-05"
+quality_dor: DoR-Ok
+quality_dor_at: "2026-09-05"
+quality_dor_by: claude-code
+quality_dor_note: "Bootstrap plan generated by statehub register; scope was fixed and fully known at creation."
+quality_dod: DoD-Ok
+quality_dod_at: "2026-09-05"
+quality_dod_by: claude-code
+quality_dod_note: "T01 resolved the CREDENTIAL_ROUTING placeholder and refreshed SCOPE.md/README.md; T02 documented the (empty) toolchain and a verification checklist in AGENTS.md, checklist command run and passing; T03 seeded PQRST-WP-0002. Residual handed off as PQRST-WP-0002."
+related:
+  - PQRST-WP-0002
 state_hub_workstream_id: "a1774666-54fd-58c8-b093-7fb40c468c86"
 ---
 
@@ -16,11 +26,19 @@ state_hub_workstream_id: "a1774666-54fd-58c8-b093-7fb40c468c86"
 
 Retrospective PQRST estimation practice for closing agentic coding sessions.
 
+**Outcome:** integration files reviewed and completed, the developer workflow
+(there is no toolchain) and a verification checklist documented in `AGENTS.md`,
+and `PQRST-WP-0002` seeded as the first real workplan.
+
+**Residuals:** none open. The substantive follow-on work — validating v0.1
+against real sessions and deciding where records are stored — is carried by
+`PQRST-WP-0002`.
+
 ## Review Generated Integration Files
 
 ```task
 id: PQRST-WP-0001-T01
-status: todo
+status: done
 priority: high
 state_hub_task_id: "9dd0cdb6-a0bb-5355-9804-eb7dd40c45f2"
 ```
@@ -32,7 +50,7 @@ Replace generated placeholders with repo-specific facts where needed.
 
 ```task
 id: PQRST-WP-0001-T02
-status: todo
+status: done
 priority: high
 state_hub_task_id: "1100f857-e774-5861-9b03-e6cfd2472a4b"
 ```
@@ -45,7 +63,7 @@ changes confidently.
 
 ```task
 id: PQRST-WP-0001-T03
-status: todo
+status: done
 priority: medium
 state_hub_task_id: "174d689e-5fc4-5fe1-93cb-1fcf0f801e7f"
 ```
diff --git a/workplans/PQRST-WP-0002-validate-v01-against-real-sessions.md b/workplans/PQRST-WP-0002-validate-v01-against-real-sessions.md
new file mode 100644
index 0000000..24a1102
--- /dev/null
+++ b/workplans/PQRST-WP-0002-validate-v01-against-real-sessions.md
@@ -0,0 +1,125 @@
+---
+id: PQRST-WP-0002
+type: workplan
+title: "Validate spec v0.1 against real sessions and cut v0.2"
+domain: agents
+repo: pqrst-practice
+status: proposed
+owner: claude-code
+topic_slug: practice
+priority: high
+created: "2026-09-05"
+updated: "2026-09-05"
+quality_dor: DoR-Ok
+quality_dor_at: "2026-09-05"
+quality_dor_by: claude-code
+quality_dor_note: "v0.1 consolidates two drafts that were written without either being applied to a session. Every open question is empirical — whether the prompt returns a valid record unassisted, whether attribution by primary purpose is decidable in practice, and where records are stored — so the next change is a bounded pilot, not more specification."
+related:
+  - PQRST-WP-0001
+---
+
+# Validate spec v0.1 against real sessions and cut v0.2
+
+Spec v0.1 was consolidated from two independent drafts, neither of which had
+been applied to an actual session. It is internally consistent and entirely
+unvalidated.
+
+The purpose of this workplan is to find out where the practice is wrong by using
+it, then cut v0.2 from the findings. It deliberately does **not** build tooling
+or a record store — both are out of scope for this repository (`SCOPE.md`).
+
+**Done when:** the prompt has been run unassisted at the end of at least eight
+real sessions, the friction is written down, the storage boundary is decided,
+and v0.2 either incorporates the findings or records why v0.1 stands.
+
+## Pilot the closing prompt on real sessions
+
+```task
+id: PQRST-WP-0002-T01
+status: todo
+priority: high
+```
+
+Paste `PqrstPrompt.md` unmodified at the end of at least **eight** real agentic
+coding sessions, spread across at least three repositories and at least two task
+classes (e.g. `feature`, `bugfix`, `explore`, `harden`).
+
+Do not coach the model, do not repair a malformed answer, and do not re-run the
+prompt for a better result. A rejected record is the finding.
+
+For each session capture, in this file under "Pilot findings":
+
+- the returned record verbatim;
+- whether it passed spec §5.5 validation on the first attempt;
+- whether `Dominant factors` cited concrete session facts or restated the
+  percentages;
+- any dimension the model hedged on, refused, or visibly guessed at;
+- the task class and the repository.
+
+The specific questions to answer:
+
+1. Does an uncoached agent return a **valid** record from the prompt alone?
+2. Is "attribute by primary purpose" (spec R5) actually decidable mid-estimate,
+   or does it collapse under overlap?
+3. Does S stay at 0 when security work did not occur, or does it drift upward?
+4. Do estimates cluster at coarse increments (R7), or does false precision
+   reappear?
+5. Is `Confidence` used meaningfully, or is it always `medium`?
+
+## Decide the record-storage boundary
+
+```task
+id: PQRST-WP-0002-T02
+status: todo
+priority: high
+```
+
+`SCOPE.md` excludes record storage from this repository but does not say where
+records go instead. Until that is answered the practice produces records with
+nowhere to live, and the trend analysis that justifies the whole exercise
+(spec §8, §9) cannot happen.
+
+Decide and record the answer as a decision (`POST /decisions/`, then an ADR in
+this repo if the decision has repo-local consequences). Options to weigh:
+
+- a State Hub surface (progress events already carry free text; a dedicated
+  record type would need a hub change and is a bigger commitment);
+- an append-only file in each consuming repository;
+- a separate collection repository outside this one.
+
+Whatever is chosen, this repository still ships no collector — the decision
+names the owner, it does not move the work here.
+
+## Cut spec v0.2
+
+```task
+id: PQRST-WP-0002-T03
+status: todo
+priority: medium
+```
+
+From the pilot findings, revise the specification and prompt together:
+
+- fix rules the pilot showed to be undecidable or routinely ignored;
+- tighten or relax the validation rules based on what actually failed;
+- add the storage-boundary decision from T02 as a `SCOPE.md` cross-reference;
+- bump to **v0.2** and add a row to the spec's Appendix B.
+
+If a change alters a dimension's meaning, the validation rules, or the stored
+record format, say plainly in Appendix B that records made under v0.1 are less
+comparable.
+
+If the pilot surfaces nothing substantive, record that outcome and leave v0.1
+standing. "No change needed, and here is the evidence" is a valid result and a
+better one than churn.
+
+Run the verification checklist in `AGENTS.md` before committing, then sync:
+
+```bash
+uv run --project ~/repo-manager rmgr sync --path . --push
+```
+
+## Pilot findings
+
+_Populated by T01. One subsection per session: repository, task class, the
+verbatim record, and whether it validated unassisted._