fix(sdd): distinguish protocol notation from repository references

docs/issues/pre-branch-sdds.mdx

@@ -76,6 +76,34 @@ The selected SDD must appear in this table too: use `create` for a new or
 companion SDD, and `update` for an existing one. A self-link or a `reference`
 row cannot replace that declaration.
 
+HTTP endpoints such as `api/v1/session`, media types such as `application/json`,
+mode alternatives such as `native/standalone` and scoped module identifiers are
+notation rather than file-existence claims. Label a file-shaped relative asset
+address explicitly, for example **URL:** `assets/main.js`. Without that role,
+a file-shaped reference remains a repository citation. A known exact file or a
+blocked symlink/submodule path retains repository checking even under a URL label.
+For ambiguous file names, use **File:** or **Path:** before the backticked path,
+a relative Markdown link or an explicit Path/Change row. Relative Markdown
+destinations and Path/Change rows always receive strict repository checks,
+regardless of whether their spelling resembles protocol notation.
+
+A whole link, image or reference-definition example inside code is illustrative
+Markdown, rather than a real destination. For example, writing the literal
+`` `[example](../missing.md)` `` does not claim that its example target exists.
+Actual links, image destinations and used reference-style links remain strict.
+Reference structure uses the existing Markdown parser, including longer backtick
+delimiters and multiline code. It checks the operative URI against immutable
+files/directories or exact proposed artifacts; normalization cannot establish
+existence. Visible NUL is rejected before it can alias a replacement-character
+filename. A file label or exact known/blocked path retains repository checking,
+including space-bearing names.
+
+A future directory can be cited only when it is an exact ancestor of a validated
+new-file `create` row. For example, declaring a new `frontend/src/domain/entry.ts`
+allows a citation of `frontend/src/domain/`. It does not create that directory,
+authorize application writes, permit a sibling directory or turn a regular file
+into a directory. Declare the new file, not a directory placeholder.
+
 The new tables apply to generated candidates. Existing owner documents remain
 verbatim and do not require a table migration to receive an appendix. These
 checks establish internal consistency for draft publication. Product,
@@ -103,6 +131,21 @@ mapping sets can still disagree on their members; that check reports mismatched
 links rather than implying equal counts prove correctness. These are observations from the actual validator;
 missing evidence is reported as unavailable rather than guessed.
 
+A repository-reference failure also identifies inline code, file-shaped prose
+or a relative Markdown destination, with a **Visible reference occurrence**.
+This is a 1-based ordinal within that category, not a source line or table row.
+Inline positions count visible code spans; prose positions count file-shaped
+matches after classified spans and links are removed; link positions count
+actual parsed destinations, including external and empty same-document links.
+Unused reference definitions add no visible destination. Hidden comments and
+fenced examples are excluded. A separate fixed explanation distinguishes unsafe
+spelling, blocked ancestry, missing evidence or a file used as a directory.
+The rejected path/text remains private; these facts locate the first rejection
+without retaining or exposing the failed draft.
+Reference ordinals also exclude the already validated Path/Change data rows;
+those declarations have their own table-row diagnostics. They are not parsed a
+second time as prose fragments or link syntax, including space-bearing file names.
+
 An illustrative failure view is:
 
 > **Specification preparation is blocked**

specs/catalog.json

@@ -1737,15 +1737,16 @@
       "id": "issue-start-and-sdd-readiness",
       "title": "Uniform issue start and pre-branch SDD readiness",
       "status": "implemented",
-      "scope": "Start every admitted issue with one explicit signal and publish a validated SDD before eligible Action-managed branch work; inspect verified SDD status and bounded structural publication comparisons and preserve complete navigable catalog links for accepted repository filenames and safely publish generated catalogs without following destination links; bootstrap truthful proposed SDK capabilities before implementation without changing readiness; reject incomplete specification discovery explicitly without following unregistered symbolic links; report confirmed missing trusted catalogs with immutable source provenance and prerequisite recovery before model or publication; bind pre-branch analysis and drafting to a verified independent read-only view of the selected immutable source without changing the canonical checkout",
+      "scope": "Start every admitted issue with one explicit signal and publish a validated SDD before eligible Action-managed branch work; inspect verified SDD status and bounded structural publication comparisons and preserve complete navigable catalog links for accepted repository filenames and safely publish generated catalogs without following destination links; bootstrap truthful proposed SDK capabilities before implementation without changing readiness; reject incomplete specification discovery explicitly without following unregistered symbolic links; report confirmed missing trusted catalogs with immutable source provenance and prerequisite recovery before model or publication; bind pre-branch analysis and drafting to a verified independent read-only view of the selected immutable source without changing the canonical checkout; distinguish visible protocol notation from repository citations, allow only constructive proposed-file directory ancestry and expose bounded private-safe origin diagnostics",
       "owner": "Copilot maintainers",
-      "lastVerified": "2026-11-02",
+      "lastVerified": "2026-11-03",
       "specs": [
         "specs/issue-start-and-branch-readiness.md",
         "specs/pre-branch-sdd-gate.md",
         "specs/pre-branch-sdd-diff.md",
         "specs/pre-branch-sdd-status-readiness.md",
-        "specs/pre-branch-sdd-source-context.md"
+        "specs/pre-branch-sdd-source-context.md",
+        "specs/sdd-reference-classification.md"
       ],
       "workflows": [
         ".github/workflows/copilot_issue.yml",
@@ -1831,7 +1832,9 @@
         "src/application/policies/agent_source_snapshot_policy.ts",
         "src/infrastructure/agents/agent_source_snapshot_git.ts",
         "src/infrastructure/agents/agent_source_snapshot_workspace.ts",
-        "src/infrastructure/agents/agent_source_snapshot_integrity.ts"
+        "src/infrastructure/agents/agent_source_snapshot_integrity.ts",
+        "src/domain/sdd_repository_reference.ts",
+        "src/domain/sdd_visible_references.ts"
       ],
       "tests": [
         "src/domain/__tests__/issue_workflow_runtime_policy.test.ts",
@@ -1900,7 +1903,8 @@
         "src/infrastructure/agents/__tests__/agent_source_snapshot_integrity.test.ts",
         "src/infrastructure/agents/__tests__/agent_source_snapshot_gate.integration.test.ts",
         "src/application/policies/__tests__/sdd_source_context_presentation.test.ts",
-        "src/infrastructure/agents/__tests__/agent_source_snapshot_admission.test.ts"
+        "src/infrastructure/agents/__tests__/agent_source_snapshot_admission.test.ts",
+        "src/domain/__tests__/sdd_repository_reference.test.ts"
       ],
       "documentation": [
         "docs/issues/branch-management.mdx",

specs/pre-branch-sdd-gate.md

@@ -19,6 +19,11 @@ analysis, drafting and its existing repair to this gate's loaded snapshot SHA.
 It preserves the canonical checkout, lifecycle and freshness guards while
 providing an independently verified SDK-owned read-only source view.
 
+The [repository-reference companion](sdd-reference-classification.md) distinguishes
+protocol notation from file citations, defines constructive future directories
+and adds private-safe reference occurrence diagnostics. Explicit file declarations
+and relative Markdown destinations retain strict immutable-inventory checks.
+
 
 A repository can enable a pre-branch SDD gate for feature issues and other
 branch-bearing issues explicitly marked as behavior changes. After an authorized