docs: stable per-primitive anchors so external standards can deep link (OpenCRE prerequisite)

[imran-siddique]

Problem

TRACE is being mapped into OpenCRE, which cross-links a topic to ASVS, CWE, ISO 27001, NIST 800-53, SAMM and the OWASP AI Exchange from a single stable link.

Working the first pass surfaced a prerequisite we do not meet. OpenCRE links into a stable anchor for one specific requirement and regenerates those links from its API in CI. Our spec pages have no stable per-primitive anchor, so an external standard can only link to the page.

What is needed

Durable anchor IDs for the primitives an external standard would actually cite, starting with:

• Trust levels L0 / L1 / L2 in docs/trust-levels.md
• The evidence record structure in docs/schema.md

Durability is the point. OpenCRE's pitch is that its links do not rot, so an anchor that shifts when a heading is reworded defeats the purpose.

Wider than this repo

The same gap applies to every agentrust-io spec carrying a control an external framework would reference: cmcp (tool invocation control), ca2a (inter-agent trust), agent-manifest (agent identity, capability manifest), agentic-usage-control (continuous usage control), weight-custody-manifest (weight custody).

Proposing we settle the convention here first and then apply it across the others rather than inventing a different scheme per repo.

Context

First-pass mapping found 25 of 30 controls land on existing CREs and 19 look like genuine additions. Discussion with the OpenCRE maintainers is in flight.

[imran-siddique]

Correcting the premise in the body, and the requirement has grown a second half.

The "19 genuine additions" line above is out of date. Rob van der Veer's rule on OWASP/OpenCRE#1045 is that OpenCRE organizes requirements that standards state, it does not state them, and a sub-control earns its place once several standards have sections to group there. Applied to all 30 controls, all 19 proposed CREs collapsed into links to existing CREs. The second pass proposes none: 30 sections, 62 links, 53 distinct CREs. That makes this issue more important rather than less, because the entire contribution is now link-shaped.

The second half. OpenCRE's docs/CONTRIBUTING.md names an alternative linking method and calls it the preferred one, because it is self-maintaining:

you add to the standard a hyperlink reference to the relevant common requirement (e.g. [Restrict XML parsing](https://www.opencre.org/cre/764-507)) in a section on that topic. And then you specify to us at OpenCRE how we can read your source (e.g. Github) automatically to extract those hyperlinks and to construct links to that section in the document, and parse the name and id.

We control every one of these spec texts, so this is the method we should use. It means two requirements, not one:

1. Stable per-control anchors, so an external standard can link in. As already described above.
2. An opencre.org/cre/<id> reference inside each control's own text, so the inbound link is generated from our source and cannot rot when we reword a heading.

Doing only (1) leaves us hand-maintaining a mapping table forever, which is the thing this method exists to avoid.

Standard identity, now settled. We submit as one standard named AgenTrust, not five, because an OpenCRE standard is one document with sections and our controls currently span trace-spec, cmcp, ca2a, agent-manifest, agentic-usage-control and weight-custody-manifest. Per-control permalinks go at:

https://agentrust-io.com/go/<slug>/

mirroring the owaspai.org/go/<slug>/ pattern OpenCRE already ingests for the AI Exchange. Each permalink resolves to the control's own section in whichever spec owns it. The 30 slugs are settled and the page can be generated from the mapping sheet rather than hand-written.

What the /go/ page actually needs. Checked rather than assumed: agentrust-io.github.io has no CI allowlist gating new pages, so /go/ deploys as soon as it is committed. What it does have is a hand-maintained sitemap.xml listing seven URLs, plus llms.txt. A new directory that is not added to both deploys and resolves but stays invisible to crawlers. With 30 permalinks that matters, so the sitemap entry belongs in the same PR. wcm/ plus wcm-launch-page.yml is the existing precedent for a per-topic directory with its own check.

Nothing is submitted upstream until the permalinks resolve. The mapping sheet currently carries the intended URLs marked do-not-ingest.

[lywinged]

I measured the deployed state before answering, because most of the second half is already
live.

Already done, as of today. /go/ serves 30 control sections, #agent-identity-credential
through #model-weight-custody, and every one of those ids is hand-chosen rather than
generated. Not one of the 30 is the slug of its own heading, and 23 of them are not the slug
even with the AT-NN stripped, so a reworded title moves nothing. All 30 /go/<slug>/
permalinks return 200, checked individually rather than sampled. The
page carries 62 links to opencre.org/cre/<id> across 53 distinct ids, which is your second
pass exactly. sitemap.xml lists eight URLs with /go/ among them, and llms.txt already
describes the permalink scheme in its own words. So the gate you set, nothing submitted until
the permalinks resolve, is met.

One thing that does not match, and it is the one worth settling. Your comment says each
permalink resolves to the control's own section in whichever spec owns it. What is deployed
does something else: all 30 of them are a meta refresh to /go/#<slug>, a section of the
aggregator page. And /go/ links to none of the six specs. Of 78 hrefs on it, 62 go to
OpenCRE and the rest to the site's own pages and assets, so a reader on AT-26 has no path to
the TRACE text that defines it.

The deployment reads as deliberate rather than as an oversight: each stub carries
noindex, follow and a canonical pointing at /go/#<slug>, which is what you write on purpose
so a permalink stays citable without competing with the page it funnels to. Both behaviours are
defensible, and they are different submissions:

if the standard is	OpenCRE constructs links to	then
/go/	the 30 stable slugs on it	this is finished, and the spec texts are not on the ingest path
the six spec texts	sections inside each spec	the cre/<id> links have to move into those texts, in a section on that topic

Under the second reading, trace-spec is not ready, and one gap is structural rather than
cosmetic. schema/trace-claim.json has sixteen properties. Twelve have a ## section of
their own, and their generated anchors are already the field name with underscores intact,
#data_class, #tool_transcript, #build_provenance. The other four, eat_profile, iat,
subject and signature, have no heading at any level on docs/schema.md; they exist
only as rows in the #top-level-fields table. The method you quote puts the hyperlink in a
section on that topic, and for those four there is no section to put it in.

The rest is ordinary. docs/trust-levels.md is all prose headings, so #level-0-software-only
and its two siblings move whenever the wording does. spec/trace-v0.2.md is worse: 39
headings, not one anchor is a field name, and origin and references sit inside numbered
headings, so #311-origin-who-assembled-this-record moves on a renumber as well as on a
reword.

One implementation note for whenever anchors do get added here. attr_list is enabled, so
{ #trace-l0 } works with no configuration change, but a custom id replaces the generated
one rather than adding to it, which would silently break the deep links that exist now.
Writing the old slug inline in the same heading keeps both and leaves no stray element:
## Level 0 — Software-only <a id="level-0-software-only"></a> { #trace-l0 }. cmcp, ca2a and
agent-manifest are on the identical stack, so the same line travels unchanged.