@juangcarmona/lighthouse-sdlc 0.15.0 → 0.15.2

package/README.md

@@ -1,150 +1,69 @@
-# Lighthouse SDLC
+# Lighthouse delivery
 
-See [request intake and relative estimates](request-triage.md) for the public form, owner admission, evidence-backed clarification, initial point anchors and native workflow upgrade route.
+Use GitHub labels to request work. The router authenticates the owner, dispatches one worker and publishes its result. Installed policy can continue delivery automatically; questions, `future`, human reservations and required approvals stop it.
 
-This package provides the provider-neutral delivery contract for Lighthouse adopters.
+## Check the installed version first
 
-It owns the six lifecycle skills, their command entrypoints, route, stage and gate descriptors, deterministic triage and decomposition projections, rebuildable state checks and the provider-neutral control-plane contract.
+Before explaining or changing an adopter's process, read its installed `@juangcarmona/lighthouse-sdlc/package.json`, this guide and `.github/workflows/lighthouse-sdlc-router.yml`. Check the router's pinned Lighthouse commit, enabled stages, `LIGHTHOUSE_AUTO_IMPLEMENT`, repository variable `LIGHTHOUSE_AUTOMATION_ENABLED` and current Git branch. Package installation, workflow installation and successful execution are separate facts. An older checkout cannot establish what is deployed on GitHub.
 
-It publishes `command-aliases.json` as the versioned, machine-readable mapping from selected `/lh:*` aliases to canonical `/lighthouse:*` command assets. Run `lighthouse-sdlc aliases --format json` to inspect it; the configured agent host decides how to expose the aliases.
+## GitHub Actions
 
-It also provides the `browser-e2e` evidence contract for Playwright journeys. The contract belongs to the SDLC because it records delivery evidence; the tests, journeys and browser configuration remain owned by the adopter.
+These actions require installed workers, enabled automation and the repository owner as actor. Opening an issue alone starts no agent. Every result links to its execution; an Actions success can contain a blocked assessment.
 
-It provides a neutral evidence contract for delivery, product and architecture references. `lighthouse-sdlc evidence` validates records or builds a deterministic coverage index; it does not replace ProductShape, ArcShape or a future quality evaluator.
+| Owner action or event | Requirement | Result and continuation | Source |
+| --- | --- | --- | --- |
+| Add `triage` | Open issue; external authors need owner admission | Assess request and estimate; publish `triaged` or `needs-info`. Stop for owner decision. | [Intake](request-triage.md) |
+| Add `refine` | Open issue; no active reservation | Define acceptance criteria; publish `ready` or a question. With implementation enabled, continue automatically unless `future` or another blocker pauses it. | [Refinement](workflows/lighthouse-sdlc-refine.md) |
+| Add `propose` | Proposal worker installed; `ready` and current successful refinement evidence; no existing proposal PR | Create a separate OpenSpec proposal PR and set `waiting-review`. No implementation or merge. | [Proposal](workflows/lighthouse-sdlc-propose.md) |
+| Add `implement` | Implementation enabled, current owner authorization and repository checks configured; no `future` | Create the OpenSpec plan, implement and verify in one workspace. Publish plan and code together in a draft PR. A separate proposal PR is optional. | [Implementation](skills/implement/SKILL.md) |
+| Add `future` | Issue not yet admitted for implementation | Pause implementation, including continuation after refinement. Triage, refinement and proposal remain available. Removing it resumes a pending `implement` request. | [Event routing](src/issue-actions.mjs) |
+| Answer the issue's pending question | Owner reply to the latest trusted blocked result | Resume that same stage. An unrelated comment grants no new work or approval. | [Reply admission](src/issue-actions.mjs) |
+| Comment or request changes on a proposal/implementation PR | Eligible bot-created PR and current owner feedback | `apply review` updates the same PR and retains its original stage. | [Corrections](workflows/lighthouse-sdlc-apply-review.md) |
+| Approve a proposal PR | Current proposal head | Record design approval. No implementation or merge starts. | [Proposal feedback](src/issue-actions.mjs) |
+| Required CI passes for a complete implementation candidate | Current PR head and adopted checks | Mark the PR ready and project `pr-ready`; wait for merge authorization. | [PR state](src/pr-state-actions.mjs) |
+| Approve the implementation PR | Completion installed; owner approval for current head and passing required checks | `integrate` assesses and performs the authorized merge. After successful post-merge CI, `review` records the retrospective and closes the issue if passed. | [Completion](completion.md) |
 
-It has no persistent execution service, transcript store or cross-repository dispatcher. The optional Actions adapter executes the selected engine under operator policy. ProductShape, ArcShape and OpenSpec retain their own authority.
+For design-only work, add `future` before `refine`, then add `propose` after refinement passes. For delivery, request `implement` directly or let successful refinement continue under the installed implementation policy. Planning still happens before code changes. Gates are evidence and decision checks; only gates configured for a human require a human stop.
 
-## External host contract
+The eight Actions names are `router`, `triage`, `refine`, `propose`, `implement`, `integrate`, `review` and `apply review`. `integrate`, `review` and `apply review` normally start from approved PR, CI or feedback events, not labels with those names. Manual router dispatch is available for recovery. [Triggers](workflows/lighthouse-sdlc-router.yml), [admission](src/issue-actions.mjs) and [continuation](src/stage-transition.mjs) define the executable behavior.
 
-`src/host-contract.mjs` validates a supervised `triage` or `refine` request against a trusted host policy and validates the resulting stage/effect envelope. It is exported as `@juangcarmona/lighthouse-sdlc/host-contract`. See [the wire contract](host-contract.md) for fields and host obligations. Execution, credentials, admission, cancellation and publication remain host responsibilities.
+## Label catalog
 
-The external-host adapter remains available for existing adopters. New repository automation uses the gh-aw path below; do not enable both routers for the same events.
+[capabilities.json](capabilities.json) contains the exact names, roles, colors and descriptions. A matching label name does not prove Lighthouse created it. Existing labels and custom descriptions are preserved by reconciliation.
 
-## GitHub Actions execution
+| Category | Labels | Meaning |
+| --- | --- | --- |
+| Requests | `triage`, `refine`, `propose`, `implement` | Owner-added commands consumed by the native router; presence alone is not authorization. |
+| Results | `triaged`, `ready`, `needs-info`, `waiting-review`, `pr-draft`, `pr-ready` | Read the linked result or PR for outcome, question or required decision. |
+| Overlays | `future`, `agent-working`, `human-working` | Pause implementation, show an agent reservation or reserve work for a human. The host owns the lock. |
+| Compatibility states | `wip`, `review` | Available to configured trackers; adding them does not dispatch a native worker. |
+| Size | `size-s`, `size-m`, `size-l`, `size-xl` | Relative work-item size. Point estimates use the separate [estimate contract](request-triage.md#estimate-contract). |
+| Urgency | `urgency-normal`, `urgency-asap`, `urgency-now` | Normal, soon or immediate attention. |
+| Impact | `impact-low`, `impact-medium`, `impact-high` | Expected impact. |
+| Risk | `risk-low`, `risk-medium`, `risk-high` | Delivery risk. |
+| Affected surface | `blast-radius-low`, `blast-radius-medium`, `blast-radius-high` | Extent of potentially affected components and consumers. |
 
-The optional router accepts an owner-added `refine` label, an owner reply to a pending `needs-info` question or an owner manual dispatch. It dispatches the compiled gh-aw refinement worker as a separate execution. With `--with-propose`, an owner-added `propose` label or explicit manual stage selection dispatches the proposal worker independently. Actions authorizes the request, reserves the issue, runs OpenCode, validates its result and publishes through a separately credentialed job. SoFa can observe these runs without participating in execution.
+Use at most one classification value per dimension. Repository labels such as `bug`, `documentation` or `integrate` are outside this catalog unless the adopter declares them. `planned` and `done` are gate results, not shipped labels. Labels capability version 2 corrects request roles and removes the obsolete `triage → refine` state-transition example; generic triage CLI callers must declare their own state transitions. Native Actions uses its authenticated result and continuation rules.
 
-Preview installation with `node node_modules/@juangcarmona/lighthouse-sdlc/src/install-workflows.mjs <repository> <immutable-lighthouse-commit>`. Install gh-aw v0.93.2, then add `--apply` to write and compile the selected sources. Existing different files require review and `--replace-reviewed`. Commit the Markdown, router, shared engine definition, generated lock and action pins together. Set the repository variable `LIGHTHOUSE_AUTOMATION_ENABLED=true` after provisioning the runner and disabling previous routers.
+## Install or update workflows
 
-The installer enables `refine` by default. Add `--with-propose` to install the proposal worker as well. Add `--with-implement` for implementation (including proposal support). Add `--with-completion` to enable integration and review with an explicit GitHub profile opt-in; see the [completion guide](completion.md). Foundation initialization and upgrades do not install workflows. On upgrade from an older baseline, existing workflows remain untouched and leave the foundation's managed-file inventory. Review and remove obsolete projections explicitly.
+Installing or upgrading npm packages does not install or update Actions workflows. Use the [workflow installer](src/install-workflows.mjs) from the selected package:
 
-Create the `propose` request label and the amber `waiting-review` attention label when opting in. The proposal worker requires `ready` and a successful refinement from the same source revision and owner intent. Preparation authenticates its Actions request and result artifacts; a label or copied comment is insufficient. If evidence expired or the source changed, run `refine` again first. The explicit owner request authorizes proposal work. It does not approve the resulting design or implementation.
-
-OpenSpec 1.15.0 supplies the `spec-driven` scaffold and artifact instructions in preparation. OpenCode returns bounded Markdown files under `openspec/changes/issue-<number>-proposal/`. The separate publisher validates those files with the provider, creates a fresh proposal branch and opens a PR with a link to the run. Existing proposal directories and open proposal PRs stop admission. Product code, existing branches and OpenSpec configuration remain untouched. Failed publication may leave a proposal branch; inspect it before retrying. The adopter must allow Actions to create PRs; this repository setting also permits Actions approvals, although these workflows never approve or merge PRs. PRs created with `GITHUB_TOKEN` generate `pull_request` runs that require maintainer approval. Review the proposed changes, then select **Approve workflows to run** on the PR before relying on CI. This is a CI execution gate, separate from accepting the proposal or authorizing implementation. See [GitHub token-triggered runs](https://docs.github.com/en/actions/concepts/security/github_token#when-github_token-triggers-workflow-runs).
-
-A completed proposal links its PR and sets `waiting-review`. Review the proposal there: owner comments, inline comments and submitted change requests run the independent `apply-review` worker with a `propose` result against the existing artifacts and update the same PR. Only open, same-repository proposals created by `github-actions[bot]` are eligible. The host checks current feedback, issue readiness and the PR head before a non-forced branch update. A changed head or discussion stops publication. Approval is acknowledged for the reviewed commit and never starts implementation or merges. This feedback route covers proposal PRs; implementation review remains governed by the completion guide.
-
-Blocked refinement and initial proposal questions can be answered on the issue. Other issue comments receive routing guidance instead of silently appearing accepted. Worker executions serialize by the source issue, including requests from its proposal PR, so unrelated issues retain independent queues. The latest queued feedback execution reads the complete bounded owner discussion, including comments posted while another execution was active. No separate bot account or GitHub App is required for this review path.
-
-The worker requires a Linux runner labelled `lighthouse-workflow`, Node.js, Docker, `flock` and `LIGHTHOUSE_ENGINE_CONFIG` pointing to an operator-owned configuration. See the source repository's `src/examples/opencode-engine` deployment example. The imported OpenCode engine starts a foreground container with read-only product source and harness package, a writable result directory and operator-managed provider authentication. Packaged skills load from `/harness/skills`; consumers do not copy the lifecycle skills into their source tree.
-
-Implementation can opt into [repository execution environments](execution-environments.md) for preflighted Node or .NET images and temporary host-managed PostgreSQL. Existing undeclared consumers keep their current image configuration.
-
-Workers can opt into [OpenAI model profiles and bounded delegation](model-profiles.md). Project settings cannot replace the legacy operator model without explicit operator opt-in; configuration receipts do not prove live provider access.
-
-The subscription profile uses Docker isolation and explicitly disables gh-aw's AWF agent sandbox. It has no AWF egress filtering or credential proxy. The engine gets no GitHub token or Docker socket. Only trusted repository workflows may use the runner, whose Docker access is privileged infrastructure access. All repository runners sharing a host must use the same operator lock path to serialize model execution.
-
-Actions exposes the `OpenCode progress and result` step with public progress messages, concise tool activity, quiet-period notices and the validated result. Redacted structured events remain in a separate `opencode-events` artifact and feed the standard gh-aw session and usage parser. The result envelope and runtime receipt identify source, harness and image revisions. Logs redact common credential formats; this is not a guarantee that arbitrary sensitive product content is removed. Review public-repository content and artifact access accordingly. Agent artifacts use GitHub retention; they are not a permanent retrospective archive.
-
-Publication validates the Lighthouse envelope and rereads owner answers, issue state and source revision. Three unresolved reply rounds require an explicit new `refine` label. `agent-working` signals a reservation; human takeover or a changed source prevents publication. Labels are cooperative signals, not locks against arbitrary editors. A runner or artifact failure can require manual reservation reconciliation. A completed refinement never authorizes the next stage or a merge.
-
-Run `lighthouse-sdlc triage --input <file>` to validate one structured triage result and receive its proposed workflow and classification labels. The command is read-only by default; `--apply --labels-file <file>` writes only after the report is ready and the labels file still matches the input.
-
-Use `lighthouse-sdlc route --route <name>` to inspect a route before running it, `stage-result --input <file>` to validate a stage result, `state --input <events.json>` to replay workflow events, `control-plane --input <file>` to validate host declarations, `decompose --input <file>` to produce a dependency-checked slice plan and `stacked --input <file>` to produce an ordered pull-request plan.
-
-Use `lighthouse-sdlc browser-e2e --input <evidence.json>` to validate a Playwright journey result. It is read-only and does not start a browser or write provider state.
-
-Use `lighthouse-sdlc evidence --input <record-or-index.json>` to validate evidence, or add `--build --output <index.json>` to build an index and its compact record files from full records. The command is read-only unless the output path is explicitly provided.
-
-Use `lighthouse-sdlc github-triage --repo <owner/repo> --issue <number> --assessment <file>` for the first GitHub projection. It reads issue metadata by default; `--apply` is the explicit label mutation boundary and rereads the issue before writing.
-
-Use `lighthouse-sdlc github-decompose --repo <owner/repo> --issue <number> --input <file>` to turn a validated slice plan into child-issue operations. The default is a preview; `--apply` creates the child issues in dependency order with the parent link and acceptance evidence in each body.
-
-Declare selected adoption capabilities in a JSON file that follows `schemas/capabilities.schema.json`. `reconcile-labels` previews and optionally applies the first local label projection; `github-labels` reads the repository labels through `gh`, creates only missing labels after an explicit `--apply`, preserves existing values and records `.lighthouse/reconciliation/labels.json`.
-
-`capabilities.json` is the versioned adoption catalog. It currently declares the GitHub labels capability, its label roles and classifications, suggested colors and descriptions, declared transition policy and allowed operations.
-
-The catalog is descriptive until a consumer creates an explicit plan. `lighthouse upgrade` can discover it, but only `lighthouse capabilities apply --plan-file ... --authorize ...` may write provider state.
-
-Every catalog entry must name a registered adapter. Package verification fails when an entry has no adapter, and a new adapter is complete only when its plan, apply, verification, evidence and packaged-consumer fixture are covered by CI.
-
-`selected-by-default` capabilities appear as pending until the adopter selects or declines them. `opt-in` capabilities appear as available and do not make `upgrade` or `verify` fail until the adopter selects them.
-
-Evidence is explicit: an absent field appears in `missingEvidence`, a check that cannot run appears in `unavailableChecks`, and a judgement awaiting review appears in `pendingReview`. Only `provided` evidence can make a report ready to apply.
-
-The package is a source of lifecycle instructions and contracts; an adopter's host adapter decides where provider-specific projections are installed.
-
-The [external host contract](host-contract.md) supports owner-authorized `refine` labels, schema-1 compatibility and the shared deterministic event router. Work reservations use `agent-working` and `human-working`; the host owns the durable lock.
-
-## Implementation delivery
-
-Install with `--with-implement` and provision the implementation engine image. An owner can request `implement` directly. With this worker installed, successful refinement also hands the issue to an independently dispatched implementation workflow. A blocked refinement waits for the owner's answer; `future` pauses implementation.
-
-The router has two jobs: decide the stage and dispatch it. Every installed stage (`refine`, `propose`, `implement`, `integrate`, `review`) has its own execution. The router records a receipt on the source issue before sending and preserves the original event in an Actions artifact. Preparation authenticates the bot comment, router run and attempt, artifact digest, stage and worker revision, then rechecks current source and owner intent. Workflow revision and product revision remain separate so an owner can test a reviewed workflow branch. Native events dispatch the default-branch worker while preserving the originating event revision; PR review events can use a [PR merge ref](https://docs.github.com/en/actions/reference/workflows-and-actions/events-that-trigger-workflows#pull_request_review), which is not a dispatchable branch.
-
-Each stage request is stable across router reruns. Automatic continuation also keys on the completed source run, preventing duplicate completion events from launching the next stage twice. Dispatch jobs serialize receipt creation; workers serialize execution by issue and claim each request once. Owner PR feedback can wait behind a confirmed active worker and reads the current bounded discussion when admitted. Unconfirmed sends block further requests for the issue until inspected. Routine reruns never reclaim an already claimed request.
-
-Issue receipts show `📥 Requested`, `▶️ Execution admitted`, `⏸️ Waiting for your response`, `✅ Completed` or `❌ Failed or cancelled`, with the phase and execution link. These are the last host observations; open Actions for current queue, cancellation and job status. Result comments retain their validated outcome separately. A lost response or interrupted cleanup can leave an older receipt status, so the display never grants permission to continue.
-
-Successful refinement explicitly wakes the router after publication and reservation release when implementation is installed. This avoids depending solely on GitHub's follow-up events for work dispatched with `GITHUB_TOKEN`. The router waits up to two minutes for the refinement execution to finish and verifies its original owner request, installed continuation policy and published result. The next worker rechecks that evidence, current owner intent and `future` before executing. Native completion events and the explicit wake-up share one dispatch identity, so they cannot start implementation twice. Owner replies resume the blocked stage; proposal review and completion keep their existing approval checks. Integration still requires an explicit owner merge decision for the accepted head. Review retains its integration origin with the protected evidence record, without depending on temporary request artifacts to authenticate that historical record.
-
-For acceptance or deliberate event replay, the owner can dispatch the router with `issue`, the expected next `stage` and `after_run` set to the completed execution ID. The bot can only request the authenticated refinement-to-implementation continuation. Both use the same fresh observations and deduplication as `workflow_run`; neither can force a transition or resend an uncertain request. If the bounded wait expires, inspect the source run and replay after it completes. An expired request artifact, changed source, changed intent or edited receipt blocks admission. Request artifacts last 14 days. Inspect origin and worker runs before reconciling uncertainty; there is no database, persistent dispatcher or SoFa dependency.
-
-The worker creates the OpenSpec plan, implements it and runs checks in one workspace. The PR contains both the plan and code. A separate proposal PR remains available for design-only work; merging one is not an implementation prerequisite.
-
-By default, repositories with a `verify` npm script use `npm ci --ignore-scripts` and `npm run verify`. Other repositories configure checks once in `.lighthouse/implement.json`:
-
-```json
-{
-  "defaults": {
-    "reviewRequired": false,
-    "scope": "Implement only the issue and its acceptance criteria.",
-    "paths": ["*"],
-    "checks": [["npm", "ci", "--ignore-scripts"], ["npm", "run", "verify"]]
-  }
-}
+```sh
+node node_modules/@juangcarmona/lighthouse-sdlc/src/install-workflows.mjs . <immutable-lighthouse-commit> --with-completion
 ```
 
-`*` permits project files; credentials, Git metadata, workflow and harness configuration remain protected. A directory ending in `/` limits writes to that subtree. Existing issue-specific policies still override defaults. `reviewRequired: true` reserves candidate acceptance for a human; `false` allows a complete candidate to become ready for PR review after required CI passes. Every implementation PR starts as a draft. Neither setting authorizes merge.
-
-OpenCode edits a temporary copy, with 30 minutes to return an envelope. The adapter validates at most 512 changed regular files, 4 MiB per file and 16 MiB total, excluding Git-ignored new output while retaining every tracked edit. New reports follow the project’s `.gitignore`; an ignore rule cannot hide changes to existing source. It reconstructs the exact candidate and reruns the configured commands in a fresh container without provider or GitHub credentials. Checks share a ten-minute limit. Only the candidate files enter the PR; logs, screenshots and the retrospective remain in the `implementation-evidence` Actions artifact for 30 days. Result receipts and redacted OpenCode events retain their existing 14-day lifetime. These artifacts are evidence delivery, not permanent archival.
-
-The publisher rechecks source, owner answers, reservation and policy before creating a new branch. Starting implementation removes the issue's `ready` label. A linked draft PR projects `pr-draft`; a complete candidate becomes `pr-ready` only when required CI passes and GitHub marks the PR ready. A successful CI job may call `pr-state-actions.mjs` with `LIGHTHOUSE_CI_RECONCILE=true` to project that state immediately; the script verifies the current run and required checks. The router also rechecks open implementation PRs every five minutes because GitHub can suppress completion events in chained workflows. The issue comment links to the PR, whose description uses `Refs #...` until post-merge review closes the issue. Owner PR feedback updates the same branch with a non-forced push and returns it to draft while corrections run. A changed head or edited feedback stops publication. The subscription engine still has outbound networking and provider authentication inside its container; shell permissions are not credential isolation. Use only owner-authorized work on the dedicated host.
-
-To recover a failed candidate, an owner may add `"seed": {"base": "<40-character commit>", "head": "<40-character commit>"}` to that issue’s implementation policy. The head must be one commit directly on the declared base in the same repository. Preparation rejects out-of-scope files, links and changes whose base file no longer matches the current default branch. It binds the validated seed to the request and restores it in the disposable workspace. The engine continues that candidate, reruns checks and creates a fresh PR; the seed branch is never modified. A seed supplies work to inspect, not completion or approval evidence.
-
-## Integration and review
-
-The optional [GitHub completion adapter](completion.md) handles PR approval, CI completion, merge checks and the final review. Install with `--with-completion` and explicitly adopt evidence publication in the GitHub profile. Merge authorization remains separate from a passed agent assessment.
-
-## Replies to blocked stages
-
-An owner reply to a blocked refinement or proposal resumes that same stage. The router reads current issue state, acknowledges receipt with a reaction and verifies the latest trusted blocked report before admitting work. Preparation validates its run and artifacts, binds the reply to the previous input and adds a source-linked acknowledgement. Proposal replies retain the passed refinement evidence and include all owner answers; they do not approve implementation or merge. Published reports name the stage explicitly.
-
-Passed proposal reports and unrelated issue comments do not grant continuation. Owner feedback on an implementation PR updates that PR; approval requests integration when completion is enabled. Reservations and existing proposal PRs prevent duplicate work. Changed source, edited earlier intent, unavailable artifacts or withdrawn readiness fail admission rather than reusing stale approval. The owner can request fresh refinement when those inputs change. Direct GitHub replies remain supported independently of any future external-client comment or receipt contract.
-
-The source repository [worker catalogue](../../../docs/architecture/06-runtime-view/worker-catalogue.md) describes installed routes and worker boundaries.
-
-The `apply-review` worker is installed with proposal support. It also handles implementation feedback when implementation is installed, preserving its `implement` result. Verified feedback has a stable dispatch identity across repeated events. Approval retains its separate integration route.
-
-## Worker maintenance
-
-Install the optional deterministic workflow with `--with-maintenance`. After reviewing its permissions, set `LIGHTHOUSE_MAINTENANCE_ENABLED=true` and the existing `LIGHTHOUSE_AUTOMATION_ENABLED=true` to observe open owner issues every 30 minutes, or dispatch a single issue manually. Observation alone performs no retry. Set `LIGHTHOUSE_RECOVERY_ENABLED=true` separately to permit bounded recovery; removing it also stops admission of already-requested retries.
-
-Recovery authenticates the original dispatch and its bounded chain, current source and workflow revision, owner intent, reservation and Actions job evidence. It retries only failed or timed-out refine/propose/implement/apply-review executions whose preparation passed and whose trusted publication step is positively recorded as skipped. Each retry is a new receipt and immutable request, at most two per original request, delayed at least 30 minutes after the previous execution. A newer owner request supersedes older recovery candidates. Workers retain their lifecycle gates and current authority checks.
-
-Cancellation, integration/review, human decisions, stale intent/source, expired artifacts, incomplete jobs, uncertain dispatch or publication, and abandoned reservations require operator inspection. A matching unclaimed execution can be identified for reconciliation, but missing confirmation never authorizes resend. Inspect the linked run and its actual effects before making a new owner request. Retries never clear another execution's reservation. Current receipt and Actions observations determine the decision; raw agent prose cannot grant retry authority.
-
-Maintenance bounds are 100 open owner issues, 500 scanned issue/PR entries, 1,000 comments per issue and 100 jobs per execution. Exceeding a bound fails visibly. Original dispatch artifacts retain their existing 14-day lifetime. Recovery does not outlive missing evidence. Scheduled observation only scans open owner issues; closed work requires explicit operator inspection.
-
-An active or queued execution without an Actions update for two hours is reported as stalled. Maintenance does not cancel it or release its reservation.
-
-### Worker error reports
+The default installs `triage` and `refine`. `--with-propose` adds proposal and corrections; `--with-implement` adds implementation and automatic refinement continuation; `--with-completion` also adds integration and review. Maintenance is a separate `--with-maintenance` opt-in.
 
-Create one open issue as the repository owner, without workflow labels, for the worker report index. Set `LIGHTHOUSE_REPORT_INDEX_ISSUE` to its issue number after enabling maintenance. The reporter preserves owner prose and maintains a reserved HTML block with report links and creation intent. Removing the variable disables report publication; recovery remains a separate opt-in.
+Review the preview, then repeat with `--apply`; updating differing existing workflows also requires `--replace-reviewed`. Use gh-aw v0.93.2. Commit the source Markdown, router, compiled locks and action pins together. Reconcile [labels](commands/github-labels.md) through the [capability plan/apply commands](commands/capabilities.md); retain adopter customizations. Existing declarations need an explicit review when adopting labels capability version 2. Provision the runner and disable older routers before setting `LIGHTHOUSE_AUTOMATION_ENABLED=true`. See [operator setup and recovery](github-actions.md) and [completion configuration](completion.md).
 
-Reports group failures by worker and a fixed cause code. They contain source issue and execution links, retry state, distinct observed counts and a concrete next action. No logs, issue text or model output enter the report. Repeated observations do not increase counts. Only a successful execution from the same request chain resolves an occurrence; unrelated success cannot hide an earlier failure. A new occurrence reopens the existing report. Manual closure survives repeated observation of that same failure.
+## References
 
-The index prevents duplicate creation when a GitHub response is lost. A later pass links a uniquely matching bot-owned report. If creation is still unconfirmed, reporting stops for inspection instead of sending again. Disable reporting, inspect the maintenance run and search open and closed reports for that worker/cause before editing the index. Preserve a pending entry until a report can be linked or the owner has established that no creation occurred; deleting it permits a new create. Resume only after reconciling actual effects.
+- [Lifecycle stages](stages.json), [gates](gates.json) and [routes](routes.json): provider-neutral contracts. Native worker compositions are described above; an implementation worker includes planning.
+- [Commands](contract.json) and [aliases](command-aliases.json): CLI utilities and agent commands; the configured host exposes aliases.
+- [Operator reference](github-actions.md): installation, credentials, receipts, runtime limits, maintenance and recovery.
+- [Execution environments](execution-environments.md) and [model profiles](model-profiles.md): optional runtime configuration.
+- [External host contract](host-contract.md): legacy host integration; enable only one router for the same events.
+- [Evidence](commands/evidence.md) and [browser evidence](commands/browser-e2e.md): validation contracts. Missing evidence, unavailable checks and pending review remain separate from success.
 
-The reporter scans at most 500 issue/PR entries and retains at most 100 worker/cause entries and 200 distinct observations per report, within a 60 KB body. Overflow fails visibly and requires operator archival; nothing is silently evicted. Counts reflect observations made while reporting was enabled. A closed source issue is outside scheduled scanning, so explicitly dispatch maintenance for it when checking recovery. All report writes share one repository-wide Actions concurrency group.
+ProductShape, ArcShape and OpenSpec own their artifacts. Lighthouse supplies delivery contracts and the optional GitHub adapter; the operator supplies runtime and credentials.

package/capabilities.json

@@ -7,23 +7,26 @@
       "id": "labels",
       "provider": "github",
       "adapter": "github-labels",
-      "version": "1",
+      "version": "2",
       "title": "Lighthouse tracker labels",
       "selection": "selected-by-default",
       "configuration": {
         "roles": ["state", "command", "classification", "overlay"],
         "labels": [
-          { "name": "triage", "role": "state", "color": "8B949E", "description": "Work item is being assessed." },
-          { "name": "refine", "role": "state", "color": "4DA3FF", "description": "Work item is being refined." },
-          { "name": "implement", "role": "state", "color": "1F6FEB", "description": "Work item is being implemented." },
+          { "name": "triage", "role": "command", "color": "8B949E", "description": "Owner request to assess this issue; publication stops at triaged." },
+          { "name": "refine", "role": "command", "color": "4DA3FF", "description": "Owner request to refine; installed policy may continue to implementation." },
+          { "name": "implement", "role": "command", "color": "1F6FEB", "description": "Owner request to plan and implement this issue in one PR." },
+          { "name": "propose", "role": "command", "color": "A371F7", "description": "Owner request for a separate proposal PR from current refinement evidence." },
+          { "name": "future", "role": "overlay", "color": "8B949E", "description": "Pause implementation; triage, refinement and proposal remain available." },
+          { "name": "waiting-review", "role": "state", "color": "D29922", "description": "Inspect the result or PR for feedback or a pending decision." },
           { "name": "wip", "role": "state", "color": "D29922", "description": "Work item is actively in progress." },
           { "name": "agent-working", "role": "overlay", "color": "D29922", "description": "An agent holds the host reservation; wait before editing." },
           { "name": "human-working", "role": "overlay", "color": "A371F7", "description": "Human reservation: agents must stop and release their work." },
-          { "name": "ready", "role": "state", "color": "238636", "description": "Refinement passed; this does not authorize implementation or merge." },
+          { "name": "ready", "role": "state", "color": "238636", "description": "Refinement passed; continuation depends on installed policy and future. Never authorizes merge." },
           { "name": "pr-draft", "role": "state", "color": "8B949E", "description": "The linked implementation PR is a draft." },
           { "name": "pr-ready", "role": "state", "color": "238636", "description": "The linked implementation PR is ready for human review." },
           { "name": "triaged", "role": "state", "color": "4FB3A4", "description": "Owner-admitted triage passed; the owner decides whether to refine." },
-          { "name": "needs-info", "role": "state", "color": "D876E3", "description": "Refinement needs information or a decision; inspect its report." },
+          { "name": "needs-info", "role": "state", "color": "D876E3", "description": "Triage or refinement needs information; the owner answers the reported question." },
           { "name": "review", "role": "state", "color": "A371F7", "description": "Work item is awaiting review." },
           { "name": "size-s", "role": "classification", "dimension": "size", "value": "S", "color": "BFE3FF", "description": "Small work item." },
           { "name": "size-m", "role": "classification", "dimension": "size", "value": "M", "color": "80C2FF", "description": "Medium work item." },
@@ -42,10 +45,10 @@
           { "name": "blast-radius-medium", "role": "classification", "dimension": "blast-radius", "value": "medium", "color": "4FB3A4", "description": "Medium affected surface." },
           { "name": "blast-radius-high", "role": "classification", "dimension": "blast-radius", "value": "high", "color": "0F766E", "description": "Large affected surface." }
         ],
-        "transitions": [{ "from": "triage", "to": "refine" }],
+        "transitions": [],
         "transitionPolicy": {
           "mode": "declared-only",
-          "description": "Only transitions declared by the adopter are legal; the catalog supplies the initial triage-to-refine example."
+          "description": "Declare state transitions for the generic triage CLI explicitly. Native Actions requests and results follow the authenticated adapter; command labels are not state transitions."
         }
       },
       "operations": {

package/completion.md

@@ -4,7 +4,7 @@ The optional completion adapter finishes an implementation through the adopter's
 
 ## Adoption
 
-Install with `install-workflows <repository> <immutable-lighthouse-commit> --with-completion`. Preview first; `--apply` writes selected workflows and compiles them with gh-aw v0.93.2. Existing differing files require `--replace-reviewed`. Completion includes refine, propose and implement; it adds no new lifecycle stage.
+Follow the [packaged workflow installation and update procedure](README.md#install-or-update-workflows) with `--with-completion`. This includes triage, refine, propose, implement and corrections; it adds no new lifecycle stage.
 
 In the existing `.lighthouse/github.json`, retain the adopted required checks and protected `evidenceBranch`, and add:
 

package/execution-environments.md

@@ -41,3 +41,24 @@ Cancellation first removes workload containers, then removes services. Forced ho
 See the source repository's `src/examples/opencode-engine/ENVIRONMENTS.md` for local build, host installation, update, rollback and clean consumer acceptance instructions. Registry publication and production deployment are not part of this profile.
 
 Implementation and independent validation each create a local Git repository containing one candidate snapshot commit, without remotes, checkout configuration or hooks. This supports Git-based working-tree checks without exposing the original checkout. It does not certify earlier commits; full-history security checks remain a separate repository CI responsibility.
+
+## Resource limits and command completion
+
+The optional operator setting `resources` accepts `implementationPids` and `planningPids`, each an integer from 128 to 4096. Defaults are 1024 and 128. Implementation and independent validation use the same implementation limit. These are Linux task slots, including threads; they do not count workflow jobs. Measure a representative sequential browser suite before lowering the limit or increasing browser concurrency.
+
+```json
+{
+  "resources": {
+    "implementationPids": 1024,
+    "planningPids": 128
+  }
+}
+```
+
+Merge this optional section into the operator configuration; preserve its image and authentication settings. The pinned adapter reads it at the start of each execution. Current runs keep their original settings. Older adapters do not consume these fields: update each adopter's immutable workflow pin through the supported installer before relying on them. The defaults require no configuration change.
+
+The [implementation skill](skills/implement/SKILL.md#workspace-command-slot) uses one managed command slot for installation, builds and tests. Each attempt has a unique receipt and log. A background shell response means execution is still pending; the agent waits for the terminal receipt before editing or retrying. Stopping a managed command terminates its process group, including background preview servers, before releasing the slot.
+
+The adapter supervises the image's existing entrypoint and each independent check with the same packaged Node helper. On Linux cgroup v2, it records task peak/limit, task-limit rejections, peak memory and OOM kills while the container still exists. `runtime.json.execution` and each `checks.json` entry retain the sanitized diagnostic summary, exit code and signal. Unsupported counters remain `null`. A confirmed resource rejection, abort, timeout or cancellation fails the attempt; diagnostics do not grant publication or retry authority.
+
+Adapter and mounted-skill updates require a new workflow source pin, without an engine-image rebuild. Rebuild only when changing tools, the engine binary or baked image policy. Follow the [workflow update procedure](README.md#install-or-update-workflows), validate on one consumer, then roll out to the remaining repositories between runs.

package/github-actions.md

@@ -0,0 +1,106 @@
+# GitHub Actions operator reference
+
+For labels, everyday actions and automatic continuation, start with the [delivery guide](README.md). Read this reference when installing workflows, provisioning the runtime or recovering a failed execution.
+
+## Installation and runtime
+
+The optional router accepts owner-added `triage` and `refine` labels, owner replies to pending questions and owner manual dispatches. It dispatches the compiled gh-aw refinement worker as a separate execution. With `--with-propose`, an owner-added `propose` label or explicit manual stage selection dispatches the proposal worker independently. Actions authorizes the request, reserves the issue, runs OpenCode, validates its result and publishes through a separately credentialed job. SoFa can observe these runs without participating in execution.
+
+Preview installation with `node node_modules/@juangcarmona/lighthouse-sdlc/src/install-workflows.mjs <repository> <immutable-lighthouse-commit>`. Install gh-aw v0.93.2, then add `--apply` to write and compile the selected sources. Existing different files require review and `--replace-reviewed`. Commit the Markdown, router, shared engine definition, generated lock and action pins together. Set the repository variable `LIGHTHOUSE_AUTOMATION_ENABLED=true` after provisioning the runner and disabling previous routers.
+
+The installer enables `triage` and `refine` by default. Add `--with-propose` to install the proposal worker as well. Add `--with-implement` for implementation (including proposal support). Add `--with-completion` to enable integration and review with an explicit GitHub profile opt-in; see the [completion guide](completion.md). Foundation initialization and upgrades do not install workflows. On upgrade from an older baseline, existing workflows remain untouched and leave the foundation's managed-file inventory. Review and remove obsolete projections explicitly.
+
+Reconcile the [label catalog](capabilities.json), including `propose`, `waiting-review` and `future`, before enabling the corresponding workers. The proposal worker requires `ready` and a successful refinement from the same source revision and owner intent. Preparation authenticates its Actions request and result artifacts; a label or copied comment is insufficient. If evidence expired or the source changed, run `refine` again first. The explicit owner request authorizes proposal work. It does not approve the resulting design or implementation.
+
+OpenSpec 1.15.0 supplies the `spec-driven` scaffold and artifact instructions in preparation. OpenCode returns bounded Markdown files under `openspec/changes/issue-<number>-proposal/`. The separate publisher validates those files with the provider, creates a fresh proposal branch and opens a PR with a link to the run. Existing proposal directories and open proposal PRs stop admission. Product code, existing branches and OpenSpec configuration remain untouched. Failed publication may leave a proposal branch; inspect it before retrying. The adopter must allow Actions to create PRs; this repository setting also permits Actions approvals, although proposal workers never approve or merge PRs. The optional integration worker merges only after current owner authorization and passing checks. PRs created with `GITHUB_TOKEN` generate `pull_request` runs that require maintainer approval. Review the proposed changes, then select **Approve workflows to run** on the PR before relying on CI. This is a CI execution gate, separate from accepting the proposal or authorizing implementation. See [GitHub token-triggered runs](https://docs.github.com/en/actions/concepts/security/github_token#when-github_token-triggers-workflow-runs).
+
+A completed proposal links its PR and sets `waiting-review`. Review the proposal there: owner comments, inline comments and submitted change requests run the independent `apply-review` worker with a `propose` result against the existing artifacts and update the same PR. Only open, same-repository proposals created by `github-actions[bot]` are eligible. The host checks current feedback, issue readiness and the PR head before a non-forced branch update. A changed head or discussion stops publication. Approval is acknowledged for the reviewed commit and never starts implementation or merges. This feedback route covers proposal PRs; implementation review remains governed by the completion guide.
+
+Blocked refinement and initial proposal questions can be answered on the issue. Other issue comments receive routing guidance instead of silently appearing accepted. Worker executions serialize by the source issue, including requests from its proposal PR, so unrelated issues retain independent queues. The latest queued feedback execution reads the complete bounded owner discussion, including comments posted while another execution was active. No separate bot account or GitHub App is required for this review path.
+
+The worker requires a Linux runner labelled `lighthouse-workflow`, Node.js, Docker, `flock` and `LIGHTHOUSE_ENGINE_CONFIG` pointing to an operator-owned configuration. See the source repository's `src/examples/opencode-engine` deployment example. The imported OpenCode engine starts a foreground container with read-only product source and harness package, a writable result directory and operator-managed provider authentication. Packaged skills load from `/harness/skills`; consumers do not copy the lifecycle skills into their source tree.
+
+Implementation can opt into [repository execution environments](execution-environments.md) for preflighted Node or .NET images and temporary host-managed PostgreSQL. Existing undeclared consumers keep their current image configuration.
+
+Implementation and validation default to 1,024 process/thread slots. The operator can set bounded `resources.implementationPids` and `resources.planningPids` in the engine configuration. The [resource guide](execution-environments.md#resource-limits-and-command-completion) covers sizing and adoption. Managed commands serialize installs, builds and tests; a background shell response must be followed to a terminal receipt. Runtime and check receipts record observed cgroup resource failures separately from abort, timeout and cancellation.
+
+Workers can opt into [OpenAI model profiles and bounded delegation](model-profiles.md). Project settings cannot replace the legacy operator model without explicit operator opt-in; configuration receipts do not prove live provider access.
+
+The subscription profile uses Docker isolation and explicitly disables gh-aw's AWF agent sandbox. It has no AWF egress filtering or credential proxy. The engine gets no GitHub token or Docker socket. Only trusted repository workflows may use the runner, whose Docker access is privileged infrastructure access. All repository runners sharing a host must use the same operator lock path to serialize model execution.
+
+Actions exposes the `OpenCode progress and result` step with public progress messages, concise tool activity, quiet-period notices and the validated result. Redacted structured events remain in a separate `opencode-events` artifact and feed the standard gh-aw session and usage parser. The result envelope and runtime receipt identify source, harness and image revisions. Logs redact common credential formats; this is not a guarantee that arbitrary sensitive product content is removed. Review public-repository content and artifact access accordingly. Agent artifacts use GitHub retention; they are not a permanent retrospective archive.
+
+Publication validates the Lighthouse envelope and rereads owner answers, issue state and source revision. Three unresolved reply rounds require an explicit new `refine` label. `agent-working` signals a reservation; human takeover or a changed source prevents publication. Labels are cooperative signals, not locks against arbitrary editors. A runner or artifact failure can require manual reservation reconciliation. Refinement can continue only under the still-effective implementation authorization recorded by the installed router; it never authorizes merge.
+
+## Implementation delivery
+
+Install with `--with-implement` and provision the implementation engine image. An owner can request `implement` directly. With this worker installed, successful refinement also hands the issue to an independently dispatched implementation workflow. A blocked refinement waits for the owner's answer; `future` pauses implementation.
+
+The router decides the stage and dispatches it. Every installed stage (`triage`, `refine`, `propose`, `implement`, `integrate`, `review`) has its own execution. The router records a receipt on the source issue before sending and preserves the original event in an Actions artifact. Preparation authenticates the bot comment, router run and attempt, artifact digest, stage and worker revision, then rechecks current source and owner intent. Workflow revision and product revision remain separate so an owner can test a reviewed workflow branch. Native events dispatch the default-branch worker while preserving the originating event revision; PR review events can use a [PR merge ref](https://docs.github.com/en/actions/reference/workflows-and-actions/events-that-trigger-workflows#pull_request_review), which is not a dispatchable branch.
+
+Each stage request is stable across router reruns. Automatic continuation also keys on the completed source run, preventing duplicate completion events from launching the next stage twice. Dispatch jobs serialize receipt creation; workers serialize execution by issue and claim each request once. Owner PR feedback can wait behind a confirmed active worker and reads the current bounded discussion when admitted. Unconfirmed sends block further requests for the issue until inspected. Routine reruns never reclaim an already claimed request.
+
+Issue receipts show `📥 Requested`, `▶️ Execution admitted`, `⏸️ Waiting for your response`, `✅ Completed` or `❌ Failed or cancelled`, with the phase and execution link. These are the last host observations; open Actions for current queue, cancellation and job status. Result comments retain their validated outcome separately. A lost response or interrupted cleanup can leave an older receipt status, so the display never grants permission to continue.
+
+Successful refinement explicitly wakes the router after publication and reservation release when implementation is installed. This avoids depending solely on GitHub's follow-up events for work dispatched with `GITHUB_TOKEN`. The router waits up to two minutes for the refinement execution to finish and verifies its original owner request, installed continuation policy and published result. The next worker rechecks that evidence, current owner intent and `future` before executing. Native completion events and the explicit wake-up share one dispatch identity, so they cannot start implementation twice. Owner replies resume the blocked stage; proposal review and completion keep their existing approval checks. Integration still requires an explicit owner merge decision for the accepted head. Review retains its integration origin with the protected evidence record, without depending on temporary request artifacts to authenticate that historical record.
+
+For acceptance or deliberate event replay, the owner can dispatch the router with `issue`, the expected next `stage` and `after_run` set to the completed execution ID. The bot can only request the authenticated refinement-to-implementation continuation. Both use the same fresh observations and deduplication as `workflow_run`; neither can force a transition or resend an uncertain request. If the bounded wait expires, inspect the source run and replay after it completes. An expired request artifact, changed source, changed intent or edited receipt blocks admission. Request artifacts last 14 days. Inspect origin and worker runs before reconciling uncertainty; there is no database, persistent dispatcher or SoFa dependency.
+
+The worker creates the OpenSpec plan, implements it and runs checks in one workspace. The PR contains both the plan and code. A separate proposal PR remains available for design-only work; merging one is not an implementation prerequisite.
+
+By default, repositories with a `verify` npm script use `npm ci --ignore-scripts` and `npm run verify`. Other repositories configure checks once in `.lighthouse/implement.json`:
+
+```json
+{
+  "defaults": {
+    "reviewRequired": false,
+    "scope": "Implement only the issue and its acceptance criteria.",
+    "paths": ["*"],
+    "checks": [["npm", "ci", "--ignore-scripts"], ["npm", "run", "verify"]]
+  }
+}
+```
+
+`*` permits project files; credentials, Git metadata, workflow and harness configuration remain protected. A directory ending in `/` limits writes to that subtree. Existing issue-specific policies still override defaults. `reviewRequired: true` reserves candidate acceptance for a human; `false` allows a complete candidate to become ready for PR review after required CI passes. Every implementation PR starts as a draft. Neither setting authorizes merge.
+
+OpenCode edits a temporary copy, with 30 minutes to return an envelope. The adapter validates at most 512 changed regular files, 4 MiB per file and 16 MiB total, excluding Git-ignored new output while retaining every tracked edit. New reports follow the project’s `.gitignore`; an ignore rule cannot hide changes to existing source. It reconstructs the exact candidate and reruns the configured commands in a fresh container without provider or GitHub credentials. Checks share a ten-minute limit. Only the candidate files enter the PR; logs, screenshots and the retrospective remain in the `implementation-evidence` Actions artifact for 30 days. Result receipts and redacted OpenCode events retain their existing 14-day lifetime. These artifacts are evidence delivery, not permanent archival.
+
+The publisher rechecks source, owner answers, reservation and policy before creating a new branch. Starting implementation removes the issue's `ready` label. A linked draft PR projects `pr-draft`; a complete candidate becomes `pr-ready` only when required CI passes and GitHub marks the PR ready. A successful CI job may call `pr-state-actions.mjs` with `LIGHTHOUSE_CI_RECONCILE=true` to project that state immediately; the script verifies the current run and required checks. The router also rechecks open implementation PRs every five minutes because GitHub can suppress completion events in chained workflows. The issue comment links to the PR, whose description uses `Refs #...` until post-merge review closes the issue. Owner PR feedback updates the same branch with a non-forced push and returns it to draft while corrections run. A changed head or edited feedback stops publication. The subscription engine still has outbound networking and provider authentication inside its container; shell permissions are not credential isolation. Use only owner-authorized work on the dedicated host.
+
+To recover a failed candidate, an owner may add `"seed": {"base": "<40-character commit>", "head": "<40-character commit>"}` to that issue’s implementation policy. The head must be one commit directly on the declared base in the same repository. Preparation rejects out-of-scope files, links and changes whose base file no longer matches the current default branch. It binds the validated seed to the request and restores it in the disposable workspace. The engine continues that candidate, reruns checks and creates a fresh PR; the seed branch is never modified. A seed supplies work to inspect, not completion or approval evidence.
+
+## Integration and review
+
+The optional [GitHub completion adapter](completion.md) handles PR approval, CI completion, merge checks and the final review. Install with `--with-completion` and explicitly adopt evidence publication in the GitHub profile. Merge authorization remains separate from a passed agent assessment.
+
+## Replies to blocked stages
+
+An owner reply to a blocked refinement or proposal resumes that same stage. The router reads current issue state, acknowledges receipt with a reaction and verifies the latest trusted blocked report before admitting work. Preparation validates its run and artifacts, binds the reply to the previous input and adds a source-linked acknowledgement. Proposal replies retain the passed refinement evidence and include all owner answers; they do not approve implementation or merge. Published reports name the stage explicitly.
+
+Passed proposal reports and unrelated issue comments do not grant continuation. Owner feedback on an implementation PR updates that PR; approval requests integration when completion is enabled. Reservations and existing proposal PRs prevent duplicate work. Changed source, edited earlier intent, unavailable artifacts or withdrawn readiness fail admission rather than reusing stale approval. The owner can request fresh refinement when those inputs change. Direct GitHub replies remain supported independently of any future external-client comment or receipt contract.
+
+The [router](workflows/lighthouse-sdlc-router.yml) and [event handler](src/issue-actions.mjs) define installed routes. The [implementation skill](skills/implement/SKILL.md) defines planning and coding within one execution.
+
+The `apply-review` worker is installed with proposal support. It also handles implementation feedback when implementation is installed, preserving its `implement` result. Verified feedback has a stable dispatch identity across repeated events. Approval retains its separate integration route.
+
+## Worker maintenance
+
+Install the optional deterministic workflow with `--with-maintenance`. After reviewing its permissions, set `LIGHTHOUSE_MAINTENANCE_ENABLED=true` and the existing `LIGHTHOUSE_AUTOMATION_ENABLED=true` to observe open owner issues every 30 minutes, or dispatch a single issue manually. Observation alone performs no retry. Set `LIGHTHOUSE_RECOVERY_ENABLED=true` separately to permit bounded recovery; removing it also stops admission of already-requested retries.
+
+Recovery authenticates the original dispatch and its bounded chain, current source and workflow revision, owner intent, reservation and Actions job evidence. It retries only failed or timed-out refine/propose/implement/apply-review executions whose preparation passed and whose trusted publication step is positively recorded as skipped. Each retry is a new receipt and immutable request, at most two per original request, delayed at least 30 minutes after the previous execution. A newer owner request supersedes older recovery candidates. Workers retain their lifecycle gates and current authority checks.
+
+Cancellation, integration/review, human decisions, stale intent/source, expired artifacts, incomplete jobs, uncertain dispatch or publication, and abandoned reservations require operator inspection. A matching unclaimed execution can be identified for reconciliation, but missing confirmation never authorizes resend. Inspect the linked run and its actual effects before making a new owner request. Retries never clear another execution's reservation. Current receipt and Actions observations determine the decision; raw agent prose cannot grant retry authority.
+
+Maintenance bounds are 100 open owner issues, 500 scanned issue/PR entries, 1,000 comments per issue and 100 jobs per execution. Exceeding a bound fails visibly. Original dispatch artifacts retain their existing 14-day lifetime. Recovery does not outlive missing evidence. Scheduled observation only scans open owner issues; closed work requires explicit operator inspection.
+
+An active or queued execution without an Actions update for two hours is reported as stalled. Maintenance does not cancel it or release its reservation.
+
+### Worker error reports
+
+Create one open issue as the repository owner, without workflow labels, for the worker report index. Set `LIGHTHOUSE_REPORT_INDEX_ISSUE` to its issue number after enabling maintenance. The reporter preserves owner prose and maintains a reserved HTML block with report links and creation intent. Removing the variable disables report publication; recovery remains a separate opt-in.
+
+Reports group failures by worker and a fixed cause code. They contain source issue and execution links, retry state, distinct observed counts and a concrete next action. No logs, issue text or model output enter the report. Repeated observations do not increase counts. Only a successful execution from the same request chain resolves an occurrence; unrelated success cannot hide an earlier failure. A new occurrence reopens the existing report. Manual closure survives repeated observation of that same failure.
+
+The index prevents duplicate creation when a GitHub response is lost. A later pass links a uniquely matching bot-owned report. If creation is still unconfirmed, reporting stops for inspection instead of sending again. Disable reporting, inspect the maintenance run and search open and closed reports for that worker/cause before editing the index. Preserve a pending entry until a report can be linked or the owner has established that no creation occurred; deleting it permits a new create. Resume only after reconciling actual effects.
+
+The reporter scans at most 500 issue/PR entries and retains at most 100 worker/cause entries and 200 distinct observations per report, within a 60 KB body. Overflow fails visibly and requires operator archival; nothing is silently evicted. Counts reflect observations made while reporting was enabled. A closed source issue is outside scheduled scanning, so explicitly dispatch maintenance for it when checking recovery. All report writes share one repository-wide Actions concurrency group.

package/host-contract.md

@@ -1,6 +1,6 @@
 # Supervised external host contract
 
-This document describes the legacy external-host adapter. The optional repository-owned issue adapter described in [README.md](README.md#repository-owned-issue-refinement) keeps orchestration and publication in GitHub Actions and uses an independent executor. Neither adapter requires SoFa as a product dependency.
+This document describes the legacy external-host adapter. The optional repository-owned issue adapter described in [README.md](README.md#github-actions) keeps orchestration and publication in GitHub Actions and uses an independent executor. Neither adapter requires SoFa as a product dependency.
 
 Schema version 1 supports one triage or refinement stage. The executable validator in `src/host-contract.mjs` is authoritative; unknown request and effect fields fail validation. Hosts install an exact package version outside the execution workspace.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juangcarmona/lighthouse-sdlc",
-  "version": "0.15.0",
+  "version": "0.15.2",
   "type": "module",
   "description": "Provider-neutral SDLC skills, commands and route contracts for Lighthouse adopters",
   "repository": {
@@ -27,6 +27,7 @@
     "gates.json",
     "meta-commands",
     "README.md",
+    "github-actions.md",
     "request-triage.md",
     "templates",
     "host-contract.md",

package/request-triage.md

@@ -1,5 +1,7 @@
 # Request intake and relative estimates
 
+For GitHub actions and labels, start with the [delivery guide](README.md).
+
 The public form requires the problem and desired result. Examples or context are optional. Do not ask a reporter for acceptance criteria, architecture, an estimate or a PR plan; refinement derives engineering criteria.
 
 ## Admission and continuation
@@ -27,4 +29,4 @@ Refinement rechecks a supplied `context.triage`, returns `output.estimate`, and
 
 ## Upgrade and recovery
 
-Preview `node src/packages/sdlc/src/install-workflows.mjs <repository> <immutable-lighthouse-commit>` from the pinned Lighthouse source. The native triage worker is installed with refinement. Inspect the plan, provision the runner and gh-aw v0.93.2, then add `--apply`; use `--replace-reviewed` only after reviewing differing workflow sources. The installer preserves an existing `.github/ISSUE_TEMPLATE/change-request.yml` and reports it instead of overwriting it. Add `triage` and `triaged` to the repository's declared labels through its normal reconciliation route. Enable automation only after reviewing the workflows and runner. To recover, disable automation and restore the previously reviewed package/workflow revision; issue bodies are never changed.
+Follow the [packaged workflow installation and update procedure](README.md#install-or-update-workflows). Triage is included by default. The installer preserves an existing `.github/ISSUE_TEMPLATE/change-request.yml`. Reconcile `triage`, `triaged` and `needs-info` through the declared label catalog. To recover, disable automation and restore the previously reviewed package/workflow revision; issue bodies are never changed.

package/skills/implement/SKILL.md

@@ -12,10 +12,18 @@ Deliver the issue in one branch, including its OpenSpec plan.
 1. Read the issue, owner answers, repository rules and acceptance criteria. If a required product decision is missing, ask one concrete question and stop.
 2. Read `/harness/skills/propose/SKILL.md` for planning and use the supplied OpenSpec instructions to create or update the proposal, specifications, design and tasks before changing production code. This is the planning part of implementation; return one final implementation envelope. Keep tasks coarse and dependency ordered. Reuse existing planning work where it still applies.
 3. Implement the tasks, with tests that exercise the changed behavior. Follow the repository's architecture and allowed write scope.
-4. Run the repository checks and capture the evidence needed to review the result. Mark only completed tasks as done.
+4. Run dependency installation, builds and tests through the workspace command slot below. Capture their completed exit status and evidence before marking tasks done.
 5. Write a short PR summary: what changed, how it was checked, and any blocker. Put logs, screenshots and the retrospective in the evidence output. Apply Humanizer when available; otherwise remove repetition and unexplained process jargon yourself.
 6. Return the implementation stage result and envelope. Keep missing evidence, failed checks and required decisions explicit. The host publishes the branch for review.
 
 ## Completion
 
 The plan and code are ready to review together, with passing checks. Merge remains subject to repository policy and reviewer authorization.
+
+## Workspace command slot
+
+Run installation, build, verification and browser commands sequentially with `node /harness/src/managed-command.mjs run /output/evidence/commands <unique-attempt-id> -- <executable> <arguments...>`. Create the evidence directory first and redirect each attempt's output to its own log. The wrapper rejects overlapping commands and writes `/output/evidence/commands/<unique-attempt-id>.json`.
+
+When the shell tool backgrounds a command, poll that receipt until `state` is `completed` or `cancelled`. A tool response or a quiet log does not establish command completion. Read `exitCode` before editing the workspace or starting the next command. To interrupt an attempt, run `node /harness/src/managed-command.mjs stop /output/evidence/commands` and wait for its terminal receipt before retrying with a new ID.
+
+Keep browser workers within the container budget. Start and stop a preview server inside the same managed command as its browser check; the wrapper cleans up that command's background children. Store screenshots and reports under `/output/evidence/` so they survive workspace cleanup.