chore(agent): track .agent/ planning tree in git

Remove the blanket .agent/ gitignore so the phase roadmap, user stories, reports, and PLAN.md are versioned with the code. Only runtime artifacts (.agent/phase-sessions/, .agent/pipeline.log) remain ignored. Update AGENTS.md git protocol rule to match.
2026-09-01 10:18:22 -04:00
parent 5fa620fde5
commit 4971e2859d
818 changed files with 23964 additions and 4 deletions
@@ -0,0 +1,51 @@
+# Phase 13 — Document Back Button Returns to Where You Came From
+
+**Story:** `.agent/user_stories/document-back-navigation.md`
+**Context:** owner report 2026-08-22 — "clicking a document from the
+chat tab pulls up the document correct, but the back button goes back to
+sources, not the chat."
+
+## Goal
+The viewer's back button returns to **the page the document was opened
+from**: chat chip → Chat; Sources table → Sources.
+
+## Diagnosis
+Chips/links open the viewer with `target="_blank"`. In the fresh tab
+`window.history.length` is 1, so `document.js`'s heuristic
+(`history.length > 1 ? history.back() : href`) always falls through to
+the static `href="/sources.html"` — wrong for chat-originated visits.
+
+## Implementation steps
+1. **Chat chips** (`frontend/assets/app.js`): `documentUrl(source, path,
+   back = "/")` — appends `&back=<encoded>`; chat passes `"/"`.
+   Existing phase-10 E2E href assertion updates to include
+   `&back=%2F`.
+2. **Sources links** — unchanged: no `back` param in the URL; the
+   viewer's default target is `/sources.html`, so the phase-10
+   assertion stays green.
+3. **Viewer** (`frontend/document.js`):
+   - Resolve back target: `back` param wins **only** when it is a
+     same-origin relative URL (starts with `/`, not `//`); otherwise
+     `/sources.html`. (Rejects `https://…`, `//…`, `javascript:…`.)
+   - Set `#doc-back` href + label: `/` → "Chat", `/sources.html` →
+     "Sources", anything else relative → "Back".
+   - Click: deterministic navigation to the resolved target (drop the
+     `history.length` heuristic — both entry points are new tabs, and
+     determinism is what the story demands).
+   - The static `href="/sources.html"` in `document.html` remains the
+     no-JS fallback.
+4. **E2E:** `tests/e2e/test_document_back_navigation.py` per the story
+   mapping; update `test_document_viewer.py` chip-href assertion.
+
+## Locked decisions
+None. A10/A11 untouched (no new endpoint, no new asset).
+
+## Testing & Quality
+- E2E in isolation (new file) + `test_document_viewer.py` regression in
+  isolation.
+- Coverage gate unchanged (frontend-only phase).
+
+## Commit
+```bash
+git add -A .agent/ frontend/ tests/e2e/ && git commit --no-gpg-sign -m "fix(ui): document viewer back button returns to the page you came from (chat or sources)"
+```