valent-pipeline 0.19.24 → 0.19.26

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "valent-pipeline",
-  "version": "0.19.24",
+  "version": "0.19.26",
   "description": "v3 multi-agent AI pipeline for software development lifecycle",
   "type": "module",
   "bin": {

package/pipeline/schemas/qa-spec-manifest.schema.json

@@ -39,7 +39,7 @@
             "items": { "type": "string" },
             "description": "Distinctive tokens that MUST appear verbatim in the implementing test code (Step 9b)."
           },
-          "required": { "type": "boolean", "description": "Defaults true; false = gate warns instead of failing, and a skip of this case is auto-waived." },
+          "required": { "type": "boolean", "description": "Defaults true (behavioral case: must FAIL at the red gate, PASS at green). false = exempt from the red-required set (gate warns instead of failing) and skip auto-waived — use for a regression-guard asserting an already-satisfied infrastructure invariant the story must not regress (already green at red-time; would pass on an empty checkout). See steps/qa-a/write-acceptance-tests.md; CRITIC's acceptance audit flags behavioral cases mislabeled required:false." },
           "ac": {
             "type": "array",
             "minItems": 1,

package/pipeline/steps/critic/acceptance-audit.md

@@ -21,6 +21,13 @@ For EACH test case in qa-test-spec.md:
 2. Are the assertions as strong as the spec requires? (No weakening — present-but-inert tokens, shape-only checks, status-only error checks.)
 3. Is database state verification present where the spec requires it?
 
+## Regression-guard honesty (`required: false` cases)
+
+For EACH acceptance case marked `required: false` in `qa-test-spec.manifest.json`:
+1. Does it genuinely assert only an **already-satisfied infrastructure invariant** (a config/harness/convention established by a prior story/epic that this story must not regress)? Or is it a **behavioral** case for THIS story's new work, mislabeled non-required to dodge the red gate?
+2. The test of intent: would an empty checkout of this story's branch (no implementation) make the case pass? If yes, it is a legitimate invariant-guard. If it should only pass *after* this story's code lands, it is behavioral and must be `required: true`.
+3. A behavioral case marked `required: false` is a spec cheat — it lets unbuilt behavior ship without ever proving red→green. Flag it HIGH: the red gate is blind to it.
+
 ## Output
 
 Record every finding in the Pass 3 table. Assign preliminary severity.

package/pipeline/steps/qa-a/write-acceptance-tests.md

@@ -6,7 +6,7 @@
 
 The acceptance test IS the spec and (after the green gate) the proof. You author it **before any implementation exists**, and the pipeline enforces the red-green mechanism around it:
 
-- The **RED gate** runs your suite pre-implementation and every required acceptance case must RUN and FAIL. A case that passes against an empty repo is a spec bug (gameable assertion or wrong expectation) and bounces straight back to you.
+- The **RED gate** runs your suite pre-implementation and every *required* acceptance case must RUN and FAIL. A case that passes against an empty repo is a spec bug (gameable assertion or wrong expectation) and bounces straight back to you — **unless** it only asserts an already-satisfied infrastructure invariant, which you mark `required: false` (Step C). Those are regression-guards: exempt from red, still asserted at green.
 - Your test files are then **frozen by hash**. Dev agents cannot edit them — any change auto-REJECTs to you for arbitration. The implementation must come to the tests; the tests never go to the implementation.
 - The **GREEN gate** re-runs the suite post-implementation; red evidence + green evidence + the diff SHA become the story's proof object (`proof.json`).
 
@@ -29,15 +29,24 @@ The Live Smoke Test tables (`api` profile) and UI Integration Smoke rows (`ui` p
 
 Run the suite once via the configured command. Verify every new test **executes and fails for the behavioral reason you expect** (assertion/404/missing element). Fix syntax/import/collection errors now — `missing-at-red` failures at the gate waste a rework cycle. On greenfield story 1 where the framework cannot run at all yet, note it: the red gate records `mode: weak` and the green gate compensates.
 
-## Step C: Manifest entries
+## Step C: Manifest entries — classify each case (behavioral vs invariant-guard)
 
-In `qa-test-spec.manifest.json` (Step 10), each acceptance case carries:
+In `qa-test-spec.manifest.json` (Step 10), each acceptance case carries a `required` flag. **It is not boilerplate — it encodes whether the case can honestly go red:**
+
+- **Behavioral case** (`required: true`, the default) — asserts the NEW behavior this story builds. It MUST fail pre-implementation (an empty/old checkout cannot satisfy it) and pass post-implementation. This is the red→green case.
+- **Invariant-guard case** (`required: false`) — asserts a cross-cutting infrastructure invariant **already established by a prior story/epic** that this story must not regress: e.g. `vitest pool: 'forks'`, a `tests/setup.ts` mock harness, an ESLint rule's presence, ESM `.js` import conventions, an existing directory contract. It is **already green at red-time** (the infra exists on the branch), so forcing it into the red-required set makes red dishonest — the gate rejects it as `premature-pass` and blocks the story with zero implementation done. Mark it `required: false`: still executed and asserted at the GREEN gate (the guard still fires on a regression), but EXEMPT from the red-required set. **Do not delete or weaken the guard — just mark it non-required so red is honest.**
 
 ```json
 { "id": "TC-3.4", "kind": "acceptance", "testFile": "tests/acceptance/{story_id}/cards.spec.ts",
   "tier": "e2e", "priority": "P0", "assertionTargets": ["422", "cards.title"], "required": true, "ac": ["AC-3"] }
+{ "id": "TC-6.1", "kind": "acceptance", "testFile": "tests/acceptance/{story_id}/determinism.spec.ts",
+  "tier": "integration", "priority": "P1", "assertionTargets": ["forks", "isolate"], "required": false, "ac": ["AC-6"] }
 ```
 
+The second case is a regression-guard — it asserts a pre-existing determinism/isolation invariant, so it is `required: false`.
+
+**Litmus test:** if an empty checkout of this story's branch (no implementation) would make the case PASS, it is an invariant-guard → `required: false`. Everything testing what *this* story adds stays `required: true`. Misclassifying a behavioral case as a guard to dodge red is a spec cheat — CRITIC's acceptance audit checks for it, so the only thing you buy by cheating is a rejection.
+
 plus the manifest-level `"files": [...]` list naming EVERY file you wrote (tests + helpers). Cases the dev should implement as unit/integration tests keep `kind: "unit-spec"` (or omit `kind`) — those remain specs, and the dev writes them.
 
 ## Step D: What remains prose

package/pipeline/templates/eslint.config.standard.mjs

@@ -0,0 +1,107 @@
+// valent-pipeline — STANDARD hardened ESLint baseline.
+// Seeded by `valent-pipeline init` into TypeScript projects that have NO ESLint config of their own;
+// it never overwrites an existing one. This is the universal base — add project-specific guards in
+// your own block.
+//
+// What it enforces (ONE `eslint .` pass, prod vs tests differentiated by file glob):
+//   • Strict TypeScript correctness — typescript-eslint `strict`, the hardest SYNTACTIC tier — on
+//     production code AND tests (a broken test is false confidence).
+//   • Maintainability caps (complexity / depth / length) on PRODUCTION code only — off for tests,
+//     where long/repetitive is fine.
+//
+// Requires (devDependencies — the standard uses NO others):
+//   eslint  @typescript-eslint/parser  @typescript-eslint/eslint-plugin
+// Recommended package.json scripts:
+//   "lint": "eslint . --max-warnings 0"      "typecheck": "tsc --noEmit"
+// Make them a blocking gate by adding both to pipeline-config.yaml `pre_critic_gate.commands`.
+//
+// Project-specific guards (e.g. banning Math.random for deterministic sims, NodeNext import-extension
+// rules, module-boundary guards) are intentionally NOT here — add them in your own config block.
+// Type-aware rules (no-floating-promises, …) are the fast-follow — see the commented block at the bottom.
+
+import tseslint from '@typescript-eslint/eslint-plugin';
+import tsParser from '@typescript-eslint/parser';
+
+// CORRECTNESS — applies to prod AND tests. STRICT = hardest syntactic tier (recommended spread first
+// so the base set is present even if strict's `.rules` is delta-only).
+const correctness = {
+  ...tseslint.configs.recommended.rules,
+  ...tseslint.configs.strict.rules,
+  '@typescript-eslint/no-explicit-any': 'error',
+  '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_' }],
+  eqeqeq: ['error', 'smart'],
+  'no-var': 'error',
+  'prefer-const': 'error',
+  'no-loop-func': 'error',
+  '@typescript-eslint/no-empty-function': 'error',
+};
+
+// MAINTAINABILITY — PRODUCTION code only (off for tests). Caps start strict; loosen per project if a
+// codebase legitimately needs it, or tighten over time.
+const maintainability = {
+  complexity: ['error', { max: 10 }],
+  'max-depth': ['error', { max: 3 }],
+  'max-lines-per-function': ['error', { max: 100, skipBlankLines: true, skipComments: true }],
+  'max-lines': ['error', { max: 500, skipBlankLines: true, skipComments: true }],
+  'no-console': ['error', { allow: ['warn', 'error'] }],
+  'no-warning-comments': ['error', { terms: ['fixme', 'xxx', 'hack'], location: 'anywhere' }],
+  'func-names': ['error', 'as-needed'],
+};
+
+// Lenient naming convention — enforces common casing without fighting external/snake_case APIs.
+const naming = ['error',
+  { selector: 'default', format: ['camelCase'], leadingUnderscore: 'allow' },
+  { selector: 'variable', format: ['camelCase', 'PascalCase', 'UPPER_CASE'], leadingUnderscore: 'allow' },
+  { selector: 'typeLike', format: ['PascalCase'] },
+  { selector: 'enumMember', format: ['PascalCase', 'UPPER_CASE'] },
+  { selector: 'parameter', format: ['camelCase'], leadingUnderscore: 'allow' },
+  { selector: 'variable', modifiers: ['destructured'], format: null },
+  { selector: 'objectLiteralProperty', format: null },
+];
+
+const tsLang = { parser: tsParser, parserOptions: { ecmaVersion: 2022, sourceType: 'module', ecmaFeatures: { jsx: true } } };
+
+export default [
+  {
+    ignores: ['dist/**', 'build/**', 'node_modules/**', 'coverage/**', 'test-results/**',
+      '.valent-pipeline/**', 'stories/**', 'knowledge/**', '**/*.config.{js,cjs,mjs,ts}'],
+  },
+
+  // ── PRODUCTION code: strict correctness + maintainability + naming ──
+  {
+    files: ['**/*.ts', '**/*.tsx'],
+    languageOptions: tsLang,
+    plugins: { '@typescript-eslint': tseslint },
+    rules: {
+      ...correctness,
+      ...maintainability,
+      '@typescript-eslint/naming-convention': naming,
+    },
+  },
+
+  // ── TESTS (dedicated + colocated): correctness ONLY — size/cosmetics off. MUST stay last. ──
+  {
+    files: ['tests/**/*.ts', 'tests/**/*.tsx', '**/*.test.ts', '**/*.test.tsx', '**/*.spec.ts', '**/*.spec.tsx'],
+    languageOptions: tsLang,
+    plugins: { '@typescript-eslint': tseslint },
+    rules: {
+      ...correctness,
+      complexity: 'off',
+      'max-depth': 'off',
+      'max-lines': 'off',
+      'max-lines-per-function': 'off',
+      'no-console': 'off',
+      'func-names': 'off',
+      'no-warning-comments': 'off',
+      '@typescript-eslint/no-non-null-assertion': 'off', // `!` is idiomatic in test assertions
+    },
+  },
+];
+
+/* ════ TYPE-AWARE FAST-FOLLOW — the eventual ceiling (strict-type-checked). Requires type info.
+   After `npm i -D typescript-eslint` (the unified pkg) and a tsconfig that includes your source:
+     • PRODUCTION block: parserOptions.projectService = true; spread ...strictTypeChecked (scoped) —
+       adds no-floating-promises, no-misused-promises, await-thenable, no-unnecessary-condition, …
+     • TESTS block: add '@typescript-eslint/no-floating-promises':'error' + no-misused-promises — the
+       highest-value test rules (they catch false-green un-awaited async assertions).
+   Needs a typescript-eslint release that supports your TypeScript major. ════ */

package/src/commands/init.js

@@ -105,6 +105,27 @@ export async function init(options = {}) {
     console.log('  Created knowledge/correction-directives.yaml');
   }
 
+  // 6b. Seed the standard hardened ESLint config for TypeScript projects — inherited ONLY when the
+  //     project has no ESLint config of its own (never clobbers an existing setup). The standard uses
+  //     just @typescript-eslint/{parser,eslint-plugin}; see the config header for the lint/typecheck
+  //     scripts to wire into pre_critic_gate.commands.
+  const projectLanguage = (config.tech_stack?.language || 'TypeScript').toLowerCase();
+  const isTsProject = projectLanguage.includes('typescript') || /\bts\b/.test(projectLanguage);
+  if (isTsProject) {
+    const eslintConfigNames = [
+      'eslint.config.js', 'eslint.config.mjs', 'eslint.config.cjs', 'eslint.config.ts',
+      '.eslintrc', '.eslintrc.js', '.eslintrc.cjs', '.eslintrc.json', '.eslintrc.yml', '.eslintrc.yaml',
+    ];
+    const hasEslintConfig = eslintConfigNames.some((n) => fileExists(join(projectRoot, n)));
+    const stdEslintSrc = join(PACKAGE_ROOT, 'pipeline', 'templates', 'eslint.config.standard.mjs');
+    if (hasEslintConfig) {
+      console.log('  ESLint config already present — kept the project\'s own (standard not seeded)');
+    } else if (existsSync(stdEslintSrc)) {
+      writeFileSafe(join(projectRoot, 'eslint.config.mjs'), readFileSync(stdEslintSrc, 'utf-8'));
+      console.log('  Seeded standard hardened ESLint config -> eslint.config.mjs');
+    }
+  }
+
   // 7. Write the vendored CLI's runtime package.json and install its deps. The CLI needs
   //    commander/yaml/ajv to run AT ALL (resolve-graph, validate-handoff, sprint-pack, …);
   //    sqlite knowledge mode additionally needs better-sqlite3 (FTS5 is compiled in — the whole