宜博 / lemonboss

Before P0 coding begins, the doc set was missing three things that would
have stalled implementation on day 3:

1. Day-1 Quick-Start (plan-migration top section)
   - 8-step "what command do I type first" walkthrough
   - pnpm install → cp .env.example → extract-manifest verification → P0.0
     services → MOCK_CLAUDE=1 phase0-verify → real phase0-verify → P1
   - Anyone cloning can reach step 4 (doc verification) immediately

2. P0.0 服务层 7 件套 (plan-migration P0 子任务表)
   - Previously P0.A "工具实现" depended on docStore/unitRegistry/sseBroker/
     bugTracker/timelineLogger/pathResolver/GitVault but none were listed
     as a task — engineer would hit "docStore.writePRD doesn't exist"
   - Now P0.0 lists them as a sequenced 4.5-day task: pathResolver first
     (everyone depends on it), then 5 other services, finally GitVault
   - GitVault tasks consolidated into P0.0 (removed duplicate P0.I)
   - Total P0: 13.5 → 17 days (3 → 3.5 weeks)

3. Mock Claude CLI Mode (arch-acp-bridge §⑦, NEW)
   - MOCK_CLAUDE=1 env toggles ClaudeCliProtocol to read stubs from
     system/mock-responses/{agent}/{mode}.json instead of real Claude
   - Mock JSON: array of steps (text emit / tool_use), $pid placeholder
   - When mock vs real: mock for dev + CI, real for prompt quality + P1+
   - Enables zero-token tool dev + phase0-verify
   - Sections renumbered (⑧ → ⑨ etc) to accommodate insertion

Total project: 10 → 10.5 weeks (still honest, still includes everything).
No new MVCP defs (54). Search index 195.7KB. _spec/ regenerated by hook.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

The 50-page PRD HTML totals ~520KB; loading it all costs Claude ~222K
tokens just for context. This adds a token-efficient sibling layer:

- scripts/extract-spec.js → npm run spec:extract / spec:check
  Walks docs/prd/newfunction/*.html and produces stripped MD into _spec/.
  Strategy varies per page (full-extract for SDD/process/data,
  shell-strip for agents to keep long system prompts intact).
  Result: 327.9KB MD (~84K tokens) — 38% of full load, saves ~138K tokens
  for every Agent invocation that reads the spec.

- scripts/git-hooks/pre-commit + scripts/install-hooks.sh
  Pre-commit guard: when any docs/prd/newfunction/*.html changes, the
  hook checks the corresponding _spec/*.md is up to date; fails commit
  if stale, telling user to `npm run spec:extract`. Auto-installed via
  package.json `prepare` script on `npm install`.

- docs/prd/newfunction/_spec/ (51 .md files + CONVENTIONS.md)
  Machine-readable mirror of HTML. Used by:
  - Coder/Architect/Tester agents when reading spec at runtime
  - External Claude Code sessions doing reproducibility
  - CI checks (npm run spec:check)
  NOT hand-edited; regenerated from HTML by extract-spec.js.

- CLAUDE.md: 1-line note directing future agents to read _spec/*.md
  preferentially, fall back to *.html only for wireframes/SVG/full
  human-readable context.

This is the user's pre-existing scaffolding that the previous commits
hadn't pulled in yet. Now tracked + enforced by hook.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Fills the gap: where does a DevLoop project actually live, and how does a user
create one? Previous docs assumed everything goes under
data/companies/{cid}/projects/{pid}/ with no user control.

Design:
- A DevLoop "project" = one directory + project.json + git history;
  the directory is the project root, the anchor for everything
- 3 modes:
  - sandbox (default, v1): root auto-generated under data/.../projects/{pid}/
  - linked-new (v1): user picks any empty path, e.g. ~/code/auto-todo
  - linked-existing (v2): bind to existing git repo subdirectory
- 3 creation entry points:
  - REST: POST /api/devloop/projects with optional {mode, target_path}
  - CLI: scripts/devloop-new.js with --path / --name / --requirement / --list
  - UI: Dashboard "+ NEW PROJECT" modal with mode radio + path picker
- New pathResolver service (path-resolver.js): single source of truth for
  resolveProjectRoot(pid). All paths derive from it; nothing hardcodes
  data/companies/... anymore
- linked projects registered in ~/.devloop/linked-projects.json
- memory stays at company level (~/data/companies/{cid}/memory/) even for
  linked projects — privacy + cross-project knowledge isolation
- Strict sandbox: blacklist /, /etc, /System, ~/.ssh, ~/.aws etc. for
  target_path; writeAllowList relative to root_path

Pages changed:
- arch-project-root.html (NEW, 15-section comprehensive design)
- sdd-model.html       (M-1 ProjectMeta + mode + root_path fields)
- sdd-control.html     (C-1 POST /projects accepts mode + target_path)
- assets/shell.js      (sidebar adds arch-project-root)
- assets/search-index.json + build-manifest.json (rebuilt)

Adds ~2 days to P0 (pathResolver + schema migration), ~1.5 days to P1
(CLI + mode params), ~1 day to P4 (UI modal). Total 10 → 10.5 weeks.

Key insight: linked-new mode means a user can DevLoop code straight into
~/code/auto-todo, then `git push origin main` to ship — without manually
exporting from the sandbox. The sandbox-vs-linked choice is path-transparent
to LoopController and all Agents.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Fills a gap pointed out post-v0.3: docs had file-mtime + history/ archival
only, no real version control. Now every Agent that completes work triggers
LoopController to git commit; project ship/sign-off/abandon tag the repo.

Design:
- One git repo per project at data/companies/{cid}/projects/{pid}/.git
- LoopController-centralized commits (Agents stay sandboxed, no git access)
- Commit cadence: each Agent success → commit; Tester red → no commit;
  shipped/sign-off/abandon → tag
- New GitVault service (C-18): spawn-git wrapper, ~150 lines,
  init/commit/tag/log/diff/status/archive/revert/resetWorkingTree
- New process P-10 (Process.GitCommit): commitAfterAgent hook in
  callAgentWithPersistence; recoverOnBoot extended to detect dirty trees
- .gitignore excludes agent-state/ (high-write) + history/ (git is history)
  + stream.log + runs stdout (too large)
- New SSE events: git.committed · git.tagged · recovery_dirty_tree
- Defer git push-to-remote to v2 (no network deps in v1)

Pages changed:
- arch-git-versioning.html (NEW, comprehensive design, 16 sections)
- sdd-control.html       (+C-18 GitVault spec)
- sdd-process.html       (+P-10 commitAfterAgent + recoverOnBoot dirty-check)
- data-layout.html       (.git/ + .gitignore in project tree)
- plan-migration.html    (P0 +3 days for GitVault, total 10 weeks)
- assets/shell.js        (sidebar adds arch-git-versioning)
- assets/search-index.json (rebuilt, 189.5KB, 50 pages)
- build-manifest.json    (52 → 54 defs, 100% extraction)

Key benefit: Coder 3-retry chain can be `git diff`-ed; L2 fail allows clean
revert; project export becomes `git archive HEAD` (tracked files only,
not the ~30MB project dir).

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Earlier PRD attempt scoped to LemonBoss-only (excludes ArenaSK Skill
marketplace / Arena / Master / Innovator / Open API / Evolution).
Generated 2026-05-12, exists side-by-side with the later 50-page
DevLoop PRD under docs/prd/newfunction/.

Structure:
- index.html (single-page shell with collapsible sidebar + lunr search)
- assets/ (app.css/js, chapter.css, menu.js, search-index.json)
- chapters/01-overview ~ 10-reproducibility (10 chapters)
- _scan-manifest.json (scope manifest pinning what's in/out)
- scripts/build-search-index.js (chapter HTML → lunr index)

This commit just brings the existing files under version control;
no edits to content.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

DevLoop: a 3-layer Loop (L1 Unit / L2 Integration / L3 Human) auto-development
system that takes a one-line human requirement and produces multi-page HTML
PRD + SDD + units.json + full backend/frontend code via 6 specialized agents.

This commit adds the complete documentation set:

50 HTML pages organized in 8 sections (3-level menu + global search):
- 01 Overview · 02 PRD · 03 Design (loops + 6 agents)
- 04 SDD (MVCP × 4) · 05 Prototype · 06 Architecture
- 07 API · 08 Ops · 09 Plan

Key specs:
- 6 agent skills (PM/Architect/Coder/Tester/Integrator/BugTriager), each with
  full system prompt, 13-17 tool signatures, 3 E2E samples, helper source code
- 52 MVCP definitions, 100% machine-extractable via data-* anchors
- 79 tool signatures with implementation guidance (arch-tool-registry)
- ACP bridge spec (arch-acp-bridge): how LoopController calls into LemonBoss
  agent-manager without breaking existing Master/Innovator flows
- 5-phase plan P0→P4 (~9.5 weeks): P0 bootstrap (tool impl + ACP bridge),
  P1 docs MVP, P2 single unit L1, P3 L1+L2 loop, P4 L3 feedback + UI
- Persistence layer: AgentState (M-10), Memory (M-11), Todolist (M-12),
  Timeline (M-13), Bugs (M-14), Changelog (M-15) + crash recovery (P-8)
- Cost & concurrency budgets (plan-cost-concurrency)
- Code lifecycle: stay-in-sandbox v1 + export API + future GitHub PR (v2)

Plus supporting scripts (zero deps, regex-based):
- scripts/extract-manifest.js: extracts MVCP defs to build-manifest.json,
  used to verify all definitions have path + shape (currently 100%)
- scripts/build-search-index.js: builds assets/search-index.json (183KB),
  enables Ctrl+K global search across all 50 pages

The PRD itself is meta-executable: a future Claude Code session reading
plan-reproducibility.html can rebuild the entire DevLoop runtime from the
docs alone.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>