contextdevkit 1.8.0

package/docs/CHANGELOG.md

@@ -0,0 +1,559 @@
+# Changelog
+
+All notable changes to VibeDevKit are documented here.
+Format based on [Keep a Changelog](https://keepachangelog.com/).
+This project adheres to [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+Add your changes here. Use sub-sections: Added / Changed / Fixed / Removed.
+
+### Added
+- **Token-economy digest layer IMPLEMENTED — [ADR-0027](../vibekit/memory/decisions/0027-token-economy-digest-layer.md)
+  (session 37, PR #41).** Shipped all 3 phases of the digest layer that lets commands
+  reason over compact output instead of raw markdown: `runtime/hooks/md-extract.mjs`
+  + `session-digest-core.mjs` (shared pure parsers) + `tools/scripts/session-digest.mjs`
+  (`/distill-sessions` + `/retro` rewired); `boot-context-readers.digestLatestSession`
+  shrinks the boot banner from 60 raw lines to a ~6-line digest with a raw fallback
+  (never empties), plus `context-pack.mjs` collapsing `/dev-start` + `/state` into one
+  call; `adr-digest.mjs` catalog + `--search` for `/ship` + `/new-adr` + `/deep-analysis`.
+  23 selfcheck assertions + a behavioural digest/raw-fallback test; `npm test` green.
+  ROADMAP items marked ✅ (PR #42). ADR-0027 Accepted; backlog 058–060 concluded.
+- **Token-economy digest layer (design) — [ADR-0027](../vibekit/memory/decisions/0027-token-economy-digest-layer.md)
+  (session 36).** Recorded the decision + plan to **reduce token consumption** by
+  pre-digesting deterministically in scripts so the AI reasons over compact output
+  instead of raw markdown. Audited the 65 commands + boot hook: the biggest
+  single-run cost is reading the **last ~10 session logs raw** (~13–16K input
+  tokens before reasoning); the highest-frequency cost is the boot banner injecting
+  60 raw lines every session. Proposed a `lib/digest/` shared extractor +
+  `session-digest.mjs` + `adr-digest.mjs` + `context-pack.mjs` + a boot rewire
+  (digest with raw fallback). New `docs/ROADMAP.md` section + `docs/token-economy-plan.md`
+  (per-command savings table ≈ **120–200K input tokens/week** on an active project,
+  5-phase rollout, guardrails) + DevPipeline backlog **058 / 059 / 060** (one per
+  phase). **No code shipped** — design/planning only (ADR-before-implementing).
+- **GitHub sync awareness in the dev flow — [ADR-0026](../vibekit/memory/decisions/0026-github-sync-awareness-dev-flow.md)
+  (session 35).** New zero-dep `templates/vibekit/tools/scripts/sync-check.mjs`
+  with two modes: `preflight` (run by `/dev-start` before coding — ahead/behind,
+  in-flight branches, and **open PRs with CI/review status**, flagging PRs
+  *awaiting status*) and `prepr` (run by `/git pr` before push — re-check
+  divergence vs the default branch and **detect a duplicate open PR** for the
+  current branch). `gh` is optional: absent/unauthed degrades to the git-only
+  half and reports the PR check as *skipped, never a pass* (Rule 8); offline ⇒
+  silent. PR queries stay **off** the SessionStart hot path (Rule 2); the script
+  is read-only. Wired into `pipeline/dev-start.md` + `vcs/git.md`; 8 selfcheck
+  assertions added.
+- **Landing-page + media generation + SEO/AISO — 3 ADRs (0023/0024/0025),
+  1 new agent, 2 playbooks, 5 scripts, 3 slash commands, 6 pipeline
+  tickets (052–057, session 34).** A coordinated drop addressing the user
+  request for "skills de UX e UI" for high-conversion landing pages,
+  Veo + Nano Banana integration, and an SEO specialist with AISO
+  (AI Search Optimization).
+
+  **ADRs (3).** [ADR-0023](../vibekit/memory/decisions/0023-landing-page-and-conversion-posture.md)
+  records the landing-page posture: fold rules (min 3 / ideal 5–7 / max 9),
+  anti-Lovable refusals (gradient hero, three feature cards, three-tier
+  pricing, testimonial slider, Inter font, Heroicons), dated package
+  recommendations (Astro recommended, Tailwind + tokens, Motion, Lucide,
+  Plausible, GrowthBook), performance budget (LCP < 2.5 s, INP < 200 ms,
+  CLS < 0.1). [ADR-0024](../vibekit/memory/decisions/0024-media-generation-veo-nano-banana.md)
+  records the media-generation adapter contract — five points
+  (no SDK, refuse-on-missing-creds, typed return, refuse-on-content-policy,
+  per-process cost cap) — and the deferred content-addressed cache
+  (ticket 056). [ADR-0025](../vibekit/memory/decisions/0025-seo-and-aiso-posture.md)
+  records the SEO + AISO posture, the audit-first stance, AISO as a
+  first-class concern (`llms.txt`, FAQ schema, semantic HTML5, author +
+  date stamps), and refuse-on-unindexable for landing surfaces (full
+  refuse-gate parked as ticket 057).
+
+  **Agent (1 new).** `templates/claude/agents/seo-specialist.md` —
+  design-team squad member. Audit-first; refuses unindexable SPAs;
+  refuses JS-rendered content for cited material; respects project-local
+  ADR overrides. Pairs with `landing-architect`, `ui-designer`,
+  `ux-designer`, `accessibility`, `code-reviewer`.
+
+  **Playbooks (2).** `templates/vibekit/workflows/playbooks/landing-page.md`
+  carries the anti-Lovable substitution table (editorial hero,
+  in-context testimonials, decision-tree pricing, inline FAQ for AISO)
+  and the package-recs table dated 2026-06-02. `templates/vibekit/workflows/
+  playbooks/seo-aiso.md` carries the SEO checklist (server-rendered HTML,
+  meta tags, sitemap, robots, structured data, images, CWV) + the AISO
+  checklist (`llms.txt`, FAQ schema, semantic HTML5, scannable Q&A
+  headings, author + date schema, robots.txt AI-crawler block detection).
+
+  **Media-gen system (5 files).**
+  `templates/vibekit/runtime/providers/media/_adapter.mjs` — contract +
+  `MediaProviderError` (7 codes: NO_CREDENTIALS, CONTENT_POLICY,
+  COST_CAP_REACHED, RATE_LIMIT, PROVIDER_ERROR, BAD_INPUT, IO) +
+  `validateAdapter` + `assertCredentials` + `noteCostOrThrow` (shared
+  per-process cost-cap tally read from `VIBEDEVKIT_MEDIA_MAX_USD`).
+  `nano-banana.mjs` — Imagen 3 image generation via `node:fetch`
+  (`POST /v1beta/models/imagen-3.0-generate-002:predict`, dated
+  2026-06-02). `veo.mjs` — Veo 3 video generation with the long-running
+  operation poll loop (`predictLongRunning` → poll until `done:
+  true` → download bytes or follow `uri`). `templates/vibekit/tools/
+  scripts/media-gen.mjs` — CLI entry with positional `image|video`,
+  `--prompt`, `--out`, `--provider`, `--aspect-ratio`, `--duration`,
+  `--model`, `--sample-count`, `--dry-run`, `--help`. New
+  `templates/vibekit/.env.example` template ships at the kit's vibekit
+  root; commented; `install.mjs` seeds it write-if-missing.
+
+  **Audit scripts (3 files).**
+  `templates/vibekit/tools/scripts/audit-shared.mjs` (~110 lines) —
+  `walkProject` (recursive walk skipping `node_modules`, `.git`, build
+  caches), `detectFramework` (Astro / Next / Nuxt / Remix / SvelteKit /
+  Gatsby / 11ty / `vite-react` / `null`), `lineOf`, `renderFindings`
+  (severity-grouped coloured terminal output), `exitCodeFor` (1 on any
+  `critical`). `seo-audit.mjs` (~125 lines) — 8 codes
+  (SPA_ENTRYPOINT critical; MISSING_TITLE/DESC/SITEMAP/MULTIPLE_H1 high;
+  MISSING_CANONICAL/ALT/ROBOTS medium); SPA-entry-point detection reads
+  `index.html` for `<div id="root\|app\|__next\|___gatsby"></div>` and
+  flags only when framework detection is `vite-react` or `null`.
+  `aiso-audit.mjs` (~130 lines) — 8 codes (MISSING_LLMS_TXT/
+  FAQ_SCHEMA/JS_RENDERED/BLOCKS_AI_CRAWLERS high;
+  MISSING_ORG_SCHEMA/DIV_SOUP medium; MISSING_AUTHOR/DATE low);
+  div-soup ratio threshold 5:1; AI-crawler block detection covers
+  GPTBot, ClaudeBot, PerplexityBot, Google-Extended, OAI-SearchBot.
+
+  **Slash commands (3).** `/seo-audit` lands in the `audit/` pack (per
+  ticket 047's taxonomy). `/landing-page` + `/media-gen` at root
+  (utility commands, like `/dashboard` and `/watch`). `commands/README.md`
+  taxonomy updated to list the three new commands.
+
+  **Pipeline tickets (6).** 052 / 053 / 054 in `testing/` (shipped
+  this session). 055 (`.env.example` install integration follow-up) +
+  056 (media-gen cache) + 057 (SEO refuse-gate in `code-reviewer`)
+  parked in `backlog/` with explicit acceptance criteria, dependencies
+  declared via the ticket-040 DAG (`dependencies: ["053"]`, etc.) and
+  T-shirt complexity (S/M).
+
+  **Tests (rule 3).** 33 new selfcheck assertions covering every shipped
+  surface — every adapter export, every audit-code constant, every
+  playbook anchor, the `127.0.0.1`-only spirit (`/media-gen` is
+  network-only, no localhost binding involved; `assertCredentials` is
+  the equivalent guard). All 7 integration suites green.
+
+  **Smoke-tested end-to-end.** `seo-audit --json` against this repo
+  emitted truthful findings (no sitemap, no robots.txt, missing meta
+  description in the TanStack starter's `index.html`). `aiso-audit
+  --json` flagged no `llms.txt` and the missing FAQ schema in the
+  starter. `media-gen image --prompt "test" --out tmp.png --dry-run`
+  detected nano-banana as the image adapter and showed
+  `GOOGLE_AI_API_KEY ✗ missing` — the refuse-on-missing-creds path
+  works without making any network call.
+
+- **Backlog sweep — 5 Compozy follow-through tickets shipped (session 33,
+  `main`).** Single `/dev-start` resolved the remaining open backlog from
+  ADRs 0018–0022; one worktree + one PR per ticket, squash-merged on green
+  CI (Node 18/20/22). **PR #29 ticket 040** (commit `42ed8c8`) — task
+  metadata v2: `dependencies: []` (strict DAG, no cycles), `complexity:
+  S\|M\|L\|XL`, extended `type` enum with `spike` + `docs`, new
+  `pipeline validate` subcommand, board `↘ blocked by N` hint, new
+  `pipeline-validate.mjs` sibling. **PR #30 ticket 047** (`9787969`) — 39
+  of 58 slash commands moved into `qa/ vcs/ forge/ pipeline/ audit/
+  setup/` subfolders (daily 20 stay at root); new `commands/README.md`
+  documents the taxonomy; selfcheck walk made recursive + new
+  basename-collision invariant. Claude Code resolves by basename →
+  invocations unchanged. **PR #31 ticket 046** (`c54b6bb`) — new
+  `/resume` re-binds the current session to an unregistered drift
+  ledger via `resume.mjs` (reads `listAllLedgers` from the runtime,
+  single-sourced); three rule-8 refusal paths (unknown id / already
+  registered / cross-session claim conflict); atomic `.last-touched`
+  rewrite. **PR #32 ticket 043** (`bb5c132`) — new `distill-detect.mjs`
+  scans the just-written session narrative for 10 Tier-1 rule-like
+  patterns ("we decided" / "from now on" / "always" / "never" /
+  "convention:" / "lesson learned"); proposal-only (never auto-invokes
+  `/distill-sessions`); skips headings + blockquotes to dodge false
+  positives; wired into `/log-session` as step 6. **PR #33 ticket 041**
+  (`8dd35a3`) — new `/workflow` macro chains roadmap → ADR → pipeline →
+  ship via a per-slug breadcrumb in `vibekit/memory/workflows/<slug>.md`;
+  `new` / `advance` / `status` subcommands; each phase is an explicit
+  user action (rule 9, no silent chaining). **Plus:** new
+  `tools/integration-test-compozy.mjs` sibling extracted from
+  `integration-test-guards.mjs` (responsibility seam — guards stays
+  input-rejection-focused; lifecycle tests for 041 / 043 / 046 live in
+  the sibling). +24 selfcheck behavioural asserts + 16 integration
+  lifecycle asserts across the five PRs. All 7 test suites green;
+  tech-debt CI gate: 0 RED-zone findings across 138 files. **049
+  (Extension SDK) and 050 (Run dispatcher) remain in `backlog/`** —
+  confirmed rule-9 parking tickets (type `spike`, P4, `sla:` empty,
+  explicit trigger conditions per ADR-0018 / ADR-0022). Bug **038**
+  (install in worktree) was also closed earlier in the same conversation
+  (PR #27, commit `4c3ed59`).
+- **`/dashboard` — visual project state in HTML, snapshot or live
+  (ticket 051, session 33)**. Zero-dep, pure `node:` stdlib. Two modes
+  from one entry: `node vibekit/tools/scripts/dashboard.mjs` writes a
+  self-contained `dashboard.html` (inline CSS + vanilla JS, no external
+  assets — opens by double-click, works offline); `--watch` spawns a
+  tiny `node:http` server bound to **127.0.0.1 only** (default port
+  `4242`, override via `--port=N` or `VIBEDEVKIT_DASHBOARD_PORT`) that
+  serves the page plus a `text/event-stream` endpoint on `/events`. An
+  `fs.watch` on the platform dir (200 ms debouncer) rebuilds the data
+  object and pushes it; the page reconnects on disconnect and patches
+  the DOM in place. Heartbeat every 15 s on idle. Four modules, each
+  under the 280-line budget: `dashboard-data.mjs` (~160 lines —
+  single owner of "read project state": pipeline lanes, ADRs,
+  sessions, roadmap, `[Unreleased]` CHANGELOG; single-sources
+  `PLATFORM_DIR` via `paths.mjs` per rule 4; exports
+  `parseFrontmatter` so other scripts can reuse the YAML reader);
+  `dashboard-html.mjs` (~180 lines — purely functional renderer with
+  `escapeHtml` everywhere, CSS Grid for the 4-column kanban,
+  `prefers-color-scheme` light/dark, type/priority/ADR-status colour
+  badges); `dashboard-server.mjs` (~115 lines — `startDashboardServer`
+  + `resolvePort` exports; defensive everywhere — `fs.watch`
+  failures log and continue; SSE clients tracked in a `Set` and
+  cleaned up on `req.close`); `dashboard.mjs` (~110 lines — CLI
+  dispatch, `--help`, clean SIGINT). New
+  `templates/claude/commands/dashboard.md` documents both modes and
+  the non-goals (read-only, no remote access, no JS framework, no
+  persistent state). 11 new selfcheck assertions covering every
+  shipped surface including the `127.0.0.1`-only bind. Smoke-tested
+  both modes: snapshot writes a 68 KB self-contained file; live mode
+  serves 69 KB on `127.0.0.1:14242` with the SSE client-script
+  appended.
+- **`home.mjs` — single owner of `~/.vibedevkit/` resolution + atomic
+  write contract (ticket 048 → testing; ADR-0020 follow-up)**. New
+  `templates/vibekit/tools/scripts/home.mjs` (~95 lines, zero-dep)
+  exports three functions: `resolveHome()` honours `VIBEDEVKIT_HOME`
+  with lazy directory creation; `readHomeFile(name)` returns `null`
+  on absent/malformed/wrong-version files (an *explicitly unknown*
+  `version` triggers a timestamped `.bak.<ms>` and a fresh start —
+  absent `version` is treated as legacy and adopted, so existing
+  `fleet.json` is not destroyed on first read); `writeHomeFile(name,
+  data)` writes atomically via `tmp.<pid>` + `renameSync`, stamping
+  `version: 1` when absent. `fleet.mjs` migrated to delegate to the
+  helper — `VIBE_FLEET_FILE` (used by the integration test as a path
+  override) keeps its precedence, so existing tests continue to pass
+  without changes. 6 new selfcheck assertions
+  (`resolveHome` / `readHomeFile` / `writeHomeFile` exports,
+  `renameSync(tmp, path)` atomic-write pattern, `VIBEDEVKIT_HOME`
+  honoured, `fleet.mjs` imports the helper). Smoke-tested end-to-end
+  with `VIBEDEVKIT_HOME=<tmpdir>`: list → add → list round-trip works
+  and the persisted file carries `"version": 1`. ADR-0020 promised
+  "any next home-scoped consumer (preferences, telemetry cache)
+  inherits the contract for free" — that promise is now real.
+- **5 new ADRs + 11 pipeline tickets from the Compozy comparison pass**
+  (session 30, `feat/tanstack-support`). Compared VibeDevKit against
+  `D:\compozy-main` and extracted what fits the constitution. Five **ADRs**
+  land the architectural decisions: **ADR-0018 — Extension SDK** (subprocess
+  JSON-RPC contract sketched; *implementation deferred* until a first external
+  author signals interest; rule-9-driven refusal of the speculative half),
+  **ADR-0019 — MCP injection in squads** (optional `mcpServers:` field in
+  agent frontmatter with required `rationale`; `optional: true` default
+  means the agent loads without the server; no shipped agent declares one
+  yet — convention only), **ADR-0020 — Workspace registry global**
+  (formalises `~/.vibedevkit/` with `VIBEDEVKIT_HOME` override, lazy
+  creation, plain JSON + `version` field, atomic tmp+rename; lists what
+  belongs there and what does *not* — no ADRs, no sessions, no SQLite, no
+  daemon), **ADR-0021 — Provider strategy for review/QA** (thin adapter
+  contract at `templates/vibekit/runtime/providers/review/` with `gh` as the
+  shipped seed; missing CLI is a refusal not a fallback — rule 8;
+  `/git` and `/qa-signoff` keep calling `gh` directly until the next
+  consumer justifies the rewrite), **ADR-0022 — Run dispatcher** (direction
+  accepted; implementation deferred behind three explicit trigger
+  conditions; locks the `dependencies: []` DAG semantics for ticket 040
+  so the future implementation does not retrofit free-text). **Three green
+  items** implemented this session: (a) **two-tier memory** via
+  `templates/vibekit/pipeline/.gitignore` excluding `*.scratch.md` +
+  one-line addition to `/dev-start` describing the per-task scratch
+  convention (ticket 042 → testing); (b) **review providers adapter
+  scaffold** — `_adapter.mjs` (contract + `ProviderError` + `validateAdapter`),
+  `detect.mjs` (`resolveAdapter` resolves from `vibekit/config.json` →
+  origin auto-detect → refusal; single-sources `PLATFORM_DIR` from
+  `paths.mjs` per rule 4), `gh.mjs` (thin `spawnSync` wrapper around
+  `gh pr create / api / pr comment`; throws typed `ProviderError` codes
+  `CLI_MISSING | AUTH | NOT_FOUND | REMOTE_REJECTED | BAD_INPUT | PARSE`)
+  (ticket 044 → testing); (c) **`/watch` slash command** —
+  `templates/vibekit/tools/scripts/watch.mjs` reuses
+  `readMostRecentLedger` from the runtime (single-sourced session
+  resolution), default prints the ledger and exits, `--follow` re-polls
+  every 500ms and exits cleanly on SIGINT, never prints "0 entries" as
+  soft success (refused-silently-to-false-negative) (ticket 045 →
+  testing). **One yellow seed**: `templates/claude/agents/_TEMPLATE.md`
+  gains a commented-out `mcpServers:` block pointing to ADR-0019 — new
+  agents read the convention without any shipped agent using it yet.
+  **Eleven pipeline tickets** (040–050) scaffolded: 040 metadata v2
+  (dependencies DAG + complexity + spike/docs types), 041 `/workflow`
+  macro, 042 two-tier memory (testing), 043 auto memory compaction at
+  `/log-session`, 044 review providers seed (testing), 045 `/watch`
+  (testing), 046 `/resume` for interrupted sessions, 047 skill packs by
+  domain (commands subfolders), 048 `home.mjs` helper for ADR-0020,
+  049/050 are the trigger-watch tickets parking ADR-0018 and ADR-0022
+  behind explicit conditions. **13 new selfcheck assertions** in
+  `tools/selfcheck-source.mjs` covering every shipped surface: agent
+  template documents `mcpServers` + `rationale`; the three adapter
+  module exports; the `/watch` `parseLedgerEntry` export + command
+  file; the pipeline `.gitignore` rule; `/dev-start`'s scratch line.
+  `npm test` green end-to-end (selfcheck + 5 integration suites).
+- **agent-forge — Fase 6: declarative pipeline DSL + dry-run engine shipped
+  on a worktree** (session 30, commit `eae2fee` on
+  `feat/agent-forge-fase6-pipeline-dsl`). Closes ADR-0015 Part A — the
+  forge orchestration becomes a diffable, simulate-impact-mappable plan.
+  New `templates/vibekit/squads/agent-forge/pipeline.yaml` declares 9
+  steps with one bounded retry loop (eval-gate → generate-prompt,
+  max_cycles: 3) and two conditional steps (`generate-tools` when
+  `blueprint.tools.length > 0`, `generate-rag` when
+  `capabilities.rag == true`). New engine
+  `templates/vibekit/tools/scripts/squad-pipeline.mjs` (252 lines) parses
+  via `lib/yaml.mjs` (ADR-0013 dynamic import); **refuses on missing
+  `yaml` with exit 0 + informative message** — pipelines are opt-in, not
+  hot-path. Sibling `squad-pipeline-condition.mjs` (192 lines) is the
+  whitelisted parser — only `<id>(.<id>)* <op> <literal>` and `…length
+  <op> <int>` (no function calls, no boolean chaining, no arithmetic, no
+  type coercion). `--dry-run` walks the graph against empty ctx and
+  prints `✓ / ⊘ / ↺` markers. `max_review_cycles` is a hard cap (engine
+  exits "manual escalation required" rather than looping). Vendor model
+  names are refused in YAML — only `model_tier: fast|powerful|reasoning`
+  (router stays the single resolver). Canonical spec
+  `docs/SQUAD-PIPELINE-FORMAT.md` (258 lines). 2 new selfchecks
+  (`checkConditionParser` + `checkSquadPipeline`, 8 asserts) +
+  4 new integration asserts. agent-forge ROADMAP Fase 6 → ✅. **NOT
+  shipped this turn** (deferred to tasks 040/039 in the worktree
+  backlog): `state.json` per run, DevPipeline `working/` stage,
+  cross-session task ownership.
+- **ADR-0017 — TanStack stack recognition: detection + curated playbook +
+  opt-in empty starter** (session 29). `templates/vibekit/tools/scripts/
+  detect-stack.mjs` `known` list extended with the TanStack family
+  (`@tanstack/react-query`, `react-router`, `react-table`, `react-form`,
+  `react-virtual`, `start`, plus `solid-query`/`vue-query`) — existing
+  projects on TanStack are no longer invisible to `/setupvibedevkit`. New
+  `templates/vibekit/workflows/playbooks/tanstack.md` (165 lines) is the
+  curated *why/when/how*: the family table (pick by concern), the **Core
+  conventions** block injected into the user's `CLAUDE.md` (server state in
+  Query never `useState`, `queryOptions` as the unit of reuse, hierarchical
+  cache keys, typed Router params, deliberate `staleTime`, minimum-key
+  invalidation), the anti-patterns review will catch, the explicit
+  Next/Nuxt/Remix conflict ("don't stack two routers"), and the freshness
+  protocol. `/aidevtool-from0` Phase 3 references the playbook when the
+  architect proposes TanStack; `/setupvibedevkit` Phase 4 inherits the
+  conventions block on detection. New `templates/vibekit/starters/tanstack/`
+  (10 files, 165 lines total) is a Router + Query + Vite skeleton offered
+  opt-in by `/aidevtool-from0` Phase 6 — **no invented domain** (one
+  placeholder route), no CSS framework, no backend choice, no example
+  query, copy-and-step-aside (no upgrade path). TanStack Start documented
+  as an upgrade path rather than shipped (Start's tooling has been evolving
+  fast; pinning to a moving target would ship fragility). `install.mjs`
+  now `copyTree`s `vibekit/starters/` on every install. Selfcheck
+  (`tools/selfcheck-source.mjs`) gains seven cases asserting detection
+  pattern, playbook presence, starter deps (`react-router` + `react-query`),
+  wiring (`QueryClientProvider`, `RouterProvider`), and installer copy —
+  without prescribing version numbers (owned by the playbook's freshness
+  protocol).
+
+- **ADR-0016 — Best-practices restructured: 2-tier rubric, split into rubric
+  + protocol, stack-agnostic, security routed out** (session 25). The
+  rubric was 69 lines, flat, hygiene-only; the auditor led with line counts
+  instead of architecture. Now: `templates/vibekit/best-practices.md`
+  (323 lines) carries the rubric — risk model, **Tier 1 System &
+  architecture** (S1 dependency direction, S2 boundaries, S3 coupling/cycles,
+  S4 state location), **Tier 2 Module & function hygiene** (H1–H7) — each
+  rule with the **Principle / Smells / Fix / Don't over-apply** shape that
+  calibrates the auditor against false positives. New companion
+  `templates/vibekit/review-protocol.md` (214 lines) carries the protocol —
+  severity vocabulary `BLOCKER`/`HARD`/`CANDIDATE`/`NIT` mapped onto the
+  scanner's existing 1..5 scale, scope clauses (Tier 2 relaxed for spikes),
+  the run-the-analysis steps, the report shape, and an honest **Scanner
+  Map** listing only the four detectors that actually exist
+  (`detectLineBudget`, `detectSrpAnd`, `detectReactStateLoop`,
+  `detectTodoMarkers`) plus the `vibekit/detectors/*.mjs` plug-in slot.
+  Deliberately rejected (recorded in the ADR): a Tier 2 — Security
+  (duplicates `code-security`/`security`/`infra-security` and
+  `/audit`/`/deps-audit`/`/security-setup` — routed out via *Adjacent
+  concerns* instead); stack-coupled examples (Supabase/RLS/zod/NEXT_PUBLIC,
+  rule 9); a `// vibe-allow §ID` pragma (not implemented); promised but
+  absent detectors (cycles, secrets, `any`-counter); a parallel severity
+  scale (would drift from the `--ci` gate). Dogfood install mirrored.
+
+- **ADR-0015 — Pipeline DSL, `working/` stage, and multi-session work-claims**
+  (session 24, proposed). One ADR opens two adjacent moves, sharing one
+  substrate (`state.json` per in-flight item). **Part A:** declarative
+  `pipeline.yaml` per squad (steps + `condition` + `on_reject` +
+  `max_review_cycles` + `model_tier` + `type: checkpoint`) with a `squad-
+  pipeline.mjs` engine — opt-in per squad, parses via `lib/yaml.mjs`
+  (ADR-0013 dynamic import), refuses on missing `yaml` with a clear message,
+  whitelisted `condition` grammar (no arbitrary expression eval), no vendor
+  model names in YAML (the router stays the single resolver), dry-run is a
+  first-class mode. **Part B:** a `working/` stage in the DevPipeline that
+  holds *only WIP*, leaving `testing/` for QA sign-off; `/pipeline start
+  <id>` and `/pipeline stop <id>` attach/detach the task to the workspace
+  record (`.claude/.workspace/<sid>.json` gains a `tasks[]` array), the
+  dashboard surfaces which session owns which task, stale auto-eviction
+  defaults to 90m without a heartbeat. **Part C:** canonical `state.json`
+  schema covers both task-in-flight and pipeline-run; future `/runs` lists
+  the last N across squads. Inspired by a read of opensquad's declarative
+  pipeline, *not* a copy — the kit's zero-dep + model-router + simulate-
+  impact invariants reshape the grammar. Roadmap markers updated:
+  agent-forge ROADMAP gains Fase 6 (task 036, 📋); `docs/ROADMAP.md` gains
+  a "Next" block before the design invariants; agent-forge ROADMAP "Net
+  additions" lists 5 new ADR-0015-driven net additions. No code touched
+  this turn — only the ADR + roadmap + this entry.
+
+### Added
+- **PR [#19](https://github.com/reiTavares/VibeDevKit/pull/19) merged to
+  `main`** (session 27, rebase strategy — individual commits preserved).
+  Ships agent-forge Fases 1–5 (ADR-0012), ADR-0015 roadmap markers,
+  ADR-0016 tiered rubric + companion review-protocol + rewritten
+  `/analyze-code-ia-practices`, and the first BLOCKER cleared by the new
+  rubric (task 036, integration-test-tooling split). 10 commits land on
+  main; local `main` fast-forwarded.
+
+### Changed
+- **selfcheck-checks.mjs split by invariant category + checkLevelsAndSchema
+  SRP split** (session 28, task 037, **PR [#20](https://github.com/reiTavares/VibeDevKit/pull/20)
+  merged to `main`** as `db0632c`) — second pair caught by the ADR-0016 rubric. The 253-line yellow-zone file carried 5 distinct
+  invariant categories under one umbrella; the rubric's H1 and H2
+  (`checkLevelsAndSchema` SRP-and) drove a split by responsibility into
+  three siblings: `tools/selfcheck-runtime.mjs` (113 — boot readers,
+  atomic I/O, sid sanitization, squad meta), `tools/selfcheck-config.mjs`
+  (80 — level taxonomy and zod schema, with `checkLevelsAndSchema` itself
+  split into `checkLevels` + `checkSchema`), `tools/selfcheck-source.mjs`
+  (123 — source-level patterns, rule 4 enforcement, SHA-pinned workflows;
+  hosts the shared `listMjs` walker). The orchestrator `tools/selfcheck
+  -checks.mjs` was deleted (no compatibility shim — rule 9). `tools/selfcheck
+  .mjs` now imports + dispatches the three new runners plus the two
+  pre-existing agent-forge ones; gained a cohesion note (241 lines, in the
+  ~308 tolerance band). `tools/selfcheck-agent-forge.mjs` updated to import
+  `listMjs` from the new source module. All five integration suites pass;
+  tech-debt scan emits zero severity-5 findings; SRP-and finding cleared.
+- **integration-test-tooling.mjs split by responsibility** (session 26, task
+  036 — first BLOCKER caught by the new ADR-0016 rubric). The file was 321
+  lines (> 308 RED) carrying ~23 subsystems. Extracted the internally-coupled
+  DevPipeline chain (add → ingest → idempotent → prioritize → wsjf → bugs,
+  ~39 lines) into a focused sibling `tools/integration-test-tooling-pipeline.mjs`
+  with its own fixture + reporter (one extra L5 install — cost paid for
+  isolation). Updated `tools/it-helpers.mjs` header to list all four
+  integration files; added the new sibling to `npm test` and `prepublishOnly`
+  scripts. The remaining tooling file is 285 lines (yellow zone) with a
+  documented cohesion note ("one fixture install, many tool scripts") and a
+  flagged next seam (agent-forge round-trip) for when budget pressure
+  returns. All 4 integration suites pass; `tech-debt-scan --ci` no longer
+  reports a RED-zone finding.
+- **`/analyze-code-ia-practices` rewritten + factual fix** (session 25,
+  ADR-0016). Command now reads both rubric files
+  (`best-practices.md` + `review-protocol.md`), walks Tier 1 (judgment, no
+  scanner help) before Tier 2 (scanner findings), routes adjacent concerns
+  (security, a11y, privacy, deps) to specialist agents instead of absorbing
+  them. Also corrected a long-standing factual drift: the command
+  previously claimed the scanner produced `missing-doc` findings — a
+  detector that has never existed in `tech-debt-detectors.mjs` — and
+  omitted `todo-marker` which does exist. Replaced with the four real
+  detectors and their actual severities.
+- **Distillation cycle 1 — refuse-by-default + defer-to-demand promoted to the
+  constitution** (session 23, ADR-0014). After agent-forge Fases 0–5 closed,
+  the 25 net additions on the squad ROADMAP surfaced two recurring postures
+  the constitution didn't have written down. `CLAUDE.md` rules 8 + 9 added
+  (refuse-over-rubber-stamp + build-what-is-asked); rule 1 refined with a
+  positive-split criterion. 140 → 170 lines (under the 200-line nudge). No
+  code touched — the cycle codifies patterns already practiced.
+
+### Added
+- **agent-forge — Fase 5: RAG designer + Go runtime + L5 gate + /fleet Forge
+  Stats** (session 22, task 035). Closes the original blueprint. New
+  `lib/rag-designer.mjs` (multilingual-vs-english embedding from
+  `intent.domain`, pgvector vs qdrant from residency, recursive chunking
+  tightened for extraction, `top_k` by complexity, hybrid + reranker on by
+  default). Packager writes 5 `rag/` files when `capabilities.rag: true` and
+  stamps the Go adapter (`go.mod` + `{{MODULE_PATH}}`). `defaults.l5.
+  highRiskPaths` now ships with `agent-packages/**` — every forged-agent edit
+  triggers the simulate-impact gate. `fleet.mjs cmdStats` aggregates per-repo
+  Forge Stats + a fleet total line. Selfcheck split by responsibility: build
+  pipeline stays in `selfcheck-agent-forge.mjs` (225 lines), ops checks moved
+  to `selfcheck-agent-forge-ops.mjs` (107 lines). New `rag-designer.md`
+  briefing — refuses pinecone-under-no-cloud and `top_k < 4`. **All Fases
+  0–5 are ✅; backlog is 0.**
+- **agent-forge — Fase 4: production maintenance + Forge Stats + docs**
+  (session 21, task 034). 13 new `/forge-*` slash commands (list/show/doctor/
+  policy/budget/audit/eval/redteam/route/fallback-test/refresh-matrix/
+  killswitch/deprecate) wired through 3 CLI modules + `lib/package-ops.mjs`.
+  Node runtime adapter ships a `createShadowEval` scaffold. `/vibe-stats`
+  gains a Forge Stats section. New reference docs `docs/SQUADS/agent-forge.md`
+  + `docs/AGENT-PACKAGE-FORMAT.md`. Selfcheck `checkPackageOps` + 19
+  inventory entries. ROADMAP Fase 4 ✅.
+- **agent-forge — Fase 3: governance + eval gate** (session 20, task 033). The
+  refuse-to-ship layer. Three new pure zero-dep modules: `lib/eval-designer.mjs`
+  (`designEvalSet` — seed golden by intent.category + universal red-team + rubric
+  + thresholds derived from blueprint privacy/sla/cost; PII-leak block rate forced
+  to 1.0 when `pii_present`), `lib/eval-runner.mjs` (`runEvalSuite` —
+  provider-agnostic; mock for CI, real adapter for prod; supports `exact` /
+  `exact_set` / `numeric_tolerance:N` / `semantic_similarity:>=N`; aggregates p95
+  latency + cost), `lib/governance-officer.mjs` (`attachGovernance` populates 3
+  pillars from blueprint + fallback chain from router decision; `validateGovernance`
+  refuses on missing sections OR `{{TOKEN}}` placeholders; **throws**). Packager
+  now calls `attachGovernance` first (throws before any I/O), writes 4 populated
+  governance YAMLs + 4 populated eval files, and stamps `provenance.eval_passed_at`
+  only when `opts.evalResult.verdict === 'pass'`. `forgeNew` gains opt-in
+  `runEval = { provider, semantic }` that runs the gate before packaging. Two
+  agent briefings ship: `eval-designer.md` + `governance-officer.md`. 11
+  behavioural selfchecks + 6 integration asserts. ROADMAP §6/§7 ✅; Fase 3 ✅.
+- **agent-forge — Fase 2: multi-provider + Python runtime** (session 19, task 032).
+  All five providers now flow end-to-end: Gemini (`systemInstruction` body +
+  safetySettings note; `functionDeclarations` adapter strips JSON-Schema fields the
+  parser rejects), DeepSeek (OpenAI-compat + explicit CoT cue prepended to Rules),
+  Ollama (Markdown body, per-model `chat_template` applied by the host).
+  `packager.mjs` writes the full 5 prompts + 5 tool adapters every package and
+  stamps `{{AGENT_NAME}}` / `{{SEE_LICENSE}}` into Node `package.json` + Python
+  `pyproject.toml` (and their READMEs) when those runtimes are requested.
+  `runtime_adapters` is now a first-class blueprint field (`enum-multi` over
+  `[node, python, go]`, default `[node]`) — `validateBlueprint` rejects unknown
+  entries; `assembleManifest` stamps `spec.runtime_adapters` straight from the
+  blueprint. Integration test gains 7 new asserts. ROADMAP §5 prompt/tool generators
+  flipped ✅. Suite green.
+- **agent-forge — Fase 1, the model-router engine** (session 18, ADR-0012 §5).
+  `lib/router.mjs` (`routeAgent`, pure zero-dep) + `router/decision-rules.json` (13
+  rules, cap 15, shortlists only — no hardcoded quality claims). Filters candidates by
+  capability + residency, enforces a cross-provider fallback, throws on
+  `abort_if_no_candidate`, emits the canonical Model Selection Rationale with the
+  eval-as-authority disclaimer. New `checkRouterEngine` behavioural test (typical +
+  on-prem blueprints). **Refactor**: agent-forge selfchecks moved to
+  `tools/selfcheck-agent-forge.mjs` (real responsibility seam; `selfcheck-checks.mjs`
+  back to 251 lines). Squad ROADMAP §4.3 / §4.4 / §12 → ✅. Task 031 now 2/7.
+- **agent-forge — Fase 0 foundations** (session 17, ADR-0012). New optional L4+
+  *factory* squad that forges portable, multi-provider Agent Packages for projects
+  outside the kit. Added the squad scaffold (`vibekit/squads/agent-forge/` README +
+  `best-practices.md`), a dated/ADR-gated `capability-matrix.json` with a parse/id
+  selfcheck guard, and the full APF v1 template tree (45 files). Agents + `/forge-*`
+  commands land in Fases 1–5 (031–035). PR #18.
+- **DevPipeline backlog cleared (all 25 tasks)** — session 16. Fixed: git-call
+  timeouts (007), boot truncation/tie-break (009/010), partial-preset crash (013),
+  atomic writes + collision-safe ids (011), live-ledger race (008). Security:
+  sanitizeSid everywhere (012), SHA-pinned Actions + least-privilege CI (019/020),
+  README trust section + installer hook backup (021/022). Added: guards test suite
+  (014–018), detectors seed (026). Changed: single-source level taxonomy + passthrough
+  schema [ADR-0010] (024/025), single-source paths via pathsFor [ADR-0011] (023),
+  shared readJsonSafe/squadOf (027/028), line-budget cohesion + nits + selfcheck split
+  (005/006/029). No public API removed.
+- Released: **v1.4.0 (npm + GitHub)** — onboarding defaults + level-cap fixes.
+- Changed: **recommended start level by project type** (ADR-0009) — installer auto-picks
+  **L3** (greenfield) / **L7** (existing) instead of always L2; docs retagged (LEVELS.md
+  now has L6/L7 sections + "Where to start"; both instrucoes; README quickstart).
+- Fixed: **level cap stuck at 6** — `install.mjs` downgraded `--level 7`→2 and `doctor.mjs`
+  flagged L7 as out of range; both accept 1–7 now. Stale 1-5/1-6 range hints corrected.
+- Released: **v1.3.0 (npm + GitHub)** — launches the **L7 "Ecosystem & Scale"** tier
+  (`/vibe-level 7`, capability tier, no new hook) + all post-1.2 capabilities.
+- Added: **L7 as a real level** — `getLevel` 1→7, labels, `--level 1-7`, `vibe-level 7`,
+  selfcheck/integration coverage. [ADR-0008]
+- Added: **Diverse & visual testing harness (MVP)** — `/visual-test` + `visual-test.mjs`
+  scaffold Playwright (JS + Python) starters; wired into scaffold-tests/qa-signoff/ship.
+  [ADR-0007]
+- Added: **Fleet mode (MVP)** — `/fleet` + `fleet.mjs`: a control plane over many
+  repos (registry at `~/.vibedevkit/fleet.json`; aggregate `stats`/`audit`; detect
+  CLAUDE.md rule drift). Roadmap #2.
+- Added: **Outcome-driven agent tuning (MVP)** — `/tune-agents` + `agent-tuning.mjs`
+  propose briefing refinements (applies nothing). Roadmap #3.
+- Added: **Editor/CI surfaces (MVP)** — status-line widget (`statusline.mjs`) +
+  `quality.yml` CI workflow (contract-drift + tech-debt gates). Roadmap #4.
+- Added: **Pluggable detectors & stack presets (MVP)** — `vibekit/detectors/*.mjs`
+  drop-ins + `install.mjs --preset next|go|python`. Roadmap #5.
+- Changed: **Split two RED-zone files** off the constitution gate — `integration-test.mjs`
+  (→ core + tooling + `it-helpers.mjs`) and `session-start.mjs` (→ `boot-signals.mjs`);
+  behaviour-identical, gate green.
+- Added: **`code-security` agent** — security-team sub-specialist for the code's
+  external surface (integration code, dependency provenance/SBOM, SAST/CodeQL).
+- Added: **GitHub-native security** — `.github/dependabot.yml` + an advisory
+  `security.yml` workflow (dependency-review + deps-audit + CodeQL), `gh-alerts.mjs`
+  (Dependabot/code-scanning alerts → DevPipeline backlog), and a `/security-setup` command.
+- Changed: **`/deps-audit` grown into a dependency policy** — license allow/deny,
+  CycloneDX SBOM (`--sbom`), lockfile-drift, driven by a new `deps` config block.
+- Added: ROADMAP "supply-chain & code security" section (shipped) + a roadmap
+  **status convention** (`⏳ in progress` alongside `✅`/`📋`/`🟡`) in `docs/ROADMAP.md`
+  and the installed-project template `templates/vibekit/memory/roadmap.md`.
+- Added: VibeDevKit context platform scaffolded (2026-05-22).