vibe-coding-master 0.0.17 → 0.2.0

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

@@ -0,0 +1,105 @@
+export function renderVcmFinalAcceptanceSkillRules() {
+    return `## Purpose
+
+Use this skill when project-manager is ready to decide whether a VCM-managed task can be accepted, returned for follow-up, or blocked for a decision.
+
+This skill is a final evidence audit. It does not replace architect docs sync, reviewer acceptance, validation, or user approval for high-risk decisions.
+
+## Required Inputs
+
+Read the relevant task evidence before deciding:
+
+- route messages or durable plan
+- \`.ai/vcm/handoffs/architecture-plan.md\`
+- \`.ai/vcm/handoffs/known-issues.md\`
+- \`.ai/vcm/handoffs/review-report.md\`
+- \`.ai/vcm/handoffs/docs-sync-report.md\`
+- current \`git status\` and \`git diff\`
+- relevant long-term docs when the task touched public behavior, architecture, tests, security, dependencies, or plans
+
+## Scope Traceability Audit
+
+Do not claim to prove that the diff is exactly equal to the task scope.
+
+Instead, classify changed files and meaningful hunks:
+
+- expected changes: directly named by the user request, durable plan, route message, or architecture plan
+- supporting changes: tests, fixtures, types, docs, or wiring needed for expected changes
+- approved deviations: changes explained by Replan, reviewer follow-up, or explicit user / project-manager approval
+- unexplained changes: changes with no traceable reason in the task evidence
+- high-risk unexpected changes: auth, permissions, payment, billing, schema, migrations, data deletion, secrets, generated artifacts, dependencies, lockfiles, or broad formatting churn
+
+Unexplained changes must be explained, reverted, or routed for follow-up before normal acceptance.
+
+High-risk unexpected changes require project-manager / user approval or Replan before acceptance.
+
+## Acceptance Checks
+
+Check:
+
+- required route was followed, or a user-approved exception is recorded
+- required handoff artifacts exist and are current
+- architecture plan was followed, or Replan was approved
+- reviewer decision is acceptable, or findings are routed for follow-up
+- docs sync is complete, or docs intentionally left unchanged are justified
+- task-local known issues were resolved, promoted to \`docs/known-issues.md\`, or explicitly left out with a reason
+- public behavior has direct tests or a recorded exception
+- tests were not weakened, deleted, or skipped just to pass
+- temporary task state is ready to clean after durable facts are promoted
+
+## Decisions
+
+Choose exactly one:
+
+- accepted
+- accepted-with-known-risks
+- needs-coder-follow-up
+- needs-architect-replan
+- needs-docs-sync
+- blocked-by-user-decision
+
+Do not accept when validation evidence is missing, reviewer findings are unresolved, docs sync is missing for durable changes, or unexplained high-risk changes remain.
+
+## Output
+
+Write or update:
+
+\`\`\`text
+.ai/vcm/handoffs/final-acceptance.md
+\`\`\`
+
+Use this structure:
+
+\`\`\`md
+# Final Acceptance: <task>
+
+## Decision
+
+accepted | accepted-with-known-risks | needs-coder-follow-up | needs-architect-replan | needs-docs-sync | blocked-by-user-decision
+
+## Evidence Reviewed
+
+## Scope Traceability
+
+### Expected Changes
+
+### Supporting Changes
+
+### Approved Deviations
+
+### Unexplained Changes
+
+### High-Risk Unexpected Changes
+
+## Validation Summary
+
+## Review And Docs Sync
+
+## Cleanup Readiness
+
+## Final User Summary
+\`\`\`
+
+The final user summary should be concise and include files changed, validation, docs updates, open risks, and next action.
+`;
+}

package/dist/backend/templates/harness/vcm-harness-bootstrap-skill.js

@@ -0,0 +1,78 @@
+export function renderVcmHarnessBootstrapSkillRules() {
+    return `## Purpose
+
+Use this skill when VCM needs AI-assisted project understanding to finish or refresh project-specific harness content.
+
+This skill is an operating procedure. It does not replace the deterministic VCM installer.
+
+## Boundaries
+
+- Read the repository before drafting project-specific harness content.
+- Do not edit product source, product tests, package manifests, lockfiles, deployment config, or secrets.
+- Do not own managed-block writes, hook merging, manifest migrations, uninstall behavior, or deterministic skeleton creation; VCM backend owns those.
+- Do not create new validation wrapper tools during bootstrap.
+
+## Procedure
+
+1. Generate context when supported: run \`.ai/tools/generate-module-index\`, then run \`.ai/tools/generate-public-surface\` after \`module-index.json\` exists.
+2. Inspect the project:  read \`README.md\`, read \`CLAUDE.md\`, durable project docs, project manifests/config, source layout, tests, and existing validation commands.
+3. Fill project context: add or update non-managed project facts in \`CLAUDE.md\` above the VCM managed block.
+4. Fill durable docs: update \`docs/ARCHITECTURE.md\`, module-level \`ARCHITECTURE.md\` files, and \`docs/TESTING.md\` with detailed project-specific content.
+5. Preserve user-authored content and VCM managed blocks.
+6. Report evidence, unknowns, confirmation-needed areas, generation failures, and recommended deterministic VCM actions.
+
+## Typical Outputs
+
+- \`CLAUDE.md\` project context and project constraints outside the VCM managed block
+- \`docs/ARCHITECTURE.md\`
+- \`docs/TESTING.md\`
+- \`docs/known-issues.md\` only for confirmed durable issues
+- module-level \`ARCHITECTURE.md\` files
+- \`.ai/generated/module-index.json\`
+- \`.ai/generated/public-surface.json\`
+
+## Output Requirements
+
+### \`CLAUDE.md\`
+
+- Write only project-specific facts outside the VCM managed block.
+- Include project type, architecture shape, important constraints, and local conventions when verified or strongly inferred.
+- Do not edit, duplicate, or summarize the VCM managed block.
+
+### Generated Context
+
+- Run \`.ai/tools/generate-module-index\` when the generator exists and the project is supported.
+- Run \`.ai/tools/generate-public-surface\` only after \`.ai/generated/module-index.json\` exists.
+- If generation fails or the project is unsupported, report the reason. Do not invent generated artifacts.
+
+### \`docs/ARCHITECTURE.md\`
+
+- Document the project-level module overview, module responsibilities, module relationships, dependency direction, and project-wide constraints.
+- Link to module-level \`ARCHITECTURE.md\` files when present.
+- Explain generated-context ownership, especially that \`.ai/generated/public-surface.json\` is the machine index for crate-external public APIs.
+
+### Module-Level \`ARCHITECTURE.md\`
+
+- Create or update one module-level \`ARCHITECTURE.md\` for each clear module boundary.
+- Document module boundaries, responsibilities, allowed dependencies, important behavior, important public surface explanations, risks, and update triggers.
+- Keep complete public API listings in \`.ai/generated/public-surface.json\`; module docs should explain meaning and design intent, not duplicate the full generated index.
+
+### \`docs/TESTING.md\`
+
+- Document validation levels, project-native validation commands, unit/integration test placement, generated-context freshness checks, and known testing gaps.
+- Keep reviewer ownership of validation strategy and testing documentation clear.
+
+## Final Summary
+
+Include:
+
+- files reviewed
+- files drafted or updated
+- verified claims
+- inferred claims
+- unknowns
+- needs human confirmation
+- suggested validation commands
+- recommended next harness steps
+`;
+}

package/dist/backend/templates/harness/vcm-long-running-validation-skill.js

@@ -0,0 +1,50 @@
+export function renderVcmLongRunningValidationSkillRules() {
+    return `## Rule
+
+Do not end the current turn only to wait for a long-running shell callback.
+
+Use a bounded file-backed job instead.
+
+## Protocol
+
+1. Start the command through \`.ai/tools/run-long-check\`.
+2. Write job state under \`.ai/vcm/jobs/<job-id>/\`.
+3. Run \`.ai/tools/watch-job <job-id> --timeout <duration>\` in the same turn.
+4. Treat success, failure, and timeout as explicit results.
+5. Read the final status and relevant log tail.
+6. Record command, result, duration, and required follow-up wherever the caller normally records command evidence.
+
+Example:
+
+\`\`\`bash
+.ai/tools/run-long-check -- cargo test --workspace
+.ai/tools/watch-job <job-id> --timeout 20m
+\`\`\`
+
+## Job Files
+
+\`\`\`text
+.ai/vcm/jobs/<job-id>/command.json
+.ai/vcm/jobs/<job-id>/status.json
+.ai/vcm/jobs/<job-id>/stdout.log
+.ai/vcm/jobs/<job-id>/stderr.log
+\`\`\`
+
+## Timeout
+
+Timeout is not "unknown". It is a command result.
+
+On timeout:
+
+- summarize the latest log tail
+- record the timeout in \`status.json\`
+- report whether the timed-out process was stopped
+- do not mark the command as passed
+
+\`watch-job\` should attempt to stop the timed-out command process group. If termination cannot be confirmed, say so in the summary.
+
+## Cleanup
+
+\`.ai/vcm/jobs/**\` is runtime state. Delete it after the command result and useful log evidence have been recorded where needed.
+`;
+}

package/dist/backend/templates/harness/vcm-route-message-skill.js

@@ -0,0 +1,86 @@
+export function renderVcmRouteMessageSkillRules() {
+    return `## Purpose
+
+Use this skill when a VCM role needs to hand work, ask a question, report a result, report a blocker, or raise a finding to another VCM role.
+
+This skill writes a route file. It does not deliver the message. VCM backend delivery is triggered later by Claude Code hooks.
+
+## Route Policy
+
+Use only routes allowed by the current VCM role rules and task approval.
+
+Allowed message types:
+
+- task
+- question
+- revise
+- cancel
+- result
+- blocked
+- finding
+
+## Route File
+
+Write or update exactly one file:
+
+\`\`\`text
+.ai/vcm/handoffs/messages/<from-role>-<to-role>.md
+\`\`\`
+
+The file name is authoritative. Do not put from/to in frontmatter and do not create alternate message paths.
+
+If the same route file already contains a not-yet-delivered message, update that file instead of creating a fragmented follow-up.
+
+## Message Format
+
+\`\`\`md
+---
+type: task
+artifact_refs:
+  - .ai/vcm/handoffs/architecture-plan.md
+  - docs/plans/example.md
+---
+
+Summary:
+...
+
+Request or result:
+...
+
+Evidence:
+...
+
+Expected next action:
+...
+\`\`\`
+
+Use the smallest body that is complete. Include artifact refs instead of copying long documents.
+
+## Required Body Content
+
+- why this message exists
+- what the target role should do or what result is being reported
+- source of truth or artifact references
+- validation or documentation state when relevant
+- blocker, decision needed, or next step when relevant
+
+## Turn Rule
+
+After writing or updating the route file, end the current Claude Code turn immediately.
+
+Do not:
+
+- send another message to the same target role in the same turn
+- poll route files
+- start a shell loop
+- wait for another role's answer
+- paste directly into another role terminal
+- use Claude Code Task/Subagent for VCM role delegation
+
+VCM scans pending route files after the Stop hook and delivers later replies in a new turn.
+
+## Recovery
+
+If delivery is manual, blocked, or the target role is busy, leave the route file non-empty. Do not clear it yourself unless the user or VCM controller has explicitly confirmed manual handling.
+`;
+}

package/dist/backend/templates/message-envelope.js

@@ -20,6 +20,7 @@ ${artifactRefs}
 
 Instructions:
 - Read the message and execute only within this VCM task.
+- If you write or update a VCM route file, use the vcm-route-message skill.
 - If you need to send a VCM message after handling this, write or update .ai/vcm/handoffs/messages/<your-role>-<target-role>.md.
 - Non-PM roles reply only to project-manager, for example ${routeFileExample}.
 - After writing a route file, end this Claude Code turn immediately.

package/dist/backend/templates/role-command.js

@@ -1,6 +1,12 @@
-export function renderRoleCommandTemplate(taskSlug, role) {
+export function renderRoleCommandTemplate(taskSlug, role, taskRepoRoot = "$VCM_TASK_REPO_ROOT", branch = "TBD") {
     return `# ${role} command for ${taskSlug}
 
+## Worktree
+
+Task repo root: ${taskRepoRoot}
+Branch: ${branch}
+Rule: only edit files under Task repo root.
+
 ## Objective
 
 TBD

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

@@ -6,15 +6,9 @@ const REQUIRED_HEADINGS = {
         "Risks",
         "Stop Conditions"
     ],
-    "implementation-log": [
-        "Summary",
-        "Files Changed",
-        "Validation",
-        "Deviations From Architecture Plan",
-        "Follow-ups"
-    ],
-    "validation-log": [
-        "Validation"
+    "known-issues": [
+        "Task Issues",
+        "Escalation To Docs"
     ],
     "review-report": [
         "Summary",
@@ -29,7 +23,18 @@ const REQUIRED_HEADINGS = {
         "Docs Reviewed And Left Unchanged",
         "Public Contract / Module Boundary Notes",
         "Remaining Documentation Risks",
+        "Known Issues Disposition",
         "Decision"
+    ],
+    "final-acceptance": [
+        "Decision",
+        "Evidence Reviewed",
+        "Scope Traceability",
+        "Validation Summary",
+        "Review And Docs Sync",
+        "Known Issues Disposition",
+        "Cleanup Readiness",
+        "Final User Summary"
     ]
 };
 const PLACEHOLDER_PATTERN = /(^|\n)\s*(TBD|Not run yet\.?|status:\s*draft)\s*(\n|$)/i;