vibe-coding-master 0.5.0 → 0.5.2

package/README.md

@@ -655,7 +655,7 @@ For every task, `taskRepoRoot` is `<baseRepoRoot>/.claude/worktrees/<task>`.
 The npm package publishes built output, not raw TypeScript entry files. `package.json` includes:
 
 - `bin.vcm`: `dist/main.js`
-- `files`: `dist`, `dist-frontend`, `docs`, `scripts`, `README.md`
+- `files`: `dist`, `dist-frontend`, `scripts`, `README.md`
 - `prepack`: `npm run build && npm run verify:package`
 
 Use this before publishing:

package/dist/backend/templates/harness/claude-root.js

@@ -6,7 +6,7 @@ export function renderRootClaudeHarnessRules() {
 - Use \`vcm-route-message\` whenever a VCM role hands off work, asks another role a question, reports a result, reports a blocker, or raises a finding. Follow its write-then-stop rule.
 - Use \`vcm-long-running-validation\` for long-running validation. Follow the background job limits below.
 - Use \`vcm-report-harness-issue\` when you notice a reusable VCM harness problem. Record feedback; do not contact Harness Engineer directly.
-- Project-manager uses \`vcm-gate-review\` at enabled Gate Review trigger points and on VCM Gate Review callbacks.
+- Project-manager runs \`vcm-gate-review\` unconditionally at every Gate Review trigger point and on VCM Gate Review callbacks; the tool reports the authoritative enable state.
 
 ## VCM Harness Scope
 

package/dist/backend/templates/harness/gate-review.js

@@ -123,7 +123,7 @@ outside the source boundary.`;
 export function renderVcmGateReviewSkillRules() {
     return `## Purpose
 
-Use this skill when project-manager reaches a VCM Gate Review or receives a VCM Gate Review callback.
+Use this skill at every project-manager Gate Review trigger point and whenever VCM sends a Gate Review callback. Running the request is mandatory and unconditional: always run the tool at each trigger point and let its output decide; do not pre-judge whether Gate Review is enabled. The tool reports the authoritative enable state.
 
 ## Trigger Points
 
@@ -133,7 +133,7 @@ Use this skill when project-manager reaches a VCM Gate Review or receives a VCM
 
 ## Request
 
-Run:
+Run this unconditionally at each trigger point (do not first check whether Gate Review is enabled):
 
 \`\`\`sh
 .ai/tools/request-gate-review --gate <architecture-plan|validation-adequacy|final-diff>
@@ -310,6 +310,16 @@ def request_id(gate: str) -> str:
 def local_request(gate: str) -> int:
     root = root_dir()
     index_path = root / ".ai/vcm/gate-reviews/index.json"
+    if not index_path.is_file():
+        # Reached only when the VCM API is unreachable (call_vcm_api returned None)
+        # AND no local index exists, so the authoritative enable state is unknown.
+        # Fail safe instead of silently treating an indeterminate state as disabled.
+        print_result(
+            "failed_to_start",
+            gate=gate,
+            reason="cannot reach VCM API and no local gate-review index; enable state is indeterminate",
+        )
+        return 2
     index = read_json(index_path)
     enabled = bool(index.get("enabled", False))
     gate_record = index.get("gates", {}).get(gate, {}) if isinstance(index.get("gates"), dict) else {}

package/dist/backend/templates/harness/project-manager-agent.js

@@ -72,11 +72,10 @@ PM may lightly rewrite the user's words to:
 
 ### Gate Review Gates
 
-- Use the \`vcm-gate-review\` skill to request a Gate Review or handle a VCM Gate Review callback.
-- If Gate Review is enabled, accept only \`approve\` or \`request_changes\`.
-- Before coder dispatch, request \`architecture-plan\`; on \`request_changes\`, route the report to architect.
-- Before docs sync or final acceptance, request \`validation-adequacy\`; on \`request_changes\`, route the report to reviewer.
-- Before PR preparation, request \`final-diff\`; on \`request_changes\`, route the report to architect for Debug Mode or Replan assessment.
+- Gate Review requests are mandatory and unconditional. At every trigger point, use the \`vcm-gate-review\` skill to run \`.ai/tools/request-gate-review --gate <gate>\` without first judging whether Gate Review is enabled. The tool (via VCM) is the single source of truth for enable state; never skip the run because you assume Gate Review is off or because the worktree has no gate-review index yet.
+- The tool's first output line decides the next step: \`disabled\`, \`not_required\`, or \`already_approved\` continue the normal VCM flow; \`started\` or \`running\` stop the turn and wait for the VCM callback; \`failed_to_start\` is a hard stop — report it to the user and do not silently proceed past the gate.
+- Trigger points (run each unconditionally): before coder dispatch run \`architecture-plan\`; before docs sync or final acceptance run \`validation-adequacy\`; before PR preparation run \`final-diff\`.
+- On a callback, accept only \`approve\` or \`request_changes\`. On \`request_changes\`, route \`architecture-plan\`/\`final-diff\` reports to architect (Debug Mode or Replan assessment) and \`validation-adequacy\` reports to reviewer.
 - Do not ask Gate Reviewer to choose owners, fixes, Replan, or user-intervention needs.
 - Record gate decision, report path, and any skip or override reason.
 

package/dist/backend/templates/harness/vcm-final-acceptance-skill.js

@@ -57,6 +57,7 @@ Check:
 - architecture plan completion, Replan, or architect follow-up decision is recorded
 - reviewer report records validation commands, results, skipped checks with reasons, and an acceptable decision
 - required Gate Reviews are approved, skipped with a recorded reason, or overridden with a recorded reason
+- Gate Review enable state is confirmed authoritatively: do not infer that no Gate Reviews were required from an absent or empty \`.ai/vcm/gate-reviews/index.json\`. When Gate Review is enabled, a missing index or a required gate without a recorded decision means the gate was skipped — run the matching \`.ai/tools/request-gate-review --gate <gate>\` (the tool is the source of truth) and do not accept until each required gate returns \`approve\`/\`already_approved\`, \`disabled\`/\`not_required\`, or a recorded skip/override
 - docs-sync report records docs updated, docs intentionally left unchanged, or required follow-up
 - known issues are either resolved, promoted to durable docs by architect, or explicitly accepted
 - temporary task state is ready to clean after durable facts are promoted

package/package.json

@@ -1,12 +1,11 @@
 {
   "name": "vibe-coding-master",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "description": "Local GUI session cockpit for Claude Code role sessions.",
   "type": "module",
   "files": [
     "dist",
     "dist-frontend",
-    "docs",
     "scripts",
     "README.md"
   ],

package/scripts/verify-package.mjs

@@ -41,7 +41,6 @@ const requiredFiles = [
 const requiredFileEntries = [
   "dist",
   "dist-frontend",
-  "docs",
   "scripts",
   "README.md"
 ];

package/docs/ARCHITECTURE.md

@@ -1,124 +0,0 @@
-# Architecture
-
-Project-level architecture for VibeCodingMaster (VCM). VCM is a single npm
-package that provides a local GUI cockpit for running and orchestrating multiple
-Claude Code role sessions around one engineering task.
-
-This document is architect-owned. It gives the project-wide module overview,
-responsibilities, relationships, dependency direction, and constraints. The
-module-level detailed design lives in [`ARCHITECTURE.md`](../ARCHITECTURE.md) at
-the repository root (the single workspace module recorded in
-`.ai/generated/module-index.json`).
-
-## Module / Layer Overview
-
-VCM is one workspace module (`vibe-coding-master`) organized into three source
-layers plus supporting tools.
-
-| Layer | Path | Responsibility |
-| --- | --- | --- |
-| Backend | `src/backend` | Fastify HTTP + WebSocket server, role/session runtime over `node-pty`, services, external adapters, mobile gateway, and the downstream harness templates. |
-| Frontend | `src/frontend` | React 19 + Vite single-page GUI: task workspace, role tabs, embedded `xterm` terminals, harness/translation panels, and client state stores. |
-| Shared | `src/shared` | Cross-layer TypeScript types, constants (role definitions, ports), and zod-backed validation helpers consumed by both backend and frontend. |
-| Tools / scripts | `.ai/tools`, `scripts` | Generated-context generators, long-running validation wrappers, bash guard, and harness install/verify scripts. |
-
-### Backend sub-areas (`src/backend`)
-
-- `api/`: Fastify route modules, one per domain (project, task, session, round,
-  message, harness, gate-review, translation, gateway, diagnostics, artifacts,
-  runtime-state, app-settings, claude-hook). Routes are thin and delegate to
-  services.
-- `services/`: business logic. Key services include `task-service`,
-  `task-launch-service` (backend-owned one-click task start, shared by the GUI
-  endpoint and the gateway), `session-service`, `round-service`,
-  `runtime-coordinator-service`, `message-service`, `harness-service`,
-  `gate-review-service`, `translation-service`/`translation-worker-service`,
-  `job-guard-service`, and `command-dispatcher`.
-- `runtime/`: PTY-backed terminal runtime (`node-pty-runtime`,
-  `terminal-runtime`, `session-registry`, `terminal-submit`) that supervises one
-  Claude Code process per role.
-- `adapters/`: side-effect boundaries — `claude-adapter`, `git-adapter`,
-  `command-runner`, `filesystem`.
-- `gateway/`: mobile gateway service plus channel implementations
-  (Weixin iLink, Lark) and command parsing.
-- `templates/`: message/handoff/role-command templates and, under
-  `templates/harness/`, the source of truth for the VCM harness that VCM installs
-  into downstream repositories.
-- `ws/`: WebSocket bridge (`terminal-ws`) streaming PTY I/O to the frontend.
-- `server.ts`, `main.ts`, `app-version.ts`, `vcm-data-dir.ts`, `errors.ts`:
-  composition root, CLI entry, version, data-dir resolution, error types.
-
-### Frontend sub-areas (`src/frontend`)
-
-- `routes/`: top-level views (`project-dashboard`, `task-workspace`).
-- `components/`: GUI building blocks (app shell, session console/toolbar, role
-  session tabs, harness panel/studio, translation panel, message timeline,
-  repo connect form, diff modal, error center).
-- `state/`: client stores and helpers (`app-store`, `session-store`,
-  `api-client`, polling schedulers, translation feed, UI error handling).
-- `terminal/`: `xterm` view and terminal websocket client.
-
-### Shared sub-areas (`src/shared`)
-
-- `types/`: domain type contracts shared across layers.
-- `validation/`: pure validators (`artifact-check`, `language-detect`,
-  `slug-check`).
-- `constants.ts`: role definitions and default ports.
-
-## Module Relationships and Dependency Direction
-
-```
-frontend  --depends on-->  shared  <--depends on--  backend
-   |                                                   ^
-   +-------- HTTP /api + WS /ws (api-client) ----------+
-```
-
-- `shared` is the leaf layer. It must not import from `backend` or `frontend`.
-- `backend` and `frontend` both depend on `shared`, and must not depend on each
-  other at the module level.
-- The only runtime coupling between frontend and backend is the HTTP `/api`
-  surface and the `/ws` WebSocket, mediated on the client by
-  `src/frontend/state/api-client.ts` and
-  `src/frontend/terminal/terminal-client.ts`.
-- Within the backend, the intended direction is
-  `api -> services -> (runtime | adapters | gateway | templates)`. Routes should
-  not contain business logic; services should reach the outside world only
-  through adapters and the runtime.
-
-## Project-Wide Constraints
-
-- Single npm package, ESM only, TypeScript strict mode. Node `^20 || >=22`.
-- Keep the layer boundary: no `shared -> backend/frontend` imports, no direct
-  `frontend <-> backend` imports.
-- Backend and frontend compile under separate tsconfigs
-  (`tsconfig.node.json`, `tsconfig.json`); new files must fall inside the correct
-  `include` globs, and `npm run typecheck` must pass both.
-- Downstream harness behavior is defined by `src/backend/templates/harness/**`;
-  change harness output there, not in generated target-repo files.
-- Long-running and background process rules from the VCM managed block in
-  `CLAUDE.md` apply; never detach processes.
-- The npm package ships only built artifacts (`dist`, `dist-frontend`, `docs`,
-  `scripts`, `README.md`).
-
-## Generated Context Ownership
-
-Generated indexes under `.ai/generated/` are machine-maintained and regenerated
-by the tools in `.ai/tools/`:
-
-- `.ai/generated/module-index.json` — produced by
-  `.ai/tools/generate-module-index`. Maps the workspace to layers, modules,
-  manifests, module docs, source files, and test files. Use it to locate code and
-  confirm module boundaries.
-- `.ai/generated/public-surface.json` — produced by
-  `.ai/tools/generate-public-surface` (after `module-index.json` exists). It is the
-  authoritative machine index of module-to-module public APIs, routes, and
-  externally consumed surfaces. Treat it as the full public-surface listing;
-  module docs explain meaning and design intent rather than duplicating it.
-
-Regenerate both after changing module layout, public exports, or HTTP routes.
-
-## Module-Level Architecture Docs
-
-- Root module: [`ARCHITECTURE.md`](../ARCHITECTURE.md) — detailed design,
-  boundaries, behavior, public surface explanation, risks, and update triggers
-  for the `vibe-coding-master` workspace module.

package/docs/TESTING.md

@@ -1,130 +0,0 @@
-# Testing
-
-Reviewer-owned validation strategy for VibeCodingMaster (VCM). This document maps
-the VCM validation levels to project-native commands, where tests live, how to
-select what to run, and the current testing gaps.
-
-## Validation Levels and Commands
-
-All commands run from the repository root (the task worktree during a VCM task).
-
-| Level | Scope | Command(s) |
-| --- | --- | --- |
-| L0 fast checks | Format/lint/typecheck/boundary. Project ships typecheck across both tsconfigs. | `npm run typecheck` |
-| L1 coder unit checks | Changed behavior + direct regressions via Vitest unit tests. | `npm test` (optionally a scoped `npx vitest run <path>`) |
-| L2 module / integration checks | Module/API/runtime wiring. Vitest config reserves `tests/integration/api/**` and `tests/integration/runtime/**`. | `npm test` (runs unit + any integration tests that exist) |
-| L3 smoke E2E checks | Core GUI journeys via Playwright. | `npm run e2e` |
-| L4 full regression / release | Build + package verification before publish. | `npm run build` then `npm run verify:package` |
-
-Notes:
-
-- `npm run typecheck` runs `tsc` against both `tsconfig.json` (frontend + shared)
-  and `tsconfig.node.json` (backend), so it is the boundary/type gate for the
-  whole module.
-- `npm test` is `vitest run`. Its `include` globs already cover unit and the
-  reserved integration directories, so a single `npm test` is both L1 and L2 once
-  integration tests exist.
-- `npm run e2e` is `playwright test` against `tests/e2e`, and its `webServer`
-  starts `npm run dev` automatically (reusing an existing server if one is up).
-
-## Validation Selection Rules
-
-- Docs-only or comment-only change: L0 (`npm run typecheck`) is usually enough; no
-  code behavior to retest.
-- `src/shared/**` change: always L0 + L1, because shared types/validators are
-  cross-cutting to both backend and frontend.
-- `src/backend/**` change: L0 + the affected `tests/unit/backend/**` files; run
-  full `npm test` before handoff. Add L2 when touching runtime, routes, or
-  cross-service wiring.
-- `src/frontend/**` change: L0 + the affected `tests/unit/frontend/**` files; add
-  L3 (`npm run e2e`) when changing a core user journey (connect repo, create task,
-  start/resume a role session, send a message, translation panel).
-- `src/backend/templates/harness/**` change: L0 + `npm test` (harness template
-  sync and harness service/route tests guard these), because output ships into
-  downstream repos.
-- `.ai/tools/**` or `scripts/harness-tools/**` change: run
-  `tests/unit/backend/harness-tools.test.ts` and `vcm-bash-guard.test.ts`.
-- Pre-publish / release: L4 (`npm run build` + `npm run verify:package`).
-
-## Long-Running Validation
-
-Use the `vcm-long-running-validation` skill (`.ai/tools/run-long-check` +
-`.ai/tools/watch-job`) for any command that may exceed ~2 minutes (notably
-`npm run e2e` and full builds). Never run validation as a detached/background
-process; the job guard denies it. Honor the 60-minute per-job ceiling.
-
-## Test Layout
-
-```
-tests/
-  unit/
-    backend/   # services, routes, runtime, adapters, gateway, harness, tools
-    frontend/  # api-client, stores, components (message timeline, harness panel, translation panel)
-    shared/    # pure validators (artifact-check, language-detect, slug-check)
-  integration/ # reserved by vitest config: api/**, runtime/** (not yet present)
-  e2e/         # reserved by playwright config (not yet present)
-```
-
-- Place unit tests next to their layer under `tests/unit/<layer>/` named
-  `<subject>.test.ts`.
-- Place integration tests under `tests/integration/api/**` or
-  `tests/integration/runtime/**` so the existing Vitest `include` picks them up.
-- Place Playwright specs under `tests/e2e/`.
-
-## Integration / E2E Case List
-
-These are reserved by configuration but not yet implemented. They are the
-recommended first cases when integration/E2E coverage is added.
-
-### Integration (reserved: `tests/integration/api/**`, `tests/integration/runtime/**`)
-
-| ID | Scenario | Entry point | Proves | Key assertions | When to run | Limitation |
-| --- | --- | --- | --- | --- | --- | --- |
-| INT-API-001 | Project + task lifecycle over HTTP | Fastify app via `project-routes` / `task-routes` | Routes + services persist task state correctly | Create project, create task, read back task, status transitions | L2, on backend api/service change | Not yet implemented |
-| INT-API-002 | Message bus round trip | `message-routes` / `message-service` | Route-file dispatch and history persistence | Posted message is persisted and retrievable in order | L2, on messaging change | Not yet implemented |
-| INT-RT-001 | Session start/resume lifecycle | `runtime-coordinator-service` + `session-registry` | PTY session can start, persist id, and resume | Session id persisted; resume reuses id; stop cleans registry | L2, on runtime change | Not yet implemented; needs `claude`/pty test doubles |
-
-### E2E (reserved: `tests/e2e/`)
-
-| ID | Scenario | Entry point | Proves | Key assertions | When to run | Limitation |
-| --- | --- | --- | --- | --- | --- | --- |
-| E2E-001 | Connect repository and create a task | GUI at `http://127.0.0.1:5173` | Core onboarding journey works end to end | Repo connects, branch/status render, task appears in list | L3, before release / on shell or routing change | Not yet implemented; requires a real `claude` binary for live sessions |
-| E2E-002 | Start a role session and observe terminal output | Task workspace role tabs | Embedded terminal streams PTY output over `/ws` | Session starts, xterm receives output, status badge updates | L3, on runtime/terminal change | Not yet implemented; environment-dependent |
-| E2E-003 | Translation panel renders translated transcript | Translation panel | Translator session reads transcript JSONL and renders | Panel shows translated entries without mutating handoffs | L3, on translation change | Not yet implemented |
-| E2E-004 | Auto-orchestration journey (one-click → auto-follow → flow-pause) | GUI task workspace, auto mode | The relocated backend-owned orchestration drives the GUI end to end | One-click starts the roster via `POST /api/tasks/:slug/one-click-start`; the role tab follows `roundState.activeRole`; a stopped round with no next turn raises the `roundState.flowPause` notice | L3, on one-click/round/role-follow change | Not yet implemented; needs a Playwright harness + live `claude`/pty. Until then the three contracts are covered at integration level: task-routes inject + gateway inbound (P1), active-role-follow + app wiring (P2), round-service flowPause matrix + flow-pause-alert (P3) |
-
-## Generated-Context Freshness Checks
-
-- Regenerate `.ai/generated/module-index.json` with `.ai/tools/generate-module-index`
-  after adding/removing/moving modules, source files, or test files.
-- Regenerate `.ai/generated/public-surface.json` with
-  `.ai/tools/generate-public-surface` (after module-index exists) after changing
-  exported APIs, HTTP routes, or shared types.
-- Treat stale generated indexes as a validation failure during review: if a
-  source/route/export change is not reflected in the indexes, regenerate before
-  acceptance.
-
-## Final-Validation Cleanup
-
-- Remove temporary scripts, scratch files, and any test-only fixtures created
-  during investigation before final acceptance.
-- Do not leave `.only`/`.skip` in committed Vitest or Playwright specs.
-- Ensure no detached/background validation jobs remain running.
-- Confirm generated indexes are regenerated and committed when source/surface
-  changed.
-- Before publish, `npm run build` and `npm run verify:package` must pass.
-
-## Known Testing Gaps
-
-- No integration tests exist yet; `tests/integration/**` is configured but empty.
-- No E2E tests exist yet; `tests/e2e/**` is configured (Playwright) but empty.
-- E2E and live runtime tests depend on a real `claude` binary and `node-pty`,
-  which are environment-sensitive and not currently stubbed for CI.
-- There is no lint command in `package.json`; L0 is currently typecheck-only.
-- Coverage thresholds are not enforced by configuration.
-- `tests/unit/backend/harness-templates-sync.test.ts` shells out to
-  `scripts/install-vcm-harness.mjs`, which needs the compiled CLI (`dist/main.js`).
-  On a clean checkout with no `dist/`, those 3 cases fail with
-  "compiled CLI not found. Run npm run build first." Run `npm run build` before
-  `npm test` (or treat these specific failures as build-state, not regressions)
-  when validating from a clean tree.