Skip to content

docs: plan psychiatrist workflow#30

Merged
nonnil merged 89 commits into
mainfrom
docs/task-24-psychiatrist-plan
Jul 16, 2026
Merged

docs: plan psychiatrist workflow#30
nonnil merged 89 commits into
mainfrom
docs/task-24-psychiatrist-plan

Conversation

@nonnil

@nonnil nonnil commented May 31, 2026

Copy link
Copy Markdown
Member

Summary:

  • Archived active workflow Tasks 20-23 under docs/workflows/archive.
  • Updated the workflow map so Task 24 is the active planning workflow.
  • Added a planning-only Task 24 Psychiatrist workflow for a reader-only memory-scoped assistant built on the existing backend-only Codex app-server integration.
  • Updated the Psychiatrist plan so user prompts and answers are stored as memory-local prompt/response pairs under each memory's threads/ subtree, not SQLite.
  • Added append-only PAIRS.jsonl pair revision storage, keeping each assistant response tied to the user prompt it answers.
  • Added durable stream replay for user-visible process/answer events so running turns survive reader navigation and browser reload.
  • Added explicit Stop semantics: submit becomes Stop while running, and route lifecycle changes do not cancel work.
  • Added same-pair Regenerate semantics: reuse stored prompt/context, keep thread_id and pair_id, overwrite RESPONSE.md/THREAD.md, and do not create a new pair/thread.
  • Added git backup planning for psychiatrist_thread_update and psychiatrist_response_regenerate commit actions.
  • Added the Codex app-server runtime policy: no shell access, no local file editing, no project/store filesystem roots, and network disabled unless the user explicitly approves web-source access for that turn.
  • Added 24.7 and 24.8 for the repo-local psychiatrist skill, deterministic runtime prompt policy, streaming continuity, Stop, Regenerate, and backup behavior.

Verification:

  • git diff --check
  • Local markdown link check over 30 workflow files for initial archive/Task 24 plan
  • Local markdown link check over 8 workflow files after thread-storage update
  • Local markdown link check over 9 Task 24 workflow files after pair/skill/runtime-policy update
  • Local markdown link check over 10 Task 24 workflow files after stream continuity/Regenerate update
  • Placeholder and stale terminology scans over Task 24 workflow
  • bun run typecheck from the Task 24 temp worktree with dependency resolution fixed
  • Pre-push hook from clean worktree: typecheck, test, build

Summary by CodeRabbit

  • Documentation
    • Updated workflow planning to add Task 24 and archive Tasks 20–23, including expanded baseline checklists and branching guidance.
    • Added comprehensive Task 24 specifications for a memory-scoped, reader-only assistant experience, covering conversation contracts, prompt/memory context rules, durable per-memory thread storage, SSE streaming with replay, reader dock/chat UI behavior, safety & freshness controls, and verification steps.
    • Corrected relative links across archived workflow documents.
  • Chores
    • Updated ignore rules to exclude the .eda/ directory.

@coderabbitai

coderabbitai Bot commented May 31, 2026

Copy link
Copy Markdown

Review Change Stack

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

  • @coderabbitai resume to resume automatic reviews.
  • @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

  • ▶️ Resume reviews
  • 🔍 Trigger review
📝 Walkthrough

Walkthrough

Adds the complete Task 24 Psychiatrist Memory Assistant specification across nine documents under docs/workflows/task-24-psychiatrist-assistant/, updates the main workflow registry to register Task 24, archives Tasks 20–23, extends the Shared Baseline checklist, corrects relative markdown link paths in four archived workflow docs, and adds .eda/ to .gitignore.

Changes

Task 24 Psychiatrist Assistant Documentation

Layer / File(s) Summary
Workflow registry, baseline, and housekeeping
docs/workflows/README.md, docs/workflows/archive/task-20-lazy-loading-performance/README.md, docs/workflows/archive/task-21-popover-and-translation-ui-fixes/README.md, docs/workflows/archive/task-22-vim-like-key-bindings.md, docs/workflows/archive/task-23-reader-toc-reading-progress/README.md, .gitignore
Task 24 added to the Task Map under feat/psychiatrist; Tasks 20–23 archived with consolidated rationale and expanded archive table; Shared Baseline checklist extended with performance, translation UI, keybinding, and reader-progress items; feat/psychiatrist added to allowed branch names; relative link paths fixed in archived READMEs; .eda/ added to .gitignore.
Task 24 main README
docs/workflows/task-24-psychiatrist-assistant/README.md
Full architecture overview: memory-scoped reader-only assistant, server-owned context/prompt construction, durable per-memory threads/ storage, pair-shaped transcript permanence, SSE streaming continuity with replay after navigation/reload, Stop/Regenerate semantics, safety and freshness contracts, ordered implementation subtasks, and browser verification baseline.
Codex conversation adapter
docs/workflows/task-24-psychiatrist-assistant/01-codex-conversation-adapter.md
CodexConversationClient interface with probe/runConversationTurn/cancelTurn/close; lifecycle sequencing (initialize/initialized before app-server requests); ephemeral vs reused thread behavior; minimum-privilege constraints (no filesystem/shell/file-edit tools, no project-root/memory-store roots); default-disabled network; model/reasoningEffort pass-through; event forwarding rules; implementation checklist and acceptance criteria.
Memory context types and deterministic prompt policy
docs/workflows/task-24-psychiatrist-assistant/02-memory-context-and-prompt-contract.md
TypeScript interfaces for memory context, thread pair structures, prompt inputs, regenerate input, and web-source policy; context builder rules for source vs translated memory with hash-mismatch stale rejection; thread manifest freshness boundary; per-turn context snapshots with provenance; deterministic buildPsychiatristPrompt() policy text and required prompt components; test coverage requirements; acceptance criteria.
Thread storage layout and REST/SSE API
docs/workflows/task-24-psychiatrist-assistant/03-thread-storage-api-and-streaming-events.md
On-disk artifacts per thread/pair/turn (THREAD.json, THREAD.md, PAIRS.jsonl, PROMPT.md, CONTEXT.json, RESPONSE.md, turns/*.json, streams/*.jsonl); atomic write/append rules; hash- and policy-version-based staleness; one-active-turn concurrency (409 turn_conflict); REST API shape for create/resume, read, send, SSE streaming with replay/idempotency, cancel, and regenerate reusing same pair_id; safe error shape with content filtering; no SQLite storage; test commands and acceptance criteria.
Reader floating dock and client request API
docs/workflows/task-24-psychiatrist-assistant/04-reader-floating-dock-and-chat-ui.md
iOS home-bar style collapsed dock, expanded transcript area, animations, keyboard behavior (Enter vs Shift+Enter), Stop/cancel semantics (explicit Stop only), Escape close with focus return, reduced-motion rules, transcript persistence; ReadyMemoryReader mounts PsychiatristDock outside data-reader-content with langCode/memoryId; psychiatrist-requests.ts client API contract; EventSource replay/streaming rules; per-turn web-source approval gating; component and E2E test scenarios.
Safety, freshness, and error handling
docs/workflows/task-24-psychiatrist-assistant/05-safety-freshness-and-errors.md
Per-turn content hash recomputation for stale-context protection; prompt-injection mitigation via untrusted-data delimiters; default-denied network with terminal network_permission_required; context bounds with context_overflow; turn lifecycle/cancellation rules; pair integrity and regenerate overwrite semantics; safe browser-visible UI error mapping (retryable vs non-retryable); test commands and acceptance criteria.
Documentation verification and PR handoff
docs/workflows/task-24-psychiatrist-assistant/06-docs-browser-verification-handoff.md
Documentation update checklist across architecture, reader routing/surfaces, design-system visuals (dock, reduced-motion, mobile), configuration scope, glossary, and psychiatrist skill policy; focused/full/browser verification commands and browser checklist; PR handoff requirements (API routes, persistence/replay guarantees, Stop/Regenerate semantics, canonical memory write boundaries, app-server restrictions, known limitations); acceptance criteria.
Psychiatrist skill contract and runtime policy
docs/workflows/task-24-psychiatrist-assistant/07-psychiatrist-skill-and-runtime-policy.md
Repo-local psychiatrist skill contract (memory-scoped/pair-oriented, no medical framing, no memory mutations, no shell/filesystem, no unapproved network, no hidden artifacts); PSYCHIATRIST_PROMPT_POLICY_VERSION persisted in THREAD.json and per-turn turns/{turnId}.json; policy text embedded before memory/pair history; freshness checks; default-denied network with per-turn permission-to-networkAccess mapping; retry_pair_id/retry_turn_id for same-pair retry; end-to-end pair/network flows; test coverage for skill content, prompt/freshness/permission, and Codex payload constraints.
Streaming continuity, Stop, Regenerate, and backup
docs/workflows/task-24-psychiatrist-assistant/08-streaming-continuity-regenerate-backup.md
New per-pair artifacts (THREAD.md, PROMPT.md, CONTEXT.json, RESPONSE.md, append-only streams/{turnId}.jsonl); gap-free replay/live continuation via subscribe-before-replay, event_id/Last-Event-ID de-duplication, browser disconnect continuation, safe SSE payload filtering; regenerate route reusing same thread_id/pair_id with new turn_id, overwriting RESPONSE.md/THREAD.md on completion and enqueuing backup; Submit→Stop UI transition; reconnection via active event_url; distinct backup reasons (psychiatrist_thread_update vs psychiatrist_response_regenerate); test coverage and acceptance criteria.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

  • hauntedfail/Trauma#20: Both PRs update docs/workflows/README.md's workflow "Task Map"/branching documentation (main adds Task 24 and archives prior tasks; retrieved adds Tasks 18–19 and extends allowed branch names), so the changes are connected at the same planning-doc surface.

Poem

🐇 A psychiatrist doc hops into the tree,
With threads and streams and memory!
THREAD.json holds the past,
Regenerate makes answers last.
Stop is Stop—not Escape or close—
And the rabbit's spec remains verbose! 📄

🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title 'docs: plan psychiatrist workflow' directly and concisely summarizes the main change: adding planning documentation for the Task 24 Psychiatrist workflow. It is clear, specific, and reflects the primary purpose of the changeset.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch docs/task-24-psychiatrist-plan

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@nonnil
nonnil marked this pull request as ready for review June 2, 2026 15:39

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: b752986f11

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 Nitpick comments (1)
docs/workflows/task-24-psychiatrist-assistant/07-psychiatrist-skill-and-runtime-policy.md (1)

69-70: ⚡ Quick win

Make the permission-to-runtime mapping explicit to prevent contract drift.

The spec uses three related literal families (web_source_permission, web_source_policy.reason, networkAccess) but only implies their mapping. Add a small canonical mapping table (or normative bullet list) so API route, turn runner, and tests cannot diverge on values/translation logic.

Suggested doc addition
 ## Pair And Network Flow
+
+Canonical mapping (normative):
+
+- `web_source_permission: "deny"` -> `networkAccess: "disabled"` and no
+  `web_source_policy.reason`.
+- `web_source_permission: "allow_for_this_turn"` ->
+  `networkAccess: "user_approved_web_sources"` and
+  `web_source_policy.reason = "user_approved_for_turn"`.
+- Any other value must be rejected at route validation.

Also applies to: 81-82, 94-95, 143-145

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In
`@docs/workflows/task-24-psychiatrist-assistant/07-psychiatrist-skill-and-runtime-policy.md`
around lines 69 - 70, Add a canonical, normative mapping between
web_source_permission values, web_source_policy.reason, and the runtime
networkAccess value so implementers cannot drift: explicitly list each
permission string (e.g., "user_approved_web_source", "no_web_source", etc.), the
corresponding web_source_policy.reason that API routes must set, and the exact
networkAccess literal that runConversationTurn() should receive (e.g., "enabled"
or "disabled"); update the doc section around runConversationTurn(), the API
route guidance, and the turn-runner/tests notes to reference this single mapping
so all three (API route, runConversationTurn, and tests) use the same
translation logic.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In
`@docs/workflows/task-24-psychiatrist-assistant/07-psychiatrist-skill-and-runtime-policy.md`:
- Around line 69-70: Add a canonical, normative mapping between
web_source_permission values, web_source_policy.reason, and the runtime
networkAccess value so implementers cannot drift: explicitly list each
permission string (e.g., "user_approved_web_source", "no_web_source", etc.), the
corresponding web_source_policy.reason that API routes must set, and the exact
networkAccess literal that runConversationTurn() should receive (e.g., "enabled"
or "disabled"); update the doc section around runConversationTurn(), the API
route guidance, and the turn-runner/tests notes to reference this single mapping
so all three (API route, runConversationTurn, and tests) use the same
translation logic.

ℹ️ Review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 907f14f7-fbc7-4019-ae3c-56bc9ae3e89d

📥 Commits

Reviewing files that changed from the base of the PR and between b752986 and 218b78f.

📒 Files selected for processing (9)
  • docs/workflows/README.md
  • docs/workflows/task-24-psychiatrist-assistant/01-codex-conversation-adapter.md
  • docs/workflows/task-24-psychiatrist-assistant/02-memory-context-and-prompt-contract.md
  • docs/workflows/task-24-psychiatrist-assistant/03-thread-storage-api-and-streaming-events.md
  • docs/workflows/task-24-psychiatrist-assistant/04-reader-floating-dock-and-chat-ui.md
  • docs/workflows/task-24-psychiatrist-assistant/05-safety-freshness-and-errors.md
  • docs/workflows/task-24-psychiatrist-assistant/06-docs-browser-verification-handoff.md
  • docs/workflows/task-24-psychiatrist-assistant/07-psychiatrist-skill-and-runtime-policy.md
  • docs/workflows/task-24-psychiatrist-assistant/README.md
✅ Files skipped from review due to trivial changes (7)
  • docs/workflows/task-24-psychiatrist-assistant/02-memory-context-and-prompt-contract.md
  • docs/workflows/task-24-psychiatrist-assistant/03-thread-storage-api-and-streaming-events.md
  • docs/workflows/task-24-psychiatrist-assistant/06-docs-browser-verification-handoff.md
  • docs/workflows/task-24-psychiatrist-assistant/05-safety-freshness-and-errors.md
  • docs/workflows/task-24-psychiatrist-assistant/04-reader-floating-dock-and-chat-ui.md
  • docs/workflows/task-24-psychiatrist-assistant/01-codex-conversation-adapter.md
  • docs/workflows/README.md

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 218b78f528

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread docs/workflows/task-24-psychiatrist-assistant/01-codex-conversation-adapter.md Outdated

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: c4ce40fae9

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread docs/workflows/task-24-psychiatrist-assistant/05-safety-freshness-and-errors.md Outdated

@nonnil nonnil left a comment

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ok ok

@nonnil nonnil left a comment

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

@nonnil nonnil left a comment

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 6771ee8615

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread docs/workflows/archive/task-24-psychiatrist-assistant/README.md Outdated
@nonnil

nonnil commented Jul 12, 2026

Copy link
Copy Markdown
Member Author

@codex review

Please review again at 19f4484.

Summary: processed all six unresolved Codex threads with per-thread replies, reactions, and resolutions; scoped public Psychiatrist thread reads to the owning memory with cross-memory regression coverage; clarified Task 24 route-test sequencing and backup-status bookkeeping; and hardened the E2E readonly SQLite fixture after a CI SQLITE_BUSY failure.

Validation: local full verify passed (116 files, 1026 tests passed, 5 todo, production build); full Playwright E2E passed 53/53; GitHub Actions Verify passed; CodeRabbit passed; final unresolved non-outdated thread count is 0; mergeStateStatus is CLEAN.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 19f44845a6

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread src/server/psychiatrist/thread-route.ts Outdated
Comment thread src/server/psychiatrist/message-route.ts Outdated
Comment thread src/server/psychiatrist/message-route.ts
Comment thread src/server/translation/codex-app-server.ts Outdated
@nonnil

nonnil commented Jul 12, 2026

Copy link
Copy Markdown
Member Author

Local implementation/security audit and all review follow-ups are complete.

Final implementation commit: 41cece3
Post-report commit: 5ffc8b8
Report: https://github.com/hauntedfail/Trauma/blob/docs/task-24-psychiatrist-plan/docs/reviews/2026-07-13-pr-30-psychiatrist-review-response-and-local-audit.md

Verification:

  • mise exec -- bun run verify: 117 files, 1048 passed, 5 todo, build passed
  • GIT_CONFIG_GLOBAL=/dev/null mise exec -- bun run test:e2e: 56/56 passed
  • final implementation CI Verify: passed
  • unresolved review threads after inline replies/reactions/resolution: 0

@codex review

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 5ffc8b8358

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread src/server/psychiatrist/regenerate-route.ts Outdated
Comment thread src/server/backup/index.ts Outdated
Comment thread src/server/psychiatrist/message-route.ts Outdated
Comment thread src/components/reader/PsychiatristDock.tsx Outdated
Comment thread src/server/psychiatrist/events-route.ts Outdated
@nonnil

nonnil commented Jul 12, 2026

Copy link
Copy Markdown
Member Author

Review trace for review 4680524779: the review body is a generic container with no standalone actionable claim, so it is classified not_valid as an independent item; its five inline findings were adjudicated separately.

All five inline findings were fixed in signed commit c5a2f22, replied to inline, reacted to, and resolved. Local verification passed (117 test files / 1064 tests + build, 60/60 Playwright, dev smoke), and the pushed Verify and CodeRabbit checks are green.

@codex review

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. Another round soon, please!

Reviewed commit: c5a2f22fba

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

@nonnil
nonnil merged commit d025d37 into main Jul 16, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants