solmate-skills 2.0.12 → 2.0.13

package/bin/harness-check.js

@@ -0,0 +1,373 @@
+const fs = require('fs');
+const path = require('path');
+
+const DEFAULT_BACKLOG = 'docs/04_Logic_Progress/00_BACKLOG.md';
+const RELATED_FIELDS = [
+    'Related Concept Docs',
+    'Related UI Docs',
+    'Related HTML Preview',
+    'Related Technical Docs',
+    'Related QA Docs',
+];
+const MANDATORY_WORK_TYPES = new Set(['code', 'deploy']);
+const ADVISORY_WORK_TYPES = new Set(['docs', 'prototype']);
+
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function findTaskBlock(content, taskId) {
+    const headingPattern = /^#{2,6}\s+\[([ xX])\]\s+([^\n]+)$/gm;
+    const headings = [];
+    let match;
+
+    while ((match = headingPattern.exec(content)) !== null) {
+        headings.push({ start: match.index, heading: match[2], checked: match[1].toLowerCase() === 'x' });
+    }
+
+    const idPattern = new RegExp(`(^|\\s)${escapeRegExp(taskId)}(?=\\s|:|$)`, 'i');
+    const index = headings.findIndex(item => idPattern.test(item.heading));
+
+    if (index === -1) {
+        return null;
+    }
+
+    const end = index + 1 < headings.length ? headings[index + 1].start : content.length;
+    return {
+        block: content.slice(headings[index].start, end),
+        checked: headings[index].checked,
+        heading: headings[index].heading,
+    };
+}
+
+function extractField(block, fieldName) {
+    const lines = block.split(/\r?\n/);
+    const fieldPattern = new RegExp(`^- ${escapeRegExp(fieldName)}:\\s*(.*)$`);
+    const start = lines.findIndex(line => fieldPattern.test(line));
+
+    if (start === -1) {
+        return null;
+    }
+
+    const firstMatch = lines[start].match(fieldPattern);
+    const collected = firstMatch[1] ? [firstMatch[1]] : [];
+
+    for (let index = start + 1; index < lines.length; index += 1) {
+        if (/^- [A-Za-z][^:]*:\s*/.test(lines[index])) {
+            break;
+        }
+        collected.push(lines[index]);
+    }
+
+    return collected.join('\n').replace(/^\n+/, '').replace(/\s+$/, '');
+}
+
+function extractNestedField(block, fieldName) {
+    const lines = block.split(/\r?\n/);
+    const fieldPattern = new RegExp(`^(\\s+)- ${escapeRegExp(fieldName)}:\\s*(.*)$`);
+    const start = lines.findIndex(line => fieldPattern.test(line));
+
+    if (start === -1) {
+        return null;
+    }
+
+    const firstMatch = lines[start].match(fieldPattern);
+    const baseIndent = firstMatch[1].length;
+    const collected = firstMatch[2] ? [firstMatch[2]] : [];
+
+    for (let index = start + 1; index < lines.length; index += 1) {
+        const nestedField = lines[index].match(/^(\s+)- [A-Za-z][^:]*:\s*/);
+        if (nestedField && nestedField[1].length <= baseIndent) {
+            break;
+        }
+        collected.push(lines[index]);
+    }
+
+    return collected.join('\n').replace(/^\n+/, '').replace(/\s+$/, '');
+}
+
+function extractLinks(value) {
+    const links = [];
+    const pattern = /\[[^\]]+\]\(([^)]+)\)/g;
+    let match;
+
+    while ((match = pattern.exec(value || '')) !== null) {
+        links.push(match[1].trim().replace(/^<|>$/g, ''));
+    }
+
+    return links;
+}
+
+function extractBacktickValues(value) {
+    const values = [];
+    const pattern = /`([^`]+)`/g;
+    let match;
+
+    while ((match = pattern.exec(value || '')) !== null) {
+        values.push(match[1].trim());
+    }
+
+    return values;
+}
+
+function normalizeReference(value) {
+    const withoutAnchor = value.split('#')[0].split('?')[0];
+    return path.normalize(withoutAnchor).replace(/\\/g, '/').replace(/^\.\//, '');
+}
+
+function hasReasonedNA(value) {
+    return /N\/A\s*-\s*\S+/i.test(value || '');
+}
+
+function isExternalLink(value) {
+    return /^[a-z][a-z0-9+.-]*:/i.test(value);
+}
+
+function validateRelatedFields(task, backlogPath, errors) {
+    const relatedLinks = [];
+    const backlogDir = path.dirname(backlogPath);
+
+    for (const fieldName of RELATED_FIELDS) {
+        const field = extractField(task.block, fieldName);
+        if (!field) {
+            errors.push(`${fieldName} is missing.`);
+            continue;
+        }
+
+        const links = extractLinks(field);
+        if (links.length === 0) {
+            if (!hasReasonedNA(field)) {
+                errors.push(`${fieldName} must contain a relative link or \`N/A - reason\`.`);
+            }
+            continue;
+        }
+
+        for (const link of links) {
+            if (isExternalLink(link)) {
+                errors.push(`${fieldName} must use a relative project path: ${link}`);
+                continue;
+            }
+
+            const normalized = normalizeReference(link);
+            const absolute = path.resolve(backlogDir, normalized);
+            if (!fs.existsSync(absolute)) {
+                errors.push(`${fieldName} points to a missing file: ${link}`);
+                continue;
+            }
+            relatedLinks.push(normalized);
+        }
+    }
+
+    return relatedLinks;
+}
+
+function validateContextReceipt(task, relatedLinks, errors) {
+    const receipt = extractField(task.block, 'Context Receipt');
+    if (!receipt) {
+        errors.push('Context Receipt is missing.');
+        return;
+    }
+
+    const status = extractNestedField(receipt, 'Status');
+    if (!status || !/^PASS\b/i.test(status)) {
+        errors.push('Context Receipt status must be PASS.');
+    }
+
+    const readField = extractNestedField(receipt, 'Required References Read');
+    if (!readField) {
+        errors.push('Context Receipt must list Required References Read.');
+    } else {
+        const readReferences = [...extractLinks(readField), ...extractBacktickValues(readField)]
+            .filter(value => !isExternalLink(value))
+            .map(normalizeReference);
+        const readSet = new Set(readReferences);
+
+        for (const linkedPath of relatedLinks) {
+            if (!readSet.has(linkedPath)) {
+                errors.push(`Linked document was not recorded as read: ${linkedPath}`);
+            }
+        }
+    }
+
+    if (!extractNestedField(receipt, 'Constraints')) {
+        errors.push('Context Receipt must include Constraints.');
+    }
+    if (!extractNestedField(receipt, 'Conflicts')) {
+        errors.push('Context Receipt must include Conflicts.');
+    }
+}
+
+function validateVerificationReceipt(task, backlogPath, errors) {
+    const receipt = extractField(task.block, 'Verification Receipt');
+    if (!receipt) {
+        errors.push('Verification Receipt is missing.');
+        return;
+    }
+
+    const status = extractNestedField(receipt, 'Status');
+    if (!status || !/^PASS\b/i.test(status)) {
+        errors.push('Verification Receipt status must be PASS.');
+    }
+    if (/\bFAIL\b/i.test(receipt)) {
+        errors.push('Verification Receipt contains a FAIL result.');
+    }
+
+    const commands = extractNestedField(receipt, 'Commands and Results');
+    if (!commands || !/\bPASS\b/i.test(commands)) {
+        errors.push('Verification Receipt must include at least one passing command result.');
+    }
+
+    const unrun = extractNestedField(receipt, 'Unrun Checks');
+    if (!unrun) {
+        errors.push('Verification Receipt must explain Unrun Checks.');
+    }
+
+    const evidence = extractNestedField(receipt, 'Detailed Evidence');
+    const evidenceLinks = extractLinks(evidence || '');
+    if (!evidence || evidenceLinks.length === 0) {
+        errors.push('Verification Receipt must link Detailed Evidence to a QA document or PR.');
+        return;
+    }
+
+    const backlogDir = path.dirname(backlogPath);
+    const hasValidEvidence = evidenceLinks.some(link => {
+        if (/^https:\/\/github\.com\/.+\/pull\/\d+/i.test(link)) {
+            return true;
+        }
+        if (isExternalLink(link)) {
+            return false;
+        }
+        const absolute = path.resolve(backlogDir, normalizeReference(link));
+        return fs.existsSync(absolute) && /(?:^|\/)05_QA_Validation\//.test(absolute.replace(/\\/g, '/'));
+    });
+
+    if (!hasValidEvidence) {
+        errors.push('Detailed Evidence must point to an existing QA document or a GitHub PR.');
+    }
+}
+
+function checkHarnessTask(options) {
+    const stage = options.stage;
+    const mode = options.mode || 'warning';
+    const taskId = options.taskId;
+    const backlogPath = path.resolve(options.cwd || process.cwd(), options.backlogPath || DEFAULT_BACKLOG);
+    const errors = [];
+    const notes = [];
+
+    if (!['preflight', 'verify'].includes(stage)) {
+        return { operationalError: true, valid: false, errors: [`Unknown harness stage: ${stage}`] };
+    }
+    if (!['warning', 'blocking'].includes(mode)) {
+        return { operationalError: true, valid: false, errors: [`Unknown harness mode: ${mode}`] };
+    }
+    if (!taskId) {
+        return { operationalError: true, valid: false, errors: ['A backlog task ID is required.'] };
+    }
+    if (!fs.existsSync(backlogPath)) {
+        return { operationalError: true, valid: false, errors: [`Backlog file not found: ${backlogPath}`] };
+    }
+
+    const content = fs.readFileSync(backlogPath, 'utf8');
+    const task = findTaskBlock(content, taskId);
+    if (!task) {
+        return { operationalError: true, valid: false, errors: [`Task not found in backlog: ${taskId}`] };
+    }
+
+    const workTypeValue = extractField(task.block, 'Work Type');
+    const workType = (workTypeValue || '').split(/\s/)[0].toLowerCase();
+    if (!workType) {
+        errors.push('Work Type is missing. Use code, deploy, docs, or prototype.');
+    } else if (ADVISORY_WORK_TYPES.has(workType)) {
+        notes.push(`Work Type ${workType} uses advisory receipts.`);
+        return {
+            stage,
+            mode,
+            taskId,
+            backlogPath,
+            workType,
+            applicable: false,
+            valid: true,
+            checked: task.checked,
+            errors,
+            notes,
+        };
+    } else if (!MANDATORY_WORK_TYPES.has(workType)) {
+        errors.push(`Unsupported Work Type: ${workType}`);
+    }
+
+    for (const fieldName of ['Implementation Preconditions', 'Acceptance Criteria']) {
+        if (!extractField(task.block, fieldName)) {
+            errors.push(`${fieldName} is missing.`);
+        }
+    }
+
+    const relatedLinks = validateRelatedFields(task, backlogPath, errors);
+    validateContextReceipt(task, relatedLinks, errors);
+
+    if (stage === 'verify') {
+        validateVerificationReceipt(task, backlogPath, errors);
+    }
+
+    return {
+        stage,
+        mode,
+        taskId,
+        backlogPath,
+        workType: workType || 'unknown',
+        applicable: true,
+        valid: errors.length === 0,
+        checked: task.checked,
+        errors,
+        notes,
+    };
+}
+
+function formatHarnessResult(result) {
+    if (result.operationalError) {
+        return ['Harness check: ERROR', ...result.errors.map(error => `- ${error}`)].join('\n');
+    }
+
+    let status = 'PASS';
+    if (!result.applicable) {
+        status = 'ADVISORY';
+    } else if (!result.valid) {
+        status = result.mode === 'blocking' ? 'BLOCK' : 'WARN';
+    }
+
+    const lines = [
+        `Harness ${result.stage}: ${status}`,
+        `Task: ${result.taskId}`,
+        `Work Type: ${result.workType}`,
+        `Mode: ${result.mode}`,
+        `Backlog: ${result.backlogPath}`,
+    ];
+
+    for (const note of result.notes || []) {
+        lines.push(`- ${note}`);
+    }
+    for (const error of result.errors || []) {
+        lines.push(`- ${error}`);
+    }
+
+    return lines.join('\n');
+}
+
+function getHarnessExitCode(result) {
+    if (result.operationalError) {
+        return 2;
+    }
+    if (!result.valid && result.mode === 'blocking') {
+        return 1;
+    }
+    return 0;
+}
+
+module.exports = {
+    DEFAULT_BACKLOG,
+    checkHarnessTask,
+    extractField,
+    extractNestedField,
+    findTaskBlock,
+    formatHarnessResult,
+    getHarnessExitCode,
+};

package/bin/harness-check.test.js

@@ -0,0 +1,159 @@
+const assert = require('assert');
+const childProcess = require('child_process');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { checkHarnessTask, getHarnessExitCode } = require('./harness-check');
+const cliPath = path.join(__dirname, 'cli.js');
+
+const root = fs.mkdtempSync(path.join(os.tmpdir(), 'solmate-harness-'));
+const backlogDir = path.join(root, 'docs', '04_Logic_Progress');
+const conceptDir = path.join(root, 'docs', '01_Concept_Design');
+const qaDir = path.join(root, 'docs', '05_QA_Validation');
+
+fs.mkdirSync(backlogDir, { recursive: true });
+fs.mkdirSync(conceptDir, { recursive: true });
+fs.mkdirSync(qaDir, { recursive: true });
+fs.writeFileSync(path.join(conceptDir, '03_PRODUCT_SPECS.md'), '# Product Specs\n');
+fs.writeFileSync(path.join(qaDir, '10_FEATURE_QA.md'), '# QA Report\n');
+
+const backlogPath = path.join(backlogDir, '00_BACKLOG.md');
+const validTask = `### [ ] TASK-001: Harness fixture
+
+- Status: Doing
+- Work Type: code
+- Related Concept Docs:
+  - [Product Specs](../01_Concept_Design/03_PRODUCT_SPECS.md) - scope
+- Related UI Docs:
+  - N/A - no UI change
+- Related HTML Preview:
+  - N/A - no UI change
+- Related Technical Docs:
+  - N/A - no technical contract change
+- Related QA Docs:
+  - [QA Report](../05_QA_Validation/10_FEATURE_QA.md) - verification evidence
+- Implementation Preconditions:
+  - [x] Read all related documents
+- Acceptance Criteria:
+  - [x] Harness fixture passes
+- Context Receipt:
+  - Status: PASS
+  - Required References Read:
+    - [Product Specs](../01_Concept_Design/03_PRODUCT_SPECS.md) - constraints extracted
+    - [QA Report](../05_QA_Validation/10_FEATURE_QA.md) - criteria extracted
+  - Constraints:
+    - Keep the fixture minimal
+  - Conflicts: None
+- Change Receipt:
+  - Files Changed:
+    - \`bin/harness-check.test.js\`
+- Verification Receipt:
+  - Status: PASS
+  - Commands and Results:
+    - \`npm test\` - PASS - fixture complete
+  - Unrun Checks:
+    - N/A - all planned checks ran
+  - Detailed Evidence:
+    - [QA Report](../05_QA_Validation/10_FEATURE_QA.md) - full evidence
+`;
+
+fs.writeFileSync(backlogPath, validTask);
+
+const preflight = checkHarnessTask({
+    stage: 'preflight',
+    mode: 'blocking',
+    taskId: 'TASK-001',
+    backlogPath,
+});
+assert.strictEqual(preflight.valid, true, preflight.errors.join('\n'));
+assert.strictEqual(getHarnessExitCode(preflight), 0);
+
+const verification = checkHarnessTask({
+    stage: 'verify',
+    mode: 'blocking',
+    taskId: 'TASK-001',
+    backlogPath,
+});
+assert.strictEqual(verification.valid, true, verification.errors.join('\n'));
+
+const cliPass = childProcess.spawnSync(
+    process.execPath,
+    [cliPath, 'verify', 'TASK-001', '--strict', '--backlog', backlogPath],
+    { cwd: root, encoding: 'utf8' },
+);
+assert.strictEqual(cliPass.status, 0, cliPass.stderr || cliPass.stdout);
+assert(cliPass.stdout.includes('Harness verify: PASS'));
+
+fs.writeFileSync(backlogPath, validTask.replace(
+    '    - [QA Report](../05_QA_Validation/10_FEATURE_QA.md) - criteria extracted\n',
+    '',
+));
+const missingRead = checkHarnessTask({
+    stage: 'preflight',
+    mode: 'warning',
+    taskId: 'TASK-001',
+    backlogPath,
+});
+assert.strictEqual(missingRead.valid, false);
+assert.strictEqual(getHarnessExitCode(missingRead), 0);
+assert(missingRead.errors.some(error => error.includes('not recorded as read')));
+
+const cliWarning = childProcess.spawnSync(
+    process.execPath,
+    [cliPath, 'preflight', 'TASK-001', '--backlog', backlogPath],
+    { cwd: root, encoding: 'utf8' },
+);
+assert.strictEqual(cliWarning.status, 0, cliWarning.stderr || cliWarning.stdout);
+assert(cliWarning.stdout.includes('Harness preflight: WARN'));
+
+const cliBlock = childProcess.spawnSync(
+    process.execPath,
+    [cliPath, 'preflight', 'TASK-001', '--strict', '--backlog', backlogPath],
+    { cwd: root, encoding: 'utf8' },
+);
+assert.strictEqual(cliBlock.status, 1, cliBlock.stderr || cliBlock.stdout);
+assert(cliBlock.stdout.includes('Harness preflight: BLOCK'));
+
+fs.writeFileSync(backlogPath, validTask.replace(
+    '  - Detailed Evidence:\n    - [QA Report](../05_QA_Validation/10_FEATURE_QA.md) - full evidence\n',
+    '',
+));
+const missingEvidence = checkHarnessTask({
+    stage: 'verify',
+    mode: 'blocking',
+    taskId: 'TASK-001',
+    backlogPath,
+});
+assert.strictEqual(missingEvidence.valid, false);
+assert.strictEqual(getHarnessExitCode(missingEvidence), 1);
+assert(missingEvidence.errors.some(error => error.includes('Detailed Evidence')));
+
+fs.writeFileSync(backlogPath, validTask.replace('Work Type: code', 'Work Type: docs'));
+const docsTask = checkHarnessTask({
+    stage: 'verify',
+    mode: 'blocking',
+    taskId: 'TASK-001',
+    backlogPath,
+});
+assert.strictEqual(docsTask.valid, true);
+assert.strictEqual(docsTask.applicable, false);
+
+const installRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'solmate-agent-install-'));
+const customAgentDir = path.join(installRoot, '.claude', 'agents');
+fs.mkdirSync(customAgentDir, { recursive: true });
+fs.writeFileSync(path.join(customAgentDir, 'custom-reviewer.md'), '# Keep this project agent\n');
+
+const agentInstall = childProcess.spawnSync(
+    process.execPath,
+    [cliPath, 'install', 'agents'],
+    { cwd: installRoot, encoding: 'utf8' },
+);
+assert.strictEqual(agentInstall.status, 0, agentInstall.stderr || agentInstall.stdout);
+assert(fs.existsSync(path.join(installRoot, '.agent', 'skills', 'rules-workflow', 'resources', 'agent-harness-contract.md')));
+assert(fs.existsSync(path.join(installRoot, '.agent', 'skills', 'rules-workflow', 'resources', 'agent-harness-v1.schema.json')));
+assert(fs.existsSync(path.join(customAgentDir, 'custom-reviewer.md')));
+for (const fileName of ['solmate-context-reader.md', 'solmate-implementer.md', 'solmate-verifier.md']) {
+    assert(fs.existsSync(path.join(customAgentDir, fileName)), `${fileName} was not installed`);
+}
+
+console.log('harness checks ok');

package/bin/test.js

@@ -0,0 +1,2 @@
+require('./harness-check.test');
+require('./harness-artifact.test');