[schickling-assistant]

Problem

axe.intent.graph.v0 preserved file/ID nodes and resolved edges, but consumers could not inspect source-located Markdown-link or normative citation records. That kept link and ID checks on separate regex scanners and made dangling versus ambiguous targets unavailable through the graph contract.

Goal

Emit additive references records for explicit req: traces, local Markdown links, A/T/R-style ID citations, and decision/delta ordinal citations. Every record must preserve its source location and written target, report resolved, ambiguous, or dangling, and expose all mechanically resolved target locations.

Decisions

• Keep nodes and edges unchanged; references is additive under the existing v0 schema.
• Use syntax values req_trace, markdown_link, id_citation, and ordinal_citation rather than inferring a family from optional fields.
• Resolve local A/T/R IDs only through their own requirements.md or a resolved requirements link. Namespaced IDs resolve by exact normalized ID. This avoids guess-based cross-node edges.
• Resolve bare decision/delta ordinals through a companion linked in the citing document first, then the nearest owning subsystem or ancestor. Duplicate targets in the selected scope are ambiguous.
• Emit one Markdown-link record per occurrence, skip external URL schemes, preserve the visible label, and validate mechanically derivable heading anchors.
• Share the graph builder's Markdown reads with existing node/edge extraction so the additional families do not double corpus I/O.

Verification

$ cargo test
24 passed; 0 failed

Dotfiles context/ parity smoke (cargo run --quiet -- graph <dotfiles>/context --json):

syntax             total  resolved  ambiguous  dangling
id_citation        10255      7488        436      2331
markdown_link       9276      9260          0        16
ordinal_citation    1417      1364         10        43
req_trace              3         0          0         3
TOTAL              20951

Comparison with the existing scanners:

• Requirement citations are within 0.7% of the regex audit (10,255 versus 10,323). The graph omits fenced-code matches and does not double-classify req: targets as plain citations. Its 324 unique dangling IDs exceed the audit's 203 globally undefined IDs because unqualified cross-scope IDs intentionally remain dangling; 58 cited IDs are ambiguous versus 84 duplicate-defined IDs, since uncited duplicates do not create reference records.
• Markdown links produce 16 dangling occurrences versus 15 broken links in the file-existence scanner. The graph is occurrence-based and also validates heading anchors; the scanner deduplicates path/target findings and strips anchors.
• Ordinals produce 53 non-resolved occurrences (10 ambiguous, 43 dangling), the same scale as the 45-entry ambiguity baseline. The graph records each occurrence; the baseline deduplicates violations within a document.
• The three existing explicit req: examples remain visible as req_trace records.

Complexity

The new parser/resolver module centralizes source indexing, repository-relative path normalization, definition/companion indexes, and family-specific resolution. Those pieces are shared across every reference family; no new runtime dependency was added.

Concerns

The Markdown extractor intentionally follows the corpus's existing inline-link grammar so its migration surface stays comparable to vrs-link-check. It can therefore retain the same regex-shaped false positives until the corpus or grammar is tightened.

Friction & bottlenecks

• Friction: the ambient cc selected GCC on macOS and could not link -liconv; the successful test run selected Xcode clang explicitly.
• No runtime or build bottleneck observed; the full test suite completed in under five seconds after compilation.

Follow-ups

None.

References

• Normative graph contract: schickling/dotfiles/context/vrs/16-enforcement/spec.md
• Existing parity scanners: vrs-link-check, vrs-id-check, and requirement-id-audit

Posted on behalf of @schickling

field	value
agent_identity	mbp2025.direct.omp.mjwjfku9
session	unknown
agent_persona	generalist
agent_supervisor	unavailable
agent_tool	OMP
agent_tool_version	18.2.11
agent_runtime	OMP 18.2.11
agent_model	openai-codex/gpt-5.6-sol
worktree	intent/2026-09-27-graph-link-citation-refs
tooling_profile	dotfiles@2df08b9-dirty

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-09-27T09:25:20.306201Z	7c3044c	Draft marked ready

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 7c3044cdf1

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Exclude delta definitions from ordinal citations

When a delta record uses the documented heading form # DELTA-001: ..., this scan treats the heading as an ordinal_citation; resolution then finds the record itself and emits a spurious resolved reference. This affects every .delta/DELTA-* or 09-delta/DELTA-* document and inflates the reference graph with definitions masquerading as citations, unlike ID definitions, which are explicitly excluded. Skip the defining ordinal occurrence in its companion document.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Require full word boundaries around ID citations

For prose containing identifiers such as parserR01State or R01value, lowercase ASCII letters are not considered boundary-blocking characters, so the embedded R01 is emitted as a normative id_citation and usually reported as dangling. Treat all alphanumeric characters and underscores as word characters on both sides so only standalone A/T/R-style IDs become references.

Useful? React with 👍 / 👎.