@codyswann/lisa 2.247.3 → 2.250.1

package/plugins/lisa-copilot/rules/eager/verification.md

@@ -10,7 +10,7 @@
 
 - **Never claim success without runtime evidence.** "The code looks correct" is not evidence.
 - **If all you did was run tests, typecheck, and lint — you have NOT verified.**
-- **Browser-controller neutrality.** For UI work, control a live browser and perform the Validation Journey as a human would. An in-app Browser/Chrome tool, interactive Playwright control (MCP, API, or ad hoc script), CDP, computer use, or an equivalent controller is acceptable. Do not block merely because one preferred backend is unavailable when another interactive controller can drive the browser. Running an automated Playwright or Maestro test alone is still a quality gate, not the initial empirical evidence; after the live journey passes, codify it in the applicable runner(s).
+- **Browser-controller neutrality.** For UI work, control a live browser and perform the Validation Journey as a human would. An in-app Browser/Chrome tool, interactive Playwright control (MCP, API, or ad hoc script), CDP, computer use, the optional Lisa-owned Kane adapter, or an equivalent controller is acceptable. Kane requires explicit upload approval, a passing `lisa kane probe`, an allow-listed non-production environment, and mutation policy `full`; its provider failure is not a product failure. Do not block merely because one preferred backend is unavailable when another interactive controller can drive the browser. Running an automated Playwright or Maestro test alone is still a quality gate, not the initial empirical evidence; after the live journey passes, codify it in the applicable native runner(s). Kane never replaces those regression gates.
 - **Before starting implementation, state your verification plan** — how you will USE the resulting software to prove it works. A plan that only lists `test`/`typecheck`/`lint` commands is not a plan. Do not begin until confirmed.
 - **After verifying empirically, codify it as a regression test** via the `codify-verification` skill — Playwright for UI, integration test for API/DB/auth, benchmark for performance. Codification is mandatory for every verification type except PR/Documentation/Deploy and Investigate-Only spikes. For **frontend work**, codification is dual-runner: a Playwright spec in the project's Playwright test runner AND a Maestro flow in the Maestro test runner whenever the project supports Maestro (`.maestro/` directory, `maestro:test` script, or Maestro CI workflow) — both encoding the same verified journey, neither a substitute for the other.
 - **The codified proof re-runs in CI.** Codified runtime verification lives where the project's e2e/Playwright tests live (`tests/e2e/**`) and runs as a required CI check for types with verification enforced — so the proof re-runs on every PR, not once by hand.

package/plugins/lisa-copilot/rules/reference/config-resolution.md

@@ -320,6 +320,30 @@ When `github.projects.v2` is present, later setup/doctor and writer preflight va
 | `linear.workspace` | `tracker = "linear"`, `source = "linear"`, or any `linear-*` skill is invoked | Linear workspace slug (e.g. `acme`). |
 | `linear.teamKey` | `tracker = "linear"` | Linear team key (e.g. `ENG`). The team owns the destination Issues. For source mode, projects are workspace-scoped or team-scoped per the URL passed. |
 
+#### `verification.browser.kane`
+
+Kane CLI is an optional empirical-browser provider. It is never enabled by executable discovery
+alone and never replaces native regression runners.
+
+| Field | Required when | Where it lives | Notes |
+|-------|---------------|----------------|-------|
+| `verification.browser.kane.enabled` | using Kane | **committed** | Must be literal `true`; absent/false means Lisa does not probe or select Kane. |
+| `verification.browser.kane.version` | enabled | **committed** | Exact contract-tested version, currently `0.6.3`. Version ranges and implicit latest are rejected. |
+| `verification.browser.kane.cloudUploadApproved` | enabled | **committed** | Exterior human approval that TestMu may receive objectives, screenshots, action logs, variables in scope, metadata, and packaged run artifacts from disposable test environments. |
+| `verification.browser.kane.allowedEnvironments` | enabled | **committed** | Non-empty environment allow-list. `prod` and `production` are invalid regardless of other config. Each environment must also resolve to `exploration.environments.<name>.mutation = full` at run time. |
+| `verification.browser.kane.projectId` | enabled | **committed** | Expected Test Manager project identifier. `lisa kane probe` verifies the active CLI config matches it. |
+| `verification.browser.kane.folderId` | no | **committed** | Optional expected Test Manager folder identifier, also verified by the probe. |
+| `verification.browser.kane.timeoutSeconds` | no | **committed** | Integer 1–600; defaults to 120. Lisa adds a small outer process-kill grace period. |
+
+Credentials never live in Lisa config. Developer OAuth state remains in Kane's protected local
+profile; CI uses its secret store and a dedicated service identity. Local config may override a
+Kane key per the normal per-key precedence, but shared upload policy, allow-list, and Test Manager
+target should be committed so teammates and automations see the same gate.
+
+Use `/lisa:setup-kane` only at the exterior setup gate. Factory workflows invoke
+`lisa-kane-browser`, which calls the Lisa adapter (`lisa kane probe/run`) rather than consuming the
+vendor's global skill or `agents.md`.
+
 #### `usage`
 
 `usage` is optional. It carries non-secret pricing metadata Lisa may use when runtime token counts are trustworthy but runtime monetary cost is absent.
@@ -677,6 +701,7 @@ The shim → vendor mapping is fixed:
 | `lisa-tracker-validate` | `lisa-jira-validate-ticket` | `lisa-github-validate-issue` | `lisa-linear-validate-issue` |
 | `lisa-tracker-verify` | `lisa-jira-verify` | `lisa-github-verify` | `lisa-linear-verify` |
 | `lisa-tracker-read` | `lisa-jira-read-ticket` | `lisa-github-read-issue` | `lisa-linear-read-issue` |
+| `lisa-tracker-claim` | `lisa-jira-claim` | `lisa-github-claim` | `lisa-linear-claim` |
 | `lisa-tracker-evidence` | `lisa-jira-evidence` | `lisa-github-evidence` | `lisa-linear-evidence` |
 | `lisa-tracker-sync` | `lisa-jira-sync` | `lisa-github-sync` | `lisa-linear-sync` |
 | `lisa-tracker-add-journey` | `lisa-jira-add-journey` | `lisa-github-add-journey` | `lisa-linear-add-journey` |
@@ -689,7 +714,7 @@ The `tracker-source-artifacts` skill (formerly `tracker-source-artifacts`) is re
 ## Caller responsibilities
 
 - **PRD-source skills** (`notion-to-tracker`, `confluence-to-tracker`, `linear-to-tracker`, `github-to-tracker`) MUST invoke `tracker-write` and `tracker-validate` — never `jira-write-ticket` / `github-write-issue` / `linear-write-issue` directly. This is what makes a project's destination switchable via config.
-- **Lifecycle skills** (`implement`, `verify`, `monitor`) MUST invoke `tracker-read`, `tracker-evidence`, `tracker-sync` for ticket interaction — never the vendor-specific equivalents.
+- **Lifecycle skills** (`implement`, `verify`, `monitor`) MUST invoke `tracker-read`, `tracker-claim`, `tracker-evidence`, `tracker-sync` for ticket interaction — never the vendor-specific equivalents.
 - **Per-vendor PRD intake skills** (`notion-prd-intake`, `confluence-prd-intake`, `linear-prd-intake`, `github-prd-intake`) compose the PRD-source skills (which in turn invoke the shims) — they do not need to read `tracker` themselves.
 - **Vendor-specific destination skills** (`jira-*`, `github-*`, `linear-*`) read their own vendor config section directly. They do NOT consult `tracker` — they are the targets of dispatch, not the dispatchers.
 

package/plugins/lisa-copilot/rules/reference/convergent-review.md

@@ -0,0 +1,69 @@
+# Convergent Review
+
+Review exists to get correct work merged, not to keep a PR in review orbit.
+Apply this contract to every product, quality, local, bot-parity, and suggestion
+implementation pass.
+
+## Severity Bar
+
+Findings block only when they name a concrete failure scenario in one of these
+classes:
+
+- Correctness: shipped behavior violates the work item, breaks an existing
+  contract, or loses required data.
+- Security: the change creates or preserves an exploitable auth, input,
+  secret-handling, permission, or data-exposure flaw.
+- Data loss: a realistic path can delete, corrupt, overwrite, or strand user or
+  operational state.
+- Contract violation: the change breaks a public API, workflow, generated
+  artifact contract, tracker lifecycle, or documented factory invariant.
+
+Lint-owned style, formatting, taste, general maintainability preferences, and
+speculative improvements are non-blocking unless the repository rule or work
+item explicitly makes them release criteria.
+
+## Required Finding Shape
+
+Every finding must state:
+
+- Severity: `critical`, `major`, `minor`, or `nit`.
+- Blocking: `yes` or `no`.
+- Failure scenario: the concrete user, operator, security, or factory outcome
+  that occurs if the change ships as-is.
+- Evidence: the file, command output, observed behavior, ticket text, or
+  external constraint proving the scenario is reachable.
+- Fix: the smallest actionable correction, or the reason no code change is
+  needed.
+
+A finding marked blocking without a concrete failure scenario is malformed by
+contract. Downgrade it to non-blocking and ask for evidence instead of treating
+it as a merge blocker.
+
+## Dispositions
+
+The implementer resolves each finding with exactly one disposition:
+
+- `fixed`: code, tests, docs, or generated artifacts changed to remove the
+  failure scenario.
+- `deferred`: the issue is real but non-blocking; record the rationale and, when
+  useful, the follow-up work item.
+- `pushed-back`: the finding is not valid for this work because evidence,
+  scope, or existing project rules refute it; reply with that rationale.
+
+If a reviewer cannot refute a `pushed-back` disposition with fresh evidence, the
+author's disposition stands.
+
+## Stopping Rule
+
+After suggestion implementation completes and the required quality and
+verification gates pass, review does not reopen unless new evidence appears:
+
+- a new commit changes the reviewed behavior,
+- a gate fails,
+- a reviewer supplies a previously uncited failure scenario, or
+- the work item scope changes.
+
+Irreconcilable blocking disagreement is not an endless review loop. Move the
+work item to the configured blocked state, add the human-needed marker when the
+decision is human-only, and summarize both positions in operator-readable
+language.

package/plugins/lisa-copilot/rules/reference/tracked-work.md

@@ -0,0 +1,26 @@
+# Tracked Work
+
+The project tracker is the durable operator-facing record for project work. Every session that will produce a durable project outcome must establish exactly one live configured-tracker leaf before the first durable mutation. Durable outcomes include code, tests, configuration, documentation, committed research or plans, investigation findings, commits, and pull requests. Read-only questions, discussion, and repository orientation are exempt until they turn into durable work.
+
+## Resolve, claim, bind
+
+Use `lisa-track` as the single entry point:
+
+1. An explicit ticket is live-read through `lisa-tracker-read` and rejected if it is missing, inaccessible, terminal, a container, outside the configured project, or outside the current repository.
+2. A plain-text request or specification file is searched conservatively within the configured project. Reuse only one uniquely high-confidence matching live leaf. If no unique match exists, create exactly one complete single-repository leaf through `lisa-tracker-write`; never create a thin placeholder or a container.
+3. Idempotently claim the resolved leaf through `lisa-tracker-claim`, which reuses the vendor build-intake claim semantics and post-read verifies the claimed-or-later state.
+4. Before any durable repository work, persist the canonical reference with `node scripts/lisa-work-item.mjs bind <ref>` and verify the worktree-local binding.
+
+The sequence is strict: **live validate/create -> claim -> bind -> durable work**. A failed tracker read/write, claim, or binding blocks the work. Tracker availability must be proven; tool presence or stale session text is not access.
+
+## One canonical identity
+
+The binding is authoritative for the worktree. Branches, commits, pull requests, usage accounting, evidence, and tracker-sync operations all carry the same canonical ref. Branch names are helpful discovery metadata but are not authoritative. After branch creation, `node scripts/lisa-work-item.mjs attach-branch` may attach the local branch to the binding.
+
+Linkage is unconditional for an Implement flow because its input gate always establishes a work item. PR creation must pass the ref to `lisa-git-submit-pr`; `lisa-tracker-sync` must prove the reverse native link or its managed fallback.
+
+## Binding lifetime
+
+Binding state is local machine state and must remain untracked. Keep it through interruptions and blocked outcomes. Run `node scripts/lisa-work-item.mjs clear` only after true terminal completion: required merge/deploy/verification is complete, evidence and two-way PR linkage are recorded, and the tracker item is in its terminal state. Verify that no current binding remains before ending the completed flow.
+
+Git hooks and CI enforce this contract but never create work items. Their recovery message directs the operator to mention the related ticket or run `/lisa:track <description>` to create and bind one.

package/plugins/lisa-copilot/rules/reference/verification.md

@@ -22,9 +22,11 @@ Never assume something works because the code "looks correct." Run a command, ob
 
 ### Browser-controller neutrality
 
-For UI work, the agent must control a live browser and use the product the way a human would: navigate, click, type, submit, and observe the rendered result. **The browser controller is an implementation detail.** An in-app Browser/Chrome tool, interactive Playwright control (MCP, API, or an ad hoc script), CDP, computer use, or an equivalent controller is valid when it drives a real browser session and captures the declared runtime artifacts. Do not block solely because a preferred browser backend is unavailable while another capable interactive controller is available.
+For UI work, the agent must control a live browser and use the product the way a human would: navigate, click, type, submit, and observe the rendered result. **The browser controller is an implementation detail.** An in-app Browser/Chrome tool, interactive Playwright control (MCP, API, or an ad hoc script), CDP, computer use, the optional Lisa-owned Kane CLI adapter, or an equivalent controller is valid when it drives a real browser session and captures the declared runtime artifacts. Do not block solely because a preferred browser backend is unavailable while another capable interactive controller is available.
 
-Running an automated Playwright or Maestro test is still a quality gate, **not the initial empirical verification evidence**. The distinction is how the browser is used, not the library name: interactive Playwright control that performs and observes the Validation Journey is valid empirical verification; invoking a prewritten Playwright spec and reporting its green result alone is not. After the live journey passes, codify that observed behavior in the project's Playwright and/or Maestro runner as required below so CI can prevent regressions.
+Kane is a guarded provider, not a global browser override. It is eligible only when the project explicitly enables it, acknowledges TestMu cloud upload, pins Lisa's contract-tested version, selects an allow-listed non-production environment, and resolves mutation policy `full`; `lisa kane probe` must prove installation, authentication, Test Manager targeting, and usable credits before a factory starts. Invoke it only through `lisa-kane-browser`. Treat auth, Chrome, upload, schema, and control-plane failures as tooling failures. Persist the local evidence pack through Lisa's evidence pipeline because a Test Manager share link is secondary and expiring.
+
+Running an automated Playwright or Maestro test is still a quality gate, **not the initial empirical verification evidence**. The distinction is how the browser is used, not the library name: interactive Playwright control or a guarded Kane objective that performs and observes the Validation Journey is valid empirical verification; invoking a prewritten test and reporting its green result alone is not. After the live journey passes, codify that observed behavior in the project's Playwright and/or Maestro runner as required below so CI can prevent regressions. Kane `_test.md`, code export, and auto-healed recordings are not authoritative substitutes during the initial rollout.
 
 Verification is mandatory. Never skip it, defer it, or claim it was unnecessary. Every task must be verified before claiming completion.
 

package/plugins/lisa-copilot/skills/lisa-codify-verification/SKILL.md

@@ -51,6 +51,8 @@ Before creating anything new, find what the project already has. Use the Tool Di
 
 Do NOT install a new framework if one already exists for the verification type. Use what's there.
 
+If the empirical proof came from Kane, consume its exact objective, observable assertions, URL, and local evidence pack as inputs. Do not commit Kane `_test.md` recordings, generated code, or auto-healed selectors as the authoritative regression. Encode the same behavior in the project's existing native runner under the deterministic rules below.
+
 ### 2. Map verification type → framework
 
 | Verification type | Preferred framework (use whichever the project already has) |

package/plugins/lisa-copilot/skills/lisa-doctor/SKILL.md

@@ -66,6 +66,13 @@ as applicable to the current repo:
 7. **Optional wiki delegation** — when a repo-local `wiki/` exists, either summarize the
    specialized `lisa-wiki-doctor` verdict or explicitly report that deeper wiki checks are
    available there. The base doctor stays narrower than full wiki migration enforcement.
+8. **Optional Kane browser provider** — when `verification.browser.kane.enabled` is true, run the
+   Lisa-owned readiness probe. Require explicit cloud-upload approval, the contract-tested exact
+   version, a non-production environment allow-list, local Chrome/Chromium, Test Manager
+   project/folder targeting, `whoami` authentication, and nonzero/observable credit readiness.
+   Report missing executable/browser, auth failure, wrong target, zero credits, and control-plane
+   failure separately. If Kane is not enabled, report an informational `OK`/not enabled rather than
+   probing or installing it.
 
 If a check family is not applicable to the current repo, report `SKIP` with the reason.
 

package/plugins/lisa-copilot/skills/lisa-exploratory-qa/SKILL.md

@@ -21,6 +21,7 @@ Experience the product the way a **brand-new end user** would: drive its real co
 ## 1. Set up
 
 - **Invoke `use-the-product`** to detect the product type, resolve the environment + mutation policy, and discover personas/subagents. Everything about *how* to drive the product, *where*, and *how much you may mutate* comes from there — do not re-derive it.
+- For a DOM web app whose resolved non-production environment has mutation policy `full`, check the optional Kane provider with `lisa kane probe`. If ready, invoke `lisa-kane-browser` for self-contained journeys and use its screenshots, HAR/network, console, and normalized verdict as evidence. Keep the run on a directly controlled browser for `read-only`/`forbidden` environments. Treat `tool_failed`/`timed_out` as provider findings, never as product bugs.
 - **Confirm the tracker is configured.** Findings are filed as tickets, so read `tracker` from `.lisa.config.json` (local overrides global). If unset, stop and report that the tracker must be configured (`/lisa:setup:jira` / `:github` / `:linear`) before exploratory QA can file findings — do not silently fall back to a report file.
 - Read the `ready` flag (default `false`).
 
@@ -62,6 +63,8 @@ Whether you may create/edit/delete — and as which account — is set by the `u
 
 No report file. Every finding becomes a **leaf work item** via `lisa-tracker-write` (the vendor-neutral writer — it dispatches to the configured tracker and runs the validation gate; never call a vendor `*-write-*` skill directly):
 
+Kane never files the work item itself. Even when it marks a failure as a confirmed product bug, run Lisa's marker-based duplicate search, apply the QA lens, and route the finding through `lisa-tracker-write` exactly as for every other controller.
+
 | Finding | `issue_type` | `build_ready` |
 |---|---|---|
 | User-visible **bug** (broken behavior) | `Bug` | the `ready` flag (default `false`) |

package/plugins/lisa-copilot/skills/lisa-github-claim/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: lisa-github-claim
+description: "Idempotently claims one live GitHub leaf issue for direct Lisa work. Reuses github-build-intake Phase 3b semantics: configured ready-to-claimed relabel, assign-only-if-unassigned, stable managed comment, and post-write verification."
+allowed-tools: ["Bash", "Skill", "Read"]
+---
+
+# Claim GitHub Issue: $ARGUMENTS
+
+Claim exactly one canonical `org/repo#<number>` reference. This is the reusable direct-session counterpart of `lisa-github-build-intake` Phase 3b.
+
+1. Resolve merged `.github.org`, `.github.repo`, optional `.github.queueRepo`, and `github.labels.build` values from local-over-global config. Resolve current-repository identity independently using `repo-scope-split` / `config-resolution` (`.repo` -> `.github.repo` -> `git remote get-url origin` basename). The queue repository defaults to `<github.org>/<github.repo>`; it is only the tracker storage/scan target and never replaces current-repository identity. Resolve the ready and claimed roles from config (defaults `status:ready` and `status:in-progress`); do not hardcode lifecycle decisions.
+2. Require the ref's `org/repo` to equal the resolved queue repository. Invoke `lisa-github-read-issue <ref>` immediately before mutation. When the queue repository differs from the current repository, require exactly the current-repository scope (`repo:<current>`); reject an unlabeled issue, `repo:<other>`, or an ambiguous multi-repo leaf. Also reject a closed issue, an active blocker, any issue with open child work, or a childless Epic per `repo-scope-split` and `leaf-only-lifecycle`.
+3. Inspect the live build lifecycle labels:
+   - Already claimed, review, environment-done, or another configured later non-terminal role -> preserve it and set `claim_outcome: reused`.
+   - Ready or no build lifecycle label -> run `gh issue edit <number> --repo <org>/<repo>`, remove ready when present, and add claimed. This is the idempotency lock.
+   - Terminal label/state -> reject; completed work cannot be rebound as new work.
+4. If and only if the issue is unassigned, add `@me`; leave every existing assignee untouched.
+5. Post the stable marker comment once, deduped against all existing comments:
+
+   ```text
+   [lisa-tracker-claim] Claimed by Lisa. Starting implementation.
+   ```
+
+6. Invoke `lisa-github-read-issue <ref>` again. Success requires the issue to remain open, leaf/current-repo (including the explicit `repo:<current>` proof for an umbrella queue), and in claimed or a later non-terminal role. If the relabel or verification fails, return failure and do not authorize a binding.
+7. Return `tracker_provider: github`, canonical `work_item_ref: <org>/<repo>#<number>`, `claim_outcome: claimed|reused`, assignee outcome, and the post-write status evidence.
+
+Never create an issue here. Never call GitHub for a configured Jira or Linear project.

package/plugins/lisa-copilot/skills/lisa-implement/SKILL.md

@@ -34,18 +34,26 @@ Treat the first successful lead-spawn request (or, on the Codex fallback, the fi
 
 ## Resolve the input (first task assigned to the team)
 
-$ARGUMENTS is either a url to a ticket containing the request, a pointer to a file containing the request, or the request in text format.
+$ARGUMENTS is either a URL/key for an existing work item, a pointer to a file containing the request, or the request in text format. Every form must resolve to exactly one live, claimed tracker leaf and a verified worktree binding before the lead may begin durable work.
 
 The team lead does NOT read the input directly. The first task on the team's plan is "resolve the input" — assigned to a bounded input-resolver teammate, which then:
 
-- If it's a ticket, calls `lisa-tracker-read` (preferred — vendor-agnostic; dispatches per `.lisa.config.json` `tracker`). **Mismatch guard**: if the ticket format doesn't match the configured tracker (e.g., a GitHub URL when `tracker` is `jira`), `tracker-read` stops and reports the error — never auto-translates vendors:
-  - JIRA ticket → `lisa-tracker-read` → `lisa-jira-read-ticket`
-  - GitHub Issue → `lisa-tracker-read` → `lisa-github-read-issue`
-  - Linear identifier or project URL → `lisa-tracker-read` → `lisa-linear-read-issue`
-  - Captures comments and metadata, not just the description.
-- If it's a file, reads the entire file without offset or limit.
-- If it's a plain-text request, uses the provided text verbatim as the resolved input.
-- Returns the resolved input to the team lead, who then proceeds to roster selection.
+The input-resolver invokes `lisa-track $ARGUMENTS` and owns its complete resolve -> claim -> bind transaction:
+
+- **Explicit ticket:** call `lisa-tracker-read` against the configured tracker and require a live open/unresolved current-project leaf. **Mismatch guard:** if the ticket format/project does not match the configured tracker (for example, a GitHub URL when `tracker` is `jira`), stop — never auto-translate vendors or trust pasted/stale ticket text. The read captures comments, graph, and metadata, not just the description.
+- **Specification file:** read the entire file without offset or limit, preserve it as the resolved input, and follow the plain-text resolution path below.
+- **Plain text or file contents:** search the configured project conservatively for open leaves describing the same outcome. Live-validate every candidate through `lisa-tracker-read`; reuse only exactly one high-confidence match. When there is no unique match (zero or ambiguous candidates), synthesize one complete single-repository leaf and invoke `lisa-tracker-write` exactly once with `build_ready: true`, then live-read its canonical returned ref. Never create a thin placeholder, hierarchy, or container.
+- **Claim:** invoke `lisa-tracker-claim <canonical-ref>` and require the provider skill's post-read verified `claimed|reused` result. A failed or inaccessible claim blocks the flow.
+- **Bind before durable work:** only after the verified claim, run:
+
+  ```bash
+  node scripts/lisa-work-item.mjs bind <canonical-ref>
+  ```
+
+  Require a successful readback of that worktree-local binding. On detached HEAD, `branch: null` is the expected pending binding; after branch creation the mandatory `attach-branch` step below must replace it before any commit. Tracker or binding failure stops the flow; never continue untracked.
+- Return the full resolved work-item context plus `tracker_provider`, canonical `work_item_ref`, resolution outcome, claim outcome, and verified binding to the team lead, who then proceeds to roster selection.
+
+The input resolver may perform these tracker and local-binding operations before the Roster Decision because they are the mandatory gate that establishes what work the team is allowed to do. No project source, documentation, plan artifact, branch, or task may be created or changed before this transaction succeeds. Read-only discussion/orientation outside an Implement flow remains exempt per the `tracked-work` rule.
 
 The input resolver is the only teammate that may be spawned before the Roster Decision exists. After it returns the resolved input, do not spawn any lifecycle, research, implementation, review, verification, or learning teammate until the Roster Decision has been recorded.
 
@@ -86,13 +94,14 @@ Using the general-purpose agent in Team Lead session, **determine the base branc
    - **Rebase the feature branch onto `origin/<base>` and resolve any merge conflicts BEFORE starting work.** If the conflicts cannot be resolved cleanly and safely, create a fix task for the agent team (with the conflicting file list and current merge state) and resolve it before implementation begins — never start work on stale or conflicted code.
 4. **The PR targets the resolved base branch** — carry it as `target_branch=<base>` into `lisa-git-submit-pr` (Verify flow). `git-submit-pr` already chooses a closing keyword when the base is the production/default branch and a non-closing reference for a non-terminal environment branch. For a bug fixed on a non-integration environment branch, the current flow is not done until the fix is merged and verified there, then forward cherry-picked down to the integration branch via a linked follow-up.
 
-When the request came from a tracker work item, preserve its native identifier for development linkage:
+Every Implement run now has a tracker work item. Preserve its canonical identifier for development linkage unconditionally:
 
-- Capture `tracker_provider` and `work_item_ref` from the resolved input before creating or reusing a branch. Examples: `github` + `CodySwannGT/lisa#614`, `linear` + `ENG-123`, `jira` + `ENG-123`.
+- Capture `tracker_provider` and `work_item_ref` from the tracked input before creating or reusing a branch. Examples: `github` + `CodySwannGT/lisa#614`, `linear` + `ENG-123`, `jira` + `ENG-123`. Missing linkage is a workflow failure, never an optional/no-ticket mode.
 - If a new branch is needed and the provider can link branches by identifier, include the identifier in the branch name before the human-readable slug. Linear and JIRA integrations commonly link from branch names; GitHub issue linkage is PR-body driven, but including the issue number in the branch name is still useful. Keep branch names URL-safe, for example `codex/ENG-123-add-checkout-copy` or `codex/614-add-checkout-copy`.
+- After the feature branch exists, run `node scripts/lisa-work-item.mjs attach-branch` so the worktree-local binding records the actual branch without treating the branch name as authority.
 - Pass the work-item ref and target branch to `lisa-git-submit-pr` when opening or updating the PR, for example `work_item_ref=CodySwannGT/lisa#614 target_branch=<base resolved from the ticket's environment above>` (not hardcoded `main`). The PR workflow owns provider-specific body text and must decide whether to use a closing keyword or a non-closing reference.
 - After `lisa-git-submit-pr` returns a PR URL, ensure the reverse backlink is present on the source work item by running `lisa-tracker-sync <work_item_ref> pr-ready pr_url=<url> tracker_provider=<provider>`. The sync path must prefer native provider linkage and fall back to one managed `[lisa-pr-link]` comment when native linkage is unavailable or cannot be verified.
-- If the provider has no native branch or PR development-linkage surface, continue without linkage and mention that the provider was skipped.
+- If the provider has no native branch or PR development-linkage surface, the managed `[lisa-pr-link]` fallback is required; never continue without proven ticket-side linkage.
 
 Using the general-purpose agent in Team Lead session, Determine which flow applies:
 1. Research -- needs a PRD (no specification exists)
@@ -185,6 +194,32 @@ Before marking a task complete, the implementing agent records concise MLD into
 
 Each task must have their learnings captured to the ledger by the learner subagent.
 
+## Implement valid suggestions
+
+When review, CodeRabbit, local-review, product, quality, security, or specialist
+feedback arrives, apply the `convergent-review` rule before changing code:
+
+1. Normalize each finding into severity, blocking yes/no, concrete failure
+   scenario, evidence, and proposed smallest fix.
+2. Treat a blocker with no concrete correctness, security, data-loss, or
+   contract-violation scenario as malformed. Reply with the missing-evidence
+   reason and handle it as non-blocking.
+3. Resolve each finding with one disposition:
+   - `fixed`: make the smallest code, test, docs, or generated-artifact change
+     that removes the failure scenario.
+   - `deferred`: record why the issue is real but non-blocking, and file or link
+     follow-up work when useful.
+   - `pushed-back`: cite the evidence, scope boundary, or repository rule that
+     refutes the finding.
+4. If a reviewer cannot refute a pushback with fresh evidence, the author's
+   disposition stands.
+5. After the suggestion-implementation task completes and required gates pass,
+   do not reopen review unless new evidence appears: a relevant new commit, a
+   failed gate, a newly cited failure scenario, or a scope change.
+6. If a blocking disagreement remains irreconcilable, stop the review loop:
+   move the work item to the configured blocked state, add `human-needed` when
+   the decision is human-only, and summarize both positions in plain language.
+
 Before shutting down the team, execute the Verify flow:
 
 1. Run quality gates: lint, typecheck, tests — all must pass. These are prerequisites, NOT verification.
@@ -214,12 +249,13 @@ Before shutting down the team, execute the Verify flow:
 4. Record Implement usage on the originating work artifact via `lisa-usage-accounting` so the work item (or other implementation-owned artifact) gains a direct `lisa-implement` usage entry in the canonical `## Lisa Usage` section. If the parent / child graph is already known, prefer `record_and_rollup` so ancestor totals refresh in the same write; otherwise still write the direct entry, and if runtime usage is unavailable, use `source: unavailable` with nullable token/cost fields instead of skipping the row.
 5. Commit ALL outstanding changes in logical batches on the branch (minus sensitive data/information) — not just changes made by the agent team. This includes pre-existing uncommitted changes that were on the branch before the plan started. Do NOT filter commits to only "task-related" files. If it shows up in git status, it gets committed (unless it contains secrets).
 6. Push the changes - if any pre-push hook blocks you, create a task for the agent team to fix the error/problem whether it was pre-existing or not
-7. Open a pull request with auto-merge on via `lisa-git-submit-pr`, targeting the **base branch resolved from the ticket's environment** (`target_branch=<base>`, per the branch step above), and including the work-item ref when one exists so the PR can be linked natively to the source issue.
+7. Open a pull request with auto-merge on via `lisa-git-submit-pr`, targeting the **base branch resolved from the ticket's environment** (`target_branch=<base>`, per the branch step above), and including the mandatory work-item ref so the PR can be linked natively to the source issue.
 7a. Confirm two-way linkage before treating PR submission as complete: the PR body/title/branch must reference the work item, and the work item must have either a verified native PR link or a single managed `[lisa-pr-link]` fallback comment from `lisa-tracker-sync`.
 8. PR Watch Loop: Drive the PR to merge via the `drive-pr-to-merge` skill — the single source of truth for clearing every blocker (auto-merge with direct-merge fallback, `BEHIND` re-sync, conflict resolution, failing-check fixes, human + bot review-comment handling with thread resolution, stale `CHANGES_REQUESTED` dismissal, and post-merge ancestry verification). `git-submit-pr` already invokes it; if you reach this step with a PR already open, invoke `drive-pr-to-merge` directly with the PR number. For a large review backlog you may fan the code-fix work out to the agent team, but `drive-pr-to-merge` owns the loop and the terminal conditions — do not re-implement them.
-9. Merge the PR, then refresh the ticket-side backlink with `lisa-tracker-sync <work_item_ref> pr-merged pr_url=<url> merge_sha=<sha> tracker_provider=<provider>` when a work item exists.
+9. Merge the PR, then refresh the ticket-side backlink with `lisa-tracker-sync <work_item_ref> pr-merged pr_url=<url> merge_sha=<sha> tracker_provider=<provider>`.
 10. Monitor the deploy action that triggers automatically from the successful merge
 11. If deploy fails, create a task for the agent team to fix the failure, open a new PR and then go back to step 7
 12. Remote verification: `verification-specialist` verifies in target environment (same checks as local verification, but on remote), and refreshes the verdict (step 2a) to reflect the remote result.
 13. `ops-specialist`: post-deploy health check, monitor for errors in first minutes
 14. If remote verification fails, create a task for the agent team to find out why it failed, fix it and return to step 5. **Bound this loop**: after a small number of full fix→deploy→reverify cycles without reaching a passing remote verdict (treat ~3 as the ceiling unless the work item states otherwise), stop retrying — file a build-ready fix ticket, write the verdict with `status: "blocked"` and the diagnosis, and move the work item to blocked rather than looping indefinitely. The completion gate releases on a `blocked` verdict, so the flow ends with a recorded outcome instead of a silent spin or a self-declared success.
+15. After true terminal completion — required merge/deploy/verification passed, usage/evidence and two-way PR linkage are recorded, and the work item is terminal — run `node scripts/lisa-work-item.mjs clear` and verify the worktree has no current binding. Do not clear on an interruption or blocked outcome; preserving the binding is what keeps resumed work attributable.