phase: 145_git_source_links

**Phase 145 final verification pass — all green, no code changes needed**

- **Verified (no defects found):** resolver `origin_for_source` + `_url_basename` (scp/`.git`/trailing-slash, sanitize, ambiguity WARNING); `origin:`/`branch:` lines in all four read shapes via shared `_origin_lines`; HIGH `<tools>` origin rule (verbatim + only-byte-change pins); `DocContent.origin_url/origin_branch` (absent-never-null serializer); `renderDocument` "Original" anchor (copyable verbatim URL, `_blank`/`noopener`, branch in title); mock scripted origin-link flow (disjoint trigger — grep-verified vs all other E2E files)
- **Tests:** `uv run pytest --cov=app --cov-report=term-missing` → 3402 passed, `app/` coverage **99%** (>90% gate); `uv run pytest tests/e2e/test_git_source_links.py -v --no-cov` → **4 passed** in isolation; `uv run ruff check .` → clean; `uv run pyright` → 0 errors, 0 warnings
- **Completion criteria:** (1) git read results carry origin/branch, local byte-identical — ✅ (unit pins + E2E control); (2) HIGH `<tools>` rule pinned, LOW byte-identical — ✅; (3) modal AND /document.html show Original link, branch in label when pinned, nothing for local — ✅; (4) full suite green + coverage + E2E + lint/types — ✅; (5) no completed-phase behavior change (read header line 1, mock prefix, done frame/SourceRef untouched, LOW sha) — ✅
- **Extra regression check:** re-ran shared-mock E2E suites `test_read_line_ranges.py` (2 passed) and `test_document_viewer.py` (8 passed) — no cross-suite regressions from the `mock_llm.py` addition
- **Documentation:** README.md reviewed in full (env table ⊇ `.env.example`, pages/routes, config defaults, scripts, 17-color palette, 300 s guard, 2 s sync poll, phase-145 provenance section matches implementation) and AGENTS.md (72rem container, no-CDN test, smoke test, gitignore, gates) — **verified consistent, no changes needed**
- **Notable:** phase-116 screenshot PNG was regenerated during this phase's E2E runs (byte re-encode only, visually identical, correct no-anchor local-source meta row) — left in tree for the harness commit
- **Next pending phase:** `146_search_tool_scope` (then 147, 148, 149)

app/rag/prompts.py

@@ -231,6 +231,40 @@ SUGGEST_INTRO = (
 #: summaries are the starting points, not the content; ``grep`` with
 #: only ``pattern`` searches the whole knowledge base, and a source
 #: name is not a document.
+#: Phase 145 (task 02) — the original-source rule the ``read`` teaching
+#: carries (LOCKED verbatim — pinned in :mod:`tests.unit.test_prompt_lock`
+#: and :mod:`tests.unit.test_prompts`). :data:`TOOLS_SECTION` embeds this
+#: exact sentence-group at the ``read`` clause's end (the truncation
+#: workflow sentence) and BEFORE the ``grep`` clause begins; the
+#: cross-pins (``TOOLS_SECTION`` minus this rule reproduces the
+#: pre-phase-145 bytes; ``count == 1`` + the boundary substring) keep
+#: the embedded copy and this constant byte-identical. A read result for
+#: a git-sourced document carries an ``origin:`` line (and a ``branch:``
+#: line when a branch is pinned) — the read contract's fact — so when
+#: the answer uses such a document it includes the original source: a
+#: link to the repository (the ``origin`` line) with the document's path
+#: (the ``Document …`` header) named and the pinned branch when one is
+#: shown, as the repository's file-view URL where the model can tell it
+#: (``<repo-url>/blob/<branch>/<path>``), or the repository URL plus the
+#: path as plain text otherwise — the user opens the complete original
+#: from the answer in one step, not a second question. The rule is
+#: CONDITIONAL on the ``origin`` line's presence — a local-sourced
+#: document's read result carries none, so the rule adds nothing to
+#: those answers (the model has no URL to cite; it must not invent one —
+#: the sentence's conditioning does that job).
+ORIGIN_RULE: str = (
+    "A read result for a document from a git source carries an origin line "
+    "(and a branch line when a branch is pinned): when your answer uses "
+    "such a document, include the original source in the answer — a link "
+    "to the repository from the origin line, with the document's path "
+    "(from the Document header) named and the pinned branch when one is "
+    "shown — as the repository's file-view URL where you can tell it "
+    "(for example <repo-url>/blob/<branch>/<path>), or the repository "
+    "URL plus the path as plain text otherwise. The user should be able "
+    "to open the complete original from your answer in one step, not ask "
+    "again for the source."
+)
+
 TOOLS_SECTION: str = (
     "<tools>\n"
     "You may extend your context with three tools. `ls` lists the "
@@ -260,7 +294,17 @@ TOOLS_SECTION: str = (
     "are capped: a "
     "cut read returns the first part plus a TRUNCATED notice — the "
     "document did not end where it stopped; use `grep` (pattern) to "
-    "find the rest, it searches the whole document. `grep` locates an exact string "
+    "find the rest, it searches the whole document. A read result for a "
+    "document from a git source carries an origin line (and a branch line "
+    "when a branch is pinned): when your answer uses such a document, "
+    "include the original source in the answer — a link to the "
+    "repository from the origin line, with the document's path (from the "
+    "Document header) named and the pinned branch when one is shown — as "
+    "the repository's file-view URL where you can tell it (for example "
+    "<repo-url>/blob/<branch>/<path>), or the repository URL plus the "
+    "path as plain text otherwise. The user should be able to open the "
+    "complete original from your answer in one step, not ask again for "
+    "the source. `grep` locates an exact string "
     "(case-insensitive) in the indexed documents and returns up to 20 "
     "matching `source/path:line: text` lines — a locator, not a "
     "context-adder: read the winner with `read`. A grep pattern is a "