agents-tdd

v0.19.0: forgeplan-web dogfood re-run follow-ups (findings A/B/C, after v0.18.0 proved the pipeline completes end-to-end on a real repo -- top map confirmed + 4/4 layers confirmed, GC-9 + parent_zone live-PASS). (A) map-emit.mjs input PRE-FLIGHT: refuse a wrong-shape (pre-v0.18) scratch instead of silently degrading. Resuming an old scratch under the new script had nested repo_head/project under meta. + a flat {edges:[]} shape, so the emit silently produced a 'nogit:' fingerprint, dropped title/description_ru, and would have shipped 0 edges -- against the pack's honest-failure discipline. The script now names the mismatch (repo_head/project must be top-level; edges must be {typedLink,codeDep} with id+namespace) and writes NOTHING; +2 test/emit-script.mjs scenarios. (B+C) scoped-layer ROLE DECOMPOSITION now mandatory in the orchestrator Scoped-pass rules + /map-build-layer + a map-emitter HARD RULE: a layer build routes input-prep through zone-extractor (scoped .extract.json + persisted .composition.json) + edge-verifier (scoped .edges.json), and map-emitter does ONLY flows + the script -- it never self-authors scoped inputs (the dogfood saw 3/5 emitters overstep, and one self-authored layer forgot repo_head -> a nogit: fingerprint on that one layer). 81 assertions green across 4 suites. Plugin v0.18.0 -> v0.19.0, catalog 1.117.0 -> 1.118.0. v0.18.0: DETERMINISTIC EMIT -- the headline fix from the 2026-07-15 forgeplan-web dogfood, which proved the LLM-typed emitter cannot scale to a real repo. On 274 nodes / 316 edges (~4,000 lines) map-emitter blew the 64,000-token output cap 3 runs out of 3; round 3 suppressed prose to five lines and STILL died, proving THE DOCUMENT is the cap-breaker, not agent chattiness (round 1 only 'barely fit': 553k tokens, 56 min -- so even the first write was at the edge, and anything larger fails outright). Neither proposed workaround was enough: granting Edit only fixes CORRECTION loops (the initial write stays at the cap), and chunked writes need Edit/Bash anyway while still having an LLM re-type 4,000 lines. Root cause is architectural -- an LLM re-typing a mechanical document whose every content DECISION was already made upstream (.extract.json=zones/nodes, .edges.json=edges, composed composition=layout). NEW scripts/map-emit.mjs (deterministic, dependency-free Node, mirroring map-guardian.mjs) now owns everything clerical: meta + 'git:<sha>' build anchor, tier-row layout + CM-22 accent de-collision, CM-07 canonical layer meta + B5 CONTENT seed_fingerprint, CM-01 visible() collapsed-child rewrite + CM-05 edge_ids resolution, CM-23 _content_sig drop + found_at hoist, the assembly-guard trio with reject-before-write, atomic tmp-rename, status:'proposed', and the NEEDS_CONFIRM sentinel. The map-emitter AGENT now decides ONLY the flows (the sole judgment call) into a tiny .work/.emit-plan.json and invokes the script (Bash granted for that one purpose; Edit + every forgeplan_* mutator still denied; it no longer writes map.json at all). The script's plain fs write is invisible to the write-hook BY CONSTRUCTION -- the same sanctioned shape ADR-017 blesses for the guardian -- and GC-5's git audit remains the single-writer backstop. Orchestrator SELECT now persists the composed base+overlays as .work/.composition.json (the script parses no YAML). NEW test/emit-script.mjs (35 assertions) including the end-to-end one that matters: emit a document, then run the REAL guardian over it and require exit 0 (GC-2/GC-7/GC-10/GC-11 PASS, GC-9 PASS on a layer) -- proving emitter and gates agree. No token cap, deterministic, instant, scales to any repo. Plugin v0.17.0 -> v0.18.0, catalog 1.116.0 -> 1.117.0. v0.17.0: first-live-dogfood fix -- /map-doctor now handles a LEGACY (pre-v0.16) map gracefully. Running the v0.16.0 /map-doctor on a REAL forgeplan-web map (generated by the OLD v0.7.1 map-pack; source_fingerprint 'fpw-map-...' is not a git anchor) surfaced 2 real command-prose defects the deterministic gates + the self-audit could NOT catch -- they test v0.16-generated maps, not legacy ones. (A) A legacy map produced a wall of GC-7/GC-9/GC-10 BLOCKERs that READ as corruption but are just schema drift (the old generator never emitted found_at / canonical layer-meta / grouped-mega-kind); /map-doctor now DETECTS a legacy map (non-git source_fingerprint, or layers lacking scope:'layer'/parent_map_id) and LEADS with a 'LEGACY MAP -> rebuild once with /map-build' banner, tagging those BLOCKERs legacy-schema-gap instead of a dozen alarming per-layer failures. (B) A layer with a MISSING meta.parent_zone was wrongly flagged an ORPHAN; orphan now means ONLY a present-but-dangling parent_zone (a zone deleted from the top map), while a missing parent_zone is non-canonical meta (GC-9's job), not orphan. The doctor itself verified WORKING on the live run (fast, read-only, accurate 11+2 checks, readable digest, correct fix commands) -- the real-run gap is now closed for /map-doctor. Plugin v0.16.0 -> v0.17.0, catalog 1.115.0 -> 1.116.0. v0.16.0: dogfood-brief batch 5 (CM-25) -- two new commands + content-aware staleness, closing the 25-finding v0.7.1 dogfood brief. Folds in an 18-finding adversarial self-audit remediation (a generator!=verifier workflow over the 5 batches of agent-prose): reconciled the E5 auto-cascade seed_fingerprint to the content-aware B5 form (it still read as membership-only, re-introducing the exact staleness-blindness B5 fixed on the default --layers path), gave the guardian a `--check-only` read-only deep flag so /map-doctor --deep exercises Layer B WITHOUT the proposed->confirmed write it previously performed (+ guardian-layer-b.mjs Scenario 7), realigned the zone-extractor AGENT body to the grouped-collapse contract its own SKILL uses (the body still taught the 170->1 single-blob dump), dropped the unfulfillable 'fold the narrating doc blob SHA' staleness claim (docs-scanner has no Bash to compute one), threaded manifests[] to edge-verifier, fixed the _content_sig/contentSig producer/consumer key drift, and corrected ~9 cross-file prose drifts (smoke-coverage GC-7..GC-11, stale GC enumerations, mtimes vs git-anchor, mega ref prefix, project shape). NEW /map-refresh: rebuild ONLY the layers whose content changed since the map was built, not the whole cascade. It rests on a real upgrade -- meta.seed_fingerprint is now a CONTENT fingerprint (sha1 over each member's id + its git blob signature / artifact updated-stamp), not the old membership-only id-set hash; so EDITING a file inside a card (git) or updating a doc now marks its layer stale, which the v0.8.0 idempotent-skip was blind to. The top map's meta.source_fingerprint becomes a robust git build anchor 'git:<HEAD-sha>' (was fragile mtimes); /map-refresh diffs `git diff <anchor>..HEAD` UNION uncommitted, maps changed files to stale zones via node provenance.ref paths + doc narration, recomputes each layer's content fingerprint, and rebuilds only the mismatched layers in parallel (the orchestrator's new Refresh mode). code-scanner records per-file git blob content_sig + repo HEAD; forgeplan-scanner records per-artifact updated; zone-extractor threads a scratch-only _content_sig (dropped before ship, CM-23) that map-emitter folds into seed_fingerprint. NEW /map-doctor: fast, read-only triage -- runs the deterministic guardian (--smoke Layer A) over the top map + every layer, flags stale layers via the same git anchor, finds orphan layers (zone gone), and prints a fix-oriented digest (which command repairs each issue) WITHOUT regenerating anything or dispatching an agent. Doctor diagnoses, refresh fixes. All agent-prose + 2 command files; no guardian/schema change. Plugin v0.15.0 -> v0.16.0, catalog 1.114.0 -> 1.115.0. v0.15.0: dogfood-brief batch 4B (CM-10/CM-15/CM-21/CM-22/CM-23/CM-24) -- layout + grouping prose, completing batch 4 (the 25-finding v0.7.1 dogfood brief is now closed except batch 5 = new /map-doctor + /map-refresh commands). CM-24: edge-verifier dedupes edges globally by (from,to,relation) (the edge id's own key), keeping the higher-trust survivor -- a relationship the graph AND a grep both surfaced no longer ships twice or double-lights a flow (A->B and B->A stay distinct). CM-22: map-emitter tier-row layout de-collides accents -- no two grid-neighbour zones share a --map-accent-* token (GC-11); minimal reassignment keeps authored accents and only breaks a colliding tie. CM-15: zone-extractor collapses at EVEN density -- ~ceil(sqrt(N)) comparably-sized group cards (sub-split a lopsided giant), never one blob next to slivers. CM-10: the decision zone can group by narrative ARC (Shape/Design/Decide/Prove) on the TOP map when the composition provides decision_grouping:"arc" + kind_to_arc (promoting the arc derivation the extractor already did one level down), instead of a bag-of-kinds. CM-21: a scoped layer build selects its sub-composition from a catalogue keyed on the target zone's KIND (store->data-shaped, surface->UI-shaped, truth->decision-arc) instead of flooring every drill-down to generic. CM-23: field discipline -- emit only schema-defined + named-consumer fields uniformly (all-or-none); drop speculative extras like the inconsistent description_ru_source / edge note the dogfood shipped. All agent-prose; GC-7..GC-11 gates + 3 test suites catch regressions. Plugin v0.14.0 -> v0.15.0, catalog 1.113.0 -> 1.114.0. v0.14.0: dogfood-brief batch 4A (CM-11/CM-16/CM-17/CM-19/CM-20) -- flows + labels prose. CM-19: a flow is a CONNECTED edge-path, not an arbitrary node set -- map-emitter walks the edge graph and, when a hint's path splits into two edge-disconnected arcs, emits two separate flows instead of one spliced one (the v0.7.1 decision flow lit two islands with a dead gap). CM-11: every flow (hint- and entrypoint-derived) carries a short EN chip name + RU steps (GC-8). CM-17 + CM-20: ONE label policy (zone-extractor Algorithm 5c) -- a code node's label is the basename/curated short name (full repo-relative path in provenance.ref), an artifact node's label is "<ID> -- <title>" (bare artifact_id in provenance.ref); the full machine ref never renders on the card. CM-17: forgeplan-scanner now carries title + a one-line summary per artifact; zone-extractor builds the artifact node's description_ru from that summary (omit when absent, never faked). CM-16: a scoped layer build narrates at FULL budget (one zone = room to explain each node richly) and the richer description propagates up so the top card never carries a thinner description than its own layer produced. All agent-prose; the GC-7..GC-11 gates + 3 test suites catch regressions. Plugin v0.13.0 -> v0.14.0, catalog 1.112.0 -> 1.113.0. v0.13.0: dogfood-brief batch 3 (CM-06/CM-07/CM-08/CM-18) -- content-provenance + meta canonicalization prose the v0.11.0 GC-7..GC-11 gates guard against regression. CM-06: real `found_at` -- code-scanner gains a NARROW git-read Bash (git log --diff-filter=A first-add date, argv-safe, read-only; same edge-verifier precedent + GC-5 git-audit backstop, user-approved) to record per-file first_seen; forgeplan-scanner records each artifact's `created`; zone-extractor Algorithm 5b stamps found_at from a REAL first-seen (code node=git first_seen, artifact node=created, mega=earliest child, deterministic repo-level fallback) -- NEVER now(), which churns the GC-7 append-stability sort key (the v0.7.1 constant/missing-found_at defect). CM-07: map-emitter Algorithm 4 freezes the canonical layer-meta struct GC-9 requires (scope:"layer" + parent_map_id + parent_zone + map_id==<parent>::<zone> frozen :: separator + no needs_confirm floor + seed_fingerprint; the top map writes NONE of these layer keys). CM-08: docs-scanner extracts a project {title, description_ru} from the real README H1 + tagline (omit if absent, never invented); zone-extractor carries it through .extract.json; map-emitter stamps meta.title + meta.description_ru (additive, meta.additionalProperties:true) -- the map finally carries a human heading instead of a bare map_id. CM-18: zone-extractor Algorithm 5 -- a group mega's kind is ALWAYS the literal "mega" (GC-10 BLOCKERs is_mega!==(kind==mega); never the members' leaf kind, which inflated counts) and its provenance.ref carries the machine-recoverable preimage mega:<zoneId>:<groupKey>, not a human sentence. The one security-surface change (code-scanner narrow git-read Bash) is user-approved and lint-safe (code-scanner stays C-coder-class: denies every forgeplan_* mutator + Edit/NotebookEdit). Plugin v0.12.0 -> v0.13.0, catalog 1.111.0 -> 1.112.0. v0.12.0: dogfood-brief batch 2 (P0 prose fixes CM-01/CM-02/CM-05) -- the flow + id-stability defects the v0.11.0 deterministic gates now guard against regression. CM-02: node `kind` is frozen as an ALTITUDE-INVARIANT identity property (zone-extractor skill Algorithm 2a) -- only a node's `zone` is re-computed per scope, so `sha1(kind:ref)` is byte-identical on the top map and inside a drilled-in layer; keeps GC-6 valid and lets forgeplan-web's deriveSubDocument carry a node across altitudes (id-carry no longer breaks when a scoped pass would classify the same entity differently). CM-05: edge-verifier now mints a stable content-hash edge id (sha1("edge:"+from+"|"+to+"|"+relation)[:12] over the REMAPPED endpoints, doubling as the CM-24 dedup key) so flows can reference edges; map-emitter carries edge.id through verbatim and resolves each consecutive flow node pair into flow.edge_ids -- GC-8 had WARNed on the always-empty edge_ids chip. CM-01: after grouped mega-collapse, map-emitter rewrites every flow's node_ids through a visible() map (a hidden collapsed-child -> its containing mega) with consecutive-dedup, so selecting a flow lights RENDERED mega cards the user can expand instead of hidden children (which lit nothing). All three are agent-prose (skills/zone-extractor, skills/edge-verifier, skills/map-emitter + a map-orchestrator scoped-layer note) -- no gate or schema change; the GC-7..GC-11 gates + the 3 test suites catch any regression. v0.11.0: five new deterministic guardian gates (CM-13, from the 5-audit v0.7.1 dogfood brief) -- GC-7 found_at completeness (BLOCKER), GC-8 flow completeness (WARN: multi-node flows must carry edge_ids + RU steps), GC-9 layer-meta canonicalization (BLOCKER: frozen keys + <parent>::<zone> map_id + no auto-confirmed needs_confirm floor), GC-10 is_mega<=>kind==mega (BLOCKER), GC-11 accent-neighbour collision (WARN). All Layer A (doc-only, run under --smoke). They deterministically catch the content defects the dogfood shipped (CM-05/06/07/18/22). Covered by test/guardian-content-gates.mjs (13 assertions). v0.10.0: composition library COMPLETE -- 7 more abstract base archetypes (data-pipeline / ml-project / ai-agent / cms / mobile-app / desktop-app / docs-site), for a full set of 13 base archetypes + 6 pattern overlays. Any common project type -- frontend, backend, CLI, library, data, ML, agentic, CMS, mobile, desktop, docs, fullstack, or the generic floor -- now has a tuned archetype, and hybrids compose base + overlays into one map. v0.9.0: composition BREADTH -- the base-TYPE + pattern-OVERLAY engine (COMPOSITIONS-GUIDE). The orchestrator SELECT stage now detects ALL active pattern overlays independently (not just one base) and composes base + overlays into one effective composition; the emitter lays the merged zones out by tier row (entry/core/data/decisions) for any zone count. Ships 6 overlays (microservices / serverless / cqrs-eventsourcing / mcp-server / api-gateway / monorepo -- the last a regroup-by-package modifier) + 4 new abstract base archetypes (web-frontend / backend-api / cli-tool / library-sdk) alongside web-fullstack / generic (rust-cli-mcp kept as a legacy forgeplan-core specialization). A hybrid repo (e.g. monorepo + backend-api + microservices) now composes into one coherent map instead of falling to the generic floor. v0.8.0: E5 auto-cascade layer generation (PRD-076 FR-5 / ADR-018) -- after the top map is CONFIRMED, /map-build (default --layers) auto-fans-out one scoped per-zone layer build IN PARALLEL (disjoint map/layers/<zone>.json write targets, own scratch + guardian pass), gated by 3 cost controls: seed-fingerprint idempotent skip (unchanged zone not rebuilt), thin-zone threshold (~6 members), depth policy (first level auto; deeper on demand via /map-build-layer or --layers-depth N). meta.seed_fingerprint doubles as forgeplan-web's staleness check. Rejected eager (top map still mutates in gate loops) + sequential (sum-of-zones wall-clock). 8-agent orchestrated pipeline that scans any forgeplan-enabled project and emits a validated .forgeplan/map/map.json (schema forgeplan.map/v1) for forgeplan-web's composed-map renderer. EMITTER profile throughout: a fail-closed PreToolUse hook + agent denylist + a deterministic map-guardian.mjs gate make it structurally impossible for the pipeline to write anywhere except the derived map/layer files or to mutate any forgeplan artifact. v0.7.0: understanding-map quality wave (PRD-076). E1 -- architecture-quality content: over-capacity zones collapse GROUPED by kind (PRD/RFC/ADR/EVID/...) instead of one opaque 170-artifact card; zones carry an abstract RU region description + meaning-subtitle; nodes get a rich RU description synthesized from GROUNDED scanned facts (code-scanner now records module facts -- top-comment, exports, role -- never fabricated from a filename). E2 -- richer flows: web-fullstack ships 4 flow_hints + the emitter derives entrypoint flows to reach 6+ named journeys. E3/E4 -- per-zone generated layers: new /map-build-layer "<zone>" command + orchestrator scoped mode emit a zone's own validated sub-map to .forgeplan/map/layers/<zone>.json (hook + guardian GC-5 extended to sanction map/layers/**); rendering the layer needs forgeplan-web's deriveSubDocument seam (cross-repo contract, PRD-076 FR-3). v0.6.0: output-quality pass on the first rendered real map -- (O-1) node.meta is now a SHORT card subline (full prose -> description_ru), fixing cards that overflowed ~5x; (O-2) the emitter derives flows[] from a composition's flow_hints (short chip name + path + RU steps), so the flow-navigation chips are no longer dark on real data; (O-3) web-fullstack lays zones out in a 2D grid instead of a tall single-column ribbon. Adds COMPOSITIONS-GUIDE.md (the abstract-archetype authoring contract: base TYPE + pattern OVERLAY model, 7-accent convention, shared canvas constants, depth-agnostic hints, flow_hints) and flow_hints on the two curated templates. v0.5.0: dogfood tail-stage fixes -- the write+validate defects the first end-to-end forgeplan-web run surfaced. (F4) map-emitter-gate.sh normalizes the plugin-qualified dispatch identity (forgeplan-map-pack:map-emitter) before its single-writer check -- an exact-string test was denying the emitter's OWN write. (F6) guardian XC-2 + the edge-verifier grep now scope every re-grep with --exclude-dir (node_modules/.git/build/... -- an identical set both sides share) -- an unbounded grep -rlF over the whole repo hung the guardian on any repo with dependencies. (F5) documents honestly that the Write-hook cannot police a Bash-mediated write (edge-verifier needs Bash for grep), so GC-5's after-the-fact git audit is the real single-writer backstop, not the hook. Adds test/emitter-gate-identity.sh + a node_modules-exclusion scenario in test/guardian-layer-b.mjs. v0.4.0: first-dogfood hardening -- fixes the 3 defects the first real forgeplan-web run surfaced. (1) Guardian XC-1 now compares typed-link edges in content-hash id-space (v0.2.0 compared them against artifact-id-keyed scan edges, failing EVERY edge). (2) Guardian GC-5 is now a write-SCOPE check that passes whether map.json is committed (forgeplan-web ships it tracked as the P0 render-proof) or gitignored -- v0.2.0 BLOCKER-ed any committed-map repo and carried a porcelain leading-space parse bug. (3) The web-fullstack composition detection + zone_hints are depth-agnostic, so a nested app root (template/src/**) is recognized instead of falling to the generic floor. Adds test/guardian-layer-b.mjs, a non-smoke regression test covering the Layer-B checks --smoke never exercised (XC-1/GC-5/GC-6/XC-2). v0.3.0: /map-build slash command as the human-facing entry point. v0.2.0: full P1 implementation -- all 8 agents, 3 skills, 3 MVP composition templates, the map-build playbook, and the guardian/hook pair. Pre-1.0: guardian fixes are regression-tested; the depth-agnostic detection fix awaits final confirmation on a full forgeplan-web re-run.

Practical cookbook of forgeplan CLI recipes — task-oriented how-to guides covering getting-started, PRD authoring, Evidence patterns, workflow cycles, multi-plugin discipline, AI-pair dispatch, troubleshooting Sprint A-O anomalies, and CLI/MCP quick-reference. Each recipe: Цель → Команда → Пример → Common errors. / Практическая поваренная книга рецептов forgeplan CLI — пошаговые руководства по онбордингу, PRD, Evidence, рабочим циклам, мультиплагинной дисциплине, диспетчеризации AI-агентов, устранению аномалий и справочнику CLI/MCP.

UX laws knowledge base and frontend code reviewer. Analyzes HTML/CSS/JS/React/Vue/Svelte code against 30 Laws of UX principles. Provides actionable recommendations for improving user experience. Use when building UI components, reviewing frontend code, or learning UX best practices. v1.4.1: ux-reviewer agent canonical-lint compliant (LR-1..LR-3).

First Principles Framework (FPF) — thinking amplifier for structured reasoning, system decomposition, and decision-making. Enhanced version with applied patterns, forgeplan integration, and practical commands. Based on the FPF specification by Anatoly Levenchuk. v1.4.1: fpf-advisor agent canonical-lint compliant (LR-1..LR-3).

ForgePlan Hindsight memory plugin for Claude Code. Long-term cross-session memory wrapping Hindsight (vectorize-io). Provides 13 MCP tools (memory_* + mental_model_* + document_ingest_*), 3 auto-hooks (recall on UserPromptSubmit, retain on Stop, force-retain on SessionEnd), and 5 helper skills (/status, /bootstrap, /mental-model, /diagnose, /export-bank). Three activation modes: plugin install (default-on, bank derived from cwd), per-project setup CLI (explicit `.mcp.json`), or direct MCP wire-up (standalone bundle). Source code colocated under plugins/fpl-hsmem/src/. Implements Ruflo-style outcome-feedback patterns (NOTE-004).