fix(socratic-recovery): make synthesized docs self-contained, cite code not Q-IDs

docs/brownfield-workflow.adoc

@@ -163,7 +163,7 @@ The LLM synthesizes the answered questions plus the code evidence from Phase 1 i
 * *arc42* with all 12 chapters from Q-3 branch
 * *Nygard ADRs* with Pugh Matrix from Q-3.9 branch
 
-Every claim references a Question ID and marks team-provided information with `(team answer)`. This dual traceability (code evidence + team input) is the key difference from a simple reverse-engineering prompt.
+Every claim references a Question ID. A code-derived claim also carries the `file:line` evidence from its `[ANSWERED]` leaf, copied into the citation so the source is visible without opening the Question Tree; team-provided information is marked `(team answer)`. This dual traceability (code evidence + team input) is the key difference from a simple reverse-engineering prompt.
 
 === Establish Baseline Tests
 
@@ -261,7 +261,7 @@ Stable code that nobody touches does not need specs.
 |{empty}--
 
 |Theory Recovery (Phase 2)
-|`Synthesize documentation from the Question Tree and team answers. Every claim references a Q-ID. Mark team input with (team answer).`
+|`Synthesize documentation from the Question Tree and team answers. Every claim references a Q-ID; for code-derived claims, also cite the file:line evidence from the ANSWERED leaf. Mark team input with (team answer).`
 |link:#/spec-driven-development[Spec-Driven Workflow]
 
 |Baseline Tests

docs/brownfield-workflow.de.adoc

@@ -161,7 +161,7 @@ Das LLM synthetisiert die beantworteten Fragen plus die Code-Evidenz aus Phase 1
 * *arc42* mit allen 12 Kapiteln aus dem Q3-Ast
 * *Nygard-ADRs* mit Pugh-Matrix aus dem Q3.9-Ast
 
-Jede Aussage referenziert eine Question-ID und markiert teamgegebene Information mit `(team answer)`. Diese doppelte Rückverfolgbarkeit (Code-Evidenz + Team-Input) ist der entscheidende Unterschied zu einem einfachen Reverse-Engineering-Prompt.
+Jede Aussage referenziert eine Question-ID. Eine code-basierte Aussage trägt zusätzlich die `file:line`-Evidenz aus ihrem `[ANSWERED]`-Leaf — in die Zitation kopiert, damit die Quelle sichtbar ist, ohne den Question Tree zu öffnen; teamgegebene Information wird mit `(team answer)` markiert. Diese doppelte Rückverfolgbarkeit (Code-Evidenz + Team-Input) ist der entscheidende Unterschied zu einem einfachen Reverse-Engineering-Prompt.
 
 === Basis-Tests aufbauen
 
@@ -259,7 +259,7 @@ Stabiler Code, den niemand anfasst, braucht keine Specs.
 |{empty}--
 
 |Theory Recovery (Phase 2)
-|`Synthesize documentation from the Question Tree and team answers. Every claim references a Q-ID. Mark team input with (team answer).`
+|`Synthesize documentation from the Question Tree and team answers. Every claim references a Q-ID; for code-derived claims, also cite the file:line evidence from the ANSWERED leaf. Mark team input with (team answer).`
 |link:#/spec-driven-development[Spec-Driven Workflow]
 
 |Basis-Tests

docs/socratic-recovery-skill.adoc

@@ -22,7 +22,7 @@ Outputs two AsciiDoc files: `QUESTION_TREE.adoc` (full reasoning trace) and `OPE
 
 === Phase 2 — Synthesize documentation
 
-The skill takes the answered tree and produces a PRD, Cockburn use cases, an arc42 architecture document, and Nygard ADRs with Pugh matrices. Every claim cites a Q-ID; team-supplied facts are marked `(team answer)`.
+The skill takes the answered tree and produces a PRD, Cockburn use cases, an arc42 architecture document, and Nygard ADRs with Pugh matrices. Every claim cites a Q-ID; code-derived claims also carry the `file:line` evidence from their `[ANSWERED]` leaf, and team-supplied facts are marked `(team answer)`.
 
 == When to use it
 
@@ -105,7 +105,8 @@ https://github.com/LLM-Coding/Semantic-Anchors/tree/main/skill/socratic-code-the
 Build a Question Tree before writing any documentation. Mark each leaf
 [ANSWERED] (with file:line evidence) or [OPEN] (with Category and Ask role).
 Synthesize docs from the answered tree only after the team has filled in
-the OPEN leaves. Cite Q-IDs in every claim.
+the OPEN leaves. Cite a Q-ID in every claim; for code-derived claims,
+also cite the file:line evidence from the ANSWERED leaf.
 ----
 
 === link:https://docs.cursor.com/[Cursor]

docs/socratic-recovery-skill.de.adoc

@@ -22,7 +22,7 @@ Output sind zwei AsciiDoc-Dateien: `QUESTION_TREE.adoc` (vollständige Begründu
 
 === Phase 2 — Dokumentation synthetisieren
 
-Der Skill nimmt den beantworteten Baum und erzeugt ein PRD, Cockburn Use Cases, eine arc42-Architekturbeschreibung und Nygard-ADRs mit Pugh-Matrix. Jede Aussage zitiert eine Q-ID; team-gegebene Fakten sind mit `(team answer)` markiert.
+Der Skill nimmt den beantworteten Baum und erzeugt ein PRD, Cockburn Use Cases, eine arc42-Architekturbeschreibung und Nygard-ADRs mit Pugh-Matrix. Jede Aussage zitiert eine Q-ID; code-basierte Aussagen tragen zusätzlich die `file:line`-Evidenz aus ihrem `[ANSWERED]`-Leaf, und team-gegebene Fakten sind mit `(team answer)` markiert.
 
 == Wann zu verwenden
 
@@ -105,7 +105,8 @@ https://github.com/LLM-Coding/Semantic-Anchors/tree/main/skill/socratic-code-the
 Build a Question Tree before writing any documentation. Mark each leaf
 [ANSWERED] (with file:line evidence) or [OPEN] (with Category and Ask role).
 Synthesize docs from the answered tree only after the team has filled in
-the OPEN leaves. Cite Q-IDs in every claim.
+the OPEN leaves. Cite a Q-ID in every claim; for code-derived claims,
+also cite the file:line evidence from the ANSWERED leaf.
 ----
 
 === link:https://docs.cursor.com/[Cursor]

skill/socratic-code-theory-recovery/SKILL.md

@@ -104,7 +104,7 @@ Use [prompts/phase-2-synthesize.md](prompts/phase-2-synthesize.md). The Phase 2
 - **arc42** with all 12 chapters from the Q3 branch
 - **Nygard ADRs** with Pugh Matrix from the Q3.9 branch
 
-Every claim references a Q-ID. Team-supplied information is marked `(team answer)`. This dual traceability — code evidence plus team input — is the difference from a simple reverse-engineering prompt that fills in gaps silently.
+Every claim references a Q-ID. A code-derived claim also carries the `file:line` evidence from its `[ANSWERED]` leaf, copied into the citation so the source is visible without opening the Question Tree. Team-supplied information is marked `(team answer)`. This dual traceability — code evidence plus team input — is the difference from a simple reverse-engineering prompt that fills in gaps silently.
 
 ## What the LLM can and cannot recover
 

skill/socratic-code-theory-recovery/prompts/phase-2-synthesize.md

@@ -50,10 +50,18 @@ Produce four artifacts:
    - Anchor: ADR according to Nygard
 
 Rules for traceability:
-- Every paragraph references the Q-IDs that support it, in square brackets:
-  "The system uses Hexagonal Architecture [Q3.5]."
-- Team-supplied facts get an inline marker: "Sessions expire after 24 hours
-  (team answer, Q3.4.2)."
+- Every paragraph references the Q-IDs that support it, in square brackets.
+- For a claim backed by an [ANSWERED] leaf, carry the code evidence from
+  that leaf into the citation alongside the Q-ID — so the reader sees the
+  source location without opening the Question Tree:
+  "The system uses Hexagonal Architecture [Q3.5; src/app/Ports.java,
+  src/adapter/JpaOrderRepository.java:30]."
+  Copy the Evidence line verbatim from the leaf; do not invent, shorten,
+  or re-derive file paths. If a leaf has no Evidence line it is not
+  [ANSWERED] and must not be cited as fact.
+- Team-supplied facts have no code evidence — mark them (team answer)
+  with the Q-ID only: "Sessions expire after 24 hours (team answer,
+  Q3.4.2)."
 - Deferred questions stay as explicit gaps: "Quality-goal priorities are
   deferred (Q4.1.deferred) and must be resolved before the next release."
 - Do not introduce facts that do not appear in QUESTION_TREE.adoc or

skill/socratic-code-theory-recovery/references/output-schema.md

@@ -141,13 +141,20 @@ _(write here)_
 
 ## Phase 2 traceability
 
-After Phase 2, every paragraph in the synthesized documentation cites at least one Q-ID:
+After Phase 2, every paragraph in the synthesized documentation cites at least one Q-ID. For a claim backed by an `[ANSWERED]` leaf, the citation also carries the code evidence copied from that leaf, so the reader sees the source location without opening the Question Tree:
 
 ```
-The system uses Hexagonal Architecture [Q3.9.HexagonalArchitecture]. Sessions
+The system uses Hexagonal Architecture [Q3.9.HexagonalArchitecture;
+src/app/Ports.java, src/adapter/JpaOrderRepository.java:30]. Sessions
 expire after 24 hours (team answer, Q3.8.Security.SessionLifetime).
 Quality-goal priorities are deferred (Q4.0.deferred) and must be resolved
 before the next release.
 ```
 
-This is the auditable trace from documentation back to either code evidence or a team answer. Anything without a Q-ID is invention.
+The three citation forms are deliberate:
+
+- `[Q-ID; file:line, ...]` — code-derived fact. The `file:line` part is the `Evidence` line of the `[ANSWERED]` leaf, copied verbatim.
+- `(team answer, Q-ID)` — team-supplied fact. No code evidence exists; the Q-ID points to the answered `[OPEN]` leaf.
+- `(Q-ID.deferred)` — an explicit gap, not a fact.
+
+This is the auditable trace from documentation back to either code evidence or a team answer. Anything without a Q-ID is invention; a code-derived claim without its `file:line` evidence is incomplete.