thachvd-kit 1.0.32 → 1.0.33

package/README.md

@@ -45,7 +45,17 @@ Superpowers is the primary workflow backend:
 
 For bugs, use `systematic-debugging`: reproduce, inspect, test hypotheses, add regression protection, fix the root cause, and verify.
 
-For a trivial one-file change with no behavior or contract change, use the client's fast path. State the narrow scope and verification before editing. If the scope grows, return to brainstorming and planning.
+Fast-path eligibility is based on risk and contract surface, not file count. A localized, mechanically obvious, low-risk change with focused verification can use the client fast path; a one-file security, schema, payment, concurrency, or public-contract change should not.
+
+## Engineering Policy
+
+The generated context optimizes for the **smallest sufficient change**, not the fewest lines of code.
+
+- Preserve required behavior, product and architectural contracts, UX/accessibility, security/data integrity, compatibility/performance, and maintainability before optimizing for simplicity.
+- Reuse an existing project abstraction when it satisfies the contract. Do not bypass it merely because a lower-level primitive is shorter.
+- Avoid speculative abstractions and unrelated refactors.
+- Do not split code solely to satisfy a hard line-count target; prefer cohesive modules and split only for a concrete design or maintenance benefit.
+- Use the cheapest reliable context source. Read known local code directly; use structural tooling for unknown ownership, call paths, architecture, or impact; avoid duplicate retrieval when one source already provides enough evidence.
 
 ## Integrations
 
@@ -55,14 +65,14 @@ Install it separately for each AI client. The official guide contains the curren
 
 ### codebase-memory-mcp
 
-Use it for symbol search, call paths, architecture, and impact analysis:
+Use it for structural discovery when symbol ownership, call paths, architecture, or impact are not already obvious:
 
 ```bash
 npm install -g codebase-memory-mcp
 codebase-memory-mcp cli index_repository --repo-path .
 ```
 
-The index is local state. Keep it out of git unless the team explicitly chooses to share a snapshot.
+The index is local state. Keep it out of git unless the team explicitly chooses to share a snapshot. If another structural index such as CodeGraph already provides sufficient evidence, avoid querying both for the same question.
 
 ### RTK
 

package/bin/entry.js

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+
+const {
+    snapshotPolicyFiles,
+    applyPolicyUpgrades
+} = require('./policy');
+
+function isInitInvocation(args) {
+    if (args.includes('--help') || args.includes('-h') || args.includes('--version') || args.includes('-v')) {
+        return false;
+    }
+    const first = args[0];
+    return !first || first === 'init' || first.startsWith('-');
+}
+
+const args = process.argv.slice(2);
+const shouldUpgradeGeneratedPolicy = isInitInvocation(args);
+const beforeSnapshot = shouldUpgradeGeneratedPolicy ? snapshotPolicyFiles(process.cwd()) : null;
+const force = args.includes('--yes') || args.includes('-y');
+
+if (shouldUpgradeGeneratedPolicy) {
+    process.once('beforeExit', code => {
+        if (code !== 0 || (process.exitCode && process.exitCode !== 0)) return;
+        const changed = applyPolicyUpgrades(process.cwd(), beforeSnapshot, { force });
+        if (changed.length > 0) {
+            console.log(`  OK Applied engineering quality policy to ${changed.length} generated context file(s)`);
+        }
+    });
+}
+
+require('./cli');

package/bin/policy.js

@@ -0,0 +1,196 @@
+const fs = require('fs');
+const path = require('path');
+
+const POLICY_PATHS = [
+    'AGENTS.md',
+    '.cursorrules',
+    path.join('.agent', 'docs', 'conventions.md'),
+    path.join('.agent', 'docs', 'workflow.md'),
+    path.join('.agent', 'docs', 'getting-started.md'),
+    path.join('.agent', 'docs', 'tooling.md')
+];
+
+const QUALITY_FLOOR_SECTION = `## Engineering Quality Floor
+
+Prefer the smallest sufficient change, not the fewest lines of code.
+
+A simpler implementation is acceptable only when it fully preserves:
+
+- required behavior and acceptance criteria;
+- existing product and architectural contracts;
+- UX and accessibility behavior;
+- security and data integrity;
+- compatibility and expected performance;
+- maintainability appropriate to the codebase.
+
+Do not bypass an existing project abstraction merely because a lower-level primitive requires less code. Existing abstractions may encode product behavior and implicit requirements. Do not introduce speculative abstractions either; add complexity only when concrete requirements or codebase evidence justify it.`;
+
+const AGENT_RULES_SECTION = `## Rules
+
+- Respond in the user's language; keep code, identifiers, and code comments in English.
+- State assumptions when the request is ambiguous.
+- Prefer established project patterns and abstractions when they satisfy the required contract.
+- Keep changes surgical, but never trade away required behavior, UX, accessibility, security, data integrity, compatibility, or maintainability just to reduce code.
+- Do not split or reorganize code solely to satisfy a line-count target. Prefer cohesive modules with clear responsibilities; split only for a concrete cohesion, ownership, testability, or maintainability benefit.
+- **Context retrieval**: use the cheapest source that can answer the question reliably. Read/search directly for a known local file or obvious local edit; use \`codebase-memory-mcp\` or another configured structural index for unknown ownership, symbol relationships, call paths, architecture, or impact; use \`context7\` for external API/docs uncertainty; use \`playwright\` for browser/UI verification. Avoid duplicate retrieval when one source already provides sufficient evidence.
+- Prefer \`rtk\` by default for verbose shell commands such as git, tests, builds, package managers, Docker, and Kubernetes. Run the underlying command directly when RTK is unavailable or incompatible.
+- Tests or equivalent verification are mandatory before claiming completion.`;
+
+const CONVENTIONS_STANDARDS_SECTION = `## Current Standards
+
+- Code comments and identifiers should be written in English.
+- Keep changes scoped to the user request and preserve established local conventions.
+- Prefer existing project abstractions when they satisfy the required contract; do not bypass them solely to save lines of code.
+- Do not split or reorganize code solely to satisfy a line-count target. Prefer cohesive modules with clear responsibilities.
+- Add abstractions only when concrete requirements or codebase evidence justify them.
+- TODO: refine naming, formatting, folder, API, state, styling, and testing conventions from the real codebase.`;
+
+const FAST_PATH_SECTION = `## Fast Path
+
+Fast-path eligibility is based on risk and contract surface, not file count. Use it only when the change is localized, mechanically obvious, has no meaningful public API, schema, security, data-integrity, dependency, CI/release, or architectural risk, and has focused verification available. A two-file change such as code plus its focused test may still be fast-path; a one-file auth, payment, schema, concurrency, or other high-risk change is not.
+
+State the narrow scope and verification before editing. If the task becomes ambiguous, introduces new behavior or architectural decisions, or its risk/contract surface grows, switch to brainstorming and planning.`;
+
+const GETTING_STARTED_FAST_PATH_SECTION = `## Fast Path
+
+Use a fast path when the change is localized, mechanically obvious, low-risk, and has focused verification. File count alone does not determine eligibility: code plus a focused test can still be trivial, while a one-file security, schema, payment, concurrency, or public-contract change requires the full workflow. If scope or risk grows, return to brainstorming and planning.`;
+
+const TOOL_ROUTING_SECTION = `## Tool Routing
+
+Use the cheapest source that can answer the question reliably and avoid retrieving the same evidence twice.
+
+- Known local file or obvious local edit: read/search directly.
+- Unknown ownership, symbol relationships, call paths, architecture, or impact: use \`codebase-memory-mcp\` or another configured structural index such as CodeGraph.
+- External library/API uncertainty: use Context7.
+- Browser/UI behavior: use Playwright.
+- Noisy shell output: prefer RTK.
+
+Structural tools are aids, not mandatory ceremony. If direct evidence is already sufficient, do not call extra MCP tools just because they are available.`;
+
+function normalizeNewlines(text) {
+    return String(text || '').replace(/\r\n/g, '\n');
+}
+
+function replaceSection(markdown, heading, replacement) {
+    const text = normalizeNewlines(markdown);
+    const marker = `${heading}\n`;
+    const start = text.indexOf(marker);
+    if (start < 0) return text;
+
+    const searchFrom = start + marker.length;
+    const nextHeading = text.indexOf('\n## ', searchFrom);
+    const end = nextHeading >= 0 ? nextHeading + 1 : text.length;
+    const prefix = text.slice(0, start);
+    const suffix = text.slice(end).replace(/^\n+/, '');
+    return `${prefix}${replacement.trimEnd()}\n\n${suffix}`.replace(/\n{3,}/g, '\n\n');
+}
+
+function insertSectionBefore(markdown, beforeHeading, section) {
+    const text = normalizeNewlines(markdown);
+    const sectionHeading = section.split('\n', 1)[0];
+    if (text.includes(`${sectionHeading}\n`)) return text;
+
+    const marker = `${beforeHeading}\n`;
+    const index = text.indexOf(marker);
+    if (index < 0) return `${text.trimEnd()}\n\n${section.trimEnd()}\n`;
+    return `${text.slice(0, index)}${section.trimEnd()}\n\n${text.slice(index)}`;
+}
+
+function replaceFastPathInline(markdown) {
+    return normalizeNewlines(markdown)
+        .replace(
+            'Questions and research do not edit product code. A simple fix may use a fast path only when it is one-file, unambiguous, and changes no behavior or contract. State the scope and verification before editing. If the scope grows, switch to the full Superpowers flow.',
+            'Questions and research do not edit product code. A fast path is allowed only when the change is localized, mechanically obvious, low-risk, and has focused verification; file count alone is not a gate. State the scope and verification before editing. If the task becomes ambiguous or its behavior, contract, or risk surface grows, switch to the full Superpowers flow.'
+        )
+        .replace(
+            'Questions and research do not edit product code. A simple fix may use a fast path only when it is one-file, unambiguous, and changes no behavior or contract. State the narrow scope and verification before editing. If the scope grows, return to brainstorming and planning.',
+            'Questions and research do not edit product code. A fast path is allowed only when the change is localized, mechanically obvious, low-risk, and has focused verification; file count alone is not a gate. State the narrow scope and verification before editing. If scope or risk grows, return to brainstorming and planning.'
+        );
+}
+
+function upgradeAgentsMarkdown(markdown) {
+    let text = replaceFastPathInline(markdown);
+    text = insertSectionBefore(text, '## Rules', QUALITY_FLOOR_SECTION);
+    text = replaceSection(text, '## Rules', AGENT_RULES_SECTION);
+    return text.trimEnd() + '\n';
+}
+
+function upgradeConventionsMarkdown(markdown) {
+    let text = replaceSection(markdown, '## Current Standards', CONVENTIONS_STANDARDS_SECTION);
+    text = insertSectionBefore(text, '## Verification', QUALITY_FLOOR_SECTION);
+    return text.trimEnd() + '\n';
+}
+
+function upgradeWorkflowMarkdown(markdown) {
+    return replaceSection(markdown, '## Fast Path', FAST_PATH_SECTION).trimEnd() + '\n';
+}
+
+function upgradeGettingStartedMarkdown(markdown) {
+    return replaceSection(markdown, '## Fast Path', GETTING_STARTED_FAST_PATH_SECTION).trimEnd() + '\n';
+}
+
+function upgradeToolingMarkdown(markdown) {
+    const text = normalizeNewlines(markdown);
+    const targetHeading = text.includes('## Codebase Memory MCP\n')
+        ? '## Codebase Memory MCP'
+        : '## codebase-memory-mcp';
+    return insertSectionBefore(text, targetHeading, TOOL_ROUTING_SECTION).trimEnd() + '\n';
+}
+
+function upgradeGeneratedContent(relativePath, content) {
+    const normalized = relativePath.split(path.sep).join('/');
+    if (normalized === 'AGENTS.md' || normalized === '.cursorrules') return upgradeAgentsMarkdown(content);
+    if (normalized.endsWith('/conventions.md')) return upgradeConventionsMarkdown(content);
+    if (normalized.endsWith('/workflow.md')) return upgradeWorkflowMarkdown(content);
+    if (normalized.endsWith('/getting-started.md')) return upgradeGettingStartedMarkdown(content);
+    if (normalized.endsWith('/tooling.md')) return upgradeToolingMarkdown(content);
+    return normalizeNewlines(content);
+}
+
+function snapshotPolicyFiles(rootDir) {
+    const snapshot = new Map();
+    for (const relativePath of POLICY_PATHS) {
+        const fullPath = path.join(rootDir, relativePath);
+        snapshot.set(relativePath, fs.existsSync(fullPath) ? fs.readFileSync(fullPath, 'utf8') : null);
+    }
+    return snapshot;
+}
+
+function applyPolicyUpgrades(rootDir, beforeSnapshot, options = {}) {
+    const force = options.force === true;
+    const changed = [];
+
+    for (const relativePath of POLICY_PATHS) {
+        const fullPath = path.join(rootDir, relativePath);
+        if (!fs.existsSync(fullPath)) continue;
+
+        const current = fs.readFileSync(fullPath, 'utf8');
+        const before = beforeSnapshot ? beforeSnapshot.get(relativePath) : null;
+        const wasWritten = force || before === null || before !== current;
+        if (!wasWritten) continue;
+
+        const upgraded = upgradeGeneratedContent(relativePath, current);
+        if (upgraded !== normalizeNewlines(current)) {
+            fs.writeFileSync(fullPath, upgraded, 'utf8');
+            changed.push(relativePath);
+        }
+    }
+
+    return changed;
+}
+
+module.exports = {
+    POLICY_PATHS,
+    QUALITY_FLOOR_SECTION,
+    AGENT_RULES_SECTION,
+    FAST_PATH_SECTION,
+    TOOL_ROUTING_SECTION,
+    upgradeGeneratedContent,
+    upgradeAgentsMarkdown,
+    upgradeConventionsMarkdown,
+    upgradeWorkflowMarkdown,
+    upgradeGettingStartedMarkdown,
+    upgradeToolingMarkdown,
+    snapshotPolicyFiles,
+    applyPolicyUpgrades
+};

package/package.json

@@ -1,9 +1,9 @@
 {
     "name": "thachvd-kit",
-    "version": "1.0.32",
+    "version": "1.0.33",
     "description": "Cross-agent project rules bootstrap kit for Codex, Antigravity, and Claude Code",
     "bin": {
-        "thachvd-kit": "./bin/cli.js"
+        "thachvd-kit": "./bin/entry.js"
     },
     "files": [
         "bin",
@@ -15,8 +15,8 @@
         "node": ">=16.7"
     },
     "scripts": {
-        "test": "node test/cli.test.js",
-        "release:verify": "npm test && node --check bin/cli.js && npm pack --dry-run",
+        "test": "node test/cli.test.js && node test/policy.test.js",
+        "release:verify": "npm test && node --check bin/cli.js && node --check bin/entry.js && node --check bin/policy.js && npm pack --dry-run",
         "preversion": "npm run release:verify",
         "release:patch": "npm version patch",
         "release:dry-run": "npm pack --dry-run",