docs: fill DISCUSSION_URL placeholders + small staleness fixes (#74)

cloakmaster · Ben · web-flow · commit e50cf005daa6 · 2026-05-04T22:04:00.000+02:00
The Discussion thread is live at: #73 Sweeps the placeholder across the 5 files where it was left for fill: - README.md (1) - docs/INTEGRATIONS.md (3) - docs/COMPOSE-WITH-FOXBOOK.md (2) - docs/decisions/0009-typed-reference-schema-for-composition.md (3 + the <DATE_POSTED> placeholder also filled with 2026-05-04) - docs/STATE-AT-STABLE-MODE-CLOSE.md (1) Three small staleness fixes folded in (same QA discipline as the post drafts): - README.md Status section: dropped `@foxbook/sdk-claim@0.2.0` version pin (now version-agnostic) — same logic as the #1803 close update; reader clicking the npm link sees latest, no version-archaeology distraction. - README.md Status section: dropped `CTEF v0.3.1` specific (now "CTEF byte-match validation") — v0.3.2 is converging in #1734; version-agnostic ages cleaner. - apps/web/index.html: added direct "Active composition spec" link to the Substrate & integrations section pointing at Discussion #73 — discoverability surface for the live spec thread that wasn't there at write-time. ## Verification - pnpm check:generated — 10 files match - All <DISCUSSION_URL> + <DATE_POSTED> placeholders cleanly filled - No code touched (docs + landing only) Co-authored-by: Ben <ben@inkog.io>
diff --git a/README.md b/README.md
@@ -26,7 +26,7 @@ Building an evidence-layer, verdict-layer, or other identity-anchored system tha
 
 - [`docs/COMPOSE-WITH-FOXBOOK.md`](docs/COMPOSE-WITH-FOXBOOK.md) — short guide for new integrators (typed-reference shape, engagement path, what's NOT in scope).
 - [`docs/INTEGRATIONS.md`](docs/INTEGRATIONS.md) — living catalog of known integrations + their status.
-- Active spec discussion: **Composition: Foxbook ↔ Concordia ↔ Sanctuary typed-reference schema** at `<DISCUSSION_URL>`.
+- Active spec discussion: **Composition: Foxbook ↔ Concordia ↔ Sanctuary typed-reference schema** at https://github.com/cloakmaster/foxbook/discussions/73.
 - `hello@foxbook.dev` for substantive offline conversations.
 
 ---
@@ -91,8 +91,8 @@ A2A and MCP both opened discussions about trust between agents — composable ev
 - Tier-2 verification via DNS TXT and signed-nonce endpoint challenge.
 - Recovery-key signed revocation: atomic across leaf append and claim delete. Observed at 467ms wall-clock against live Postgres (single-run benchmark).
 - Firehose stream: 20ms median commit-to-receive latency (single-run benchmark).
-- `@foxbook/sdk-claim@0.2.0` on npm — six-function reference SDK with `verified_signing_key_hex` on the verified branch + structured `reason_code` on the unverified branch.
-- Registered as `evidence_provider` on the identity-layer slot at [`agentgraph.co/.well-known/interop-harness.json`](https://agentgraph.co/.well-known/interop-harness.json) with CTEF v0.3.1 byte-match validation (4/4 vectors).
+- `@foxbook/sdk-claim` on npm — six-function reference SDK with `verified_signing_key_hex` on the verified branch + structured `reason_code` on the unverified branch.
+- Registered as `evidence_provider` on the identity-layer slot at [`agentgraph.co/.well-known/interop-harness.json`](https://agentgraph.co/.well-known/interop-harness.json) with CTEF byte-match validation (4/4 vectors).
 
 **Not in scope under stable mode**
 
diff --git a/apps/web/index.html b/apps/web/index.html
@@ -66,6 +66,7 @@ <h2>Substrate &amp; integrations</h2>
         <ul class="links">
           <li><a href="https://agentgraph.co/.well-known/interop-harness.json">Harness aggregator entry</a><span class="desc"> — claim_type_layer: identity</span></li>
           <li><a href="https://github.com/cloakmaster/foxbook/blob/main/docs/INTEGRATIONS.md">Active compositions</a><span class="desc"> — known integrators &amp; status</span></li>
+          <li><a href="https://github.com/cloakmaster/foxbook/discussions/73">Active composition spec</a><span class="desc"> — typed-reference schema with Concordia + Sanctuary</span></li>
           <li><a href="https://github.com/cloakmaster/foxbook/blob/main/docs/COMPOSE-WITH-FOXBOOK.md">Compose with Foxbook</a><span class="desc"> — guide for new integrators</span></li>
           <li><a href="https://agentgraph.co">AgentGraph litepaper §1.8</a><span class="desc"> — substrate-and-primitive layering, publishing 2026-05-12</span></li>
         </ul>
diff --git a/docs/COMPOSE-WITH-FOXBOOK.md b/docs/COMPOSE-WITH-FOXBOOK.md
@@ -17,7 +17,7 @@ The most common pattern: your envelope / receipt / attestation carries a **typed
 
 The active spec discussion for the typed-reference schema is here:
 
-**`<DISCUSSION_URL>`**
+**https://github.com/cloakmaster/foxbook/discussions/73**
 
 (Once the schema is agreed, [`docs/decisions/0009-typed-reference-schema-for-composition.md`](decisions/0009-typed-reference-schema-for-composition.md) ratifies it on the Foxbook side.)
 
@@ -41,7 +41,7 @@ If your shape doesn't fit any of the above, open a Discussion in `cloakmaster/fo
 ## How to engage
 
 1. **Read the existing context** — [README.md](../README.md), [RATIONALE.md](RATIONALE.md), [ADRs 0001–0008](decisions/), the active Discussion thread above.
-2. **Open a thread** — for typed-reference compositions, the existing thread at `<DISCUSSION_URL>`. For novel compositions, a new Discussion in `cloakmaster/foxbook`.
+2. **Open a thread** — for typed-reference compositions, the existing thread at https://github.com/cloakmaster/foxbook/discussions/73. For novel compositions, a new Discussion in `cloakmaster/foxbook`.
 3. **Substantive offline** — `hello@foxbook.dev` for spec sessions, walk-throughs, or anything that benefits from a back-and-forth that's not public.
 4. **Once agreed publicly** — open a PR adding your composition to [INTEGRATIONS.md](INTEGRATIONS.md). The catalog grows organically.
 
diff --git a/docs/INTEGRATIONS.md b/docs/INTEGRATIONS.md
@@ -21,7 +21,7 @@ If you're integrating, see [`COMPOSE-WITH-FOXBOOK.md`](COMPOSE-WITH-FOXBOOK.md)
 | Systems | **Concordia v0.4.0** (evidence-composition layer) + **Sanctuary Castle Architecture v1.2** (verdict-policy gateway) |
 | Integration shape | Typed-reference: a Concordia attestation envelope carries a typed reference to a Foxbook leaf as supporting evidence. Sanctuary verdict-policy anchors on the typed reference. |
 | Status | **Proposed** |
-| Schema discussion | <DISCUSSION_URL> |
+| Schema discussion | https://github.com/cloakmaster/foxbook/discussions/73 |
 | Origin | [A2A Discussion #1803, eriknewton 2026-05-04T17:39Z](https://github.com/a2aproject/A2A/discussions/1803#discussioncomment-13655678) |
 
 Three-layer stack:
@@ -30,7 +30,7 @@ Three-layer stack:
 2. **Evidence** — Concordia v0.4.0 (#1734-shape attestation envelopes)
 3. **Verdict** — Sanctuary Castle Architecture v1.2 (gateway-side policy enforcement)
 
-The typed-reference shape under discussion at <DISCUSSION_URL>. Once consensus lands, [`docs/decisions/0009-typed-reference-schema-for-composition.md`](decisions/0009-typed-reference-schema-for-composition.md) ratifies the shape on the Foxbook side.
+The typed-reference shape under discussion at https://github.com/cloakmaster/foxbook/discussions/73. Once consensus lands, [`docs/decisions/0009-typed-reference-schema-for-composition.md`](decisions/0009-typed-reference-schema-for-composition.md) ratifies the shape on the Foxbook side.
 
 ---
 
@@ -51,7 +51,7 @@ These aren't application-layer integrations but are load-bearing for the cross-i
 
 If you're integrating Foxbook into your system:
 
-1. Open a thread at the schema-discussion venue (typically `<DISCUSSION_URL>` for Concordia/Sanctuary-shape integrations, or a new Discussion in `cloakmaster/foxbook` for novel shapes).
+1. Open a thread at the schema-discussion venue (typically https://github.com/cloakmaster/foxbook/discussions/73 for Concordia/Sanctuary-shape integrations, or a new Discussion in `cloakmaster/foxbook` for novel shapes).
 2. Once your integration shape is agreed publicly, open a PR adding an entry to this file.
 3. Update Status as the integration progresses (Proposed → Spec'd → Live).
 
diff --git a/docs/STATE-AT-STABLE-MODE-CLOSE.md b/docs/STATE-AT-STABLE-MODE-CLOSE.md
@@ -51,7 +51,7 @@ Per [ADR 0006](decisions/0006-protocol-not-marketplace.md) §4, named cross-impl
 
 See [`docs/INTEGRATIONS.md`](INTEGRATIONS.md). Current entries:
 
-- **Concordia v0.4.0 + Sanctuary Castle v1.2** (eriknewton) — typed-reference composition. Status: Proposed; schema discussion at [`<DISCUSSION_URL>`](https://github.com/cloakmaster/foxbook/discussions). ADR 0009 ratifies the agreed shape on the Foxbook side once consensus lands.
+- **Concordia v0.4.0 + Sanctuary Castle v1.2** (eriknewton) — typed-reference composition. Status: Proposed; schema discussion at [https://github.com/cloakmaster/foxbook/discussions/73](https://github.com/cloakmaster/foxbook/discussions). ADR 0009 ratifies the agreed shape on the Foxbook side once consensus lands.
 
 ---
 
diff --git a/docs/decisions/0009-typed-reference-schema-for-composition.md b/docs/decisions/0009-typed-reference-schema-for-composition.md
@@ -19,15 +19,15 @@
 
 Specifying the typed-reference shape is a **composition decision** that affects multiple implementations. Per [ADR 0006](0006-protocol-not-marketplace.md)'s protocol-not-marketplace stance, the spec belongs in the open: reviewable, archival, multi-party. The active spec venue is:
 
-**`<DISCUSSION_URL>`**
+**https://github.com/cloakmaster/foxbook/discussions/73**
 
 This ADR is the Foxbook-side ratification record. It is **`under-public-discussion`** until consensus lands in the thread; once schema v1.0 is agreed, this ADR is updated **in-place** with the ratified shape and `Status: accepted`. A new ADR (0010) is not opened for the ratification — the thread is the discussion record, this ADR is the decision record.
 
 ## Decision
 
 ### Schema (placeholder pending public consensus)
 
-The strawman from `<DISCUSSION_URL>` is reproduced here for traceability. The ratified schema lands in this section once the thread reaches consensus.
+The strawman from https://github.com/cloakmaster/foxbook/discussions/73 is reproduced here for traceability. The ratified schema lands in this section once the thread reaches consensus.
 
 ```json
 {
@@ -94,7 +94,7 @@ The composition pattern itself (typed-reference, embedded inside a higher-layer
 
 ## Verified
 
-- The strawman schema in this ADR matches the strawman posted at `<DISCUSSION_URL>` first-comment as of `<DATE_POSTED>`.
+- The strawman schema in this ADR matches the strawman posted at https://github.com/cloakmaster/foxbook/discussions/73 first-comment as of `2026-05-04`.
 - Foxbook SDK v0.2.0 (`@foxbook/sdk-claim@0.2.0`) surfaces `verified_signing_key_hex` + `leaf_index` on the `verified` branch of `verifyAgentCard`. Verified by `npm view @foxbook/sdk-claim`.
 - tl-leaf v1.2's canonical-bytes shape (per [ADR 0004 addendum-3](0004-tl-leaf-schema-evolution.md)) is what `tl_leaf_canonical_hash` references. Cross-language byte-match validation in [`schemas/crypto-test-vectors.json`](../../schemas/crypto-test-vectors.json).
 - Concordia v0.4.0 and Sanctuary Castle Architecture v1.2 are the named cross-impl reference candidates per [@eriknewton's 2026-05-04 comment](https://github.com/a2aproject/A2A/discussions/1803#discussioncomment-13655678) on A2A Discussion #1803.
