vibe-coding-master 0.3.1 → 0.3.2

package/README.md

@@ -163,7 +163,7 @@ The recommended flow is:
 
 ```text
 project-manager
-  -> architect architecture plan and code scaffolding
+  -> architect architecture plan, Scaffold Manifest, and code scaffolding
   -> coder implementation and baseline unit checks
   -> reviewer independent validation
   -> architect docs sync / architecture drift check

package/dist/backend/services/codex-review-service.js

@@ -537,7 +537,7 @@ async function computeInputHash(deps, taskRepoRoot, gate) {
             digest.update("<missing>");
         }
     }
-    if (gate === "final-diff") {
+    if (gate === "architecture-plan" || gate === "final-diff") {
         digest.update(await commandStdout(deps.runner, taskRepoRoot, ["status", "--porcelain=v1"]));
         digest.update(await commandStdout(deps.runner, taskRepoRoot, ["diff", "--binary"]));
         digest.update(await commandStdout(deps.runner, taskRepoRoot, ["diff", "--cached", "--binary"]));

package/dist/backend/templates/handoff.js

@@ -9,6 +9,16 @@ TBD
 
 TBD
 
+## Scaffold Manifest
+
+Task-specific context and coder guidance go here, not in source-code comments.
+Source-code comments should only describe durable behavior, contracts, invariants,
+error boundaries, or non-obvious logic that should remain useful after this task.
+
+| File | Action | Task Context | Durable Code Comment Needed | Coder Work | Allowed Freedom | VCM:CODE | Proof Point | Replan Trigger |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| TBD | TBD | TBD | TBD | TBD | TBD | TBD | TBD | TBD |
+
 ## Implementation Plan
 
 TBD

package/dist/backend/templates/harness/architect-agent.js

@@ -21,24 +21,28 @@ export function renderArchitectHarnessRules() {
 
 ### Architecture Plan
 
-- Before coder work starts, write \`.ai/vcm/handoffs/architecture-plan.md\` and materialize the plan in code scaffolding.
+- Before coder work starts, write \`.ai/vcm/handoffs/architecture-plan.md\`, choose the minimum necessary code scaffolding, and include a Scaffold Manifest for task-specific context and coder guidance.
 
 #### Plan Document
 
 - Define the expected implementation scope: affected modules, changed or created files, each file's responsibility, why it is in scope, and user-visible behavior changes.
 - Define every non-private callable surface intended for use outside its file: visibility, signature shape, responsibility, expected callers, behavior contract, side effects, and error boundaries.
+- Include a \`Scaffold Manifest\` for task-specific file context: file action, why the file is in scope, coder work, allowed implementation freedom, expected \`VCM:CODE\` placeholders, durable code comment needs, proof points, and Replan triggers.
+- Put task context, phase notes, handoff instructions, temporary rationale, and coder guidance in the \`Scaffold Manifest\`, not in source-code comments.
 - Cover architecture docs impact, known risks, and Replan triggers.
 - For docs impact, state whether changes belong in \`docs/ARCHITECTURE.md\`, affected \`<module>/ARCHITECTURE.md\`, \`.ai/generated/public-surface.json\`, or no durable architecture doc.
 
 #### Code Scaffolding
 
-- Create or update module/file scaffolding so file responsibilities, logic boundaries, collaborators, and non-goals are documented in code.
-- When changing an existing file, update only the affected in-code scaffold: responsibility, boundary, collaborators, non-goals, or callable surfaces; do not rewrite unrelated file comments.
+- Create or update only the minimum module/file scaffolding needed to make boundaries, callable surfaces, and placeholders unambiguous.
+- Source-code comments must describe durable behavior, contracts, invariants, error boundaries, or non-obvious logic that should remain useful after the task is complete.
+- Do not put task-specific context, phase notes, handoff instructions, temporary plan rationale, or coder guidance in source-code comments.
+- When changing an existing file, update only affected durable comments or callable surfaces; do not rewrite unrelated file comments.
 - Define every new or changed non-private callable surface directly in code with its signature shape and contract comment.
 - When changing an existing non-private callable surface, update its signature and contract comment in code before coder work starts; leave \`VCM:CODE\` only where implementation must change.
 - Non-private callable surface includes any function, method, type, trait, enum, constant, re-export, or similar symbol that another file can call or depend on.
 - Mark incomplete implementation bodies with \`VCM:CODE\`; coder must implement them and remove the markers before handoff.
-- Architect scaffolding may include modules, files, signatures, type shapes, comments, and placeholder bodies, but not real business implementation beyond minimal scaffold code.
+- Architect scaffolding may include modules, files, signatures, type shapes, durable comments, and placeholder bodies, but not real business implementation beyond minimal scaffold code.
 - Coder may add private implementation helpers, but must not add or change cross-file callable surface without architect replan.
 
 ### Phase Planning

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

@@ -27,7 +27,7 @@ export function renderRootClaudeHarnessRules() {
 ## VCM Task Flow
 
 - Code changes use the full route: \`project-manager -> architect -> coder -> reviewer -> architect docs sync -> project-manager final acceptance\`.
-- Before code changes, architect must write an architecture plan and code scaffolding that cover file responsibilities, cross-file callable surfaces, user-visible behavior, docs impact, risks, and Replan triggers.
+- Before code changes, architect must write an architecture plan with a Scaffold Manifest and minimum necessary code scaffolding that cover file responsibilities, cross-file callable surfaces, user-visible behavior, docs impact, risks, and Replan triggers.
 - Docs-only changes may use: \`project-manager -> architect -> project-manager final acceptance\`.
 - Test-only or validation-only work may use: \`project-manager -> reviewer -> project-manager final acceptance\`.
 - If a docs/test/validation-only task reveals required code, architecture, public contract, dependency, durable-doc, or test-strategy changes, route back through the full code-change flow.

package/dist/backend/templates/harness/coder-agent.js

@@ -14,7 +14,7 @@ export function renderCoderHarnessRules() {
 - Do not fake completion: no hardcoded success, disabled logic, swallowed errors, test-only shortcuts, or silent fallback that hides failure.
 - Keep the diff inside approved scope: no unrelated rewrites, drive-by refactors, renamed symbols, moved files, or formatting churn.
 - Preserve existing behavior unless the architecture plan explicitly changes it; keep existing call sites and shared code paths working.
-- Maintain code documentation: preserve architect-written comments, add comments for non-obvious implementation logic, remove stale/debug/TODO comments, and keep code and comments consistent.
+- Maintain code documentation: preserve durable architect-written contract comments, do not copy Scaffold Manifest task context into source comments, add comments only for non-obvious durable logic, remove stale/debug/TODO/task-process comments, and keep code and comments consistent.
 
 ### General Coding Standards
 

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

@@ -31,10 +31,12 @@ Check that the plan:
 - matches the user request and approved scope
 - names affected modules/files, file responsibilities, and user-visible changes
 - defines new or changed non-private callable surfaces: visibility, signature shape, callers, contract, side effects, and error boundaries
+- includes a Scaffold Manifest that carries task-specific context, coder guidance, allowed freedom, expected \`VCM:CODE\`, durable code comment needs, proof points, and Replan triggers
 - preserves dependency direction and avoids unapproved dependencies
 - states docs/generated-context impact or explains why none is needed
 - names risks, proof points, phase boundaries when needed, and Replan triggers
 - uses \`VCM:CODE\` for incomplete implementation and leaves no coder ambiguity
+- keeps task-specific context, phase notes, handoff instructions, and coder guidance out of source-code comments
 - does not take over reviewer-owned validation strategy or test adequacy
 
 ### Validation Adequacy
@@ -56,6 +58,7 @@ Check that the final diff:
 - stays inside the approved plan, phase, and user constraints
 - introduces no unapproved modules, dependencies, public contracts, cross-file callable surfaces, or durable-doc changes
 - removes all \`VCM:CODE\` markers
+- leaves no task-specific process comments in source or test code, such as role handoff notes, phase notes, current-task rationale, or coder instructions
 - contains no fake completion: hardcoded success, disabled logic, swallowed errors, test-only shortcuts, or silent fallback hiding failure
 - preserves existing behavior unless the plan changes it
 - keeps changed functions focused and meaningfully named
@@ -161,6 +164,7 @@ Review whether the architecture plan is ready for coder implementation.
 - \`../../.claude/agents/coder.md\`
 - \`../../.claude/agents/reviewer.md\`
 - \`../../.ai/vcm/handoffs/architecture-plan.md\`
+- current git status and scaffold diff from \`../..\`
 - \`../../.ai/generated/module-index.json\`
 - \`../../.ai/generated/public-surface.json\`
 

package/dist/backend/templates/harness/reviewer-agent.js

@@ -23,6 +23,7 @@ export function renderReviewerHarnessRules() {
 - Record failed commands, observed behavior, expected behavior, reproduction steps, skipped checks, and coverage gaps.
 - If validation fails or expected behavior is unclear, report the evidence to project-manager; architect owns diagnosis and next-step routing.
 - Add or modify tests, fixtures, or test helpers needed for validation confidence.
+- If task-specific process comments appear in changed code while reviewing behavior, report them as a maintainability gap; task context belongs in handoff artifacts, not durable code comments.
 - Update \`docs/TESTING.md\` when validation strategy, commands, level mapping, integration/E2E case definitions, selection rules, final-validation cleanup, test gaps, or test expectations change.
 
 ### Testing Documentation

package/dist/shared/validation/artifact-check.js

@@ -2,6 +2,7 @@ const REQUIRED_HEADINGS = {
     "architecture-plan": [
         "Context",
         "Architecture Decision",
+        "Scaffold Manifest",
         "Implementation Plan",
         "Risks",
         "Stop Conditions"

package/docs/cc-best-practices.md

@@ -904,6 +904,7 @@ Handoff artifact schemas:
 ## Architecture Summary
 ## Task Classification
 ## Required Role Route
+## Scaffold Manifest
 ## Modules / Files
 ## File Responsibilities
 ## Public Surface Contract

package/docs/codex-review-gates.md

@@ -123,6 +123,7 @@ Recommended inputs:
 - original user request
 - project-manager route message or durable task plan when present
 - architecture plan
+- Scaffold Manifest and any architect-created scaffold diff
 - relevant durable architecture docs
 - `docs/TESTING.md` when the plan depends on validation strategy
 - changed file list when architect created scaffolding
@@ -132,6 +133,8 @@ Codex should review whether:
 - the plan matches the user request
 - the architecture boundaries are clear and compatible with the existing repo
 - file responsibilities and public contracts are specific enough for coder
+- the Scaffold Manifest carries task-specific context and coder guidance instead
+  of putting that information in source-code comments
 - the plan avoids unnecessary scope expansion
 - risks, dependencies, migrations, permissions, data, and error paths are named
 - acceptance and validation evidence can be produced
@@ -215,6 +218,8 @@ Codex should review whether:
 - the final diff satisfies the user request
 - the implementation contains correctness bugs or behavior regressions
 - the code follows existing project conventions
+- source and test comments contain no task-specific process notes, phase notes,
+  current-task rationale, or coder instructions
 - tests and implementation remain aligned
 - durable docs and generated artifacts are consistent with the diff
 - files outside the expected scope are explained

package/docs/full-harness-baseline.md

@@ -81,7 +81,7 @@ These entries match the current `example/rust-layered/.ai/vcm-harness-manifest.j
 | Claude settings | `.claude/settings.json` | json-merge | Long-term | VCM owns hook entries matching VCM command markers. |
 | Agent directory | `.claude/agents/` | VCM-created directory | Long-term | Contains the four core VCM role agents. |
 | Core agent | `.claude/agents/project-manager.md` | managed-block | Long-term | Project-manager role rules. |
-| Core agent | `.claude/agents/architect.md` | managed-block | Long-term | Architect role rules: plan document, code scaffolding, Debug Mode, docs sync. |
+| Core agent | `.claude/agents/architect.md` | managed-block | Long-term | Architect role rules: plan document, Scaffold Manifest, code scaffolding, Debug Mode, docs sync. |
 | Core agent | `.claude/agents/coder.md` | managed-block | Long-term | Coder role rules: scaffold implementation, coding standards, baseline unit checks. |
 | Core agent | `.claude/agents/reviewer.md` | managed-block | Long-term | Reviewer role rules: independent validation, TESTING.md strategy, integration/E2E case lists. |
 | Skill directory | `.claude/skills/` | VCM-created directory | Conditional long-term | Keep while repo-local VCM skills are installed. |

package/docs/product-design.md

@@ -75,7 +75,7 @@ Recommended flow:
 
 ```text
 project-manager
-  -> architect architecture plan and code scaffolding
+  -> architect architecture plan, Scaffold Manifest, and code scaffolding
   -> coder implementation and baseline unit checks
   -> reviewer independent validation
   -> architect docs sync / architecture drift check
@@ -219,6 +219,7 @@ The project manager must not become the architect, coder, reviewer, or debugger
 The architect owns:
 
 - architecture plan
+- Scaffold Manifest for task-specific file context and coder guidance
 - module boundaries
 - file responsibilities
 - cross-file callable surfaces and contract comments

package/docs/vcm-cc-best-practices.md

@@ -194,8 +194,9 @@ VCM uses four core roles:
 - `architect`: technical planner and docs-sync owner. It defines module/file
   responsibilities, cross-file callable surfaces, public contracts, phase
   boundaries, risks, and durable docs updates. Before coder work starts,
-  architect writes the plan and materializes it in code scaffolding with
-  contract comments and `VCM:CODE` placeholders.
+  architect writes the plan with a Scaffold Manifest and materializes only the
+  minimum necessary code scaffolding with durable contract comments and
+  `VCM:CODE` placeholders.
 - `coder`: implementation owner. It changes production code and baseline unit
   tests within the approved plan. It follows the architect-defined scaffold,
   implements and removes `VCM:CODE` placeholders, follows general coding
@@ -240,19 +241,28 @@ workload or context size is not a valid reason to change the architect plan.
 ## 7.1 Architecture Plan And Code Scaffolding
 
 For code changes, the architect plan is not only a markdown handoff. It is a
-plan document plus code scaffolding.
+plan document plus a Scaffold Manifest and the minimum necessary code
+scaffolding.
 
 The plan document defines affected modules, changed or created files, file
 responsibilities, why each file is in scope, user-visible behavior changes,
 non-private cross-file callable surfaces, docs impact, risks, and Replan
 triggers.
 
+The Scaffold Manifest carries task-specific file context for the current handoff:
+why a file is in scope, what coder should implement, allowed implementation
+freedom, expected `VCM:CODE` placeholders, durable code comment needs, proof
+points, and Replan triggers. Task context, phase notes, handoff instructions,
+temporary rationale, and coder guidance belong in the Scaffold Manifest, not in
+source-code comments.
+
 Code scaffolding materializes that plan in the repository before coder work
 starts:
 
 - new modules or files are created when needed
-- file-level responsibilities, logic boundaries, collaborators, and non-goals
-  are documented in code
+- durable behavior, contracts, invariants, error boundaries, or non-obvious
+  logic are documented in code only when they should remain useful after the
+  task is complete
 - new or changed non-private callable surfaces are defined directly in code with
   signature shape and contract comments
 - incomplete implementation bodies are marked with `VCM:CODE`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vibe-coding-master",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "Local GUI session cockpit for Claude Code role sessions.",
   "type": "module",
   "files": [