refactor(agents): migrate .agent/ planning tree to .agents/

Standardize on the .agents/ directory (shared with project skills): phases/, user_stories/, reports/, screenshots/, validate.sh, and phase-sessions/ + pipeline.log all move to .agents/ (git mv preserves history; runtime artifacts move alongside). Updates every reference in AGENTS.md, README.md, .gitignore, app docstrings, and test story headers. Historical KB content in data/ and the runtime pipeline.log transcript are left untouched.
2026-09-05 10:57:07 -04:00
parent 766702c750
commit dbf2af26c6
1118 changed files with 664 additions and 664 deletions
@@ -1,6 +1,6 @@
 """Playwright E2E fixtures (shared by every story's test file).

-Each user story in ``.agent/user_stories/`` gets its own isolated E2E test
+Each user story in ``.agents/user_stories/`` gets its own isolated E2E test
 file; this conftest provides the shared environment:

 * ``mock_llm``   — deterministic OpenAI-compatible server (see mock_llm.py).
@@ -1,6 +1,6 @@
 """Phase 16 E2E (Playwright): single-admin sign-in (A10 revised).

-Story: ``.agent/user_stories/admin-auth.md``
+Story: ``.agents/user_stories/admin-auth.md``
 Run in isolation (DB must be up: ``podman compose up -d db``):

    uv run pytest tests/e2e/test_admin_auth.py -v --no-cov
@@ -1,6 +1,6 @@
 """Phase 37 E2E (Playwright, mock-only): agent document tools (list + read).

-Story: ``.agent/user_stories/agent-document-tools.md``
+Story: ``.agents/user_stories/agent-document-tools.md``
 Run in isolation (DB must be up: ``podman compose up -d db``):

    uv run pytest tests/e2e/test_agent_document_tools.py -v --no-cov
@@ -1,6 +1,6 @@
 """Phase 45 E2E (Playwright, mock-only): as many tool calls as the model wants.

-Story: ``.agent/user_stories/agent-unlimited-tools.md``
+Story: ``.agents/user_stories/agent-unlimited-tools.md``
 Run in isolation (DB must be up: ``podman compose up -d db``):

    uv run pytest tests/e2e/test_agent_unlimited_tools.py -v --no-cov
@@ -1,6 +1,6 @@
 """Phase 49 story E2E (Playwright): archive upload sources.

-Story: ``.agent/user_stories/archive-upload-sources.md``
+Story: ``.agents/user_stories/archive-upload-sources.md``
 Run in isolation (DB must be up: ``podman compose up -d db``):

    uv run pytest tests/e2e/test_archive_upload_sources.py -v --no-cov
@@ -1,9 +1,9 @@
 """Phase 22 E2E (Playwright): the background layers — now a regression
 suite for the phase-25 no-motion design.

-Story: ``.agent/user_stories/background-no-motion.md`` (the phase-25
+Story: ``.agents/user_stories/background-no-motion.md`` (the phase-25
 owner direction supersedes this suite's original pins; the phase-22
-history lives in ``.agent/user_stories/background-animation.md``)
+history lives in ``.agents/user_stories/background-animation.md``)
 Run in isolation (DB must be up: ``podman compose up -d db``):

    uv run pytest tests/e2e/test_background_animation.py -v --no-cov
@@ -1,6 +1,6 @@
 """Phase 25 E2E (Playwright): the background no longer moves — it only fades.

-Story: ``.agent/user_stories/background-no-motion.md`` (supersedes
+Story: ``.agents/user_stories/background-no-motion.md`` (supersedes
 ``background-animation.md``)
 Run in isolation (DB must be up: ``podman compose up -d db``):

@@ -12,7 +12,7 @@ It should be smooth, fluxuating, dimming and brightening, but not
 moving. Different bright spots should slowly fade in and out."

 The two root causes (phase-22 measurements in
-``.agent/reports/22_background_animation/``):
+``.agents/reports/22_background_animation/``):
  - the "jitter" was the grid's 44px/60s drift (0.73px/s, diagonally
    down-right) — a 1px line translated sub-pixel by sub-pixel
    rasterizes with per-frame stepping, not smooth motion;
@@ -1,7 +1,7 @@
 """Phase 33 E2E (Playwright): cache busting — what the browser actually
 receives and requests.

-Story: ``.agent/user_stories/cache-busting.md``
+Story: ``.agents/user_stories/cache-busting.md``
 Run in isolation (DB must be up: ``podman compose up -d db``):

    uv run pytest tests/e2e/test_cache_busting.py -v --no-cov
@@ -1,6 +1,6 @@
 """Phase 14 E2E (Playwright): the chat conversation survives a refresh.

-Story: ``.agent/user_stories/chat-persistence.md``
+Story: ``.agents/user_stories/chat-persistence.md``
 Run in isolation (DB must be up: ``podman compose up -d db``):

    uv run pytest tests/e2e/test_chat_persistence.py -v --no-cov
@@ -1,6 +1,6 @@
 """Phase 03 E2E (Playwright): the happy-path RAG chat turn.

-Story: ``.agent/user_stories/chat-rag-answer.md``
+Story: ``.agents/user_stories/chat-rag-answer.md``
 Run in isolation (DB must be up: ``podman compose up -d db``):

    uv run pytest tests/e2e/test_chat_rag.py -v --no-cov
@@ -1,6 +1,6 @@
 """Phase 39 E2E (Playwright): the configurable app name (``BOR_APP_NAME``).

-Story: ``.agent/user_stories/configurable-brand.md``
+Story: ``.agents/user_stories/configurable-brand.md``
 Run in isolation (DB must be up: ``podman compose up -d db``):

    uv run pytest tests/e2e/test_configurable_brand.py -v --no-cov
@@ -1,7 +1,7 @@
 """Phase 08 E2E (Playwright): dark tech theme — palette, no emoji, animated
 background, reduced motion, behavior intact, all assets local.

-Story: ``.agent/user_stories/dark-tech-theme.md``
+Story: ``.agents/user_stories/dark-tech-theme.md``
 Run in isolation (DB must be up: ``podman compose up -d db``):

    uv run pytest tests/e2e/test_dark_tech_theme.py -v --no-cov
@@ -1,7 +1,7 @@
 """Phase 13 E2E (Playwright): the viewer's back button returns to the
 page the document was opened from.

-Story: ``.agent/user_stories/document-back-navigation.md``
+Story: ``.agents/user_stories/document-back-navigation.md``
 Run in isolation (DB must be up: ``podman compose up -d db``):

    uv run pytest tests/e2e/test_document_back_navigation.py -v --no-cov
@@ -1,6 +1,6 @@
 """Phase 30 E2E (Playwright): a summary hit delivers the full source doc.

-Story: ``.agent/user_stories/document-summaries.md``
+Story: ``.agents/user_stories/document-summaries.md``
 Run in isolation (DB must be up: ``podman compose up -d db``):

    uv run pytest tests/e2e/test_document_summaries.py -v --no-cov
@@ -1,7 +1,7 @@
 """Phase 26 E2E (Playwright): documents open in the almost-fullscreen
 modal — not in a new page.

-Story: ``.agent/user_stories/document-modal.md``
+Story: ``.agents/user_stories/document-modal.md``
 Run in isolation (DB must be up: ``podman compose up -d db``):

    uv run pytest tests/e2e/test_document_viewer.py -v --no-cov
@@ -1,7 +1,7 @@
 """Phase 35 story E2E (Playwright): the admin page to add / remove git
 sources (``/git-sources.html``).

-Story: ``.agent/user_stories/git-sources-admin.md``
+Story: ``.agents/user_stories/git-sources-admin.md``
 Run in isolation (DB must be up: ``podman compose up -d db``):

    uv run pytest tests/e2e/test_git_sources_admin.py -v --no-cov
@@ -12,7 +12,7 @@ admin-only "Tuning" nav link (``#nav-tuning`` — is-active on this page):
 like the Sources link it ships hidden and ``header.js`` reveals it once
 whoami says admin, so an anonymous visitor never sees it.

-Story: ``.agent/user_stories/global-tuning.md``
+Story: ``.agents/user_stories/global-tuning.md``
 Run in isolation (DB must be up: ``podman compose up -d db``):

    uv run pytest tests/e2e/test_global_tuning.py -v --no-cov
@@ -1,7 +1,7 @@
 """Phase 70 E2E (Playwright, mock-only): the harness-aligned tool surface
 (``ls`` / ``read(path)`` / ``grep(pattern, path?)``).

-Story: ``.agent/user_stories/agent-document-tools.md`` (phase 70 reshapes
+Story: ``.agents/user_stories/agent-document-tools.md`` (phase 70 reshapes
 the tools that story delivered — owner decision 2026-09-03: "match
 existing harnesses as much as possible", the pi.dev tool shapes).
 Run in isolation (DB must be up: ``podman compose up -d db``):
@@ -1,6 +1,6 @@
 """Phase 12 E2E (Playwright): one header, same size on every page.

-Story: ``.agent/user_stories/header-consistency.md``
+Story: ``.agents/user_stories/header-consistency.md``
 Run in isolation (DB must be up: ``podman compose up -d db``):

    uv run pytest tests/e2e/test_header_consistency.py -v --no-cov
@@ -1,6 +1,6 @@
 """Phase 04 E2E (Playwright): honest deflection when retrieval is weak.

-Story: ``.agent/user_stories/honest-deflection.md``
+Story: ``.agents/user_stories/honest-deflection.md``
 Run in isolation (DB must be up: ``podman compose up -d db``):

    uv run pytest tests/e2e/test_honest_deflection.py -v --no-cov
@@ -1,6 +1,6 @@
 """Phase 02 E2E (Playwright): the Sources page reflects the imported KB.

-Story: ``.agent/user_stories/import-documents.md``
+Story: ``.agents/user_stories/import-documents.md``
 Run in isolation (DB must be up: ``podman compose up -d db``):

    uv run pytest tests/e2e/test_import_documents.py -v --no-cov
@@ -1,6 +1,6 @@
 """Phase 31 E2E (Playwright): the stored KB overview reaches every turn.

-Story: ``.agent/user_stories/kb-overview-prompt.md``
+Story: ``.agents/user_stories/kb-overview-prompt.md``
 Run in isolation (DB must be up: ``podman compose up -d db``):

    uv run pytest tests/e2e/test_kb_overview.py -v --no-cov
@@ -1,6 +1,6 @@
 """Phase 06 E2E (Playwright): loading feedback & progress.

-Story: ``.agent/user_stories/loading-feedback.md``
+Story: ``.agents/user_stories/loading-feedback.md``
 Run in isolation (DB must be up: ``podman compose up -d db``):

    uv run pytest tests/e2e/test_loading_feedback.py -v --no-cov
@@ -167,7 +167,7 @@ def llm_down(mock_llm: int, _cleanup_replacement_mocks: None) -> Iterator[None]:


 # --------------------------------------------------------------------------
-# Tests (story → test mapping, .agent/user_stories/loading-feedback.md)
+# Tests (story → test mapping, .agents/user_stories/loading-feedback.md)
 # --------------------------------------------------------------------------


@@ -1,6 +1,6 @@
 """Phase 38 story E2E (Playwright): local directory sources.

-Story: ``.agent/user_stories/local-directory-sources.md``
+Story: ``.agents/user_stories/local-directory-sources.md``
 Run in isolation (DB must be up: ``podman compose up -d db``):

    uv run pytest tests/e2e/test_local_directory_sources.py -v --no-cov
@@ -1,6 +1,6 @@
 """Phase 11 E2E (Playwright): long answers stream to completion.

-Story: ``.agent/user_stories/long-answers.md``
+Story: ``.agents/user_stories/long-answers.md``
 Run in isolation (DB must be up: ``podman compose up -d db``):

    uv run pytest tests/e2e/test_long_answers.py -v --no-cov
@@ -1,6 +1,6 @@
 """Phase 44 E2E (Playwright): GFM pipe tables in the shared renderer.

-Story: ``.agent/user_stories/markdown-tables.md``
+Story: ``.agents/user_stories/markdown-tables.md``
 Run in isolation (DB must be up: ``podman compose up -d db``):

    uv run pytest tests/e2e/test_markdown_tables.py -v --no-cov
@@ -1,6 +1,6 @@
 """Phase 46 E2E (Playwright): the mobile hamburger dropdown nav.

-Story: ``.agent/user_stories/mobile-hamburger-nav.md``
+Story: ``.agents/user_stories/mobile-hamburger-nav.md``
 TODO.md L9 (owner permission 2026-08-27): "The navbar on mobile is way
 too squished. Make it a hamburger dropdown menu with a nice animation."

@@ -1,6 +1,6 @@
 """Phase 34 story E2E (Playwright): ONE navbar on every page.

-Story: ``.agent/user_stories/nav-consistency.md``
+Story: ``.agents/user_stories/nav-consistency.md``
 Run in isolation (DB must be up: ``podman compose up -d db``):

    uv run pytest tests/e2e/test_nav_consistency.py -v --no-cov
@@ -1,7 +1,7 @@
 """Phase 48 story E2E (Playwright): the nav rename — "Sources" becomes
 "RAG", "Git sources" becomes "Sources".

-Story: ``.agent/user_stories/nav-sources-rag-rename.md``
+Story: ``.agents/user_stories/nav-sources-rag-rename.md``
 Run in isolation (DB must be up: ``podman compose up -d db``):

    uv run pytest tests/e2e/test_nav_rename_sources.py -v --no-cov
@@ -1,6 +1,6 @@
 """Phase 42 E2E (Playwright, mock-only): the chat NEVER autoscrolls.

-Story: ``.agent/user_stories/no-reply-autoscroll.md`` — owner direction
+Story: ``.agents/user_stories/no-reply-autoscroll.md`` — owner direction
 2026-08-27 (TODO.md L5) revising the phase-18 follow-the-bottom choice:
 "Get rid of the chat reply autoscroll, it's breaking things like making
 it impossible for the user to scroll while a reply generates."
@@ -1,7 +1,7 @@
 """Phase 47 E2E (Playwright): quadlet unit files + Jinja templates ride the
 A9 import path end to end (A9 revised 2026-08-27, owner permission).

-Story: ``.agent/user_stories/quadlet-jinja-import.md``
+Story: ``.agents/user_stories/quadlet-jinja-import.md``
 Run in isolation (DB must be up: ``podman compose up -d db``):

    uv run pytest tests/e2e/test_quadlet_jinja_import.py -v --no-cov
@@ -1,6 +1,6 @@
 """Phase 07 E2E (Playwright): responsive + WCAG 2.1 AA polish sweep.

-Story: ``.agent/user_stories/responsive-polish.md``
+Story: ``.agents/user_stories/responsive-polish.md``
 This phase IS the visual/a11y verification (PLAN §7 end-to-end); the suite
 below is the acceptance test. Run in isolation (DB must be up:
 ``podman compose up -d db``):
@@ -1,6 +1,6 @@
 """Phase 09 E2E (Playwright): retrieval quality — hybrid search end to end.

-Story: ``.agent/user_stories/retrieval-quality.md``
+Story: ``.agents/user_stories/retrieval-quality.md``
 Run in isolation (DB must be up: ``podman compose up -d db``):

    uv run pytest tests/e2e/test_retrieval_quality.py -v --no-cov
@@ -1,6 +1,6 @@
 """Phase 19 E2E (Playwright): the shared header bar on every page.

-Story: ``.agent/user_stories/shared-header.md``
+Story: ``.agents/user_stories/shared-header.md``
 Run in isolation (DB must be up: ``podman compose up -d db``):

    uv run pytest tests/e2e/test_shared_header.py -v --no-cov
@@ -1,6 +1,6 @@
 """Phase 20 E2E (Playwright): navigating away mid-turn keeps the answer.

-Story: ``.agent/user_stories/sources-midstream.md``
+Story: ``.agents/user_stories/sources-midstream.md``
 Bug report (TODO.md L3): *"Clicking "sources" while chat is generating
 clears chat and result will never show up."*
 Run in isolation (DB must be up: ``podman compose up -d db``):
@@ -3,7 +3,7 @@
 Phase 16 adaptation: tuning is admin-only — every test performs the real
 form login (``e2e.auth_helpers.login``) before touching the tuning UI.

-Story: ``.agent/user_stories/steering-notes.md``
+Story: ``.agents/user_stories/steering-notes.md``
 Run in isolation (DB must be up: ``podman compose up -d db``):

    uv run pytest tests/e2e/test_steering.py -v --no-cov
@@ -1,6 +1,6 @@
 """Phase 05 E2E (Playwright): onboarding suggestion chips, one-tap submit.

-Story: ``.agent/user_stories/suggestion-chips.md``
+Story: ``.agents/user_stories/suggestion-chips.md``
 Run in isolation (DB must be up: ``podman compose up -d db``):

    uv run pytest tests/e2e/test_suggestion_chips.py -v --no-cov
@@ -1,7 +1,7 @@
 """Phase 36 E2E (Playwright): the summary and the original document
 are visible **together** in the viewer.

-Story: ``.agent/user_stories/summary-in-viewer.md``
+Story: ``.agents/user_stories/summary-in-viewer.md``
 Run in isolation (DB must be up: ``podman compose up -d db``):

    uv run pytest tests/e2e/test_summary_in_viewer.py -v --no-cov
@@ -1,6 +1,6 @@
 """Phase 32 E2E (Playwright): the admin-only "Sync sources" button.

-Story: ``.agent/user_stories/admin-sync-button.md``
+Story: ``.agents/user_stories/admin-sync-button.md``
 Run in isolation (DB must be up: ``podman compose up -d db``; git on
 PATH — a documented environment prerequisite, phase 28):

@@ -1,6 +1,6 @@
 """Phase 41 E2E (Playwright): model-down sync fails fast with a modal.

-Story: ``.agent/user_stories/sync-model-fail-fast.md``
+Story: ``.agents/user_stories/sync-model-fail-fast.md``
 Run in isolation (DB must be up: ``podman compose up -d db``; git on
 PATH — a documented environment prerequisite, phase 28):

@@ -1,6 +1,6 @@
 """Phase 17 E2E (Playwright, mock-only): the model's "thinking" display.

-Story: ``.agent/user_stories/thinking-display.md``
+Story: ``.agents/user_stories/thinking-display.md``
 Run in isolation (DB must be up: ``podman compose up -d db``):

    uv run pytest tests/e2e/test_thinking_display.py -v --no-cov
@@ -1,6 +1,6 @@
 """Phase 43 E2E (Playwright, mock-only): the Thinking window scrolls again.

-Story: ``.agent/user_stories/thinking-scroll-back.md``
+Story: ``.agents/user_stories/thinking-scroll-back.md``
 Run in isolation (DB must be up: ``podman compose up -d db``):

    uv run pytest tests/e2e/test_thinking_scroll.py -v --no-cov
@@ -1,7 +1,7 @@
 """Phase 72 E2E (Playwright, mock-only): the ls-teaching
 self-correction loop through the real UI.

-Story: ``.agent/user_stories/agent-document-tools.md`` (this phase
+Story: ``.agents/user_stories/agent-document-tools.md`` (this phase
 repairs the model-facing contract the phase-70 tools reshaped — the
 2026-09-03 incident: the harness-prior ``ls(path='.')`` misuse met the
 terse refusal, and the model re-reasoned the same paragraphs over and
@@ -23,7 +23,7 @@ No KB seeding is needed: the link is pure header markup gated by
 ``/api/whoami``, so a light environment (app + mock LLM + ``db_ready``)
 suffices — there is no ``_reset_db`` here.

-Story: ``.agent/user_stories/global-tuning.md``
+Story: ``.agents/user_stories/global-tuning.md``
 Run in isolation (DB must be up: ``podman compose up -d db``):

    uv run pytest tests/e2e/test_tuning_nav_link.py -v --no-cov
@@ -26,7 +26,7 @@ browser-level contract:
  (``#nav-sources`` / ``#nav-git-sources`` / ``#nav-tuning``) holds:
  hidden for anonymous, revealed for admin.

-Story: ``.agent/user_stories/tuning-toggle-flash.md``
+Story: ``.agents/user_stories/tuning-toggle-flash.md``
 Run in isolation (DB must be up: ``podman compose up -d db``):

    uv run pytest tests/e2e/test_tuning_toggle_flash.py -v --no-cov
@@ -1,6 +1,6 @@
 """Phase 24 E2E (Playwright): a matched document reaches the LLM whole.

-Story: ``.agent/user_stories/whole-document-context.md``
+Story: ``.agents/user_stories/whole-document-context.md``
 Run in isolation (DB must be up: ``podman compose up -d db``):

    uv run pytest tests/e2e/test_whole_document_context.py -v --no-cov
@@ -32,8 +32,8 @@ spot gradients, reduced motion across all four layers) is pinned in
 tests/unit/test_background_no_motion.py; browser behavior is E2E-covered
 by tests/e2e/test_background_no_motion.py (task 02).

-Story: .agent/user_stories/background-no-motion.md (supersedes
-.agent/user_stories/background-animation.md).
+Story: .agents/user_stories/background-no-motion.md (supersedes
+.agents/user_stories/background-animation.md).
 """
 from __future__ import annotations

@@ -5,7 +5,7 @@ and to the right every second and it slowly blinks brighter and darker.
 It should be smooth, fluxuating, dimming and brightening, but not
 moving. Different bright spots should slowly fade in and out."

-The diagnosis (`.agent/reports/25_background_no_motion/`) found both
+The diagnosis (`.agents/reports/25_background_no_motion/`) found both
 root causes in the phase-22 design:
  - "jitters down and to the right" = the grid's 44px/60s drift
    (0.73px/s, diagonally down-right) — a 1px grid line translated
@@ -21,7 +21,7 @@ negative delays → out of phase; LCM 4641s → the composite pattern
 effectively never repeats within a viewing session), so the total light
 fluxuates smoothly and irregularly — no blink, no jitter, no movement.

-Story: .agent/user_stories/background-no-motion.md. Browser behavior
+Story: .agents/user_stories/background-no-motion.md. Browser behavior
 (no motion, visible fades, no occlusion, no overflow) is E2E-covered by
 tests/e2e/test_background_no_motion.py (task 02).
 """