@juangcarmona/lighthouse-sdlc 0.15.2 → 0.16.1

package/src/unattended.mjs

@@ -0,0 +1,161 @@
+import { createHash } from 'node:crypto';
+import { withinScope } from './implementation.mjs';
+import { validateStageCompletion } from './contracts.mjs';
+
+export const unattendedDigest = value => createHash('sha256').update(JSON.stringify(value)).digest('hex');
+const record = value => value !== null && typeof value === 'object' && !Array.isArray(value);
+const boundedPath = path => typeof path === 'string' && path !== '*' && !/[?*\[\]{}]/.test(path) && withinScope(path.replace(/\/$/, ''), { paths: ['*'] }) && !path.startsWith('.github') && !/^docs\/product(?:\/|$)/.test(path) && !/^openspec(?:\/|$)/.test(path);
+const contains = (prefix, path) => prefix.endsWith('/') ? path.startsWith(prefix) : prefix === path;
+const strings = (list, max = 40) => Array.isArray(list) && list.length > 0 && list.length <= max && list.every(boundedPath) && new Set(list).size === list.length;
+const command = value => Array.isArray(value) && value.length > 0 && value.length <= 30 && value.every(arg => typeof arg === 'string' && arg.length > 0 && arg.length <= 1000 && !/[\0\r\n]/.test(arg));
+
+export function validateUnattendedPolicy(policy, route) {
+  if (!record(policy) || Object.keys(policy).some(k => !['schemaVersion', 'enabled', 'routes', 'paths', 'reviewerProfile', 'allowFivePoint', 'merge', 'maxCorrections', 'timeoutSeconds', 'hotfix'].includes(k)) ||
+      policy.schemaVersion !== 1 || policy.enabled !== true || !['ff', 'hotfix'].includes(route) ||
+      !Array.isArray(policy.routes) || !policy.routes.includes(route) || policy.routes.some(r => !['ff', 'hotfix'].includes(r)) ||
+      !strings(policy.paths) || !['plan', 'build', 'fast'].includes(policy.reviewerProfile) ||
+      typeof policy.allowFivePoint !== 'boolean' || typeof policy.merge !== 'boolean' ||
+      !Number.isInteger(policy.maxCorrections) || policy.maxCorrections < 0 || policy.maxCorrections > 2 ||
+      !Number.isInteger(policy.timeoutSeconds) || policy.timeoutSeconds < 60 || policy.timeoutSeconds > 7200) throw Error('Invalid or disabled bounded unattended policy');
+  if (route === 'hotfix') {
+    const hotfix = policy.hotfix;
+    if (!record(hotfix) || Object.keys(hotfix).sort().join(',') !== 'failurePattern,modules,regressionCommand,setupCommands,testPaths' || !strings(hotfix.testPaths) ||
+        !command(hotfix.regressionCommand) || !Array.isArray(hotfix.setupCommands) || hotfix.setupCommands.length > 8 || hotfix.setupCommands.some(c => !command(c)) || !Array.isArray(hotfix.failurePattern) || !hotfix.failurePattern.length ||
+        hotfix.failurePattern.length > 8 || hotfix.failurePattern.some(s => typeof s !== 'string' || !s.trim() || s.length > 200) ||
+        !record(hotfix.modules) || Object.keys(hotfix.modules).length === 0 || Object.keys(hotfix.modules).length > 40 ||
+        Object.entries(hotfix.modules).some(([name, paths]) => !/^[a-z][a-z0-9-]{0,63}$/.test(name) || !strings(paths))) throw Error('Hotfix needs declared test paths and module boundaries');
+  }
+  return policy;
+}
+
+export function admitUnattended(assessment, policy, route) {
+  validateUnattendedPolicy(policy, route);
+  if (!record(assessment) || assessment.risk !== 'low' || assessment.reversible !== true || assessment.dependenciesResolved !== true ||
+      assessment.scopeKnown !== true || assessment.productChangeNeeded !== false || assessment.humanDecisionRequired !== false ||
+      typeof assessment.reason !== 'string' || !assessment.reason.trim() || assessment.reason.length > 4000) throw Error('Issue needs a human decision or lacks low-risk eligibility evidence');
+  if (route === 'ff' && ![1, 2, 3, ...(policy.allowFivePoint ? [5] : [])].includes(assessment.points)) throw Error('Fast-forward point estimate is outside the delegated limit');
+  if (route === 'hotfix' && (assessment.confirmedDefect !== true || typeof assessment.rollback !== 'string' || !assessment.rollback.trim())) throw Error('Hotfix needs confirmed defect and rollback context');
+  return true;
+}
+
+export function hotfixScope(files, policy) {
+  validateUnattendedPolicy(policy, 'hotfix');
+  if (!Array.isArray(files) || !files.length || files.length > 10 || new Set(files.map(f => f.path)).size !== files.length) throw Error('Hotfix exceeds 10 changed files or has an invalid inventory');
+  let productionLines = 0;
+  const modules = new Set(), tests = [];
+  for (const file of files) {
+    if (!boundedPath(file.path) || !policy.paths.some(p => contains(p, file.path)) || file.binary ||
+        !Number.isSafeInteger(file.additions) || file.additions < 0 || !Number.isSafeInteger(file.deletions) || file.deletions < 0) throw Error('Hotfix has out-of-scope or unassessed binary/generated changes');
+    const owners = Object.entries(policy.hotfix.modules).filter(([, paths]) => paths.some(p => contains(p, file.path)));
+    if (owners.length !== 1) throw Error('Hotfix file needs exactly one declared module');
+    modules.add(owners[0][0]);
+    if (policy.hotfix.testPaths.some(p => contains(p, file.path))) tests.push(file.path);
+    else productionLines += file.additions + file.deletions;
+  }
+  if (productionLines > 100 || modules.size > 2) throw Error('Hotfix exceeds 100 production-code lines or two modules');
+  return { productionLines, files: files.length, modules: [...modules].sort(), tests };
+}
+
+export function regressionPlan(value) {
+  if (!record(value) || !command(value.command) || typeof value.assertion !== 'string' || !value.assertion.trim() ||
+      value.assertion.length > 1000 || !Number.isInteger(value.estimatedProductionLines) || value.estimatedProductionLines < 0 || value.estimatedProductionLines > 100 || typeof value.rootCause !== 'string' || !value.rootCause.trim() ||
+      !Array.isArray(value.plannedFiles) || !value.plannedFiles.length || value.plannedFiles.length > 10 || value.plannedFiles.some(p => !boundedPath(p))) throw Error('Hotfix needs bounded regression command, assertion, root cause and planned files');
+  return value;
+}
+
+export function assertRegression(receipt, expected, color) {
+  const check = receipt?.checks?.find(c => JSON.stringify(c.command) === JSON.stringify(expected.command));
+  if (!check || !Number.isInteger(check.exitCode) || check.execution?.status !== (color === 'red' ? 'failed' : 'passed') ||
+      check.execution.signal || !Number.isInteger(check.execution.exitCode) || check.execution.exitCode !== check.exitCode ||
+      (color === 'red' ? check.exitCode <= 0 || check.exitCode >= 124 : check.exitCode !== 0)) throw Error('Regression did not demonstrate ' + color.toUpperCase());
+  if (color === 'red' && (typeof check.log !== 'string' || !check.log.includes(expected.assertion))) throw Error('RED did not contain the identified behavioral assertion');
+  return check;
+}
+
+export function assertIndependentReview(result, binding, producer, reviewer) {
+  if (!producer?.model || !reviewer?.model || producer.model === reviewer.model || !reviewer.runId || reviewer.runId === producer.runId) throw Error('Independent review requires a separate execution and distinct resolved model');
+  const errors = validateStageCompletion(result, { stage: 'integrate', runId: reviewer.runId });
+  const review = result?.output?.review;
+  if (errors.length || !record(review) || review.binding !== binding || review.verdict !== 'accept' ||
+      !Array.isArray(review.findings) || review.findings.length !== 0) throw Error('Independent review is blocked, invalid or stale');
+  return true;
+}
+
+export async function verifyUnattendedIntegration(api, authorization, run, binding) {
+  const delegation = authorization?.unattended;
+  if (!delegation || delegation.owner !== binding.repository.split('/')[0] ||
+      run.path !== '.github/workflows/lighthouse-sdlc-unattended.yml' || run.event !== 'workflow_dispatch' ||
+      run.actor?.login !== delegation.owner || run.triggering_actor?.login !== delegation.owner ||
+      run.head_sha !== binding.base) return false;
+  const file = await api('contents/.lighthouse/unattended.json?ref=' + binding.base);
+  const policy = validateUnattendedPolicy(JSON.parse(Buffer.from(file.content, 'base64').toString()), delegation.route);
+  const review = delegation.review;
+  return policy.merge === true && unattendedDigest(policy) === delegation.policyDigest &&
+    review?.execution?.status === 'passed' && review.result?.stage === 'integrate' &&
+    review.result.status === 'passed' && review.result.output?.review?.binding === review.binding &&
+    review.result.output.review.verdict === 'accept' && review.result.output.review.findings?.length === 0;
+}
+
+// All effects are trusted host callbacks; the model cannot supply authorization or receipts.
+export async function runUnattended({ route, policy, host, signal }) {
+  validateUnattendedPolicy(policy, route);
+  const started = Date.now(), deadline = started + policy.timeoutSeconds * 1000;
+  const check = async () => {
+    if (signal?.aborted || Date.now() >= deadline) throw Error('Unattended execution stopped or exceeded its deadline');
+    await host.recheck();
+  };
+  const evidence = [];
+  try {
+    await check();
+    const refined = await host.refine();
+    admitUnattended(refined.eligibility, policy, route);
+    const plan = route === 'hotfix' ? regressionPlan(refined.hotfix) : await host.propose(refined);
+    await check();
+    await host.reviewPlan({ refined, plan });
+    let red = null;
+    if (route === 'hotfix') {
+      red = await host.reproduce(plan);
+      assertRegression(red.receipt, plan, 'red');
+      const regression = red.receipt.checks.find(c => JSON.stringify(c.command) === JSON.stringify(plan.command));
+      if (JSON.stringify(plan.command) !== JSON.stringify(policy.hotfix.regressionCommand) ||
+          !policy.hotfix.failurePattern.some(pattern => regression.log.includes(pattern))) throw Error('RED did not use the owner-declared regression runner and assertion failure signal');
+      const scope = hotfixScope(red.files, policy);
+      if (scope.tests.length !== red.files.length) throw Error('Reproduction phase may change regression tests only');
+      evidence.push({ kind: 'red', receipt: red.receipt, tests: red.tests });
+    }
+    let candidate, accepted = false;
+    for (let round = 0; round <= policy.maxCorrections; round++) {
+      await check();
+      candidate = await host.implement({ refined, plan, red, previous: candidate, round });
+      admitUnattended(candidate.eligibility, policy, route);
+      if (route === 'hotfix') {
+        hotfixScope(candidate.files, policy);
+        if (unattendedDigest(candidate.tests) !== unattendedDigest(red.tests)) throw Error('Hotfix repair changed its regression assertions');
+      }
+      if (!candidate.receipt?.checks?.length) throw Error('Required candidate checks are unavailable');
+      if (candidate.receipt.checks.some(c => c.exitCode !== 0)) {
+        candidate.feedback = ['Required host checks failed; preserve regression assertions and repair only the authorized scope.'];
+        evidence.push({ kind: 'failed-checks', round, checks: candidate.receipt.checks });
+        continue;
+      }
+      if (route === 'hotfix') assertRegression(candidate.receipt, plan, 'green');
+      await check();
+      const review = await host.reviewCandidate(candidate);
+      evidence.push({ kind: 'candidate', round, review });
+      if (review.accepted === true) { accepted = true; break; }
+      if (review.verdict !== 'request-changes') throw Error('Independent review requires a human decision');
+      candidate.feedback = review.findings;
+    }
+    if (!accepted) throw Error('Independent review correction limit exhausted');
+    await check();
+    const published = await host.publish(candidate);
+    await check();
+    if (!policy.merge) return { status: 'waiting-human', published, evidence, nextAction: 'Authorize integration of the reviewed PR head' };
+    const integrated = await host.integrate(candidate, published);
+    evidence.push({ kind: 'integration', result: integrated });
+    return { status: 'passed', published, integrated, evidence, durationMs: Date.now() - started, nextAction: 'Follow existing post-merge review and release policy' };
+  } catch (error) {
+    await host.stop(error.message, evidence);
+    return { status: 'blocked', evidence, reason: error.message, nextAction: 'Inspect execution evidence and resolve the identified blocker' };
+  }
+}

package/templates/unattended.json

@@ -0,0 +1,37 @@
+{
+  "schemaVersion": 1,
+  "enabled": false,
+  "routes": [
+    "ff",
+    "hotfix"
+  ],
+  "paths": [
+    "src/features/example/",
+    "tests/example/"
+  ],
+  "reviewerProfile": "plan",
+  "allowFivePoint": false,
+  "merge": false,
+  "maxCorrections": 2,
+  "timeoutSeconds": 3600,
+  "hotfix": {
+    "setupCommands": [],
+    "testPaths": [
+      "tests/example/"
+    ],
+    "modules": {
+      "example": [
+        "src/features/example/",
+        "tests/example/"
+      ]
+    },
+    "regressionCommand": [
+      "node",
+      "--test",
+      "tests/example/regression.test.mjs"
+    ],
+    "failurePattern": [
+      "ERR_ASSERTION"
+    ]
+  }
+}

package/unattended.md

@@ -0,0 +1,40 @@
+# Bounded unattended delivery
+
+Install the opt-in composition with `node node_modules/@juangcarmona/lighthouse-sdlc/src/install-workflows.mjs . <immutable-lighthouse-commit> --with-unattended`. Preview first; add `--apply` after reviewing the plan. This also installs completion workers. Existing policy is preserved. The initial `.lighthouse/unattended.json` template has execution and merge disabled.
+
+Use the existing adopted GitHub completion profile, enforced checks, evidence branch and provisioned OpenCode runner. Configure implementation and reviewer profiles to distinct available model identifiers. Different profile names can resolve to the same model; admission rejects that combination. The runtime records requested/resolved configuration separately from provider-reported settings, which may remain unverified.
+
+## Configure and request work
+
+Edit the project-owned policy using [the template](templates/unattended.json). Replace the example paths and module map with actual repository boundaries, choose enabled routes and a finite time/correction budget, then explicitly enable execution. `merge: true` is a separate bounded delegation of integration; `merge: false` leaves the reviewed PR for owner authorization. The policy cannot change itself through a candidate.
+
+For hotfix, declare trusted setup commands (an empty list when unnecessary), the regression command and assertion-failure signals in project policy. The model must use that command; it cannot authorize a custom shell script or choose an arbitrary failure as regression proof. Setup runs before the distinct regression check in each clean verification workspace. Test authoring remains limited to the declared test paths. The reviewer inspects the actual test and RED/GREEN evidence against the reported behavior.
+
+Run either composition from the repository's default branch:
+
+```sh
+gh workflow run lighthouse-sdlc-unattended.yml -f issue=<number> -f route=ff
+gh workflow run lighthouse-sdlc-unattended.yml -f issue=<number> -f route=hotfix
+```
+
+Only an authenticated owner dispatch is admitted initially. The issue must be open, authored by the owner, and free of human reservations, pauses and pending answer/review gates. External intake uses the existing owner-admission route before it can become eligible; this composition does not broaden that route. Installation and workflow availability are separate from successful execution.
+
+## Fast-forward
+
+Refinement must establish low risk, known reversible scope, resolved dependencies, no missing product decision and an explained numeric estimate of 1, 2 or 3. Five points requires `allowFivePoint: true`; legacy size labels are not converted into points. A separate read-only reviewer checks readiness and the real provider-generated engineering plan before code changes. The implementation and required host checks are then reviewed independently against the original issue, owner answers and actual before/after source.
+
+At most the configured correction rounds are permitted, with two as the maximum. Changed scope, failed or unavailable evidence, human-only decisions, cancellation, revoked authority or exhausted corrections stop dependent advancement and retain the candidate. Required checks cannot be waived by a reviewer verdict.
+
+## Hotfix
+
+The expedited route assesses the confirmed defect and root cause, records a compact correction plan and authors regression tests before changing production code. The trusted host runs the declared command against unchanged production code and requires both the identified assertion and an owner-declared assertion-failure signal. An environment/compilation failure is not acceptable proof. Independent review must confirm that the test exercises the actual failing behavior.
+
+The complete candidate is limited to 100 added plus deleted production-code lines, 10 files including tests and two declared modules. Test lines are excluded only from the production-code cap. The host measures the actual diff and rejects ambiguous module ownership, binary changes and unassessed scope. The regression-test bytes from RED must survive the repair unchanged. GREEN and adjacent/required checks precede independent candidate review. The RED receipt and test snapshot are part of that review's binding.
+
+## Integration and recovery
+
+The host rechecks source, policy, owner intent, reservations, the exact PR head, required CI and hosting rules before a delegated merge. Required GitHub checks must actually pass. A merge queue requires a supported queue-aware adapter; protected decisions retain their configured owners.
+
+The trusted host retains the integration bundle on the adopted evidence branch for existing post-merge review. Release, deployment, smoke checks and rollback continue only through their existing separately authorized paths. A merge does not establish deployment.
+
+Each request receives an immutable identity before execution. A rerun with an existing receipt stops for inspection rather than repeating uncertain effects. Failed/blocked attempts retain candidate and host execution artifacts; resolve the named blocker before a fresh owner request. GitHub issue concurrency is shared with the stage workers and reservations are released on completion. No runner stays allocated while waiting for a new human decision.