@juangcarmona/lighthouse-sdlc 0.18.0 → 0.18.2

package/github-actions.md

@@ -109,7 +109,9 @@ An active or queued execution without an Actions update for two hours is reporte
 
 Read-only observation runs independently of the issue's execution lease, so reporting can inspect a stalled worker. Dispatch and reconciliation wait for that same per-issue lease before changing receipts, labels or handoffs. A separate report records the reconciliation outcome after the lease is available.
 
-For the latest authenticated unattended run, maintenance reports an interrupted failed or cancelled execution whose last handoff still says it is working or queued. The restored notice marks publication effects as unknown and directs the maintainer to inspect them; it does not release a reservation or request a retry.
+For the latest authenticated unattended run, maintenance reports a completed execution whose last handoff still says it is working or queued. It identifies confirmed failures and cancellations, and treats publication effects as unknown until inspected. A successful execution without its terminal handoff also receives an uncertain-outcome notice. Maintenance does not release a reservation or request a retry in these cases.
+
+If publication succeeds but reservation cleanup fails, maintenance preserves the published result and asks the maintainer to inspect the reservation before releasing it.
 
 ### Worker error reports
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juangcarmona/lighthouse-sdlc",
-  "version": "0.18.0",
+  "version": "0.18.2",
   "type": "module",
   "description": "Provider-neutral SDLC skills, commands and route contracts for Lighthouse adopters",
   "repository": {

package/src/handoff.mjs

@@ -54,7 +54,7 @@ export function handoff({ status, stage, happened, action, next, link, details }
 
 // A newer authenticated dispatch owns current status, even if an older cleanup finishes late.
 export async function publishObservedStop(api, { repository, issue, stage, run, attempt, dispatch, observation, sourceRevision, answerRetained = false, preparationReason }) {
-  if (!['failure', 'cancelled', 'pre-agent-cancelled', 'preparation-failure', 'provider-preparation-failure', 'preparation-cancelled', 'activation-failure', 'provider-failure', 'provider-cancelled', 'publication-unknown'].includes(observation) || !dispatch?.commentId) return false;
+  if (!['failure', 'cancelled', 'pre-agent-cancelled', 'preparation-failure', 'provider-preparation-failure', 'preparation-cancelled', 'activation-failure', 'provider-failure', 'provider-cancelled', 'publication-unknown', 'cleanup-failure'].includes(observation) || !dispatch?.commentId) return false;
   const { checkDispatchClaim, issueComments, readDispatchReceipt } = await import('./stage-dispatch.mjs');
   await checkDispatchClaim(api, repository, issue, dispatch, run);
   const comments = await issueComments(api, issue);
@@ -77,9 +77,9 @@ export async function publishObservedStop(api, { repository, issue, stage, run,
   }
   const available = adopted && await api('labels/execution-failed', 'GET', undefined, true);
   if (available) await api(`issues/${issue}/labels`, 'POST', { labels: ['execution-failed'] });
-  const status = ['cancelled', 'pre-agent-cancelled', 'preparation-cancelled', 'provider-cancelled'].includes(observation) ? 'cancelled' : observation === 'publication-unknown' ? 'unknown' : 'failed';
+  const status = ['cancelled', 'pre-agent-cancelled', 'preparation-cancelled', 'provider-cancelled'].includes(observation) ? 'cancelled' : observation === 'publication-unknown' ? 'unknown' : observation === 'cleanup-failure' ? 'blocked' : 'failed';
   const missingChecks = observation === 'preparation-failure' && preparationReason === 'missing-implementation-checks';
-  const result = observation === 'publication-unknown' ? 'Publication did not complete cleanly; its effects and final result are not confirmed.' : missingChecks ? 'Preparation stopped because the repository has no implementation verification policy; the agent did not start.' : observation === 'preparation-failure' ? 'Preparation failed before the agent started; no validated result was published.' : observation === 'provider-preparation-failure' ? 'Product Change preparation failed before the provider started.' : observation === 'preparation-cancelled' ? 'Preparation was cancelled before work started; no validated result was published.' : observation === 'activation-failure' ? 'The execution environment failed before the agent started; no validated result was published.' : observation === 'provider-failure' ? 'The credential-free Product Change provider failed before publication.' : observation === 'provider-cancelled' ? 'The credential-free Product Change provider was cancelled before publication.' : observation === 'pre-agent-cancelled' ? 'The execution was cancelled before the agent started; no validated result was published.' : observation === 'failure' ? 'The agent execution failed before a validated result could be published.' : 'The execution was cancelled before a validated result could be published.';
+  const result = observation === 'cleanup-failure' ? 'The validated result was published, but reservation cleanup did not complete.' : observation === 'publication-unknown' ? 'Publication did not complete cleanly; its effects and final result are not confirmed.' : missingChecks ? 'Preparation stopped because the repository has no implementation verification policy; the agent did not start.' : observation === 'preparation-failure' ? 'Preparation failed before the agent started; no validated result was published.' : observation === 'provider-preparation-failure' ? 'Product Change preparation failed before the provider started.' : observation === 'preparation-cancelled' ? 'Preparation was cancelled before work started; no validated result was published.' : observation === 'activation-failure' ? 'The execution environment failed before the agent started; no validated result was published.' : observation === 'provider-failure' ? 'The credential-free Product Change provider failed before publication.' : observation === 'provider-cancelled' ? 'The credential-free Product Change provider was cancelled before publication.' : observation === 'pre-agent-cancelled' ? 'The execution was cancelled before the agent started; no validated result was published.' : observation === 'failure' ? 'The agent execution failed before a validated result could be published.' : 'The execution was cancelled before a validated result could be published.';
   const gap = ['failure', 'preparation-failure', 'provider-preparation-failure', 'activation-failure', 'provider-failure'].includes(observation) && !available ? ' The execution-failed label is not adopted or available; the maintainer must review label capability adoption.' : '';
   const reservation = item.labels.some(l => l.name === 'agent-working') ? ' The maintainer must also inspect the remaining agent-working reservation and release it only after verifying that no newer worker owns it.' : '';
   const action = (missingChecks ? 'The repository maintainer must configure checks in .lighthouse/implement.json or add npm run verify before requesting implementation again.' : observation === 'publication-unknown' ? 'The workflow maintainer must inspect the linked execution and compare the issue and any linked PR with its publication steps.' : 'The workflow maintainer must inspect the failed or cancelled execution and the configured recovery policy.') + reservation;

package/src/issue-actions.mjs

@@ -122,6 +122,13 @@ export function continuationHistory(continuation, answer) {
 export function checkProductEntry(product, snapshot) {
   if (!product || product.entry !== (snapshot.productEntry ?? 'idea')) throw Error('Product Change worker returned an outcome for a different authorized entry');
 }
+
+export function productGapNextAction({ gap, enabled, dispatched, paused }) {
+  if (!gap) return null;
+  if (paused) return { action: 'Owner: remove the future label when work may resume.', next: !enabled ? 'The workflow maintainer must also install and enable the Product Change workflow, then request a new authorized stage execution.' : dispatched ? 'Then replay this run through the router using this issue, stage and run ID as after_run.' : 'Then request a new authorized stage execution.' };
+  if (enabled && dispatched) return { action: 'None. Wait for the Product Change preparation outcome.', next: 'The workflow will authenticate this prerequisite and check whether product preparation is authorized; implementation remains stopped.' };
+  return { action: enabled ? 'Workflow maintainer: request a new authorized stage execution in the router.' : 'Workflow maintainer: install and enable the Product Change workflow.', next: 'Request a new authorized stage execution in the router; implementation remains stopped until the product prerequisite is approved and applied.' };
+}
 export function productApplyRequest({ dispatch, current, issueNumber, issue, repository, owner }) {
   if (dispatch?.request.worker !== 'apply-product-change' || !dispatch.request.productApproval) throw Error('Trusted Product Change apply dispatch is missing');
   const requested = dispatch.request.productApproval;
@@ -762,8 +769,9 @@ async function main(command) {
     const projection = resultHandoffState({ status: value.result.status, stage: snapshot.stage, question, reviewTarget, draft: !!prStateProof });
     const isReview = projection.review;
     const productRecovery = snapshot.worker === 'product-change' ? value.result.output?.productChange?.recovery : null;
-    const action = question ? `Owner: ${question} Reply here.` : isReview ? snapshot.worker === 'product-change' ? 'Owner: review the linked Product Change PR and approve the proposal or request changes there.' : 'Owner: open the linked result and record your decision there.' : value.result.status === 'blocked' ? productRecovery ? `Workflow maintainer: ${productRecovery}` : visibleNextAction(value.result.nextAction) : refinementAction?.action ?? 'None.';
-    const whatNext = question ? `The answer will be checked against this question before ${snapshot.stage} continues.` : isReview ? 'The workflow waits for the required decision before continuing.' : value.result.status === 'blocked' ? 'Work remains stopped until the blocker is resolved and continuation is authorized.' : refinementAction?.next ?? 'Any continuation follows the configured authorization.';
+    const productGap = value.result.status === 'blocked' && snapshot.worker !== 'product-change' ? productGapNextAction({ gap: value.result.output?.productGap, enabled: snapshot.productChangeEnabled === true, dispatched: !!snapshot.dispatch, paused: publicationIssue.labels.some(label => label.name === 'future') }) : null;
+    const action = question ? `Owner: ${question} Reply here.` : isReview ? snapshot.worker === 'product-change' ? 'Owner: review the linked Product Change PR and approve the proposal or request changes there.' : 'Owner: open the linked result and record your decision there.' : value.result.status === 'blocked' ? productRecovery ? `Workflow maintainer: ${productRecovery}` : productGap?.action ?? visibleNextAction(value.result.nextAction) : refinementAction?.action ?? 'None.';
+    const whatNext = question ? `The answer will be checked against this question before ${snapshot.stage} continues.` : isReview ? 'The workflow waits for the required decision before continuing.' : value.result.status === 'blocked' ? productGap?.next ?? 'Work remains stopped until the blocker is resolved and continuation is authorized.' : refinementAction?.next ?? 'Any continuation follows the configured authorization.';
     const happened = productPublicationMessage({ worker: snapshot.worker, outcome: value.result.output?.productChange?.outcome, reviewTarget, agentMessage: value.effect.body });
     const body = renderHandoff({ status: projection.status, stage: snapshot.stage, happened, action, next: whatNext, link: proposalLink.trim() || undefined, details: `Outcome: ${value.result.status}\n\n[Workflow run](${runUrl}) · source \`${snapshot.sourceRevision}\`\n\n${marker}\n<!-- lighthouse-handoff:v1 -->\n${prStateProof}\n<!-- lighthouse-stage:${snapshot.stage}:${value.result.status} -->${question ? '\n<!-- lighthouse-question -->' : ''}${productWorkflowMarker}${continuationHint}` });
     const handoff = snapshot.worker !== 'product-change' && snapshot.stage === 'refine' && value.result.status === 'passed' && env.LIGHTHOUSE_AUTO_IMPLEMENT === 'true' && !decompositionPlanned;

package/src/worker-recovery.mjs

@@ -7,6 +7,7 @@ export const maintenancePath = '.github/workflows/lighthouse-worker-maintenance.
 export const retryLimit = 2;
 export const retryDelayMs = 30 * 60 * 1000;
 export const recoveryId = (repository, rootId, attempt) => digest(`${repository}:${rootId}:retry:${attempt}`);
+const publishStep = job => job?.steps?.find(step => ['Recheck authority and publish the validated result', 'Recheck authority and publish'].includes(step.name));
 const identity = r => ({ issue: r.request.issue, worker: workerFor(r.request), runId: String(r.run.id), rootId: r.request.recovery?.rootId ?? r.request.id, attempt: r.request.recovery?.attempt ?? 0 });
 const ownerAnswers = comments => comments.filter(c => c.user?.login === c.owner && !c.body.includes('<!-- lighthouse-run:') && !c.body.includes('<!-- lighthouse-actions:'));
 const intent = (issue, comments, owner) => digest(JSON.stringify({ title: issue.title, body: issue.body, comments: ownerAnswers(comments.map(c => ({ ...c, owner }))).map(c => ({ id: c.id, body: c.body, updated_at: c.updated_at })) }));
@@ -29,9 +30,9 @@ export function recoveryDecision({ request, receipt, run, jobs, issue, comments,
   if (!['refine', 'propose', 'implement'].includes(request.stage) || !['failure', 'timed_out'].includes(run.conclusion)) return result('uncertain', 'manual-recovery', 'Inspect the outcome and request a new authorized execution if needed.');
   const preparation = jobs.find(j => j.name === 'Authorize and reserve issue');
   const publication = jobs.find(j => j.name === 'Validate, publish and release');
-  const publishStep = publication?.steps?.find(s => s.name === 'Recheck authority and publish the validated result');
+  const publish = publishStep(publication);
   const failedExecution = jobs.some(j => ['pre_activation', 'activation', 'agent'].includes(j.name) && ['failure', 'timed_out'].includes(j.conclusion));
-  if (preparation?.conclusion !== 'success' || !failedExecution || publishStep?.conclusion !== 'skipped') return result('uncertain', 'publication-uncertain', 'Inspect publication and remote effects before creating another request.');
+  if (preparation?.conclusion !== 'success' || !failedExecution || publish?.conclusion !== 'skipped') return result('uncertain', 'publication-uncertain', 'Inspect publication and remote effects before creating another request.');
   if (base.attempt >= retryLimit) return result('exhausted', 'worker-technical-failure', 'Retry budget exhausted. Inspect the failure and make a new owner decision.');
   const ended = Date.parse(run.updated_at);
   if (!Number.isFinite(ended) || !Number.isFinite(now)) return result('uncertain', 'execution-time-unknown', 'Inspect the execution timestamps.');
@@ -63,14 +64,16 @@ export async function observeDispatch(api, repository, owner, comment, issue, co
   const workflowRevision = (await api(`commits/${encodeURIComponent(dispatch.request.ref)}`)).sha;
   const agent = jobs.jobs.find(job => job.name === 'agent');
   const publishJob = jobs.jobs.find(job => job.name === 'Validate, publish and release');
-  const publish = publishJob?.steps?.find(step => step.name === 'Recheck authority and publish the validated result');
+  const publish = publishStep(publishJob);
+  const cleanup = publishJob?.steps?.find(step => ['Release the issue reservation', 'Release reservation'].includes(step.name));
   const prepare = jobs.jobs.find(job => job.name === 'Authorize and reserve issue');
   const unpublished = publish?.conclusion === 'skipped' || publishJob?.conclusion === 'skipped';
   const notStarted = !agent || agent.conclusion === 'skipped';
   const activationFailed = jobs.jobs.some(job => ['pre_activation', 'activation'].includes(job.name) && ['failure', 'timed_out'].includes(job.conclusion));
-  const observation = ['completed', 'waiting', 'blocked'].includes(receipt.status) ? null
+  const observation = publish?.conclusion === 'success' && ['failure', 'timed_out', 'cancelled'].includes(cleanup?.conclusion) ? 'cleanup-failure'
+    : ['completed', 'waiting', 'blocked'].includes(receipt.status) ? null
     : workerFor(dispatch.request) === 'apply-product-change' ? productApplyObservation({ prepare: jobs.jobs.find(job => job.name === 'Recheck product approval')?.conclusion, apply: jobs.jobs.find(job => job.name === 'Apply with the pinned ProductShape provider')?.conclusion, publish: jobs.jobs.find(job => job.name === 'Recheck and publish provider output')?.conclusion })
-    : agent?.conclusion === 'success' && ['failure', 'timed_out', 'cancelled'].includes(publish?.conclusion) ? 'publication-unknown'
+    : agent?.conclusion === 'success' && (!publishJob || ['failure', 'timed_out', 'cancelled', 'skipped'].includes(publish?.conclusion) || ['failure', 'timed_out', 'cancelled', 'skipped'].includes(publishJob.conclusion)) ? 'publication-unknown'
     : ['failure', 'timed_out'].includes(prepare?.conclusion) && notStarted ? 'preparation-failure'
     : prepare?.conclusion === 'success' && activationFailed && notStarted && unpublished ? 'activation-failure'
     : unpublished && ['failure', 'timed_out'].includes(agent?.conclusion) ? 'failure'
@@ -118,7 +121,7 @@ export async function reconcileAbandonedReservation(api, repository, owner, issu
   const prepare = jobs.find(job => job.name === 'Authorize and reserve issue');
   const agent = jobs.find(job => job.name === 'agent');
   const publish = jobs.find(job => job.name === 'Validate, publish and release');
-  const step = publish?.steps?.find(item => item.name === 'Recheck authority and publish the validated result');
+  const step = publishStep(publish);
   if (prepare?.conclusion !== 'success' || !['failure', 'timed_out', 'cancelled', 'skipped'].includes(agent?.conclusion) || !(publish?.conclusion === 'skipped' || step?.conclusion === 'skipped')) return false;
   let snapshot;
   try { snapshot = await readArtifact(api, repository, run.id, `lighthouse-input-${issue.number}-${run.run_attempt}`, 'request.json'); } catch { return false; }
@@ -167,7 +170,7 @@ export async function reconcilePublishedStage(api, repository, owner, issue, com
   const { dispatch, run, jobs = [], revision, workflowRevision } = observation;
   if (!dispatch || !run) return 'not-applicable';
   const publication = jobs.find(j => j.name === 'Validate, publish and release');
-  const publish = publication?.steps?.find(s => s.name === 'Recheck authority and publish the validated result');
+  const publish = publishStep(publication);
   const failedPublication = run.conclusion === 'failure' && jobs.find(j => j.name === 'agent')?.conclusion === 'success' && publish?.conclusion === 'failure';
   const interrupted = failedPublication && ['running', 'unknown'].includes(dispatch.receipt.status);
   const completed = (run.conclusion === 'success' || failedPublication) && ['completed', 'waiting', 'blocked'].includes(dispatch.receipt.status);
@@ -235,12 +238,12 @@ export async function reconcileUnattendedStop(api, repository, owner, issue, com
   if (!last.body.includes(marker)) return 'uncertain';
   const run = await api(`actions/runs/${runId}`);
   if (run?.repository?.full_name !== repository || run.path !== '.github/workflows/lighthouse-sdlc-unattended.yml' || run.event !== 'workflow_dispatch' || run.actor?.login !== owner || run.triggering_actor?.login !== owner || run.display_title !== `${route} #${issue.number} · ${owner}` || run.run_attempt !== 1) return 'uncertain';
-  if (run.status !== 'completed' || !['failure', 'timed_out', 'cancelled'].includes(run.conclusion)) return 'not-applicable';
+  if (run.status !== 'completed' || !['success', 'failure', 'timed_out', 'cancelled'].includes(run.conclusion)) return 'not-applicable';
   const fresh = await api(`issues/${issue.number}`), latest = await issueComments(api, issue.number);
   const current = latest.filter(c => c.user?.login === 'github-actions[bot]' && c.user.type === 'Bot' && /<!-- lighthouse-(?:unattended:|unattended-recovery:|dispatch:|actions:|stop:)/.test(c.body ?? '')).at(-1);
   if (fresh.state !== 'open' || fresh.user?.login !== owner || current?.id !== last.id) return 'uncertain';
   const reservation = fresh.labels.some(l => l.name === 'agent-working') ? ' The agent-working reservation remains; verify ownership before releasing it.' : '';
-  const body = handoff({ status: 'unknown', stage: route, happened: `The unattended execution ended ${run.conclusion}, but its terminal handoff is missing. Publication and integration effects have not been confirmed.`, action: `Workflow maintainer: inspect the execution, artifacts, issue and any candidate PR before resuming.${reservation}`, next: 'Do not retry or release a reservation until the observed effects and current ownership are reconciled.', link: `[Execution](https://github.com/${repository}/actions/runs/${runId})`, details: `<!-- lighthouse-unattended-recovery:${runId}:1 -->` });
+  const body = handoff({ status: run.conclusion === 'success' ? 'unknown' : run.conclusion === 'cancelled' ? 'cancelled' : 'failed', stage: route, happened: `The unattended execution ended ${run.conclusion}, but its terminal handoff is missing. Publication and integration effects have not been confirmed.`, action: `Workflow maintainer: inspect the execution, artifacts, issue and any candidate PR before resuming.${reservation}`, next: 'Do not retry or release a reservation until the observed effects and current ownership are reconciled.', link: `[Execution](https://github.com/${repository}/actions/runs/${runId})`, details: `<!-- lighthouse-unattended-recovery:${runId}:1 -->` });
   await api(`issues/${issue.number}/comments`, 'POST', { body });
   return 'restored';
 }
@@ -286,7 +289,7 @@ export async function prepareRecovery(api, repository, owner, issueNumber, paren
       if (preparationRun && await reconcilePreparationFailure(api, repository, owner, issueNumber, comment.id, preparationRun, readArtifact)) { observation.stop = null; Object.assign(publicObservation, { state: 'reconciled', code: 'preparation-failed', nextAction: 'Inspect the confirmed failed execution before requesting new work.' }); }
       const reconciliation = await reconcilePublishedStage(api, repository, owner, issue, comments, observation, readArtifact);
       if (reconciliation === 'restored' || reconciliation === 'present') {
-        observation.stop = null;
+        if (observation.stop?.observation !== 'cleanup-failure') observation.stop = null;
         if (run?.conclusion === 'failure') Object.assign(publicObservation, { state: 'reconciled', code: 'handoff-restored', nextAction: 'Follow the restored handoff.' });
       }
       if (reconciliation === 'uncertain') Object.assign(publicObservation, { state: 'uncertain', code: 'handoff-unconfirmed', nextAction: 'Inspect the retained result and current issue state before restoring its handoff.' });