@sha3/code 1.0.0

package/lib/verify/typescript-style-verifier.mjs

@@ -0,0 +1,407 @@
+import ts from "typescript";
+
+import { DEFAULT_PROFILE } from "../constants.mjs";
+import { createContractIssue, getActiveVerifyRuleIds, shouldRunRule } from "./issue-helpers.mjs";
+import { getIdentifierText, getLineAndColumn } from "./source-analysis.mjs";
+
+const MODULE_CONSTANT_PATTERN = /^[A-Z0-9_]+$/;
+const CAMEL_CASE_PATTERN = /^[a-z][a-zA-Z0-9]*$/;
+
+function createIssue(contract, ruleId, relativePath, node, message, options = {}) {
+  const location = node && "getStart" in node && "getSourceFile" in node ? getLineAndColumn(node.getSourceFile(), node.getStart(node.getSourceFile())) : {};
+  return createContractIssue(contract, {
+    ruleId,
+    category: "typescript-style",
+    relativePath,
+    line: location.line,
+    column: location.column,
+    message,
+    verificationMode: options.verificationMode,
+    confidence: options.confidence,
+    evidence: options.evidence,
+    suggestion: options.suggestion,
+  });
+}
+
+function isExported(node) {
+  return Array.isArray(node.modifiers) && node.modifiers.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword);
+}
+
+function isTypePosition(node) {
+  let current = node;
+
+  while (current.parent) {
+    if (ts.isTypeNode(current.parent) || ts.isExpressionWithTypeArguments(current.parent) || ts.isHeritageClause(current.parent)) {
+      return true;
+    }
+
+    if (
+      ts.isImportClause(current.parent) ||
+      ts.isImportSpecifier(current.parent) ||
+      ts.isImportEqualsDeclaration(current.parent) ||
+      ts.isExportSpecifier(current.parent)
+    ) {
+      return false;
+    }
+
+    current = current.parent;
+  }
+
+  return false;
+}
+
+function collectPublicApiExports(indexFile) {
+  const exportNames = new Set();
+
+  if (!indexFile) {
+    return exportNames;
+  }
+
+  ts.forEachChild(indexFile.ast, (node) => {
+    if (ts.isExportDeclaration(node) && node.exportClause && ts.isNamedExports(node.exportClause)) {
+      for (const element of node.exportClause.elements) {
+        exportNames.add(element.name.text);
+      }
+    }
+
+    if (
+      (ts.isClassDeclaration(node) || ts.isFunctionDeclaration(node) || ts.isTypeAliasDeclaration(node) || ts.isInterfaceDeclaration(node)) &&
+      isExported(node) &&
+      node.name
+    ) {
+      exportNames.add(node.name.text);
+    }
+  });
+
+  return exportNames;
+}
+
+function collectImportUsages(ast) {
+  const usages = new Map();
+
+  function visit(node) {
+    if (ts.isIdentifier(node)) {
+      const references = usages.get(node.text) ?? [];
+      references.push(node);
+      usages.set(node.text, references);
+    }
+
+    ts.forEachChild(node, visit);
+  }
+
+  visit(ast);
+  return usages;
+}
+
+function bodyLineCount(node) {
+  const sourceFile = node.getSourceFile();
+  const start = sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile)).line;
+  const end = sourceFile.getLineAndCharacterOfPosition(node.getEnd()).line;
+  return end - start + 1;
+}
+
+function nodeLineCount(node) {
+  const sourceFile = node.getSourceFile();
+  const start = sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile)).line;
+  const end = sourceFile.getLineAndCharacterOfPosition(node.getEnd()).line;
+  return end - start + 1;
+}
+
+export async function verifyTypeScriptStyle(_targetPath, contract, analysisContext, options = {}) {
+  const activeRuleIds = getActiveVerifyRuleIds(contract);
+  const issues = [];
+  const publicApiExports = collectPublicApiExports(analysisContext.sourceFilesByRelativePath.get("src/index.ts"));
+  const sectionOrder = Array.isArray(contract.profile.comment_section_blocks)
+    ? contract.profile.comment_section_blocks
+    : DEFAULT_PROFILE.comment_section_blocks;
+
+  for (const file of analysisContext.sourceFiles) {
+    const importUsages = collectImportUsages(file.ast);
+
+    ts.forEachChild(file.ast, function visit(node) {
+      if (activeRuleIds.has("no-any") && shouldRunRule(options.onlyRuleIds, "no-any") && node.kind === ts.SyntaxKind.AnyKeyword) {
+        issues.push(createIssue(contract, "no-any", file.relativePath, node, "explicit any is forbidden"));
+      }
+
+      if (
+        activeRuleIds.has("module-constant-case") &&
+        shouldRunRule(options.onlyRuleIds, "module-constant-case") &&
+        ts.isVariableStatement(node) &&
+        isTopLevelConst(node)
+      ) {
+        for (const declaration of node.declarationList.declarations) {
+          const name = getIdentifierText(declaration.name);
+          const isCanonicalConfigExport = file.relativePath === "src/config.ts" && name === "config";
+          const isCanonicalLoggerExport = file.relativePath === "src/logger.ts" && name === "logger";
+
+          if (name && !isCanonicalConfigExport && !isCanonicalLoggerExport && !MODULE_CONSTANT_PATTERN.test(name)) {
+            issues.push(
+              createIssue(
+                contract,
+                "module-constant-case",
+                file.relativePath,
+                declaration.name,
+                `module-level constants must use SCREAMING_SNAKE_CASE: ${name}`,
+              ),
+            );
+          }
+        }
+      }
+
+      if (
+        activeRuleIds.has("config-default-export-name") &&
+        shouldRunRule(options.onlyRuleIds, "config-default-export-name") &&
+        file.relativePath === "src/config.ts"
+      ) {
+        issues.push(...verifyConfigDefaultExport(contract, file));
+      }
+
+      if (
+        activeRuleIds.has("explicit-export-return-types") &&
+        shouldRunRule(options.onlyRuleIds, "explicit-export-return-types") &&
+        ((ts.isFunctionDeclaration(node) && isExported(node)) ||
+          (ts.isMethodDeclaration(node) && ts.isClassDeclaration(node.parent) && isExported(node.parent)))
+      ) {
+        const isPublicMethod =
+          !ts.isMethodDeclaration(node) || !Array.isArray(node.modifiers) || node.modifiers.every((modifier) => modifier.kind !== ts.SyntaxKind.PrivateKeyword);
+        if (isPublicMethod && !node.type) {
+          issues.push(
+            createIssue(
+              contract,
+              "explicit-export-return-types",
+              file.relativePath,
+              node.name ?? node,
+              "exported functions and public methods must declare an explicit return type",
+            ),
+          );
+        }
+      }
+
+      if (
+        activeRuleIds.has("prefer-types-over-interfaces") &&
+        shouldRunRule(options.onlyRuleIds, "prefer-types-over-interfaces") &&
+        ts.isInterfaceDeclaration(node)
+      ) {
+        const isPublicContract = isExported(node) && node.name && publicApiExports.has(node.name.text);
+        if (!isPublicContract) {
+          issues.push(
+            createIssue(contract, "prefer-types-over-interfaces", file.relativePath, node.name, "prefer type aliases over interfaces for local modeling"),
+          );
+        }
+      }
+
+      if (activeRuleIds.has("control-flow-braces") && shouldRunRule(options.onlyRuleIds, "control-flow-braces")) {
+        issues.push(...verifyControlFlowBraces(contract, file.relativePath, node));
+      }
+
+      if (
+        activeRuleIds.has("single-responsibility-heuristic") &&
+        shouldRunRule(options.onlyRuleIds, "single-responsibility-heuristic") &&
+        (ts.isFunctionDeclaration(node) || ts.isMethodDeclaration(node)) &&
+        node.body &&
+        bodyLineCount(node.body) > 30
+      ) {
+        issues.push(
+          createIssue(
+            contract,
+            "single-responsibility-heuristic",
+            file.relativePath,
+            node.name ?? node,
+            "long functions should be split when they start mixing responsibilities",
+            {
+              verificationMode: "heuristic",
+              confidence: "medium",
+              evidence: `${bodyLineCount(node.body)} body lines`,
+            },
+          ),
+        );
+      }
+
+      if (
+        activeRuleIds.has("large-class-heuristic") &&
+        shouldRunRule(options.onlyRuleIds, "large-class-heuristic") &&
+        ts.isClassDeclaration(node) &&
+        isExported(node) &&
+        nodeLineCount(node) > 400
+      ) {
+        issues.push(
+          createIssue(
+            contract,
+            "large-class-heuristic",
+            file.relativePath,
+            node.name ?? node,
+            "very large classes should be decomposed into smaller cohesive units",
+            {
+              verificationMode: "heuristic",
+              confidence: "medium",
+              evidence: `${nodeLineCount(node)} total lines`,
+              suggestion: "split the class by responsibility into smaller private methods or dedicated role-specific files",
+            },
+          ),
+        );
+      }
+
+      ts.forEachChild(node, visit);
+    });
+
+    if (activeRuleIds.has("local-constant-case") && shouldRunRule(options.onlyRuleIds, "local-constant-case")) {
+      issues.push(...verifyLocalConstants(contract, file));
+    }
+
+    if (activeRuleIds.has("type-only-imports") && shouldRunRule(options.onlyRuleIds, "type-only-imports")) {
+      issues.push(...verifyTypeOnlyImports(contract, file, importUsages));
+    }
+
+    if (activeRuleIds.has("comments-policy-audit") && shouldRunRule(options.onlyRuleIds, "comments-policy-audit") && file.relativePath.startsWith("src/")) {
+      issues.push(...verifyCommentsAudit(contract, file, sectionOrder));
+    }
+  }
+
+  return issues;
+}
+
+function isTopLevelConst(node) {
+  return ts.isSourceFile(node.parent) && node.declarationList.flags & ts.NodeFlags.Const;
+}
+
+function verifyLocalConstants(contract, file) {
+  const issues = [];
+
+  function visit(node) {
+    if (ts.isVariableDeclaration(node) && node.parent && ts.isVariableDeclarationList(node.parent) && node.parent.flags & ts.NodeFlags.Const) {
+      const isTopLevel = ts.isVariableStatement(node.parent.parent) && ts.isSourceFile(node.parent.parent.parent);
+      const name = getIdentifierText(node.name);
+      if (!isTopLevel && name && !CAMEL_CASE_PATTERN.test(name)) {
+        issues.push(createIssue(contract, "local-constant-case", file.relativePath, node.name, `local constants must use camelCase: ${name}`));
+      }
+    }
+
+    ts.forEachChild(node, visit);
+  }
+
+  visit(file.ast);
+  return issues;
+}
+
+function verifyConfigDefaultExport(contract, file) {
+  const issues = [];
+  let hasNamedConfigDeclaration = false;
+  let hasDefaultExportConfig = false;
+
+  for (const statement of file.ast.statements) {
+    if (ts.isVariableStatement(statement)) {
+      for (const declaration of statement.declarationList.declarations) {
+        if (getIdentifierText(declaration.name) === "config") {
+          hasNamedConfigDeclaration = true;
+        }
+      }
+    }
+
+    if (ts.isExportAssignment(statement) && ts.isIdentifier(statement.expression) && statement.expression.text === "config") {
+      hasDefaultExportConfig = true;
+    }
+  }
+
+  if (!hasNamedConfigDeclaration || !hasDefaultExportConfig) {
+    issues.push(
+      createIssue(
+        contract,
+        "config-default-export-name",
+        file.relativePath,
+        file.ast,
+        "src/config.ts must declare `config` and export it as `export default config`",
+      ),
+    );
+  }
+
+  return issues;
+}
+
+function verifyControlFlowBraces(contract, relativePath, node) {
+  const issues = [];
+
+  if (ts.isIfStatement(node)) {
+    if (!ts.isBlock(node.thenStatement)) {
+      issues.push(createIssue(contract, "control-flow-braces", relativePath, node.thenStatement, "if branches must use braces"));
+    }
+
+    if (node.elseStatement && !ts.isBlock(node.elseStatement)) {
+      issues.push(createIssue(contract, "control-flow-braces", relativePath, node.elseStatement, "else branches must use braces"));
+    }
+  }
+
+  if (
+    (ts.isForStatement(node) || ts.isForInStatement(node) || ts.isForOfStatement(node) || ts.isWhileStatement(node) || ts.isDoStatement(node)) &&
+    !ts.isBlock(node.statement)
+  ) {
+    issues.push(createIssue(contract, "control-flow-braces", relativePath, node.statement, "loop bodies must use braces"));
+  }
+
+  return issues;
+}
+
+function verifyTypeOnlyImports(contract, file, importUsages) {
+  const issues = [];
+
+  for (const statement of file.ast.statements) {
+    if (!ts.isImportDeclaration(statement) || !statement.importClause || statement.importClause.isTypeOnly) {
+      continue;
+    }
+
+    const importedIdentifiers = [];
+
+    if (statement.importClause.name) {
+      importedIdentifiers.push(statement.importClause.name.text);
+    }
+
+    if (statement.importClause.namedBindings && ts.isNamedImports(statement.importClause.namedBindings)) {
+      for (const element of statement.importClause.namedBindings.elements) {
+        importedIdentifiers.push(element.name.text);
+      }
+    }
+
+    for (const importedIdentifier of importedIdentifiers) {
+      const identifierUsages = (importUsages.get(importedIdentifier) ?? []).filter(
+        (node) => !ts.isImportClause(node.parent) && !ts.isImportSpecifier(node.parent) && !ts.isNamespaceImport(node.parent),
+      );
+      if (identifierUsages.length > 0 && identifierUsages.every((node) => isTypePosition(node))) {
+        issues.push(
+          createIssue(
+            contract,
+            "type-only-imports",
+            file.relativePath,
+            statement,
+            `import used only in type positions must use import type: ${importedIdentifier}`,
+          ),
+        );
+      }
+    }
+  }
+
+  return issues;
+}
+
+function verifyCommentsAudit(contract, file, sectionOrder) {
+  const issues = [];
+  const hasSections = sectionOrder.some((section) => file.raw.includes(`@section ${section}`));
+  const complexSignals = ["if (", "switch (", "try {", ".map(", ".reduce(", ".filter("].filter((token) => file.raw.includes(token)).length;
+  const commentSignal = /\/\//.test(file.raw) || /\/\*/.test(file.raw);
+
+  if (complexSignals >= 3 && !commentSignal && !hasSections) {
+    issues.push(
+      createIssue(
+        contract,
+        "comments-policy-audit",
+        file.relativePath,
+        file.ast,
+        "non-trivial logic should include explicit comments under the active comments policy",
+        {
+          verificationMode: "audit",
+          confidence: "medium",
+        },
+      ),
+    );
+  }
+
+  return issues;
+}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@sha3/code",
+  "version": "1.0.0",
+  "description": "AI-first code standards, tooling exports, and project initializer",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/sha3dev/code"
+  },
+  "bin": {
+    "code-standards": "./bin/code-standards.mjs"
+  },
+  "exports": {
+    ".": "./index.mjs",
+    "./biome": "./biome.json",
+    "./tsconfig/base.json": "./tsconfig/base.json",
+    "./tsconfig/node-lib.json": "./tsconfig/node-lib.json",
+    "./tsconfig/node-service.json": "./tsconfig/node-service.json"
+  },
+  "files": ["AGENTS.md", "README.md", "ai", "biome.json", "bin", "index.mjs", "lib", "prompts", "resources", "standards", "templates", "tsconfig", "profiles"],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20.11.0"
+  },
+  "scripts": {
+    "check": "npm run standards:validate && npm run profile:validate && npm run ai:validate && npm run lint && npm run format:check && npm run typecheck && npm run test",
+    "fix": "npm run lint:fix && npm run format:write",
+    "standards:validate": "node scripts/validate-standards.mjs",
+    "ai:validate": "node scripts/validate-ai-resources.mjs",
+    "lint": "biome check .",
+    "lint:fix": "biome check . --write",
+    "format:check": "biome format .",
+    "format:write": "biome format . --write",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "node scripts/smoke-fixtures.mjs && node --test ./test/*.test.mjs",
+    "release:check": "npm run check",
+    "release:publish": "node scripts/release-publish.mjs",
+    "hooks:install": "git config core.hooksPath .githooks",
+    "profile:validate": "node scripts/validate-profile.mjs"
+  },
+  "dependencies": {
+    "@biomejs/biome": "^1.9.4",
+    "ajv": "^8.17.1"
+  },
+  "devDependencies": {
+    "@hono/node-server": "^1.19.11",
+    "@sha3/logger": "^2.0.0",
+    "@types/node": "^22.13.10",
+    "hono": "^4.12.7",
+    "typescript": "^5.8.2",
+    "tsx": "^4.19.3"
+  }
+}

package/profiles/default.profile.json

@@ -0,0 +1,40 @@
+{
+  "version": "v2",
+  "paradigm": "class-first",
+  "function_size_policy": "max_30_lines_soft",
+  "return_policy": "single_return_strict_no_exceptions",
+  "class_design": "constructor_injection",
+  "comments_policy": "extensive",
+  "testing_policy": "tests_required_for_behavior_change",
+  "architecture": "feature_folders",
+  "error_handling": "mixed",
+  "async_style": "async_await_only",
+  "class_file_policy": "one_public_class_per_file",
+  "type_contract_policy": "prefer_types_over_interfaces",
+  "mutability": "immutability_preferred",
+  "comment_section_blocks": [
+    "imports:externals",
+    "imports:internals",
+    "consts",
+    "types",
+    "class",
+    "private:attributes",
+    "protected:attributes",
+    "public:properties",
+    "constructor",
+    "static:properties",
+    "factory",
+    "private:methods",
+    "protected:methods",
+    "public:methods",
+    "static:methods"
+  ],
+  "comment_section_format": "jsdoc-section-tag",
+  "comment_sections_required_when_empty": false,
+  "if_requires_braces": true,
+  "readme_style": "top-tier",
+  "rule_severity_model": "tiered",
+  "language": "english_technical",
+  "examples_density": "rule_with_good_bad_examples",
+  "instruction_file_location": "root_agents_md"
+}

package/profiles/schema.json

@@ -0,0 +1,96 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://sha3.dev/code/profile.schema.json",
+  "title": "AI Style Profile",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "version",
+    "paradigm",
+    "function_size_policy",
+    "return_policy",
+    "class_design",
+    "comments_policy",
+    "testing_policy",
+    "architecture",
+    "error_handling",
+    "async_style",
+    "class_file_policy",
+    "type_contract_policy",
+    "mutability",
+    "comment_section_blocks",
+    "comment_section_format",
+    "comment_sections_required_when_empty",
+    "if_requires_braces",
+    "readme_style",
+    "rule_severity_model",
+    "language",
+    "examples_density",
+    "instruction_file_location"
+  ],
+  "properties": {
+    "version": { "type": "string", "const": "v2" },
+    "paradigm": { "type": "string", "enum": ["class-first", "functional-first", "hybrid"] },
+    "function_size_policy": { "type": "string", "enum": ["max_20_lines_hard", "max_30_lines_soft", "no_fixed_limit"] },
+    "return_policy": { "type": "string", "enum": ["single_return_strict_no_exceptions", "single_return_with_guard_clauses", "free_return_style"] },
+    "class_design": { "type": "string", "enum": ["constructor_injection", "internal_instantiation", "mixed"] },
+    "comments_policy": { "type": "string", "enum": ["extensive", "complex_logic_only", "minimal"] },
+    "testing_policy": { "type": "string", "enum": ["tests_required_for_behavior_change", "tests_critical_only", "tests_optional"] },
+    "architecture": { "type": "string", "enum": ["feature_folders", "layered", "simple_src_lib"] },
+    "error_handling": { "type": "string", "enum": ["exceptions_with_typed_errors", "result_either", "mixed"] },
+    "async_style": { "type": "string", "enum": ["async_await_only", "promise_chains", "both"] },
+    "class_file_policy": { "type": "string", "enum": ["one_public_class_per_file", "multiple_classes_allowed", "no_rule"] },
+    "type_contract_policy": { "type": "string", "enum": ["prefer_types_over_interfaces", "interfaces_everywhere", "interfaces_public_only"] },
+    "mutability": { "type": "string", "enum": ["immutability_preferred", "immutability_strict", "mutable_pragmatic"] },
+    "comment_section_blocks": {
+      "type": "array",
+      "minItems": 15,
+      "maxItems": 15,
+      "items": {
+        "type": "string",
+        "enum": [
+          "imports:externals",
+          "imports:internals",
+          "consts",
+          "types",
+          "class",
+          "private:attributes",
+          "protected:attributes",
+          "public:properties",
+          "constructor",
+          "static:properties",
+          "factory",
+          "private:methods",
+          "protected:methods",
+          "public:methods",
+          "static:methods"
+        ]
+      },
+      "const": [
+        "imports:externals",
+        "imports:internals",
+        "consts",
+        "types",
+        "class",
+        "private:attributes",
+        "protected:attributes",
+        "public:properties",
+        "constructor",
+        "static:properties",
+        "factory",
+        "private:methods",
+        "protected:methods",
+        "public:methods",
+        "static:methods"
+      ]
+    },
+    "comment_section_format": { "type": "string", "const": "jsdoc-section-tag" },
+    "comment_sections_required_when_empty": { "type": "boolean" },
+    "if_requires_braces": { "type": "boolean", "const": true },
+    "readme_style": { "type": "string", "const": "top-tier" },
+    "rule_severity_model": { "type": "string", "enum": ["tiered", "all_preferred"] },
+    "language": { "type": "string", "enum": ["english_technical", "spanish_technical", "bilingual"] },
+    "examples_density": { "type": "string", "enum": ["rule_with_good_bad_examples", "rules_only", "rules_plus_long_templates"] },
+    "instruction_file_location": { "type": "string", "enum": ["root_agents_md", "ai_instructions_md", "both"] }
+  }
+}

package/prompts/init-contract.md

@@ -0,0 +1,25 @@
+## Init Contract
+
+Use this contract during implementation and verification phases, not as phase-1 planning input unless the plan proves it is necessary.
+
+- This workflow is an init-based implementation. You MUST load `skills/init-workflow/SKILL.md` and follow it as the primary procedural guide for execution order and reporting.
+- You MUST load `skills/feature-shaping/SKILL.md`, `skills/simplicity-audit/SKILL.md`, and `skills/change-synchronization/SKILL.md` as part of the default init workflow.
+- If the task introduces meaningful behavior changes, you MUST load `skills/test-scope-selection/SKILL.md`.
+- You MUST preserve the scaffold structure and naming conventions.
+- You MUST add or update tests for behavior changes.
+- In class-oriented source files, you MUST keep helper logic inside the class as private or static methods rather than module-scope functions.
+- You MUST split oversized classes into smaller cohesive units instead of keeping large monolithic class files.
+- If the task creates or updates `README.md`, you MUST load `skills/readme-authoring/SKILL.md` and follow it.
+- If the project is a `node-service` or the task changes HTTP endpoints, you MUST load `skills/http-api-conventions/SKILL.md` and follow its transport conventions.
+- You MUST execute `npm run standards:check` yourself, fix every `error`, review every `warning`, report every `audit` item, and rerun until the default verification passes.
+- You MUST let Biome decide final layout and wrapping.
+- You MUST execute `npm run check` yourself before finishing.
+- If `npm run check` fails, you MUST fix the issues and rerun it until it passes.
+- As the final step, you MUST create or update `SCAFFOLD-FEEDBACK.md` in the project root with concrete feedback about scaffold problems, unclear instructions, friction, missing patterns, and suggested improvements.
+
+When you respond after implementation, include:
+
+- changed files
+- a short compliance checklist
+- proof that `npm run check` passed
+- confirmation that `SCAFFOLD-FEEDBACK.md` was created or updated

package/prompts/init-phase-2-implement.md

@@ -0,0 +1,25 @@
+This is phase 2 of the init workflow. Implement the task now.
+
+Read only:
+
+- `PROMPT.md`
+- `prompts/init-contract.md`
+- the plan you produced in phase 1
+- the files you identified as necessary during phase 1
+
+Load optional skills only if they are actually needed for the approved plan:
+
+- `skills/test-scope-selection/SKILL.md` for meaningful behavior changes
+- `skills/readme-authoring/SKILL.md` when `README.md` changes
+- `skills/http-api-conventions/SKILL.md` for `node-service` projects or HTTP endpoint work
+
+Execution rules:
+
+- Follow `prompts/init-contract.md` and `skills/init-workflow/SKILL.md`.
+- Keep the scaffold-native structure unless the request explicitly requires a standards update.
+- Inspect more files only when the approved plan proves they are necessary.
+- Implement the smallest correct change in `src/` and `test/`.
+- Rewrite `README.md` only after behavior is stable.
+- Do not stop at the end of this phase unless blocked.
+
+At the end of this phase, summarize internally what changed, note any unresolved risks that matter for verification, and continue directly into `prompts/init-phase-3-verify.md`.

package/prompts/init-phase-3-verify.md

@@ -0,0 +1,23 @@
+This is phase 3 of the init workflow. Verify and close the task.
+
+Read only:
+
+- `PROMPT.md`
+- `prompts/init-contract.md`
+- your phase 2 implementation summary
+- the files changed during implementation
+- the latest command output that shows current verification status
+
+Execution rules:
+
+- Run the remaining required verification, including `npm run check`.
+- If verification fails, fix the issues and rerun until it passes.
+- Create or update `SCAFFOLD-FEEDBACK.md` as the final project artifact.
+- Keep the final response concise and evidence-based.
+
+Your final response must include:
+
+1. Changed files.
+2. A short compliance checklist.
+3. Proof that `npm run check` passed.
+4. Confirmation that `SCAFFOLD-FEEDBACK.md` was created or updated.