@hongmaple0820/scale-engine 0.13.0 → 0.14.0

package/dist/workflow/GovernanceTemplates.js

@@ -1,29 +1,56 @@
-import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { skillRoutingPolicyTemplate } from '../skills/routing/SkillPolicy.js';
+import { readGovernanceLock, writeGovernanceLock } from './GovernanceLock.js';
+import { resolveGovernanceTemplatePack, } from './GovernanceTemplatePacks.js';
 export function writeGovernanceTemplates(projectDir = process.cwd(), options = {}) {
     const mode = options.mode ?? 'standard';
     const projectName = options.projectName ?? 'Project';
+    const pack = resolveGovernanceTemplatePack(options.pack);
+    const packMode = pack.modeDefaults[mode];
+    const services = options.services ?? pack.defaultServices ?? [];
+    const exclude = options.exclude ?? pack.exclude ?? ['node_modules', 'dist', 'tmp', 'vendor'];
     const result = { created: [], skipped: [] };
-    writeIfMissing(result, join(projectDir, 'docs', 'workflow', 'README.md'), workflowReadme(projectName, mode));
-    writeIfMissing(result, join(projectDir, 'docs', 'workflow', 'templates', 'explore.md'), governanceTemplateContent('explore.md'));
-    writeIfMissing(result, join(projectDir, 'docs', 'workflow', 'templates', 'mini-prd.md'), governanceTemplateContent('mini-prd.md'));
-    writeIfMissing(result, join(projectDir, 'docs', 'workflow', 'templates', 'skill-plan.md'), governanceTemplateContent('skill-plan.md'));
-    writeIfMissing(result, join(projectDir, 'docs', 'workflow', 'templates', 'ui-spec.md'), governanceTemplateContent('ui-spec.md'));
-    writeIfMissing(result, join(projectDir, 'docs', 'workflow', 'templates', 'visual-review.md'), governanceTemplateContent('visual-review.md'));
-    writeIfMissing(result, join(projectDir, 'docs', 'workflow', 'templates', 'api-contract.md'), governanceTemplateContent('api-contract.md'));
-    writeIfMissing(result, join(projectDir, 'docs', 'workflow', 'templates', 'security-review.md'), governanceTemplateContent('security-review.md'));
-    writeIfMissing(result, join(projectDir, 'docs', 'workflow', 'templates', 'db-change-plan.md'), governanceTemplateContent('db-change-plan.md'));
-    writeIfMissing(result, join(projectDir, 'docs', 'workflow', 'templates', 'e2e-plan.md'), governanceTemplateContent('e2e-plan.md'));
-    writeIfMissing(result, join(projectDir, 'docs', 'workflow', 'templates', 'plan.md'), governanceTemplateContent('plan.md'));
-    writeIfMissing(result, join(projectDir, 'docs', 'workflow', 'templates', 'verification.md'), governanceTemplateContent('verification.md'));
-    writeIfMissing(result, join(projectDir, 'docs', 'workflow', 'templates', 'review.md'), governanceTemplateContent('review.md'));
-    writeIfMissing(result, join(projectDir, 'docs', 'workflow', 'templates', 'summary.md'), governanceTemplateContent('summary.md'));
-    writeIfMissing(result, join(projectDir, 'docs', 'workflow', 'templates', 'github-actions-scale-preflight.yml'), githubActionsPreflightTemplate());
-    writeIfMissing(result, join(projectDir, 'docs', 'workflow', 'templates', 'pre-push-scale-preflight.sh'), prePushPreflightTemplate());
-    writeIfMissing(result, join(projectDir, 'docs', 'worklog', 'metrics.md'), metricsTemplate());
-    writeIfMissing(result, join(projectDir, '.scale', 'verification.json'), verificationMatrixTemplate(mode));
-    writeIfMissing(result, join(projectDir, '.scale', 'skills.json'), skillRoutingPolicyTemplate(mode));
+    const lockFiles = new Map();
+    for (const file of readGovernanceLock(projectDir)?.files ?? []) {
+        lockFiles.set(file.path, file);
+    }
+    writeTracked(result, lockFiles, projectDir, 'docs/workflow/README.md', workflowReadme(projectName, mode, pack.id));
+    writeTracked(result, lockFiles, projectDir, 'docs/workflow/templates/explore.md', governanceTemplateContent('explore.md'));
+    writeTracked(result, lockFiles, projectDir, 'docs/workflow/templates/mini-prd.md', governanceTemplateContent('mini-prd.md'));
+    writeTracked(result, lockFiles, projectDir, 'docs/workflow/templates/skill-plan.md', governanceTemplateContent('skill-plan.md'));
+    writeTracked(result, lockFiles, projectDir, 'docs/workflow/templates/skill-evidence.md', governanceTemplateContent('skill-evidence.md'));
+    writeTracked(result, lockFiles, projectDir, 'docs/workflow/templates/ui-spec.md', governanceTemplateContent('ui-spec.md'));
+    writeTracked(result, lockFiles, projectDir, 'docs/workflow/templates/visual-review.md', governanceTemplateContent('visual-review.md'));
+    writeTracked(result, lockFiles, projectDir, 'docs/workflow/templates/api-contract.md', governanceTemplateContent('api-contract.md'));
+    writeTracked(result, lockFiles, projectDir, 'docs/workflow/templates/docs-impact.md', governanceTemplateContent('docs-impact.md'));
+    writeTracked(result, lockFiles, projectDir, 'docs/workflow/templates/security-review.md', governanceTemplateContent('security-review.md'));
+    writeTracked(result, lockFiles, projectDir, 'docs/workflow/templates/db-change-plan.md', governanceTemplateContent('db-change-plan.md'));
+    writeTracked(result, lockFiles, projectDir, 'docs/workflow/templates/e2e-plan.md', governanceTemplateContent('e2e-plan.md'));
+    writeTracked(result, lockFiles, projectDir, 'docs/workflow/templates/plan.md', governanceTemplateContent('plan.md'));
+    writeTracked(result, lockFiles, projectDir, 'docs/workflow/templates/verification.md', governanceTemplateContent('verification.md'));
+    writeTracked(result, lockFiles, projectDir, 'docs/workflow/templates/review.md', governanceTemplateContent('review.md'));
+    writeTracked(result, lockFiles, projectDir, 'docs/workflow/templates/summary.md', governanceTemplateContent('summary.md'));
+    writeTracked(result, lockFiles, projectDir, 'docs/workflow/templates/github-actions-scale-preflight.yml', githubActionsPreflightTemplate());
+    writeTracked(result, lockFiles, projectDir, 'docs/workflow/templates/pre-push-scale-preflight.sh', prePushPreflightTemplate());
+    writeTracked(result, lockFiles, projectDir, 'docs/worklog/metrics.md', metricsTemplate());
+    writeTracked(result, lockFiles, projectDir, '.scale/verification.json', verificationMatrixTemplate(mode, {
+        services,
+        exclude,
+        artifactGate: packMode.artifactGate,
+    }));
+    writeTracked(result, lockFiles, projectDir, '.scale/skills.json', skillRoutingPolicyTemplate(mode));
+    for (const file of pack.generatedFiles) {
+        writePackGeneratedFile(result, lockFiles, projectDir, pack.id, pack.version, file);
+    }
+    const lockPath = join(projectDir, '.scale', 'governance.lock.json');
+    writeGovernanceLock(projectDir, {
+        pack: pack.id,
+        packVersion: pack.version,
+        scaleVersion: packageVersion(),
+        files: [...lockFiles.values()],
+    });
+    result.created.push(lockPath);
     return result;
 }
 export function governanceTemplateContent(name) {
@@ -31,9 +58,11 @@ export function governanceTemplateContent(name) {
         case 'explore.md': return exploreTemplate();
         case 'mini-prd.md': return miniPrdTemplate();
         case 'skill-plan.md': return skillPlanTemplate();
+        case 'skill-evidence.md': return skillEvidenceTemplate();
         case 'ui-spec.md': return uiSpecTemplate();
         case 'visual-review.md': return visualReviewTemplate();
         case 'api-contract.md': return apiContractTemplate();
+        case 'docs-impact.md': return docsImpactTemplate();
         case 'security-review.md': return securityReviewTemplate();
         case 'db-change-plan.md': return dbChangePlanTemplate();
         case 'e2e-plan.md': return e2ePlanTemplate();
@@ -46,18 +75,42 @@ export function governanceTemplateContent(name) {
 function writeIfMissing(result, path, content) {
     if (existsSync(path)) {
         result.skipped.push(path);
-        return;
+        return false;
     }
     const dir = path.split(/[\\/]/).slice(0, -1).join('/');
     if (dir && !existsSync(dir))
         mkdirSync(dir, { recursive: true });
     writeFileSync(path, content, 'utf-8');
     result.created.push(path);
+    return true;
+}
+function writeTracked(result, lockFiles, projectDir, relativePath, content) {
+    const created = writeIfMissing(result, join(projectDir, relativePath), content);
+    if (created)
+        lockFiles.set(relativePath, { path: relativePath, owned: true });
+}
+function writePackGeneratedFile(result, lockFiles, projectDir, packId, packVersion, file) {
+    const content = shouldUseGeneratedHeader(file)
+        ? generatedHeader(packId, packVersion) + file.content
+        : file.content;
+    const created = writeIfMissing(result, join(projectDir, file.path), content);
+    if (created)
+        lockFiles.set(file.path, { path: file.path, owned: file.owned });
+}
+function shouldUseGeneratedHeader(file) {
+    return file.kind === 'doc' || file.kind === 'template' || file.kind === 'script';
 }
-function workflowReadme(projectName, mode) {
+function generatedHeader(packId, packVersion) {
+    return `# Generated by scale-engine governance pack: ${packId}@${packVersion}
+# Edit policy: prefer editing the pack in scale-engine; local overrides should be documented.
+
+`;
+}
+function workflowReadme(projectName, mode, packId = 'standard') {
     return `# ${projectName} Workflow
 
 Governance mode: ${mode}
+Governance pack: ${packId}
 
 ## Task Levels
 
@@ -86,10 +139,12 @@ Use service-aware verification when configured:
 
 \`\`\`bash
 scale preflight --service all
+scale preflight --service all --preflight-profile full
 scale verify <task-id> --profile default
 scale verify <task-id> --service <service-name>
 scale verify <task-id> --artifact-gate warn
 scale verify <task-id> --artifact-gate block
+scale verify <task-id> --require-installed-skills
 scale task-artifacts check --dir docs/worklog/tasks/<task-dir> --level L
 \`\`\`
 
@@ -97,14 +152,40 @@ Keep \`.scale/verification.json\` as the source of truth for profiles and servic
 Keep \`.scale/skills.json\` as the source of truth for active skill routing policy.
 Use \`artifactGate: "warn"\` while introducing the workflow, then move M/L/CRITICAL work to \`"block"\` once templates and local gates are stable.
 
+## Active Skill Routing
+
+SCALE plans required skills from task description, service selection, and changed files. UI/API work requires a Mini-PRD plus domain evidence such as \`ui-spec.md\`, \`visual-review.md\`, or \`api-contract.md\`. Security and database work require explicit review or rollback artifacts.
+
+When a task records \`servicesTouched\`, \`scale verify <task-id>\` uses those services automatically. You can still override selection with \`--service all\`, \`--service api\`, or \`--service api,gateway\`.
+
+Before M/L work, check whether required workflow skills are physically installed:
+
+\`\`\`bash
+scale skill doctor --json
+scale skill check --require-installed --json
+\`\`\`
+
+## Workspace Lifecycle
+
+Before finishing an agent-created branch or deleting a temporary worktree, inspect root and child repository state:
+
+\`\`\`bash
+scale workspace status --json
+scale workspace finish --json
+scale workspace cleanup --dir <temporary-worktree> --dry-run --json
+scale workspace cleanup --dir <temporary-worktree> --apply --confirm <branch-or-head> --json
+\`\`\`
+
+Do not remove a temporary worktree while any submodule or nested repository has uncommitted or unpushed work. Child repositories must be committed and reviewed in their own remotes, then the root repository can record any required pointer or governance updates. Cleanup defaults to dry-run. Applying cleanup requires the reported confirmation token, normally the temporary branch name.
+
 ## Automation Templates
 
 Optional automation templates are generated under \`docs/workflow/templates/\`:
 
-- \`github-actions-scale-preflight.yml\`: CI workflow that runs \`scale preflight --service all\`.
-- \`pre-push-scale-preflight.sh\`: local pre-push hook template for the same checks.
+- \`github-actions-scale-preflight.yml\`: CI workflow that runs \`scale preflight --service all --preflight-profile ci\`.
+- \`pre-push-scale-preflight.sh\`: local pre-push hook template that runs the default quick preflight.
 
-Keep these templates advisory until \`scale preflight --service all\` is reliable locally for the project.
+Keep these templates advisory until \`scale preflight --service all --preflight-profile full\` is reliable locally for the project.
 `;
 }
 function exploreTemplate() {
@@ -112,20 +193,22 @@ function exploreTemplate() {
 
 ## Files Read
 
-- 
+- TBD
 
 ## Current Behavior
 
+TBD
 
 ## Main Conflict
 
+TBD
 
 ## Affected Modules
 
+TBD
 
 ## Evidence
-
-
+TBD
 `;
 }
 function miniPrdTemplate() {
@@ -133,38 +216,44 @@ function miniPrdTemplate() {
 
 ## Background
 
+TBD
 
 ## Target Users
 
+TBD
 
 ## Core Scenario
 
+TBD
 
 ## Non-Goals
 
+TBD
 
 ## User Path
 
+TBD
 
 ## Permission Rules
 
+TBD
 
 ## Data Impact
 
+TBD
 
 ## Exception Scenarios
 
-1. 
-2. 
-3. 
+1. TBD
+2. TBD
+3. TBD
 
 ## Acceptance Criteria
 
-- [ ] 
+- [ ] TBD
 
 ## Rollback Or Disable Strategy
-
-
+TBD
 `;
 }
 function skillPlanTemplate() {
@@ -178,19 +267,19 @@ function skillPlanTemplate() {
 
 ## Required Skills
 
-- 
+- TBD
 
 ## Recommended Skills
 
-- 
+- TBD
 
 ## Required Artifacts
 
-- 
+- TBD
 
 ## Required Verification Evidence
 
-- 
+- TBD
 
 ## Skipped Skills
 
@@ -199,14 +288,36 @@ function skillPlanTemplate() {
 |  |  |  |
 `;
 }
+function skillEvidenceTemplate() {
+    return `# Skill Evidence
+
+## Planned Skills
+
+- TBD
+
+## Used Skills
+
+| Skill | Phase | Trigger | Evidence | Status |
+| --- | --- | --- | --- | --- |
+| skill-id | plan/build/verify/review | why it was selected | command, screenshot, report, or artifact path | executed/skipped/fallback |
+
+## Skipped Skills
+
+| Skill | Reason | Fallback Evidence |
+| --- | --- | --- |
+| skill-id | why it could not run | manual review, alternate command, or explicit risk |
+`;
+}
 function uiSpecTemplate() {
     return `# UI Spec
 
 ## User Goal
 
+TBD
 
 ## Primary Flow
 
+TBD
 
 ## Interaction States
 
@@ -218,13 +329,15 @@ function uiSpecTemplate() {
 
 ## Responsive Behavior
 
+TBD
 
 ## Accessibility Requirements
 
+TBD
 
 ## Acceptance Criteria
 
-- [ ] 
+- [ ] TBD
 `;
 }
 function visualReviewTemplate() {
@@ -232,19 +345,22 @@ function visualReviewTemplate() {
 
 ## Screenshots Or Evidence
 
+TBD
 
 ## Layout And Responsiveness
 
+TBD
 
 ## Text Fit And Overlap
 
+TBD
 
 ## Accessibility Notes
 
+TBD
 
 ## Final Verdict
-
-
+TBD
 `;
 }
 function apiContractTemplate() {
@@ -252,25 +368,51 @@ function apiContractTemplate() {
 
 ## Endpoint Or Interface
 
+TBD
 
 ## Request
 
+TBD
 
 ## Response
 
+TBD
 
 ## Errors
 
+TBD
 
 ## Permission Rules
 
+TBD
 
 ## Compatibility Notes
 
+TBD
 
 ## Acceptance Criteria
 
-- [ ] 
+- [ ] TBD
+`;
+}
+function docsImpactTemplate() {
+    return `# Docs Impact
+
+## Code Changes Requiring Docs
+
+- TBD
+
+## Documentation Updated
+
+- TBD
+
+## No-Docs-Needed Rationale
+
+TBD
+
+## Links Checked
+
+- TBD
 `;
 }
 function securityReviewTemplate() {
@@ -278,25 +420,28 @@ function securityReviewTemplate() {
 
 ## Assets And Trust Boundaries
 
+TBD
 
 ## Authorization Rules
 
+TBD
 
 ## Abuse Cases
 
-1. 
-2. 
-3. 
+1. TBD
+2. TBD
+3. TBD
 
 ## Sensitive Data Impact
 
+TBD
 
 ## Rollback Or Disable Strategy
 
+TBD
 
 ## Final Verdict
-
-
+TBD
 `;
 }
 function dbChangePlanTemplate() {
@@ -304,19 +449,22 @@ function dbChangePlanTemplate() {
 
 ## Schema Or Data Change
 
+TBD
 
 ## Backward Compatibility
 
+TBD
 
 ## Migration Steps
 
+TBD
 
 ## Rollback Plan
 
+TBD
 
 ## Verification
-
-
+TBD
 `;
 }
 function e2ePlanTemplate() {
@@ -324,19 +472,22 @@ function e2ePlanTemplate() {
 
 ## User Paths
 
+TBD
 
 ## Browser Coverage
 
+TBD
 
 ## Test Data
 
+TBD
 
 ## Assertions
 
+TBD
 
 ## Evidence
-
-
+TBD
 `;
 }
 function planTemplate() {
@@ -344,22 +495,24 @@ function planTemplate() {
 
 ## Approach
 
+TBD
 
 ## Boundaries
 
+TBD
 
 ## Exception Contract
 
-1. 
-2. 
-3. 
+1. TBD
+2. TBD
+3. TBD
 
 ## Rollback Plan
 
+TBD
 
 ## Test Strategy
-
-
+TBD
 `;
 }
 function verificationTemplate() {
@@ -373,13 +526,14 @@ function verificationTemplate() {
 
 ## Output Summary
 
+TBD
 
 ## Failures And Fixes
 
+TBD
 
 ## Final Status
-
-
+TBD
 `;
 }
 function reviewTemplate() {
@@ -387,16 +541,18 @@ function reviewTemplate() {
 
 ## Code Review
 
+TBD
 
 ## Security Review
 
+TBD
 
 ## Same-Pattern Scan
 
+TBD
 
 ## Residual Risks
-
-
+TBD
 `;
 }
 function summaryTemplate() {
@@ -404,12 +560,15 @@ function summaryTemplate() {
 
 ## Delivered Changes
 
+TBD
 
 ## Remaining Risks
 
+TBD
 
 ## Follow-Ups
 
+TBD
 
 ## Metric Row
 
@@ -431,41 +590,53 @@ function metricsTemplate() {
 
 ### Repeated Failure Patterns
 
+TBD
 
 ### Slowest Gates
 
+TBD
 
 ### Documentation Gaps
 
+TBD
 
 ### Product Design Misses
 
+TBD
 
 ### Proposed Workflow Changes
-
-
+TBD
 `;
 }
-function verificationMatrixTemplate(mode) {
+function verificationMatrixTemplate(mode, options = {}) {
     return JSON.stringify({
         version: 1,
         defaultProfile: 'default',
         profiles: {
             default: {
                 commands: {},
-                services: [],
+                services: options.services?.filter(service => service.required !== false).map(service => service.name) ?? [],
             },
         },
-        services: [],
-        exclude: ['node_modules', 'dist', 'tmp', 'vendor'],
+        services: options.services ?? [],
+        exclude: options.exclude ?? ['node_modules', 'dist', 'tmp', 'vendor'],
         policy: {
             mode,
             optionalToolsWarnOnly: true,
-            artifactGate: mode === 'critical' ? 'block' : 'warn',
+            artifactGate: options.artifactGate ?? (mode === 'critical' ? 'block' : 'warn'),
             artifactGateLevels: ['M', 'L', 'CRITICAL'],
         },
     }, null, 2) + '\n';
 }
+function packageVersion() {
+    try {
+        const pkg = JSON.parse(readFileSync(join(process.cwd(), 'package.json'), 'utf-8'));
+        return pkg.version ?? '0.0.0-dev';
+    }
+    catch {
+        return '0.0.0-dev';
+    }
+}
 function githubActionsPreflightTemplate() {
     return `name: SCALE Preflight
 
@@ -498,7 +669,7 @@ jobs:
           fi
 
       - name: Run SCALE preflight
-        run: npx @hongmaple0820/scale-engine@latest preflight --service all
+        run: npx @hongmaple0820/scale-engine@latest preflight --service all --preflight-profile ci
 `;
 }
 function prePushPreflightTemplate() {