feat: Sign glyph images, anchor review flow, loop UX, and experiment ID consolidation

.agents/skills/specsmith-audit/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: specsmith-audit
+description: Run specsmith audit to check for governance drift between requirements, tests, and architecture. Required before advancing an AEE phase.
+---
+
+# Specsmith Audit
+
+Checks the project for drift between requirements (ARCHITECTURE.md), test cases, and the codebase. Must pass before advancing an AEE phase.
+
+## How to run
+
+```bash
+specsmith audit
+```
+
+## Interpreting results
+
+```
+29 PASS   ← all requirements have matching tests and implementation
+ 2 WARN   ← drift detected — investigate these
+ 0 FAIL
+```
+
+**All items must be PASS or suppressed before `specsmith phase advance`.**
+
+## When a WARN appears
+
+1. Read the warning — it will reference a requirement ID (e.g. `R20`) and describe what's missing
+2. Fix it: add the missing test, update ARCHITECTURE.md, or implement the requirement
+3. Re-run `specsmith audit` to confirm it passes
+4. If it's a confirmed false positive: `specsmith audit --suppress <CODE>`
+
+## Suppressing a false positive
+
+Only suppress if you've verified the requirement IS met but the audit can't detect it automatically:
+
+```bash
+specsmith audit --suppress SEAL-XXXX-001
+```
+
+Suppressions are permanent and stored in governance state — use them sparingly.
+
+## Common causes of WARN
+
+- Requirement in ARCHITECTURE.md has no corresponding test case
+- Test exists but requirement ID reference is missing from the test
+- Implementation exists but the architecture doc wasn't updated to match
+
+## After fixing all warnings
+
+```bash
+specsmith audit        # confirm all pass
+specsmith phase advance  # advance the phase
+specsmith save         # commit the phase bump
+```
+
+## Quick audit before a session
+
+Run `specsmith audit` at the start of a session to catch any drift from the previous session before making new changes.

.agents/skills/specsmith-save/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: specsmith-save
+description: Run specsmith save to commit and push all current changes with governance state backup. Use at the end of any work session or after completing a feature/fix.
+---
+
+# Specsmith Save
+
+Saves governance state: backs up the ESDB, commits any staged/unstaged changes, and pushes to the remote.
+
+## When to use
+
+- At the end of any work session
+- After implementing a feature, fix, or refactor
+- After advancing a phase
+- Whenever the user says "save", "commit and push", or "specsmith save"
+
+## How to run
+
+```bash
+specsmith save
+```
+
+## What it does (in order)
+
+1. **ESDB backup** — snapshots the epistemic state database
+2. **Commit** — stages all changes and commits with a governance-aware message (or reports "Nothing to commit")
+3. **Push** — pushes the branch to origin (or reports "Everything up-to-date")
+
+## Expected successful output
+
+```
+  ✓ esdb_backup: JSON fallback (no WAL to backup)
+  ✓ commit: Nothing to commit          ← or a commit hash
+  ✓ push: Everything up-to-date        ← or "pushed to origin/phase-next"
+```
+
+## If there are changes to commit
+
+Specsmith will auto-stage and commit. It generates a governance-aware commit message from the diff. You can also pre-stage and commit manually first:
+
+```bash
+git add -A
+git commit -m "feat: description
+
+Co-Authored-By: Oz <oz-agent@warp.dev>"
+specsmith save   # will see nothing to commit, just pushes
+```
+
+## Do NOT use `git push` directly
+
+Always use `specsmith save` — it ensures the ESDB backup runs before the push, keeping governance state consistent with the remote.

.agents/skills/specsmith/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: specsmith
+description: Reference for the specsmith AEE governance tool used in this project. Use this to understand specsmith commands, the session workflow, and how to interact with the governance layer correctly.
+---
+
+# Specsmith — Project Governance Tool
+
+Specsmith is the AEE (Agile Epistemic Engineering) governance CLI used in this project. It manages requirements, phases, audit trails, and session state. It wraps git with governance-aware commits and backs up the epistemic state DB (ESDB).
+
+## Key concepts
+
+- **ESDB** — Epistemic State Database. Tracks certainty, audit state, session memory. Backed up on `specsmith save`.
+- **Phases** — AEE lifecycle: Inception → Elaboration → Construction → Transition → Validation → Hardening → Release. Advance with `specsmith phase advance`.
+- **Ledger** — Running log of changes in `LEDGER.md`. Auto-updated by commits.
+- **Audit** — Checks requirements vs tests vs architecture for drift. Run before advancing a phase.
+- **Save** — ESDB backup + governance-aware git commit + push.
+
+## Session workflow
+
+```
+1. specsmith audit          # check for drift before working
+2. <make code changes>
+3. specsmith save           # commit + push + ESDB backup
+```
+
+## Common commands
+
+| Command | What it does |
+|---------|-------------|
+| `specsmith save` | ESDB backup → commit (if needed) → push |
+| `specsmith audit` | Drift/health check — requirements vs tests vs arch |
+| `specsmith audit --suppress <CODE>` | Accept a known false positive |
+| `specsmith phase` | Show current AEE phase |
+| `specsmith phase advance` | Advance to the next phase (requires clean audit) |
+| `specsmith commit` | Governance-aware commit (wraps git commit) |
+| `specsmith ledger` | Show/manage the change ledger |
+| `specsmith compress` | Compress old ledger entries |
+| `specsmith req` | Manage requirements |
+| `specsmith test` | Manage test cases |
+| `specsmith status` | VCS/CI/PR status |
+
+## Commit conventions
+
+Specsmith commits follow: `type: message` where type is one of:
+`feat`, `fix`, `refactor`, `test`, `docs`, `chore`, `perf`
+
+Always append `Co-Authored-By: Oz <oz-agent@warp.dev>` when committing as an AI agent.
+
+## Important rules
+
+- **Never use `git commit` directly** — use `specsmith save` or `specsmith commit` so governance state stays consistent.
+- **Run `specsmith audit` before advancing a phase** — a phase advance with drift will fail.
+- **Suppressed audit findings** are stored permanently; only suppress genuine false positives.
+- After `specsmith save` outputs `✓ push: Everything up-to-date` with nothing to commit, the repo is fully clean.
+
+## Audit result codes
+
+- `PASS` — requirement/test/arch is consistent
+- `WARN` — drift detected, investigate
+- `SKIP` / suppressed — accepted false positive
+- Numbers like `R20`, `R21` — requirement IDs in ARCHITECTURE.md
+
+## Phase advancement
+
+```bash
+specsmith audit          # must be all-pass (or suppressed)
+specsmith phase advance  # bumps phase, writes ledger entry
+specsmith save           # commit the phase bump
+```

.github/workflows/ci.yml

@@ -68,7 +68,7 @@ jobs:
   frontend-tests:
     name: Frontend tests (Playwright)
     runs-on: ubuntu-latest
-    timeout-minutes: 25
+    timeout-minutes: 35  # includes 2-min research-loop SSE test
     needs: []  # run in parallel with backend-tests
 
     steps:
@@ -87,6 +87,24 @@ jobs:
           python -m pip install --upgrade pip
           pip install -e ".[dev]" || pip install -e "." || true
 
+      # Build the frontend FIRST so the backend can mount dist/ via StaticFiles
+      # when it starts.  If the frontend is built after the backend starts, the
+      # StaticFiles mount is never registered and Playwright gets 404s.
+      - name: Set up Node.js 20
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: npm
+          cache-dependency-path: frontend/package-lock.json
+
+      - name: Install frontend dependencies
+        working-directory: frontend
+        run: npm ci
+
+      - name: Build frontend
+        working-directory: frontend
+        run: npm run build
+
       - name: Start backend in background
         working-directory: backend
         env:
@@ -98,7 +116,7 @@ jobs:
             --host 127.0.0.1 --port 8001 \
             --log-level warning &
           echo $! > /tmp/backend.pid
-          # Wait for backend to be healthy (up to 30s)
+          # Wait for backend to be healthy (up to 30s) AND frontend to be served
           for i in $(seq 1 30); do
             if curl -sf http://127.0.0.1:8001/api/v1/health > /dev/null 2>&1; then
               echo "Backend healthy after ${i}s"
@@ -107,21 +125,8 @@ jobs:
             sleep 1
           done
           curl -sf http://127.0.0.1:8001/api/v1/health || echo "Backend may not be running"
-
-      - name: Set up Node.js 20
-        uses: actions/setup-node@v4
-        with:
-          node-version: "20"
-          cache: npm
-          cache-dependency-path: frontend/package-lock.json
-
-      - name: Install frontend dependencies
-        working-directory: frontend
-        run: npm ci
-
-      - name: Build frontend
-        working-directory: frontend
-        run: npm run build
+          # Verify frontend is served
+          curl -sf http://127.0.0.1:8001/ > /dev/null && echo "Frontend OK" || echo "Frontend not served"
 
       - name: Install Playwright browsers (Chromium only)
         working-directory: frontend
@@ -132,6 +137,10 @@ jobs:
         env:
           CI: "true"
           BACKEND_RUNNING: "true"
+          # Backend at port 8001 serves both the built frontend (StaticFiles) and
+          # the API on the same origin.  No separate Vite preview server needed.
+          PLAYWRIGHT_USE_BACKEND: "1"
+          PLAYWRIGHT_BACKEND_URL: "http://127.0.0.1:8001"
         run: |
           npx playwright test \
             --reporter=github \

.gitignore

@@ -100,6 +100,7 @@ temp/
 *.db-wal
 
 # ---- Local config / secrets ----
+project.yml
 .env
 .env.*
 *.pem
@@ -147,6 +148,7 @@ data/.keys.json
 
 # ---- Database files ----
 data/glossa.db
+frontend/data/glossa.db
 
 # ---- Backend runtime logs at root ----
 backend/uvicorn_stdout.log
@@ -187,6 +189,13 @@ backend/glossa_lab/data/phase16_corpora/kalyanaraman_devanagari_corpus.txt
 # Phase-18 derived: large stream txt regenerable from CSV
 backend/glossa_lab/data/phase18_corpora/rv_padapatha_stream.txt
 
+# ---- Sign image raw download cache (reconstructable via harvest_ivc2tyc_signs.py) ----
+backend/static/signs/originals/ivc2tyc_cache/
+# The manifest.json and processed M*.png files ARE committed (authoritative).
+# The originals/ folder itself is also gitignored to keep the repo lean.
+backend/static/signs/originals/
+!backend/static/signs/originals/.gitkeep
+
 # ---- ML model weights (large binaries, not for version control) ----
 *.pt
 *.pth
@@ -216,5 +225,8 @@ docs/*.bak
 *.fdb_latexmk
 *.synctex.gz
 
+# Bulk mine outputs — large JSON files (regenerable from scripts)
+outputs/phase*_bulk_mine_*.json
+
 # Private correspondence — local context only, never pushed
 .correspondence/

AGENTS.md

@@ -40,3 +40,26 @@ The following project-specific rule files apply to all sessions:
 
 - `docs/research/NORMALIZATION_RULES.md` — Indus sign normalization rules for
   corpus processing and sign-ID canonicalization.
+
+---
+
+## MCP server
+
+A FastMCP server lives at `backend/glossa_mcp/server.py` and exposes 27 tools
+for querying and controlling the backend without manual API calls:
+
+- **Status/metrics** — `get_status`, `get_system_metrics`
+- **Jobs** — `list_jobs`, `get_job`, `create_job`, `cancel_job`, `get_job_results`
+- **Experiments** — `list_experiments`, `get_experiment`, `run_experiment`
+- **Research loop** — `start_research_loop`, `get_research_loop_status`,
+  `stop_research_loop`, `get_research_loop_results`, `get_anchor_staging`
+- **Foundation check** — `run_foundation_check`
+- **Discovery** — `list_discovery_items`, `get_discovery_stats`,
+  `trigger_discovery_fetch`, `update_discovery_item_status`
+- **Dashboard** — `get_latest_insight`, `get_dashboard_highlights`
+- **Anchor sets** — `list_anchor_sets`, `get_anchor_set`, `create_anchor_set`
+- **Reports** — `list_reports`, `get_report`
+
+The server connects to the running backend at `GLOSSA_BASE_URL`
+(default: `http://127.0.0.1:8001`). Tools return clean JSON error objects when
+the backend is unreachable — they never crash the MCP process.