@magnusekdahl/parallix 1.1.1 → 1.2.0

package/config/integration-pipelines.json

@@ -0,0 +1,9 @@
+{
+  "gates": {
+    "lib": {
+      "command": "./scripts/verify-local.sh static-analysis",
+      "order": 1,
+      "run_last": false
+    }
+  }
+}

package/docs/adr/0032-mission-refinement-state-and-usage-budget-signals.md

@@ -55,22 +55,23 @@ Also adopt one explicit place for selection metadata:
 
 `## Refinement Signals` must contain:
 
-- `Estimated agent % usage limit`: one of `0-25%`, `25-50%`, `50-75%`, `75-100%`, `100%+`
+- `Predicted NEL bucket`: one of `Small (0–80)`, `Medium (81–235)`, `Large (235+)` per ADR 0047
 - `Confidence`: `High`, `Medium`, or `Low`
 - `Selection note`: `activate as-is`, `split first`, or `defer`, with one short reason
 - `Main drivers`: the 2-4 factors driving the estimate
 
-Interpretation rule for `% usage limit`:
+Interpretation rule for NEL bucket:
 
-- it is an approximate share of a meaningful AI-assisted execution budget under the current repo workflow
+- it is an approximate measure of engineering change volume (insertions + deletions, whitespace-ignored) for the mission's merge diff against the primary branch
 - it may reflect scope breadth, trust-tier sensitivity, validation burden, review/handoff overhead, context churn, and cross-surface coupling
 - it is a selection aid, not a delivery promise or pseudo-scientific schedule estimate
+- NEL is computed by the reusable `nels` module (`lib/core/nels.js`) which excludes workflow/bookkeeping files per ADR 0047
 
 Default activation guidance:
 
-- `0-25%` or `25-50%`: normally safe to activate as-is when confidence is not low
-- `50-75%`: split first unless the mission is unusually high leverage and already sharply bounded
-- `75-100%` or `100%+`: defer or split before activation under normal conditions
+- `Small (0–80)`: normally safe to activate as-is when confidence is not low
+- `Medium (81–235)`: split first unless the mission is unusually high leverage and already sharply bounded
+- `Large (235+)`: defer or split before activation under normal conditions
 - if confidence is `Low`, keep refining instead of treating the estimate as reliable enough for pickup
 
 Current rollout blocker:
@@ -84,14 +85,14 @@ Current rollout blocker:
 
 - The workflow now distinguishes "not ready yet" from "ready, but not yet started."
 - Mission comparison becomes more deliberate because shovel-ready candidates can be compared without immediately activating them.
-- The `% usage limit` signal is lightweight enough to aid selection without creating a second planning system.
+- The NEL bucket signal is lightweight enough to aid selection without creating a second planning system.
 - `MISSION.md` remains the detailed execution contract while Backlog stays the current-state surface.
 
 ### Negative
 
 - The lifecycle gains one more state conceptually, so operators must learn one more transition.
 - Some older workflow docs and historical artifacts will continue to mention the earlier five-state model.
-- `% usage limit` still depends on judgment and may drift if agents stop recording the main drivers behind the estimate.
+- NEL bucket estimates still depend on judgment and may drift if agents stop recording the main drivers behind the estimate.
 
 ## Alternatives Considered
 
@@ -132,4 +133,5 @@ Negative:
 ## Links
 
 - [ADR 0026](0026-ai-task-state-and-agent-recovery-surface.md)
+- [ADR 0047: Per-Mission Change Size Budget](0047-per-mission-change-size-budget.md) — NEL bucket definitions and exclusion globs
 - [Mission](../missions/2026/task-024-mission-complexity-estimation/MISSION.md)

package/docs/adr/0036-mission-sizing-and-dependency-wave-heuristics.md

@@ -18,21 +18,21 @@ Introduce three sizing tracks and a dependency-wave planning heuristic.
 
 ### 1. Sizing Tracks
 
-| Track | Scope | Process | Agent Budget |
-|-------|-------|---------|--------------|
-| **Quick Flow** | < 3 files, < 2h estimated, or docs-only. | Minimal `MISSION.md` (Goal, Why Now, Refinement Signals, Gates). Skip detailed checkpoints if straightforward. | < 10% of agent limit |
-| **Full Method** | > 3 files, complex logic, or > 2h. | Standard `MISSION.md` with all sections. Detailed checkpoints. Mandatory external review (C2 review remains required for sensitive scopes per AGENTS.md). | 10-50% of agent limit |
-| **Multi-Wave** | Very large, high risk, or complex dependencies. | Split into multiple `Full Method` missions (waves). | Total > 50% (requiring split) |
+| Track | Scope | Process | NEL Budget |
+|-------|-------|---------|------------|
+| **Quick Flow** | < 3 files, < 2h estimated, or docs-only. | Minimal `MISSION.md` (Goal, Why Now, Refinement Signals, Gates). Skip detailed checkpoints if straightforward. | 0–80 NEL (Small) |
+| **Full Method** | > 3 files, complex logic, or > 2h. | Standard `MISSION.md` with all sections. Detailed checkpoints. Mandatory external review (C2 review remains required for sensitive scopes per AGENTS.md). | 81–235 NEL (Medium) |
+| **Multi-Wave** | Very large, high risk, or complex dependencies. | Split into multiple `Full Method` missions (waves). | 235+ NEL (Large) |
 
-### 2. "Too Large" Thresholds by Agent
+### 2. "Too Large" Thresholds
 
-A mission is "Too Large" if its `Estimated agent % usage limit` exceeds the following thresholds per session/work-unit:
+A mission is "Too Large" for single-wave execution when its predicted NEL bucket exceeds the following thresholds:
 
-- **Claude**: > 50% of daily limit.
-- **Codex**: > 25% of weekly limit.
-- **Gemini**: > 50% of the reasonable session/context budget (approx. 50k-100k tokens for execution).
+- **Small (0–80 NEL)**: suitable for Quick Flow; no decomposition needed.
+- **Medium (81–235 NEL)**: suitable for Full Method; consider splitting if dependencies are complex.
+- **Large (235+ NEL)**: MUST be split into dependency waves before activation.
 
-Missions exceeding these thresholds MUST be split into dependency waves before activation.
+These thresholds are derived from empirical terciles in task-1355 data (n=29 missions) as documented in ADR 0047. Missions exceeding these thresholds MUST be split into dependency waves before activation.
 
 ### 3. Dependency-Wave Heuristic
 
@@ -70,10 +70,12 @@ Agents MUST assign themselves to a task in `Backlog.md` before beginning work in
 - Improved visibility of parallel work via mandatory assignment.
 
 ### Negative
+
 - Requires upfront estimation effort during the `draft` phase.
-- Agents must learn to judge their own usage limits accurately.
+- Agents must estimate NEL buckets, which requires understanding the exclusion rules from ADR 0047.
 
 ## Links
 - [ADR 0032](0032-mission-refinement-state-and-usage-budget-signals.md)
+- [ADR 0047: Per-Mission Change Size Budget](0047-per-mission-change-size-budget.md) — NEL bucket definitions and exclusion globs
 - [MISSION_FLOW.md](../../MISSION_FLOW.md)
 - [AGENTS.md](../../AGENTS.md)

package/docs/adr/0041-integration-pipeline-gates.md

@@ -145,7 +145,7 @@ Option B (Forgejo Actions) would require runner credentials for docker push and
 
 ## Deliverables
 
-1. **Repo-side config:** `config/integration-pipelines.json` with entries for `server`, `auth-server`, `web-client`, `web-e2e`; `web-e2e` carries `run_last: true`
+1. **Repo-side config:** `config/integration-pipelines.json` with entries for `server`, `auth-server`, `web-client`, `web-e2e`; `web-e2e` carries `run_last: true`. Task-1362 added a `lib` entry mapping to `./scripts/verify-local.sh static-analysis` as a required gate for `lib/` changes.
 2. **Change detection:** Compute the set of top-level dirs touched by `mission/<slug>` vs the primary branch
 3. **Dispatch in `scripts/verify-local.sh`:** New `gate_integrate()` function and `integrate` area in the case statement
 4. **`node workflow integrate` preflight:** Calls the new `integrate` area as part of `printIntegrationPreflight`

package/lib/commands/handoff.js

@@ -12,6 +12,7 @@ const fmt = require('../core/fmt');
 const { runVerificationGate } = require('../core/verification');
 const { isForgejoReviewEnabled } = require('../core/product-config');
 const { rebaseBeforeReviewRound } = require('../review/rebase');
+const nels = require('../core/nels');
 
 /**
   * Verifies that the current environment is ready for handoff.
@@ -228,6 +229,15 @@ const { rebaseBeforeReviewRound } = require('../review/rebase');
     }
   }
 
+  // Step 1.7: NEL capture — compute actual NEL from merge diff and persist record
+  log('Step 1.7: Capturing Net Engineering Lines (NEL) at handoff...');
+  const nelResult = captureNelAtHandoff(slug, { rootDir, missionDir: missionDirPath, log, error });
+  if (nelResult.ok) {
+    log(fmt.status('PASS', `NEL captured: ${nelResult.nel} NEL (${nelResult.bucket.label} bucket)`));
+  } else {
+    log(fmt.status('WARN', `NEL capture skipped: ${nelResult.error}`));
+  }
+
   // Step 2: Forgejo PR Update/Create (optional mirror when Forgejo is enabled)
   let token = null;
   let fallbackUser = null;
@@ -570,6 +580,89 @@ function buildAutoCheckpointContent(slug) {
   return true;
 }
 
+/**
+ * Capture NEL (Net Engineering Lines) at handoff time.
+ *
+ * Computes actual NEL from the merge diff (primary..HEAD), reads the predicted
+ * bucket from the mission's Refinement Signals, resolves review rounds from
+ * review-state.json, and persists a per-mission NEL record as `nel-record.json`.
+ *
+ * This is purely observational — no enforcement, gates, or blocks.
+ *
+ * @param {string} slug - Mission slug
+ * @param {{ rootDir: string, missionDir: string, log: Function, error: Function }} options
+ * @returns {{ ok: boolean, nel?: number, bucket?: string, error?: string }}
+ */
+function captureNelAtHandoff(slug, options) {
+   const { rootDir, missionDir, error } = options;
+
+  // 1. Determine primary branch for diff range
+  let primaryBranch;
+  try {
+    primaryBranch = missionUtils.getPrimaryBranch(rootDir);
+  } catch (_) {
+    return { ok: false, error: 'could not detect primary branch for NEL diff range' };
+  }
+
+  if (!primaryBranch) {
+    return { ok: false, error: 'primary branch is empty' };
+  }
+
+  // 2. Compute actual NEL from primary..HEAD
+  let nelRecord;
+  try {
+    nelRecord = nels.computeNELRecord(`${primaryBranch}..HEAD`, { cwd: rootDir });
+  } catch (_) {
+    return { ok: false, error: 'NEL computation failed' };
+  }
+
+  const actualNel = nelRecord.nel;
+  const actualBucket = nelRecord.bucket.label;
+
+  // 3. Read predicted bucket from MISSION.md Refinement Signals
+  const missionMdPath = path.join(missionDir, 'MISSION.md');
+  let predictedBucket = 'Unknown';
+  if (fs.existsSync(missionMdPath)) {
+    const content = fs.readFileSync(missionMdPath, 'utf8');
+    const predictedMatch = content.match(/Predicted NEL bucket:\s*(Small|Medium|Large)/i);
+    if (predictedMatch) {
+      predictedBucket = predictedMatch[1];
+    }
+  }
+
+  // 4. Read review rounds from review-state.json
+  let reviewRounds = 1;
+  const reviewStatePath = path.join(missionDir, 'review-state.json');
+  if (fs.existsSync(reviewStatePath)) {
+    try {
+      const rs = JSON.parse(fs.readFileSync(reviewStatePath, 'utf8'));
+      reviewRounds = rs.round || 1;
+    } catch (_) {
+      // ignore parse errors
+    }
+  }
+
+  // 5. Persist NEL record
+  const nelRecordPath = path.join(missionDir, 'nel-record.json');
+  const record = {
+    slug,
+    predictedBucket,
+    actualNel,
+    actualBucket,
+    reviewRounds,
+    capturedAt: new Date().toISOString(),
+  };
+
+  try {
+    fs.writeFileSync(nelRecordPath, JSON.stringify(record, null, 2) + '\n', 'utf8');
+  } catch (err) {
+    error(`Failed to write NEL record: ${err.message}`);
+    return { ok: false, error: `failed to write NEL record: ${err.message}` };
+  }
+
+  return { ok: true, nel: actualNel, bucket: actualBucket };
+}
+
 /** @param {string[]} args */
 async function handoffCommand(args) {
   const explicitSlug = args[0];
@@ -593,3 +686,4 @@ module.exports.verifyHandoff = verifyHandoff;
 module.exports.performHandoff = performHandoff;
 module.exports.gatekeeper = gatekeeper;
 module.exports.runDeclaredGates = runDeclaredGates;
+module.exports.captureNelAtHandoff = captureNelAtHandoff;

package/lib/commands/integrate.js

@@ -269,7 +269,7 @@ function detectChangedAreas(slug, opts = {}) {
 /** @param {string} filesOutput */
 function parseFilesToAreas(filesOutput) {
   const areas = new Set();
-  const knownAreas = ['server', 'auth-server', 'web-client', 'docs', 'workflow', 'android', 'kubernetes'];
+  const knownAreas = ['lib', 'server', 'auth-server', 'web-client', 'docs', 'workflow', 'android', 'kubernetes'];
   
   filesOutput.split('\n').forEach((/** @type{string} */ file) => {
     file = file.trim();

package/lib/core/nels.js

@@ -0,0 +1,199 @@
+/**
+ * Net Engineering Lines (NEL) computation.
+ *
+ * Computes NEL from `git diff --numstat -w` for a given diff range,
+ * excluding workflow/process bookkeeping, documentation, and generated files
+ * per ADR 0047.
+ *
+ * Bucket thresholds (empirical terciles from task-1355 data, n=29):
+ * - Small:  0–80 NEL  (11% rework rate)
+ * - Medium: 81–235 NEL (22% rework rate)
+ * - Large:  235+ NEL  (73% rework rate)
+ *
+ * This module is purely observational — no enforcement, gates, or blocks.
+ *
+ * @module lib/core/nels
+ */
+
+const { spawnSync } = require('child_process');
+
+// ---------- exclusion globs (ADR 0047) ----------
+// Each entry is a minimatch-compatible pattern. Patterns are checked in order;
+// the first match wins.
+
+const EXCLUSION_PATTERNS = [
+  'missions/**',        // workflow/process bookkeeping
+  'backlog/**',         // workflow/process bookkeeping
+  'review-*',           // workflow/process bookkeeping
+  'CP-*',               // workflow/process bookkeeping
+  '**/*.md',            // documentation
+  'docs/**',            // documentation
+  'package-lock.json',  // generated/vendored
+  'coverage/**',        // generated/vendored
+  '*lock*',             // lockfiles (package-lock.json, yarn.lock, pnpm-lock.yaml, Gemfile.lock, etc.)
+  '*.lock',             // additional lockfile safety net
+];
+
+/**
+ * Bucket constants derived from ADR 0047 empirical terciles.
+ */
+const BUCKET_SMALL_MAX = 80;
+const BUCKET_MEDIUM_MAX = 235;
+
+/**
+ * Classify NEL count into a bucket label.
+ *
+ * @param {number} nel
+ * @returns {{ label: 'Small' | 'Medium' | 'Large', min: number, max: number }}
+ */
+function classifyBucket(nel) {
+  if (nel <= BUCKET_SMALL_MAX) {
+    return { label: 'Small', min: 0, max: BUCKET_SMALL_MAX };
+  }
+  if (nel <= BUCKET_MEDIUM_MAX) {
+    return { label: 'Medium', min: BUCKET_SMALL_MAX + 1, max: BUCKET_MEDIUM_MAX };
+  }
+  return { label: 'Large', min: BUCKET_MEDIUM_MAX + 1, max: Infinity };
+}
+
+/**
+ * Check whether a file path matches any exclusion pattern.
+ *
+ * @param {string} filePath - Relative file path from repo root
+ * @returns {boolean}
+ */
+function isExcluded(filePath) {
+  // Normalize to forward slashes
+  const normalized = filePath.replace(/\\/g, '/');
+
+  for (const pattern of EXCLUSION_PATTERNS) {
+    if (patternMatches(normalized, pattern)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Simple glob matcher supporting *, **, and literal segments.
+ * Does not require a full minimatch dependency — keeps this module light.
+ *
+ * @param {string} str
+ * @param {string} pattern
+ * @returns {boolean}
+ */
+function patternMatches(str, pattern) {
+  // Convert minimatch-style glob to regex
+  // Escape regex special chars except * and ?
+  let regexStr = '';
+  let i = 0;
+  const pLen = pattern.length;
+
+  while (i < pLen) {
+    const ch = pattern[i];
+    if (ch === '*') {
+      if (i + 1 < pLen && pattern[i + 1] === '*') {
+        // ** matches everything including /
+        if (i + 2 < pLen && pattern[i + 2] === '/') {
+          regexStr += '(?:.*/)?';
+          i += 3;
+          continue;
+        } else {
+          regexStr += '.*';
+          i += 2;
+          continue;
+        }
+      } else {
+        regexStr += '[^/]*';
+        i += 1;
+        continue;
+      }
+    } else if (ch === '?') {
+      regexStr += '[^/]';
+    } else if ('.+^${}()|[]\\'.includes(ch)) {
+      regexStr += '\\' + ch;
+    } else {
+      regexStr += ch;
+    }
+    i++;
+  }
+
+  const re = new RegExp('^' + regexStr + '$');
+  return re.test(str);
+}
+
+/**
+ * Compute Net Engineering Lines (NEL) from a git diff range.
+ *
+ * Runs `git diff --numstat -w <range>` and sums insertions+deletions
+ * for files not matching exclusion globs from ADR 0047.
+ *
+ * @param {string} range - Git diff range, e.g. `main..HEAD` or `HEAD~1..HEAD`
+ * @param {{ cwd?: string }} [options]
+ * @returns {number} Total NEL count (insertions + deletions, whitespace-ignored)
+ */
+function computeNEL(range, options = {}) {
+  const cwd = options.cwd || process.cwd();
+
+  const result = spawnSync('git', ['diff', '--numstat', '-w', range], {
+    cwd,
+    encoding: 'utf8',
+    maxBuffer: 50 * 1024 * 1024, // 50 MB
+  });
+
+  if (result.status !== 0) {
+    // Git error, empty diff, or uncomputable — return 0
+    return 0;
+  }
+
+  const stdout = result.stdout || '';
+  const lines = stdout.split('\n').filter(line => line.trim().length > 0);
+
+  let total = 0;
+
+  for (const line of lines) {
+    // numstat format: <insertions>\t<deletions>\t<filename>
+    // Binary files show: -\t-\t<filename>
+    const parts = line.split('\t');
+    if (parts.length < 3) { continue; }
+
+    const adds = parts[0];
+    const dels = parts[1];
+    const filePath = parts.slice(2).join('\t');
+
+    // Skip binary files
+    if (adds === '-' || dels === '-') { continue; }
+
+    // Apply exclusion globs
+    if (isExcluded(filePath)) { continue; }
+
+    const addsNum = parseInt(adds, 10) || 0;
+    const delsNum = parseInt(dels, 10) || 0;
+
+    total += addsNum + delsNum;
+  }
+
+  return total;
+}
+
+/**
+ * Compute NEL and return the full NEL record including bucket classification.
+ *
+ * @param {string} range - Git diff range
+ * @param {{ cwd?: string }} [options]
+ * @returns {{ nel: number, bucket: { label: string, min: number, max: number } }}
+ */
+function computeNELRecord(range, options) {
+  const nel = computeNEL(range, options);
+  return { nel, bucket: classifyBucket(nel) };
+}
+
+module.exports = {
+  computeNEL,
+  computeNELRecord,
+  classifyBucket,
+  isExcluded,
+  EXCLUSION_PATTERNS,
+  BUCKET_SMALL_MAX,
+  BUCKET_MEDIUM_MAX,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@magnusekdahl/parallix",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "description": "AI mission workflow toolkit with a px CLI — local-first, human-in-the-loop multi-agent development",
   "license": "AGPL-3.0-or-later",
   "private": false,

package/templates/mission-scaffold.md

@@ -7,7 +7,7 @@
 <Why Now>
 
 ## Refinement Signals
-- Estimated agent % usage limit: 25-50%
+- Predicted NEL bucket: Small (0–80) / Medium (81–235) / Large (235+)
 - Confidence: High
 - Selection note: activate as-is
 - Main drivers: <drivers>