refactor(learnings): externalize per-repo learnings to separate GitHub repo

AGENTS.md

@@ -7,7 +7,7 @@ Humans steer. Agents execute. When agents struggle, fix the harness.
 
 Run the session-start script to gather context before doing anything else:
 ```bash
-SESSION=$(bash /Users/nicknisi/Developer/case/scripts/session-start.sh <target-repo-path> --task <task.json>)
+SESSION=$(bash ${CASE_REPO}/scripts/session-start.sh <target-repo-path> --task <task.json>)
 echo "$SESSION"
 ```
 
@@ -33,7 +33,7 @@ Full metadata (commands, remotes, language): `projects.json`
 | Playbooks | `docs/playbooks/` |
 | Agent roles | `agents/` |
 | Entropy management | `docs/conventions/entropy-management.md` |
-| Repo learnings | `docs/learnings/` |
+| Repo learnings | `docs/learnings/README.md` (external — see setup) |
 
 ## Task Dispatch
 

README.md

@@ -235,7 +235,7 @@ docs/
   playbooks/                        Step-by-step guides for recurring operations
   golden-principles.md              Enforced invariants across all repos
   philosophy.md                     Design principles guiding case (incl. context engineering)
-  learnings/                        Per-repo tactical knowledge from retrospective
+  learnings/README.md               Setup for external learnings repo (per-repo knowledge)
   ideation/                         Ideation artifacts (contracts, specs)
 
 tasks/

agents/closer.md

@@ -12,18 +12,20 @@ Create a pull request with a thorough description based on the task file, progre
 
 You receive from the orchestrator:
 
-- **Task file path** — absolute path to the `.md` task file in `/Users/nicknisi/Developer/case/tasks/active/`
+- **Case repo path** (`CASE_REPO`) — absolute path to the case harness repo
+- **Task file path** — absolute path to the `.md` task file in `${CASE_REPO}/tasks/active/`
 - **Task JSON path** — the `.task.json` companion
 - **Target repo path** — absolute path to the repo
 - **Verifier AGENT_RESULT** — structured output from the verifier (screenshot URLs, evidence markers, pass/fail)
+- **Reviewer AGENT_RESULT** — structured output from the reviewer (findings, severity counts)
 
 ## Workflow
 
 ### 0. Session Context
 
 Run the session-start script to orient yourself:
 ```bash
-SESSION=$(bash /Users/nicknisi/Developer/case/scripts/session-start.sh <target-repo-path> --task <task.json>)
+SESSION=$(bash ${CASE_REPO}/scripts/session-start.sh <target-repo-path> --task <task.json>)
 echo "$SESSION"
 ```
 
@@ -38,7 +40,7 @@ Read the output to understand: current branch, last commits, task status, which
    - `.case-manual-tested` — should have `evidence` field (if src/ files changed)
    - `.case-reviewed` — should have `critical: 0` (review findings summary)
 4. Extract video and screenshot tags from the verifier's progress log entry or AGENT_RESULT (look for `<video` tags and `![` image tags)
-5. Read `/Users/nicknisi/Developer/case/docs/conventions/pull-requests.md` for PR format rules
+5. Read `${CASE_REPO}/docs/conventions/pull-requests.md` for PR format rules
 
 ### 2. Draft PR
 
@@ -151,8 +153,8 @@ Only post if there are actual findings to share. Skip this step if the reviewer
 
 1. **Update task JSON** — agent phase only. The `status → pr-opened` transition is owned by the post-PR hook (fires automatically after `gh pr create` succeeds). Do NOT set status here — it creates duplicate ownership.
    ```bash
-   bash /Users/nicknisi/Developer/case/scripts/task-status.sh <task.json> agent closer status completed
-   bash /Users/nicknisi/Developer/case/scripts/task-status.sh <task.json> agent closer completed now
+   bash ${CASE_REPO}/scripts/task-status.sh <task.json> agent closer status completed
+   bash ${CASE_REPO}/scripts/task-status.sh <task.json> agent closer completed now
    ```
    The hook will handle: `status → pr-opened` and `prUrl`.
 

agents/implementer.md

@@ -12,19 +12,20 @@ Implement a fix or feature in the target repo. Write code, run automated tests,
 
 You receive from the orchestrator:
 
-- **Task file path** — absolute path to the `.md` task file in `/Users/nicknisi/Developer/case/tasks/active/`
+- **Case repo path** (`CASE_REPO`) — absolute path to the case harness repo
+- **Task file path** — absolute path to the `.md` task file in `${CASE_REPO}/tasks/active/`
 - **Task JSON path** — the `.task.json` companion (same stem as the .md)
 - **Target repo path** — absolute path to the repo where you'll work
 - **Issue summary** — title, body, and key details from the GitHub/Linear issue
-- **Playbook path** — reference to the relevant playbook in `/Users/nicknisi/Developer/case/docs/playbooks/`
+- **Playbook path** — reference to the relevant playbook in `${CASE_REPO}/docs/playbooks/`
 
 ## Workflow
 
 ### 0. Session Context
 
 Run the session-start script to orient yourself:
 ```bash
-SESSION=$(bash /Users/nicknisi/Developer/case/scripts/session-start.sh <target-repo-path> --task <task.json>)
+SESSION=$(bash ${CASE_REPO}/scripts/session-start.sh <target-repo-path> --task <task.json>)
 echo "$SESSION"
 ```
 
@@ -34,15 +35,19 @@ Read the output to understand: current branch, last commits, task status, which
 
 1. Update task JSON: set status to `implementing` and agent phase to running
    ```bash
-   bash /Users/nicknisi/Developer/case/scripts/task-status.sh <task.json> status implementing
-   bash /Users/nicknisi/Developer/case/scripts/task-status.sh <task.json> agent implementer status running
-   bash /Users/nicknisi/Developer/case/scripts/task-status.sh <task.json> agent implementer started now
+   bash ${CASE_REPO}/scripts/task-status.sh <task.json> status implementing
+   bash ${CASE_REPO}/scripts/task-status.sh <task.json> agent implementer status running
+   bash ${CASE_REPO}/scripts/task-status.sh <task.json> agent implementer started now
    ```
 2. Read the task file (`.md`) — understand the objective, acceptance criteria, and checklist
 3. Read the target repo's `CLAUDE.md` for project-specific instructions
 4. Read the playbook referenced in the task file
-5. Read `/Users/nicknisi/Developer/case/projects.json` to find the repo's available commands (test, typecheck, lint, build, format)
-6. Read `/Users/nicknisi/Developer/case/docs/learnings/{repo}.md` for tactical knowledge from previous tasks in this repo
+5. Read `${CASE_REPO}/projects.json` to find the repo's available commands (test, typecheck, lint, build, format)
+6. Read tactical knowledge from previous tasks in this repo:
+   ```bash
+   bash ${CASE_REPO}/scripts/read-learning.sh {repo} || true
+   ```
+   Review the output before starting. If the command fails (CASE_LEARNINGS_REPO not set), skip — learnings are supplementary.
 
 ### 2. Implement
 
@@ -91,9 +96,9 @@ Then create the final commit as usual.
    Prefer the JSON reporter for structured evidence (pass/fail counts, duration, per-file breakdown):
    ```bash
    # Preferred — structured evidence via vitest JSON reporter
-   pnpm test --reporter=json 2>&1 | bash /Users/nicknisi/Developer/case/scripts/mark-tested.sh
+   pnpm test --reporter=json 2>&1 | bash ${CASE_REPO}/scripts/mark-tested.sh
    # Fallback — if JSON reporter is unavailable or the repo doesn't use vitest
-   pnpm test 2>&1 | bash /Users/nicknisi/Developer/case/scripts/mark-tested.sh
+   pnpm test 2>&1 | bash ${CASE_REPO}/scripts/mark-tested.sh
    ```
    This creates `.case-tested` with a hash of test output AND updates the task JSON `tested` field. You do NOT set `tested` directly.
 
@@ -115,8 +120,8 @@ Then create the final commit as usual.
 
 4. **Update task JSON**:
    ```bash
-   bash /Users/nicknisi/Developer/case/scripts/task-status.sh <task.json> agent implementer status completed
-   bash /Users/nicknisi/Developer/case/scripts/task-status.sh <task.json> agent implementer completed now
+   bash ${CASE_REPO}/scripts/task-status.sh <task.json> agent implementer status completed
+   bash ${CASE_REPO}/scripts/task-status.sh <task.json> agent implementer completed now
    ```
 
 ### 5. Output

agents/retrospective.md

@@ -12,6 +12,7 @@ You run after every `/case` pipeline completion (success or failure). Your job:
 
 You receive from the orchestrator:
 
+- **Case repo path** (`CASE_REPO`) — absolute path to the case harness repo
 - **Task file path** — absolute path to the `.md` task file (with progress log from all agents)
 - **Task JSON path** — the `.task.json` companion (with status, agent phases, evidence flags)
 - **Pipeline outcome** — "completed" (PR created) or "failed" (stopped at some agent)
@@ -23,7 +24,7 @@ You receive from the orchestrator:
 
 Run the session-start script to orient yourself:
 ```bash
-SESSION=$(bash /Users/nicknisi/Developer/case/scripts/session-start.sh <target-repo-path> --task <task.json>)
+SESSION=$(bash ${CASE_REPO}/scripts/session-start.sh <target-repo-path> --task <task.json>)
 echo "$SESSION"
 ```
 
@@ -91,7 +92,7 @@ For each finding, apply the fix directly:
 4. For script changes, verify syntax with `bash -n <file>` after editing
 5. Log each applied change with file path and one-line summary
 
-**What you can edit** (all within `/Users/nicknisi/Developer/case/`):
+**What you can edit** (all within `${CASE_REPO}/`):
 - `docs/architecture/` — architecture docs
 - `docs/conventions/` — convention docs
 - `docs/playbooks/` — playbooks
@@ -100,7 +101,7 @@ For each finding, apply the fix directly:
 - `scripts/` — harness scripts
 - `hooks/` — hook scripts
 - `skills/` — skill files
-- `docs/learnings/` — per-repo tactical knowledge
+- External learnings repo (via `${CASE_REPO}/scripts/write-learning.sh`) — per-repo tactical knowledge
 
 **What you must NEVER edit:**
 - Target repo source code (anything outside `case/`)
@@ -124,21 +125,28 @@ After applying harness improvements, check if the run produced tactical knowledg
 
 **How to append:**
 1. Identify the target repo from the task file's `## Target Repos` section
-2. Read `docs/learnings/{repo}.md`
+2. Read existing learnings to check for duplicates:
+   ```bash
+   bash ${CASE_REPO}/scripts/read-learning.sh {repo}
+   ```
 3. Check if a similar learning already exists (don't duplicate)
 4. Append a new entry:
-   ```
-   - **{YYYY-MM-DD}** — `{file or area}`: {1-2 line tactical note}. (from task {task-filename})
+   ```bash
+   bash ${CASE_REPO}/scripts/write-learning.sh {repo} "- **{YYYY-MM-DD}** — \`{file or area}\`: {1-2 line tactical note}. (from task {task-filename})"
    ```
 
 ### 4c. Escalate Repeated Violations
 
-After updating learnings, scan the learnings file for patterns:
+After updating learnings, scan the learnings for patterns:
 
-1. Read `docs/learnings/{repo}.md`
+1. Read the learnings:
+   ```bash
+   LEARNINGS=$(bash ${CASE_REPO}/scripts/read-learning.sh {repo})
+   echo "$LEARNINGS"
+   ```
 2. Look for 3+ entries describing the same class of issue (e.g., multiple entries about mocking, multiple about import paths)
 3. If found, escalate:
-   - If it's a repo-specific pattern -> note it for the repo's CLAUDE.md (add a comment to the learnings file: "ESCALATION CANDIDATE: consider adding to {repo} CLAUDE.md")
+   - If it's a repo-specific pattern -> note it for the repo's CLAUDE.md (add an entry: "ESCALATION CANDIDATE: consider adding to {repo} CLAUDE.md")
    - If it's a cross-repo pattern -> add to `docs/golden-principles.md` or the relevant convention doc
 4. Log the escalation in your output summary
 

agents/reviewer.md

@@ -12,7 +12,8 @@ You start with a **completely fresh context**. You did not write the code — yo
 
 You receive from the orchestrator:
 
-- **Task file path** — absolute path to the `.md` task file in `/Users/nicknisi/Developer/case/tasks/active/`
+- **Case repo path** (`CASE_REPO`) — absolute path to the case harness repo
+- **Task file path** — absolute path to the `.md` task file in `${CASE_REPO}/tasks/active/`
 - **Task JSON path** — the `.task.json` companion
 - **Target repo path** — absolute path to the repo where the fix was implemented
 
@@ -22,7 +23,7 @@ You receive from the orchestrator:
 
 Run the session-start script to orient yourself:
 ```bash
-SESSION=$(bash /Users/nicknisi/Developer/case/scripts/session-start.sh <target-repo-path> --task <task.json>)
+SESSION=$(bash ${CASE_REPO}/scripts/session-start.sh <target-repo-path> --task <task.json>)
 echo "$SESSION"
 ```
 
@@ -32,9 +33,9 @@ Read the output to understand: current branch, last commits, task status, which
 
 1. Update task JSON:
    ```bash
-   bash /Users/nicknisi/Developer/case/scripts/task-status.sh <task.json> status reviewing
-   bash /Users/nicknisi/Developer/case/scripts/task-status.sh <task.json> agent reviewer status running
-   bash /Users/nicknisi/Developer/case/scripts/task-status.sh <task.json> agent reviewer started now
+   bash ${CASE_REPO}/scripts/task-status.sh <task.json> status reviewing
+   bash ${CASE_REPO}/scripts/task-status.sh <task.json> agent reviewer status running
+   bash ${CASE_REPO}/scripts/task-status.sh <task.json> agent reviewer started now
    ```
 2. Read the task file — understand the issue, objective, and acceptance criteria
 3. Read the git diff to understand what the implementer changed:
@@ -120,7 +121,7 @@ Format each finding as:
 
 1. If **no critical findings**: create the evidence marker:
    ```bash
-   bash /Users/nicknisi/Developer/case/scripts/mark-reviewed.sh \
+   bash ${CASE_REPO}/scripts/mark-reviewed.sh \
      --critical 0 --warnings <N> --info <N>
    ```
 
@@ -138,8 +139,8 @@ Format each finding as:
 
 4. **Update task JSON**:
    ```bash
-   bash /Users/nicknisi/Developer/case/scripts/task-status.sh <task.json> agent reviewer status completed
-   bash /Users/nicknisi/Developer/case/scripts/task-status.sh <task.json> agent reviewer completed now
+   bash ${CASE_REPO}/scripts/task-status.sh <task.json> agent reviewer status completed
+   bash ${CASE_REPO}/scripts/task-status.sh <task.json> agent reviewer completed now
    ```
 
 ### 5. Output

agents/verifier.md

@@ -12,7 +12,8 @@ You start with a **completely fresh context**. You did not write the code — yo
 
 You receive from the orchestrator:
 
-- **Task file path** — absolute path to the `.md` task file in `/Users/nicknisi/Developer/case/tasks/active/`
+- **Case repo path** (`CASE_REPO`) — absolute path to the case harness repo
+- **Task file path** — absolute path to the `.md` task file in `${CASE_REPO}/tasks/active/`
 - **Task JSON path** — the `.task.json` companion
 - **Target repo path** — absolute path to the repo where the fix was implemented
 
@@ -22,7 +23,7 @@ You receive from the orchestrator:
 
 Run the session-start script to orient yourself:
 ```bash
-SESSION=$(bash /Users/nicknisi/Developer/case/scripts/session-start.sh <target-repo-path> --task <task.json>)
+SESSION=$(bash ${CASE_REPO}/scripts/session-start.sh <target-repo-path> --task <task.json>)
 echo "$SESSION"
 ```
 
@@ -32,9 +33,9 @@ Read the output to understand: current branch, last commits, task status, which
 
 1. Update task JSON:
    ```bash
-   bash /Users/nicknisi/Developer/case/scripts/task-status.sh <task.json> status verifying
-   bash /Users/nicknisi/Developer/case/scripts/task-status.sh <task.json> agent verifier status running
-   bash /Users/nicknisi/Developer/case/scripts/task-status.sh <task.json> agent verifier started now
+   bash ${CASE_REPO}/scripts/task-status.sh <task.json> status verifying
+   bash ${CASE_REPO}/scripts/task-status.sh <task.json> agent verifier status running
+   bash ${CASE_REPO}/scripts/task-status.sh <task.json> agent verifier started now
    ```
 2. Read the task file — understand the issue, objective, and acceptance criteria
 3. Read the git diff to understand what the implementer changed:
@@ -61,7 +62,7 @@ git diff --name-only HEAD~1 | grep "^src/" || git diff --name-only main | grep "
 
 1. Read the issue description from the task file's `## Issue Reference` or `## Objective` section
 2. Identify the specific bug/feature scenario to reproduce
-3. Read `/Users/nicknisi/Developer/case/projects.json` to find if the target repo has an example app
+3. Read `${CASE_REPO}/projects.json` to find if the target repo has an example app
 
 **3a. Port hygiene — MANDATORY before starting any app:**
 ```bash
@@ -120,12 +121,12 @@ If the implementer added a new export, alias, or API:
 3. **Upload video and screenshots** for PR inclusion:
    ```bash
    # Upload video — the script auto-converts to GIF (inline) + mp4 (download)
-   VIDEO_MARKDOWN=$(/Users/nicknisi/Developer/case/scripts/upload-screenshot.sh /tmp/verification.webm)
+   VIDEO_MARKDOWN=$(${CASE_REPO}/scripts/upload-screenshot.sh /tmp/verification.webm)
    echo "$VIDEO_MARKDOWN"
 
    # Upload screenshot
    cp .playwright-cli/page-*.png /tmp/after.png
-   SCREENSHOT=$(/Users/nicknisi/Developer/case/scripts/upload-screenshot.sh /tmp/after.png)
+   SCREENSHOT=$(${CASE_REPO}/scripts/upload-screenshot.sh /tmp/after.png)
    echo "$SCREENSHOT"
    ```
 
@@ -137,7 +138,7 @@ If the implementer added a new export, alias, or API:
 
 4. Create the manual testing evidence marker:
    ```bash
-   bash /Users/nicknisi/Developer/case/scripts/mark-manual-tested.sh
+   bash ${CASE_REPO}/scripts/mark-manual-tested.sh
    ```
    This checks for recent playwright screenshots and creates `.case-manual-tested` with evidence. It also updates the task JSON `manualTested` field. You do NOT set `manualTested` directly.
 
@@ -156,8 +157,8 @@ If the implementer added a new export, alias, or API:
 
 2. **Update task JSON**:
    ```bash
-   bash /Users/nicknisi/Developer/case/scripts/task-status.sh <task.json> agent verifier status completed
-   bash /Users/nicknisi/Developer/case/scripts/task-status.sh <task.json> agent verifier completed now
+   bash ${CASE_REPO}/scripts/task-status.sh <task.json> agent verifier status completed
+   bash ${CASE_REPO}/scripts/task-status.sh <task.json> agent verifier completed now
    ```
 
 ### 6. Output