Document and harden project handoff

2026-07-12 14:54:03 +08:00
parent ab758e774e
commit 8e4ff3779b
17 changed files with 1030 additions and 32 deletions
@@ -0,0 +1,62 @@
+# Project Handoff Audit
+
+status: completed
+date: 2026-07-12
+baseline_commit: `ab758e7`
+
+## Objective
+
+Make the repository sufficient for another AI to clone, validate, understand prior decisions, run the service, and continue the actual product goal without access to the original conversation.
+
+## Initial Findings
+
+- Git was clean and synchronized with `origin/main` at `ab758e7`.
+- Content and research artifacts were committed, but there was no single AI continuation entrypoint.
+- The root README described repository sections but not current completion, failed routes, runtime state, or next priorities.
+- The 12-paper learning pilot was marked failed in its experiment file, while `experiments/README.md`, `learning/README.md`, and `module.json` still described it as an active pilot.
+- The web process was stopped; `lab.k1412.top` returned 502.
+- The web app requested stale `light/fast/large` model tags. Live Ollama exposed Luna/Terra/Sol instead.
+- Ordinary `nohup` passed one health check but was reaped with the Codex command session, so it was not a reliable service manager.
+
+## Changes
+
+- Added `AGENTS.md` with read order, truth hierarchy, commands, and repository contracts.
+- Added project status, exploration history, and continuation plan under `docs/06-08`.
+- Added `tools/check_project.py` for deterministic item/index/research/syntax/contract checks.
+- Reconciled failed-pilot status across learning and experiment indexes.
+- Made Ollama model tiers configurable and aligned defaults with live Luna/Terra/Sol tags.
+- Added model readiness and missing-default reporting to `/api/health`.
+- Added an enabled user-level systemd service and `web/manage.sh` lifecycle commands.
+- Updated web and root documentation with product boundaries and operations.
+
+## Validation Performed
+
+Offline:
+
+- parsed every committed JSON research/learning file used by the checker;
+- verified 989 indexed items match 6 job, 974 paper, and 9 industry files;
+- verified the memory snapshots remain 516 candidates, 379 title-central, and 293 local paper records;
+- parsed all Python files under `tools/` and `web/app.py` with `ast`;
+- asserted the web client does not send `num_ctx` or `keep_alive`;
+- ran `git diff --check`.
+
+Live:
+
+- verified Tailscale address `100.114.68.27` exists;
+- verified Ollama inventory and all default model tags;
+- started the Atlas as `agent-knowledge-atlas.service`;
+- verified `/api/health`, `/api/models`, `/api/atlas`, `/`, and the public mapped domain;
+- verified the Atlas reports 974 papers, 15 topics, 5 routes, and 13 timeline buckets;
+- completed one real paper-summary request through the web API with Luna in 5.32 seconds.
+
+## External State Boundary
+
+Git contains the application, unit file, management script, and documentation. The following remain external:
+
+- Gitea credentials and credential helper;
+- Cloudflare/reverse-proxy/TLS mapping for `lab.k1412.top`;
+- Ollama model manifests and server residency/context configuration;
+- the company GPT-5.5 data-agent endpoint and credentials.
+- temporary full-paper PDFs/text and regenerable web caches.
+
+Future handoffs must verify those live rather than treating this record as permanent state.