From 0686c28a49678c66a62002c4fb0db04b3ee8d2c2 Mon Sep 17 00:00:00 2001 From: Holger Selover-Stephan Date: Tue, 4 Aug 2026 08:09:28 +0200 Subject: [PATCH 1/2] docs: switch CLAUDE.md to the v2 URN grammar CLAUDE.md is loaded verbatim as mandatory instruction every session, so its v1 `::` URNs actively teach the stale grammar to every agent working here. v1 still resolves forever via the stored alias map, which is exactly why the habit never gets corrected by feedback. Per cor:urn:010:01, `::` is v1; v2 is flat single-colon and the platform has emitted it since #697/#720. - memory refs `hrn:memory:::` -> `hrn:mem::` (the type word changes too, per the v2 registry) - node refs collapse to a single colon and KEEP/GAIN the `hrn:node:` prefix: a bare v2 node URN has no positional memory-vs-loc split without the type word, and the CLI rejects it (dev:findings:bare-v2-node-urn-ambiguous-to-cli) - `-m :` args stay bare -- the flag fixes the arity there - shorthand spelled out in full Every site was instructional -- no ownership chains and no accepted-input examples to preserve (dev:conventions:memory-audit-fix-vs-preserve). Every rewritten target verified to resolve. Co-Authored-By: Claude Opus 5 Closes #3. Part of hadron-memory/hadron-server#866. --- CLAUDE.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index f26d60e..9ecab7e 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -10,24 +10,24 @@ See [docs/architecture.md](docs/architecture.md) for the boundary. Hadron is the platform's institutional memory. Relevant memories: -- `hrn:memory:hadronmemory.com::hadrontool-pdf` — this tool's own findings/conventions -- `hrn:memory:hadronmemory.com::dev` — shared findings, conventions, ops, the `preflight` routing index -- `hrn:memory:hadronmemory.com::hadron-server` — the caller; newer server findings/conventions -- `hrn:memory:hadronmemory.com::specs` — product specs (loc-as-citation). This service implements +- `hrn:mem:hadronmemory.com:hadrontool-pdf` — this tool's own findings/conventions +- `hrn:mem:hadronmemory.com:dev` — shared findings, conventions, ops, the `preflight` routing index +- `hrn:mem:hadronmemory.com:hadron-server` — the caller; newer server findings/conventions +- `hrn:mem:hadronmemory.com:specs` — product specs (loc-as-citation). This service implements the PDF render path of the **export contract** at `cor:int:020:02` (presentation export; HTML/PDF phases tracked in hadron-server#394). (1) **Query Hadron before reading code.** For the topics/entities in a request, run `hadron_find_nodes` first, then `hadron_get_node` on promising hits; cite node `loc` values. -(2) Read `hadron_get_node hrn:node:hadronmemory.com::dev::instructions` once per session (what -Hadron is, URN grammar, the specs corpus), and `hadron_get_node hrn:node:hadronmemory.com::dev::preflight` +(2) Read `hadron_get_node hrn:node:hadronmemory.com:dev:instructions` once per session (what +Hadron is, URN grammar, the specs corpus), and `hadron_get_node hrn:node:hadronmemory.com:dev:preflight` before a change (the shared server/platform routing index). (3) Capture a non-obvious finding the moment it emerges (`hadron_create_node` / `hadron_update_node`) — don't batch to end-of-session. -(4) The **Hadron CLI is a superset of the MCP tools**: e.g. `hadron spec get cor:int:020:02 -m hadronmemory.com::specs`. +(4) The **Hadron CLI is a superset of the MCP tools**: e.g. `hadron spec get cor:int:020:02 -m hadronmemory.com:specs`. ## Quick reference From e4b8ffbfd9aabfcaac358fd883fe323c0b2cad42 Mon Sep 17 00:00:00 2001 From: Holger Selover-Stephan Date: Tue, 4 Aug 2026 08:13:45 +0200 Subject: [PATCH 2/2] docs: same v2 URN rewrite in docs/architecture.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Codex caught this on the hadrontool-billing PR: fixing CLAUDE.md alone left two copies of the same decision-record URN disagreeing inside one repo, so a developer reading the README would keep copying the v1 form this sweep exists to remove. The point of the sweep is what the repo TEACHES, and a README teaches just as loudly as CLAUDE.md. Same rules: node refs keep/gain the `hrn:node:` prefix; targets verified to resolve. My original survey only counted CLAUDE.md — that was the gap. Co-Authored-By: Claude Opus 5 --- docs/architecture.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/architecture.md b/docs/architecture.md index df9fcec..e6e54ec 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -15,7 +15,7 @@ implementation spec. | Prior art | What we take from it | |---|---| -| [`design:export-node-pdf`](hrn:node:hadronmemory.com::hadron-server::design:export-node-pdf) | The whole boundary analysis. It recommends **splitting the PDF pipeline at HTML→PDF**: hadron-server keeps auth + decryption + node loading; a **stateless renderer holds no DB, no keys, no access-control logic**. It also picks **Chromium (Puppeteer)** over pure-JS for Markdown fidelity, rules out hosted SaaS render APIs (in-infra privacy posture), and says **delete any `/tmp` "file mode."** This tool is that renderer. | +| [`design:export-node-pdf`](hrn:node:hadronmemory.com:hadron-server:design:export-node-pdf) | The whole boundary analysis. It recommends **splitting the PDF pipeline at HTML→PDF**: hadron-server keeps auth + decryption + node loading; a **stateless renderer holds no DB, no keys, no access-control logic**. It also picks **Chromium (Puppeteer)** over pure-JS for Markdown fidelity, rules out hosted SaaS render APIs (in-infra privacy posture), and says **delete any `/tmp` "file mode."** This tool is that renderer. | | [hadrontool-email architecture](https://github.com/hadron-memory/hadrontool-email) | The "a tool is a separate process that owns one provider-specific concern" shape, and the deployment model (separate container alongside hadron-server). | **One difference from the design node, by request:** the node's recommendation