release: v0.3.0 — IDEF0 composed-map program (render, drill-down, onboarding, 3D-iso)

.claude/rules/12-forgeplan-agent-dispatch.md

@@ -16,6 +16,11 @@ forgeplan_dispatch → forgeplan_claim → (sub-agent работает) → forg
 
 Перед запуском параллельных sub-агентов:
 
+0. **`forgeplan_claims`** — СНАЧАЛА посмотреть, что уже занято и кем.
+   Никогда не клеймить артефакт, на котором уже висит активный claim
+   другого агента; направь нового агента на свободную работу или дождись
+   release. Это и есть «следующий смотрит, что уже взято и кто над этим
+   работает» — без этой проверки два агента возьмут один артефакт.
 1. **`forgeplan_dispatch agents=N status=<status>`** — получить план
    (bucket'ы по агентам + serial queue для остатка). Read-only вызов;
    re-dispatch при изменении claim-set'а.
@@ -32,6 +37,28 @@ forgeplan_dispatch → forgeplan_claim → (sub-agent работает) → forg
 При crash sub-агента или зависании claim'а: `forgeplan_release <id>
 --force` — orchestrator escape hatch.
 
+## Claim hygiene — no висяки (orchestrator MUST)
+
+Висяк = claim, оставшийся после того как агент закончил/упал. Он вводит в
+заблуждение таб Agents / `forgeplan_health` и блокирует следующего агента до
+TTL-expiry. Чтобы их не было:
+
+1. **Sweep после каждого sprint'а / workflow'а.** Как только пачка
+   параллельных агентов отработала (или workflow завершился/упал):
+   `forgeplan_claims` → для каждого оставшегося claim этой пачки
+   `forgeplan_release <id> --force`. Терминальное состояние —
+   `active_claim_count == 0` (см. Verification).
+2. **Release on crash/timeout — сразу, не по TTL.** Если sub-агент упал,
+   завис, или workflow-агент не отработал (например, schema/StructuredOutput
+   retry-cap) — `forgeplan_release <id> --force` немедленно.
+3. **Read-only ревьюеры тоже подметай.** Им claim не нужен (см. ниже), но
+   если агент-фреймворк поставил claim от их имени — orchestrator снимает его
+   тем же sweep'ом. (Наблюдалось: конформанс-аудит оставил 3 висяка на
+   RFC-008/009/010 после падения architect-reviewer'ов на schema.)
+4. **/smith и /autorun** перед рекомендацией следующего шага сверяются с
+   `forgeplan_claims` — не предлагать работу, которая уже claimed другим
+   агентом, и сообщать пользователю кто над чем работает.
+
 ## Required (sub-agent-side)
 
 Если sub-агент получил инструкцию редактировать файлы в рамках

.claude/rules/22-readonly-proxy.md

@@ -44,7 +44,7 @@ Constraints (every one of these is enforceable from the diff):
 - Headers: `accept: application/json` and a static `user-agent`. No cookies,
   no credentials.
 - Response shape mirrors the standard envelope: `{ ok, data: { current,
-  latest, hasUpdate }, cmd, error? }` with `current = __FORGEPLAN_WEB_VERSION__`.
+latest, hasUpdate }, cmd, error? }` with `current = __FORGEPLAN_WEB_VERSION__`.
 - Network failures (timeout, non-2xx, JSON parse error) MUST fall back to
   `{ ok: false, error, data: { ..., hasUpdate: false } }` — never throw.
 
@@ -75,17 +75,142 @@ Constraints (every one of these is enforceable from the diff):
   inflight promise) inside
   `template/src/shared/server/registry.ts#readInstances`.
 - Response shape mirrors the standard envelope: `{ ok, data: { instances },
-  cmd: "registry:read", error? }`. `instances` MUST conform to the
+cmd: "registry:read", error? }`. `instances` MUST conform to the
   SPEC-003 v1 row shape (id / host / port / pid / scope / workspaceRoot /
   projectName / startedAt / heartbeatAt / webVersion / forgeplanCli);
   malformed rows are silently dropped from the live view.
 - Errors (file read, JSON parse) MUST fall back to `{ ok: false, error,
-  data: { instances: [] } }` — never throw.
+data: { instances: [] } }` — never throw.
 
 Any additional non-forgeplan endpoint (whether it hits npm, GitHub,
 crates.io, the local filesystem outside the registry, or anything else)
 requires a new Forgeplan artifact and a fresh amendment to this rule.
 
+## Allow-list extension: `/api/map` (non-forgeplan; PRD-036 / SPEC-006 / RFC-030)
+
+`/api/map` is a read-only mirror of the composed-map document at
+`<workspaceRoot>/.forgeplan/map/map.json` (SPEC-006 C5), backing the
+composed-map view (the 9th graph view, Phase-1 render-proof).
+
+Constraints (every one of these is enforceable from the diff):
+
+- Method: `GET` only.
+- File path: `path.join(workspaceRoot(), ".forgeplan", "map", "map.json")` —
+  **no interpolation, no env override beyond the standard `workspaceRoot()`
+  resolution, no user input** on the path.
+- **No spawn, no Forgeplan invocation, no network.** The endpoint reads via
+  `node:fs.readFileSync` only, inside
+  `template/src/shared/server/map.ts#readMapFile`. The file's content is
+  mirrored **verbatim** — the endpoint performs NO structural validation.
+  Validation (`validateMapDocument`) is the web client's job (SPEC-006 C4);
+  the server is the third of the three validation call sites (§20) and is
+  deliberately a "dumb honest mirror" — forking the rule list between
+  server and client would hide errors from the error-surface UX.
+- Response shape mirrors the standard envelope: `{ ok, data, cmd: "map:read",
+error? }`. HTTP 200 in every handled case.
+  - File present, parseable JSON → `{ ok: true, data: <file content
+verbatim> }`.
+  - File missing (ENOENT) → `{ ok: true, data: {} }` — a NORMAL state
+    ("no map yet"), never an error.
+  - Unreadable / unparseable → `{ ok: false, data: {}, error }` — never a
+    thrown exception.
+
+Any additional non-forgeplan endpoint requires a new Forgeplan artifact and
+a fresh amendment to this rule.
+
+## Allow-list extension: `/api/map/layers/<zone>` (non-forgeplan; PRD-038 FR-002)
+
+`/api/map/layers/<zone>` is a read-only mirror of a **map-pack-emitted
+per-zone layer** document at
+`<workspaceRoot>/.forgeplan/map/layers/<zone>.json` (PRD-038 FR-002), backing
+the composed-map's "prefer emitted layer, fall back to client-derived"
+descend seam (FD-6, RFC-031's `deriveSubDocument` seam). This is a distinct,
+**read-only** amendment — categorically separate from ADR-008's later,
+human-gated **write** amendment for the append/deeper-scan loop (PRD-038
+Non-Goals).
+
+Constraints (every one of these is enforceable from the diff):
+
+- Method: `GET` only.
+- Route param: `zone` (single dynamic segment, `routes/api/map/layers/[zone]/+server.ts`).
+  Validated against `^[a-zA-Z0-9._-]+$` **and** rejected if it contains `..`
+  — no interpolation of unvalidated input into the filesystem path. The
+  charset excludes `/` outright (no path-traversal via a raw slash); the
+  explicit `..` rejection closes the two-adjacent-dots gap the charset alone
+  would allow.
+- File path: `path.join(workspaceRoot(), ".forgeplan", "map", "layers",
+\`${zone}.json\`)`— the validated`zone` is the only interpolated segment.
+- **No spawn, no Forgeplan invocation, no network.** The endpoint reads via
+  `node:fs.readFileSync` only, inside
+  `template/src/shared/server/map.ts#readMapLayerFile`. The file's content
+  is mirrored **verbatim** — the endpoint performs NO structural validation
+  (validation is the web client's job, SPEC-006 C4, same division of labour
+  as `/api/map`).
+- Response shape mirrors the standard envelope: `{ ok, data, cmd:
+"map:layer:read", error? }`.
+  - File present, parseable JSON → `{ ok: true, data: <file content
+verbatim> }`.
+  - File missing (ENOENT) → `{ ok: true, data: {} }` — a NORMAL state ("no
+    emitted layer for this zone yet"), never an error.
+  - Unreadable / unparseable → `{ ok: false, data: {}, error }` — never a
+    thrown exception.
+  - Invalid `zone` param → HTTP 400 (`error(400, ...)`), the only non-GET-2xx
+    response this endpoint returns.
+- **MVP scope**: single-segment top-level zone ids only. A nested
+  `<ancestor>/<zone>` layer path is a follow-up — out of scope for this
+  amendment, rejected by the same `zone` validation (no `/` in the charset).
+
+Any additional non-forgeplan endpoint requires a new Forgeplan artifact and
+a fresh amendment to this rule.
+
+## Allow-list extension: git-reconstruction endpoints (`/api/snapshot`, `/api/timeline-events`)
+
+Time-travel (PRD-008 / RFC-007) and snapshot identity (PRD-016 / RFC-015) need
+the workspace's _history_, which the `forgeplan` CLI does not expose read-only.
+Two endpoints therefore spawn **`git`** (not `forgeplan`) in read-only mode:
+
+- `/api/timeline-events` — `git log` over `.forgeplan/` to list create / activate
+  / supersede / score events for the scrubber.
+- `/api/snapshot` — reconstructs a past workspace state: `git rev-list` (resolve
+  the commit at/before an ISO timestamp), `git cat-file -e` (reachability),
+  `git worktree add --detach <tmp> <sha>` into an OS tmpdir, then runs
+  `forgeplan reindex` **inside that ephemeral throwaway worktree** plus
+  `forgeplan list/graph --json` against it, then `git worktree remove --force`.
+
+Constraints (every one enforceable from the diff):
+
+- Method: `GET` only.
+- Every `git` / `forgeplan` invocation goes through `child_process.spawn` with an
+  **argv array** — never a shell-string. The only interpolated values are the
+  SHA (validated `^[0-9a-f]{40}$`) and the `at` timestamp (validated against an
+  ISO-8601 regex); no raw user input reaches argv.
+- `git` runs are scoped to the repo root (`git rev-parse --show-toplevel`) with
+  the pathspec restricted to `.forgeplan/`; every spawn carries a timeout.
+- **The `forgeplan reindex` here is the documented exception to the "forbidden
+  reindex" rule below.** It writes the Lance index of a _disposable_ git worktree
+  under `tmpdir`, never the host `.forgeplan/lance/`; the host workspace is never
+  mutated, and the worktree is always removed in a `finally`.
+- No network; no host filesystem write outside the OS-tmpdir worktree.
+
+These are the only places `git` is spawned from `/api/*`, and the only place
+`reindex` runs (ephemeral-worktree-scoped). Any new git-spawning or
+history-reconstruction endpoint requires an updating Forgeplan artifact and a
+revision of this rule. See PRD-008 / RFC-007 and PRD-016 / RFC-015.
+
+## OPTIONS preflight + CORS carve-out (`/api/instance-status`)
+
+`/api/instance-status` (issue #134) reports a single instance's live status using
+only the allow-listed `health` + `claims` subcommands — fully compliant with the
+forgeplan allow-list above. Because the instance switcher fetches _other_
+forgeplan-web instances **cross-origin** (different port = different origin), this
+endpoint is the one permitted exception to the strict "GET only" shape: it also
+exports an `OPTIONS` handler returning `204` with `Access-Control-Allow-Origin: *`
+
+- `Access-Control-Allow-Methods: GET` for the browser preflight. The `OPTIONS`
+  handler is side-effect-free (no spawn, no body); `GET` stays the only data path.
+  No other `/api/*` route may export a non-GET handler or set CORS headers without
+  an updating artifact.
+
 ## Forbidden `forgeplan` subcommands from any `/api/*` endpoint
 
 Any subcommand that mutates the workspace:
@@ -122,8 +247,13 @@ browser invalidates that.
 
 - `grep -RIn "forgeplan" template/src/routes/api/` must show only commands
   from the allow-list above.
+- `grep -RIn "spawn\|execFile" template/src/routes/api/ template/src/shared/server/`
+  may show `git` spawns ONLY in the snapshot / timeline-events reconstruction
+  path (see git-reconstruction extension above); every such spawn is argv-based
+  with validated SHA / ISO inputs.
 - Every route file is `+server.ts` exporting `GET` only (no `POST`, `PUT`,
-  `PATCH`, `DELETE`).
+  `PATCH`, `DELETE`) — the sole exception is the side-effect-free `OPTIONS`
+  preflight on `/api/instance-status` (CORS carve-out above).
 - `runForgeplan` in `template/src/shared/server/forgeplan.ts` MUST check
   `args[0] ∈ READ_ONLY_SUBCOMMANDS` before spawning, and the constant MUST
   match this allow-list (see rule above). The check is the runtime backstop
@@ -136,3 +266,18 @@ browser invalidates that.
   call (read-only constraint above). The reader
   `template/src/shared/server/registry.ts` MAY only call
   `existsSync` + `readFileSync` against `~/.forgeplan-web/instances.json`.
+- `template/src/routes/api/map/+server.ts` MUST NOT contain any `spawn`,
+  `execFile`, `writeFileSync`, `renameSync`, or `mkdirSync` call, and MUST
+  NOT call `validateMapDocument` (validation stays client-side per SPEC-006
+  C4/C5). The reader `template/src/shared/server/map.ts#readMapFile` MAY
+  only call `existsSync` + `readFileSync` against
+  `<workspaceRoot>/.forgeplan/map/map.json`.
+- `template/src/routes/api/map/layers/[zone]/+server.ts` MUST NOT contain
+  any `spawn`, `execFile`, `writeFileSync`, `renameSync`, or `mkdirSync`
+  call, and MUST NOT call `validateMapDocument` (validation stays
+  client-side, same as `/api/map`). It MUST validate `params.zone` via
+  `isValidZoneId` and respond `400` before calling `readMapLayerFile` on an
+  invalid id. The reader
+  `template/src/shared/server/map.ts#readMapLayerFile` MAY only call
+  `existsSync` + `readFileSync` against
+  `<workspaceRoot>/.forgeplan/map/layers/<zone>.json`.

.forgeplan/adrs/ADR-002-sub-agent-dispatch-must-go-through-forgeplan-dispatch-forgeplan-claim.md

@@ -4,7 +4,7 @@ id: ADR-002
 kind: adr
 last_modified_at: 2026-05-04T13:50:41.701061+00:00
 last_modified_by: claude-code/2.1.126
-status: draft
+status: active
 title: Sub-agent dispatch must go through forgeplan_dispatch + forgeplan_claim
 ---
 
@@ -198,3 +198,5 @@ markdown-правки + status-flip.
 | RFC-003 | RFC | informs (наблюдение симптомов на нём триггернуло этот ADR) |
 | ADR-001 | ADR | based_on (host isolation contract — близкий по духу) |
 
+
+

.forgeplan/adrs/ADR-003-permit-citty-zero-dep-esm-cli-library-in-bin-amend-rule-23.md

@@ -414,3 +414,4 @@ windows CI), брать MAX как worst-case; если worst-case <100ms — CL
 
 
 
+