@codyswann/lisa 3.33.6 → 3.33.8

package/eslint-plugin-component-structure/rules/enforce-component-structure.js

@@ -158,51 +158,71 @@ module.exports = {
     // Check for required files in the directory (only once per directory)
     // We'll do this check only for the first file we encounter
     const cache = new Map();
-    const checkRequiredFiles = () => {
+
+    /**
+     * List the component directory, or return null when there is no directory
+     * to list.
+     *
+     * The previous form wrapped this read AND every `context.report` call below
+     * in one bare `catch (_err) {}`. That swallowed three different things
+     * behind one comment: a missing directory (expected), an unreadable one
+     * (EACCES/EMFILE — the check could not run), and any error thrown by the
+     * reporting calls themselves (the rule is broken). Only the first is
+     * "nothing to check"; the other two made a rule that could not run
+     * indistinguishable from a rule that found nothing wrong.
+     * @returns {string[]|null} Directory entries, or null when absent
+     */
+    const readComponentDir = () => {
+      if (cache.has(dirPath)) return cache.get(dirPath);
       try {
-        const files = cache.has(dirPath)
-          ? cache.get(dirPath)
-          : (() => {
-              const dirFiles = fs.readdirSync(dirPath);
-              cache.set(dirPath, dirFiles);
-              return dirFiles;
-            })();
-        const hasContainer = files.some(
-          f =>
-            f === `${componentName}Container.tsx` ||
-            f === `${componentName}Container.jsx`
-        );
-        const hasView = files.some(
-          f =>
-            f === `${componentName}View.tsx` || f === `${componentName}View.jsx`
-        );
-        const hasIndex = files.some(
-          f => f === "index.ts" || f === "index.tsx" || f === "index.jsx"
-        );
+        const dirFiles = fs.readdirSync(dirPath);
+        cache.set(dirPath, dirFiles);
+        return dirFiles;
+      } catch (error) {
+        // A path that is not a directory is the one genuinely uninteresting
+        // case: there is nothing to check. Anything else means the check did
+        // not run, and must not be reported as a clean result.
+        if (error.code === "ENOENT" || error.code === "ENOTDIR") return null;
+        throw error;
+      }
+    };
 
-        if (!hasContainer) {
-          context.report({
-            node: context.getSourceCode().ast,
-            messageId: "missingContainer",
-            data: { componentName },
-          });
-        }
-        if (!hasView) {
-          context.report({
-            node: context.getSourceCode().ast,
-            messageId: "missingView",
-            data: { componentName },
-          });
-        }
-        if (!hasIndex) {
-          context.report({
-            node: context.getSourceCode().ast,
-            messageId: "missingIndex",
-            data: { componentName },
-          });
-        }
-      } catch (_err) {
-        // Directory might not exist or be accessible
+    const checkRequiredFiles = () => {
+      const files = readComponentDir();
+      if (files === null) return;
+      const hasContainer = files.some(
+        f =>
+          f === `${componentName}Container.tsx` ||
+          f === `${componentName}Container.jsx`
+      );
+      const hasView = files.some(
+        f =>
+          f === `${componentName}View.tsx` || f === `${componentName}View.jsx`
+      );
+      const hasIndex = files.some(
+        f => f === "index.ts" || f === "index.tsx" || f === "index.jsx"
+      );
+
+      if (!hasContainer) {
+        context.report({
+          node: context.getSourceCode().ast,
+          messageId: "missingContainer",
+          data: { componentName },
+        });
+      }
+      if (!hasView) {
+        context.report({
+          node: context.getSourceCode().ast,
+          messageId: "missingView",
+          data: { componentName },
+        });
+      }
+      if (!hasIndex) {
+        context.report({
+          node: context.getSourceCode().ast,
+          messageId: "missingIndex",
+          data: { componentName },
+        });
       }
     };
 

package/package.json

@@ -45,6 +45,7 @@
     "check:duplicate-versions": "node scripts/check-duplicate-versions.mjs",
     "check:required-check-promotions": "node scripts/check-required-check-promotions.mjs",
     "check:work-item": "node scripts/lisa-work-item.mjs validate-pr",
+    "check:work-item:push": "node scripts/lisa-work-item.mjs validate-push",
     "check:thresholds": "node plugins/src/base/hooks/threshold-ratchet.mjs --base HEAD^",
     "verify:health-contract": "bun run build:dist && node scripts/verify-health-contract-built.mjs",
     "verify:health-deterministic": "bun run build:dist && node scripts/verify-health-deterministic-built.mjs",
@@ -131,7 +132,7 @@
     "ws": ">=8.21.0"
   },
   "name": "@codyswann/lisa",
-  "version": "3.33.6",
+  "version": "3.33.8",
   "description": "Claude Code governance framework that applies guardrails, guidance, and automated enforcement to projects",
   "main": "dist/index.js",
   "exports": {

package/plugins/lisa/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa",
-  "version": "3.33.6",
+  "version": "3.33.8",
   "description": "Universal governance — agents, skills, commands, hooks, and rules for all projects",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa",
-  "version": "3.33.6",
+  "version": "3.33.8",
   "description": "Universal governance: agents, skills, commands, hooks, and rules for all projects.",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa/.codex-plugin/skills/lisa-git-submit-pr/SKILL.md

@@ -66,10 +66,17 @@ When updating an existing PR, preserve any existing linkage line unless the new
 After creating or updating the PR, always make the reverse link durable on the source work item when `work_item_ref` is available:
 
 1. Resolve the live PR URL with `gh pr view <pr-number> --json url --jq .url`.
-2. Invoke `lisa-tracker-sync` with the original work item ref, milestone `pr-ready`, `pr_url=<url>`, and `tracker_provider=<provider>` when known.
-3. The vendor sync skill must prefer the provider's native development-link primitive where one is available and verifiable.
-4. If native linkage is unavailable, unconfigured, or cannot be verified, the vendor sync skill must create or update a single managed `[lisa-pr-link]` comment on the work item containing the PR URL. The fallback comment is not optional; it is the ticket-side half of the two-way link.
-5. When the PR later merges, invoke `lisa-tracker-sync` again with milestone `pr-merged`, the same `pr_url`, and the merge SHA when available, so the managed backlink reflects the final state.
+2. Run the backlink command. It is the executable form of this requirement — it writes the managed `[lisa-pr-link]` comment on the work item, or updates the one already there, for every tracker Lisa supports:
+
+   ```bash
+   node scripts/lisa-work-item.mjs backlink --ref <work_item_ref> --pr-url <url>
+   ```
+
+   It is idempotent, so run it on every push rather than deciding whether it is needed. It refuses loudly for a tracker it cannot write, and never silently no-ops. Do not hand-post the comment, and do not describe the posting procedure anywhere: the same file that writes it is the file that checks it, which is what keeps producer and consumer from drifting.
+3. Invoke `lisa-tracker-sync` with the original work item ref, milestone `pr-ready`, `pr_url=<url>`, and `tracker_provider=<provider>` when known. That is the progress-note and status side; it is not what satisfies the traceability check.
+4. When the PR later merges, invoke `lisa-tracker-sync` again with milestone `pr-merged`, the same `pr_url`, and the merge SHA when available.
+
+**Why step 2 exists — do not "simplify" it away as redundant with the `Refs` line.** Under the non-closing rule above, GitHub never creates a native development link at all: that surface *is* the closing-reference mechanism, so no non-closing form can populate it. A PR carrying a perfectly correct `Refs` line still fails the required Work-Item Traceability check without the comment. The managed comment is the ticket-side half of the link, not a fallback for when native linkage happens to be absent.
 
 Do not report PR submission as fully synced while the PR body references the ticket but the ticket has neither a verified native PR link nor the managed backlink comment.
 

package/plugins/lisa/.codex-plugin/skills/lisa-github-sync/SKILL.md

@@ -57,8 +57,13 @@ Optional arguments include `pr_url=<url>` for the live pull request and `merge_s
 When `$ARGUMENTS` includes `pr_url=<url>` for `PR ready` or `PR merged`, ensure the GitHub Issue has a durable ticket -> PR link:
 
 1. Make sure the PR body contains `Refs #<n>` (or the fully qualified cross-repo form) — never a closing keyword, per the GitHub rule in `lisa-git-submit-pr`. Read the issue side with `gh api graphql` against `issue.timelineItems`, or `gh issue view <number> --json closedByPullRequestsReferences`. **Not** `gh issue view --json timelineItems`: `timelineItems` is not a supported field for that command, so the check silently returns nothing useful rather than failing loudly.
-2. Post or update a single managed issue comment starting with `[lisa-pr-link]`. Include the PR URL, milestone (`pr-ready` or `pr-merged`), and merge SHA when available. This is **unconditional**, not contingent on step 1 failing: under the non-closing rule GitHub never creates a native development link (that surface is the closing-reference mechanism), so this comment is the only ticket-side backlink there will be.
-3. Keep the fallback idempotent: search existing comments for `[lisa-pr-link]` and the PR URL; update/replace that managed comment where the provider allows updates, otherwise skip when the current body already matches. Do not append duplicate backlink comments on reruns.
+2. Establish the managed backlink comment by running the command that owns it — never by hand, and never by describing the procedure here:
+
+   ```bash
+   node scripts/lisa-work-item.mjs backlink --ref <work-item> --pr-url <url>
+   ```
+
+   It creates the `[lisa-pr-link]` comment or updates the one already present, instead of appending duplicates, so it is safe to run on every milestone. This is **unconditional**, not contingent on step 1 failing: under the non-closing rule GitHub never creates a native development link (that surface is the closing-reference mechanism), so this comment is the only ticket-side backlink there will be — run it whether or not native linkage exists or cannot be verified, because the required Work-Item Traceability check reads this comment and nothing else guarantees one. The comment carries the marker and the PR URL only; the milestone (`pr-ready` / `pr-merged`) and merge SHA belong in the milestone progress note, so that a rerun at a new milestone still converges on one backlink comment.
 
 Native GitHub linkage cannot be verified under the non-closing rule because it is never created in the first place, so the managed comment is not a contingency here — it is the mechanism. The issue must show the PR from at least one ticket-side surface, and this is the only one available.
 

package/plugins/lisa/.codex-plugin/skills/lisa-implement/SKILL.md

@@ -341,7 +341,7 @@ Before shutting down the team, execute the Verify flow:
 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 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`.
+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 the single managed `[lisa-pr-link]` comment. Establish that comment with `node scripts/lisa-work-item.mjs backlink --ref <work_item_ref> --pr-url <url>` rather than posting it by hand — it is idempotent, and it is the same file that enforces the check, so producer and consumer cannot drift.
 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>`.
 10. Monitor the deploy action that triggers automatically from the successful merge

package/plugins/lisa/.codex-plugin/skills/lisa-jira-sync/SKILL.md

@@ -55,8 +55,13 @@ Before adding a comment, check for an existing milestone comment to avoid duplic
 When `$ARGUMENTS` includes `pr_url=<url>` for `PR ready` or `PR merged`, ensure the JIRA ticket has a durable ticket -> PR link:
 
 1. Prefer the JIRA development-link surface when the site's GitHub/JIRA integration or remote-link API is available through `lisa-atlassian-access`; verify by re-reading the ticket's remote links / development metadata.
-2. If native linkage is unavailable, unconfigured, cross-system, or cannot be verified, create or update a single managed JIRA comment containing the PR URL. The comment must start with `[lisa-pr-link]` and include the milestone (`pr-ready` or `pr-merged`) and merge SHA when available.
-3. Keep the fallback idempotent: read existing comments, find the `[lisa-pr-link]` comment for the same PR URL, and update/skip it instead of appending duplicates. If the current access layer cannot update comments in place, skip when an identical managed comment already exists and otherwise add exactly one replacement comment with the stable marker.
+2. Establish the managed backlink comment by running the command that owns it — never by hand, and never by describing the procedure here:
+
+   ```bash
+   node scripts/lisa-work-item.mjs backlink --ref <work-item> --pr-url <url>
+   ```
+
+   It creates the `[lisa-pr-link]` comment or updates the one already present, instead of appending duplicates, so it is safe to run on every milestone. This is **unconditional** — run it whether or not native linkage exists or cannot be verified, because the required Work-Item Traceability check reads this comment and nothing else guarantees one. The comment carries the marker and the PR URL only; the milestone (`pr-ready` / `pr-merged`) and merge SHA belong in the milestone progress note, so that a rerun at a new milestone still converges on one backlink comment.
 
 The PR body/branch issue key is the PR -> ticket side. This step is the required ticket -> PR side.
 

package/plugins/lisa/.codex-plugin/skills/lisa-linear-sync/SKILL.md

@@ -72,8 +72,13 @@ Call `lisa-linear-access operation: save-comment({issueId: <id>, body: <comment>
 When `$ARGUMENTS` includes `pr_url=<url>` for `pr-ready` or `pr-merged`, ensure the Linear Issue has a durable ticket -> PR link:
 
 1. Prefer Linear's native GitHub attachment / pull request link when the integration has attached the PR through the branch name, PR title, or PR body issue identifier. Verify by re-reading the Issue and its attachments / relations where the Linear access layer exposes them.
-2. If native linkage is unavailable, unconfigured, cross-system, or cannot be verified, create or update a single managed Linear comment containing the PR URL. The comment must start with `[lisa-pr-link]` and include the milestone (`pr-ready` or `pr-merged`) and merge SHA when available.
-3. Keep the fallback idempotent: read existing comments where the access layer exposes them, find the `[lisa-pr-link]` comment for the same PR URL, and update/skip it instead of appending duplicates. If comment update is unavailable, skip when an identical managed comment already exists and otherwise add exactly one replacement comment with the stable marker.
+2. Establish the managed backlink comment by running the command that owns it — never by hand, and never by describing the procedure here:
+
+   ```bash
+   node scripts/lisa-work-item.mjs backlink --ref <work-item> --pr-url <url>
+   ```
+
+   It creates the `[lisa-pr-link]` comment or updates the one already present, instead of appending duplicates, so it is safe to run on every milestone. This is **unconditional** — run it whether or not native linkage exists or cannot be verified, because the required Work-Item Traceability check reads this comment and nothing else guarantees one. The comment carries the marker and the PR URL only; the milestone (`pr-ready` / `pr-merged`) and merge SHA belong in the milestone progress note, so that a rerun at a new milestone still converges on one backlink comment.
 
 The PR branch/title/body identifier is the PR -> Linear side. This phase is the required Linear -> PR side.
 

package/plugins/lisa/.codex-plugin/skills/lisa-tracker-sync/SKILL.md

@@ -52,8 +52,13 @@ When `$ARGUMENTS` includes `pr_url=<url>` with milestone `pr-ready` or `pr-merge
 
 1. Prefer the provider's native development-link primitive when Lisa can write and verify it for that provider.
 2. Verify the native link using the provider read surface when available.
-3. If the native link is unavailable, unconfigured, cross-system, or cannot be verified, create or update one managed backlink comment on the work item containing the PR URL and current milestone.
-4. Keep the comment idempotent by using a stable marker such as `[lisa-pr-link]`; reruns update or skip the existing managed comment rather than appending duplicates.
+3. Whether or not the native link exists or cannot be verified, establish the managed backlink comment with the one command that owns it:
+
+   ```bash
+   node scripts/lisa-work-item.mjs backlink --ref <work-item> --pr-url <url>
+   ```
+
+4. That command is idempotent by construction — it updates the existing `[lisa-pr-link]` comment rather than appending duplicates — and it refuses loudly for a tracker it cannot write. Do not restate its procedure in a vendor skill; the file that writes the comment is the file that checks it, and that is what stops the two from drifting.
 
 This is the reverse half of `lisa-git-submit-pr`'s PR body linkage. A PR that mentions a ticket is not considered fully synced until the ticket also has either a verified native PR link or the managed fallback comment.
 

package/plugins/lisa/skills/lisa-git-submit-pr/SKILL.md

@@ -66,10 +66,17 @@ When updating an existing PR, preserve any existing linkage line unless the new
 After creating or updating the PR, always make the reverse link durable on the source work item when `work_item_ref` is available:
 
 1. Resolve the live PR URL with `gh pr view <pr-number> --json url --jq .url`.
-2. Invoke `lisa-tracker-sync` with the original work item ref, milestone `pr-ready`, `pr_url=<url>`, and `tracker_provider=<provider>` when known.
-3. The vendor sync skill must prefer the provider's native development-link primitive where one is available and verifiable.
-4. If native linkage is unavailable, unconfigured, or cannot be verified, the vendor sync skill must create or update a single managed `[lisa-pr-link]` comment on the work item containing the PR URL. The fallback comment is not optional; it is the ticket-side half of the two-way link.
-5. When the PR later merges, invoke `lisa-tracker-sync` again with milestone `pr-merged`, the same `pr_url`, and the merge SHA when available, so the managed backlink reflects the final state.
+2. Run the backlink command. It is the executable form of this requirement — it writes the managed `[lisa-pr-link]` comment on the work item, or updates the one already there, for every tracker Lisa supports:
+
+   ```bash
+   node scripts/lisa-work-item.mjs backlink --ref <work_item_ref> --pr-url <url>
+   ```
+
+   It is idempotent, so run it on every push rather than deciding whether it is needed. It refuses loudly for a tracker it cannot write, and never silently no-ops. Do not hand-post the comment, and do not describe the posting procedure anywhere: the same file that writes it is the file that checks it, which is what keeps producer and consumer from drifting.
+3. Invoke `lisa-tracker-sync` with the original work item ref, milestone `pr-ready`, `pr_url=<url>`, and `tracker_provider=<provider>` when known. That is the progress-note and status side; it is not what satisfies the traceability check.
+4. When the PR later merges, invoke `lisa-tracker-sync` again with milestone `pr-merged`, the same `pr_url`, and the merge SHA when available.
+
+**Why step 2 exists — do not "simplify" it away as redundant with the `Refs` line.** Under the non-closing rule above, GitHub never creates a native development link at all: that surface *is* the closing-reference mechanism, so no non-closing form can populate it. A PR carrying a perfectly correct `Refs` line still fails the required Work-Item Traceability check without the comment. The managed comment is the ticket-side half of the link, not a fallback for when native linkage happens to be absent.
 
 Do not report PR submission as fully synced while the PR body references the ticket but the ticket has neither a verified native PR link nor the managed backlink comment.
 

package/plugins/lisa/skills/lisa-github-sync/SKILL.md

@@ -57,8 +57,13 @@ Optional arguments include `pr_url=<url>` for the live pull request and `merge_s
 When `$ARGUMENTS` includes `pr_url=<url>` for `PR ready` or `PR merged`, ensure the GitHub Issue has a durable ticket -> PR link:
 
 1. Make sure the PR body contains `Refs #<n>` (or the fully qualified cross-repo form) — never a closing keyword, per the GitHub rule in `lisa-git-submit-pr`. Read the issue side with `gh api graphql` against `issue.timelineItems`, or `gh issue view <number> --json closedByPullRequestsReferences`. **Not** `gh issue view --json timelineItems`: `timelineItems` is not a supported field for that command, so the check silently returns nothing useful rather than failing loudly.
-2. Post or update a single managed issue comment starting with `[lisa-pr-link]`. Include the PR URL, milestone (`pr-ready` or `pr-merged`), and merge SHA when available. This is **unconditional**, not contingent on step 1 failing: under the non-closing rule GitHub never creates a native development link (that surface is the closing-reference mechanism), so this comment is the only ticket-side backlink there will be.
-3. Keep the fallback idempotent: search existing comments for `[lisa-pr-link]` and the PR URL; update/replace that managed comment where the provider allows updates, otherwise skip when the current body already matches. Do not append duplicate backlink comments on reruns.
+2. Establish the managed backlink comment by running the command that owns it — never by hand, and never by describing the procedure here:
+
+   ```bash
+   node scripts/lisa-work-item.mjs backlink --ref <work-item> --pr-url <url>
+   ```
+
+   It creates the `[lisa-pr-link]` comment or updates the one already present, instead of appending duplicates, so it is safe to run on every milestone. This is **unconditional**, not contingent on step 1 failing: under the non-closing rule GitHub never creates a native development link (that surface is the closing-reference mechanism), so this comment is the only ticket-side backlink there will be — run it whether or not native linkage exists or cannot be verified, because the required Work-Item Traceability check reads this comment and nothing else guarantees one. The comment carries the marker and the PR URL only; the milestone (`pr-ready` / `pr-merged`) and merge SHA belong in the milestone progress note, so that a rerun at a new milestone still converges on one backlink comment.
 
 Native GitHub linkage cannot be verified under the non-closing rule because it is never created in the first place, so the managed comment is not a contingency here — it is the mechanism. The issue must show the PR from at least one ticket-side surface, and this is the only one available.
 

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

@@ -341,7 +341,7 @@ Before shutting down the team, execute the Verify flow:
 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 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`.
+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 the single managed `[lisa-pr-link]` comment. Establish that comment with `node scripts/lisa-work-item.mjs backlink --ref <work_item_ref> --pr-url <url>` rather than posting it by hand — it is idempotent, and it is the same file that enforces the check, so producer and consumer cannot drift.
 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>`.
 10. Monitor the deploy action that triggers automatically from the successful merge

package/plugins/lisa/skills/lisa-jira-sync/SKILL.md

@@ -55,8 +55,13 @@ Before adding a comment, check for an existing milestone comment to avoid duplic
 When `$ARGUMENTS` includes `pr_url=<url>` for `PR ready` or `PR merged`, ensure the JIRA ticket has a durable ticket -> PR link:
 
 1. Prefer the JIRA development-link surface when the site's GitHub/JIRA integration or remote-link API is available through `lisa-atlassian-access`; verify by re-reading the ticket's remote links / development metadata.
-2. If native linkage is unavailable, unconfigured, cross-system, or cannot be verified, create or update a single managed JIRA comment containing the PR URL. The comment must start with `[lisa-pr-link]` and include the milestone (`pr-ready` or `pr-merged`) and merge SHA when available.
-3. Keep the fallback idempotent: read existing comments, find the `[lisa-pr-link]` comment for the same PR URL, and update/skip it instead of appending duplicates. If the current access layer cannot update comments in place, skip when an identical managed comment already exists and otherwise add exactly one replacement comment with the stable marker.
+2. Establish the managed backlink comment by running the command that owns it — never by hand, and never by describing the procedure here:
+
+   ```bash
+   node scripts/lisa-work-item.mjs backlink --ref <work-item> --pr-url <url>
+   ```
+
+   It creates the `[lisa-pr-link]` comment or updates the one already present, instead of appending duplicates, so it is safe to run on every milestone. This is **unconditional** — run it whether or not native linkage exists or cannot be verified, because the required Work-Item Traceability check reads this comment and nothing else guarantees one. The comment carries the marker and the PR URL only; the milestone (`pr-ready` / `pr-merged`) and merge SHA belong in the milestone progress note, so that a rerun at a new milestone still converges on one backlink comment.
 
 The PR body/branch issue key is the PR -> ticket side. This step is the required ticket -> PR side.
 

package/plugins/lisa/skills/lisa-linear-sync/SKILL.md

@@ -72,8 +72,13 @@ Call `lisa-linear-access operation: save-comment({issueId: <id>, body: <comment>
 When `$ARGUMENTS` includes `pr_url=<url>` for `pr-ready` or `pr-merged`, ensure the Linear Issue has a durable ticket -> PR link:
 
 1. Prefer Linear's native GitHub attachment / pull request link when the integration has attached the PR through the branch name, PR title, or PR body issue identifier. Verify by re-reading the Issue and its attachments / relations where the Linear access layer exposes them.
-2. If native linkage is unavailable, unconfigured, cross-system, or cannot be verified, create or update a single managed Linear comment containing the PR URL. The comment must start with `[lisa-pr-link]` and include the milestone (`pr-ready` or `pr-merged`) and merge SHA when available.
-3. Keep the fallback idempotent: read existing comments where the access layer exposes them, find the `[lisa-pr-link]` comment for the same PR URL, and update/skip it instead of appending duplicates. If comment update is unavailable, skip when an identical managed comment already exists and otherwise add exactly one replacement comment with the stable marker.
+2. Establish the managed backlink comment by running the command that owns it — never by hand, and never by describing the procedure here:
+
+   ```bash
+   node scripts/lisa-work-item.mjs backlink --ref <work-item> --pr-url <url>
+   ```
+
+   It creates the `[lisa-pr-link]` comment or updates the one already present, instead of appending duplicates, so it is safe to run on every milestone. This is **unconditional** — run it whether or not native linkage exists or cannot be verified, because the required Work-Item Traceability check reads this comment and nothing else guarantees one. The comment carries the marker and the PR URL only; the milestone (`pr-ready` / `pr-merged`) and merge SHA belong in the milestone progress note, so that a rerun at a new milestone still converges on one backlink comment.
 
 The PR branch/title/body identifier is the PR -> Linear side. This phase is the required Linear -> PR side.
 

package/plugins/lisa/skills/lisa-tracker-sync/SKILL.md

@@ -52,8 +52,13 @@ When `$ARGUMENTS` includes `pr_url=<url>` with milestone `pr-ready` or `pr-merge
 
 1. Prefer the provider's native development-link primitive when Lisa can write and verify it for that provider.
 2. Verify the native link using the provider read surface when available.
-3. If the native link is unavailable, unconfigured, cross-system, or cannot be verified, create or update one managed backlink comment on the work item containing the PR URL and current milestone.
-4. Keep the comment idempotent by using a stable marker such as `[lisa-pr-link]`; reruns update or skip the existing managed comment rather than appending duplicates.
+3. Whether or not the native link exists or cannot be verified, establish the managed backlink comment with the one command that owns it:
+
+   ```bash
+   node scripts/lisa-work-item.mjs backlink --ref <work-item> --pr-url <url>
+   ```
+
+4. That command is idempotent by construction — it updates the existing `[lisa-pr-link]` comment rather than appending duplicates — and it refuses loudly for a tracker it cannot write. Do not restate its procedure in a vendor skill; the file that writes the comment is the file that checks it, and that is what stops the two from drifting.
 
 This is the reverse half of `lisa-git-submit-pr`'s PR body linkage. A PR that mentions a ticket is not considered fully synced until the ticket also has either a verified native PR link or the managed fallback comment.
 

package/plugins/lisa-agy/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa",
-  "version": "3.33.6",
+  "version": "3.33.8",
   "description": "Universal governance — agents, skills, commands, hooks, and rules for all projects",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-agy/skills/lisa-git-submit-pr/SKILL.md

@@ -66,10 +66,17 @@ When updating an existing PR, preserve any existing linkage line unless the new
 After creating or updating the PR, always make the reverse link durable on the source work item when `work_item_ref` is available:
 
 1. Resolve the live PR URL with `gh pr view <pr-number> --json url --jq .url`.
-2. Invoke `lisa-tracker-sync` with the original work item ref, milestone `pr-ready`, `pr_url=<url>`, and `tracker_provider=<provider>` when known.
-3. The vendor sync skill must prefer the provider's native development-link primitive where one is available and verifiable.
-4. If native linkage is unavailable, unconfigured, or cannot be verified, the vendor sync skill must create or update a single managed `[lisa-pr-link]` comment on the work item containing the PR URL. The fallback comment is not optional; it is the ticket-side half of the two-way link.
-5. When the PR later merges, invoke `lisa-tracker-sync` again with milestone `pr-merged`, the same `pr_url`, and the merge SHA when available, so the managed backlink reflects the final state.
+2. Run the backlink command. It is the executable form of this requirement — it writes the managed `[lisa-pr-link]` comment on the work item, or updates the one already there, for every tracker Lisa supports:
+
+   ```bash
+   node scripts/lisa-work-item.mjs backlink --ref <work_item_ref> --pr-url <url>
+   ```
+
+   It is idempotent, so run it on every push rather than deciding whether it is needed. It refuses loudly for a tracker it cannot write, and never silently no-ops. Do not hand-post the comment, and do not describe the posting procedure anywhere: the same file that writes it is the file that checks it, which is what keeps producer and consumer from drifting.
+3. Invoke `lisa-tracker-sync` with the original work item ref, milestone `pr-ready`, `pr_url=<url>`, and `tracker_provider=<provider>` when known. That is the progress-note and status side; it is not what satisfies the traceability check.
+4. When the PR later merges, invoke `lisa-tracker-sync` again with milestone `pr-merged`, the same `pr_url`, and the merge SHA when available.
+
+**Why step 2 exists — do not "simplify" it away as redundant with the `Refs` line.** Under the non-closing rule above, GitHub never creates a native development link at all: that surface *is* the closing-reference mechanism, so no non-closing form can populate it. A PR carrying a perfectly correct `Refs` line still fails the required Work-Item Traceability check without the comment. The managed comment is the ticket-side half of the link, not a fallback for when native linkage happens to be absent.
 
 Do not report PR submission as fully synced while the PR body references the ticket but the ticket has neither a verified native PR link nor the managed backlink comment.
 

package/plugins/lisa-agy/skills/lisa-github-sync/SKILL.md

@@ -57,8 +57,13 @@ Optional arguments include `pr_url=<url>` for the live pull request and `merge_s
 When `$ARGUMENTS` includes `pr_url=<url>` for `PR ready` or `PR merged`, ensure the GitHub Issue has a durable ticket -> PR link:
 
 1. Make sure the PR body contains `Refs #<n>` (or the fully qualified cross-repo form) — never a closing keyword, per the GitHub rule in `lisa-git-submit-pr`. Read the issue side with `gh api graphql` against `issue.timelineItems`, or `gh issue view <number> --json closedByPullRequestsReferences`. **Not** `gh issue view --json timelineItems`: `timelineItems` is not a supported field for that command, so the check silently returns nothing useful rather than failing loudly.
-2. Post or update a single managed issue comment starting with `[lisa-pr-link]`. Include the PR URL, milestone (`pr-ready` or `pr-merged`), and merge SHA when available. This is **unconditional**, not contingent on step 1 failing: under the non-closing rule GitHub never creates a native development link (that surface is the closing-reference mechanism), so this comment is the only ticket-side backlink there will be.
-3. Keep the fallback idempotent: search existing comments for `[lisa-pr-link]` and the PR URL; update/replace that managed comment where the provider allows updates, otherwise skip when the current body already matches. Do not append duplicate backlink comments on reruns.
+2. Establish the managed backlink comment by running the command that owns it — never by hand, and never by describing the procedure here:
+
+   ```bash
+   node scripts/lisa-work-item.mjs backlink --ref <work-item> --pr-url <url>
+   ```
+
+   It creates the `[lisa-pr-link]` comment or updates the one already present, instead of appending duplicates, so it is safe to run on every milestone. This is **unconditional**, not contingent on step 1 failing: under the non-closing rule GitHub never creates a native development link (that surface is the closing-reference mechanism), so this comment is the only ticket-side backlink there will be — run it whether or not native linkage exists or cannot be verified, because the required Work-Item Traceability check reads this comment and nothing else guarantees one. The comment carries the marker and the PR URL only; the milestone (`pr-ready` / `pr-merged`) and merge SHA belong in the milestone progress note, so that a rerun at a new milestone still converges on one backlink comment.
 
 Native GitHub linkage cannot be verified under the non-closing rule because it is never created in the first place, so the managed comment is not a contingency here — it is the mechanism. The issue must show the PR from at least one ticket-side surface, and this is the only one available.
 

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

@@ -341,7 +341,7 @@ Before shutting down the team, execute the Verify flow:
 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 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`.
+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 the single managed `[lisa-pr-link]` comment. Establish that comment with `node scripts/lisa-work-item.mjs backlink --ref <work_item_ref> --pr-url <url>` rather than posting it by hand — it is idempotent, and it is the same file that enforces the check, so producer and consumer cannot drift.
 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>`.
 10. Monitor the deploy action that triggers automatically from the successful merge

package/plugins/lisa-agy/skills/lisa-jira-sync/SKILL.md

@@ -55,8 +55,13 @@ Before adding a comment, check for an existing milestone comment to avoid duplic
 When `$ARGUMENTS` includes `pr_url=<url>` for `PR ready` or `PR merged`, ensure the JIRA ticket has a durable ticket -> PR link:
 
 1. Prefer the JIRA development-link surface when the site's GitHub/JIRA integration or remote-link API is available through `lisa-atlassian-access`; verify by re-reading the ticket's remote links / development metadata.
-2. If native linkage is unavailable, unconfigured, cross-system, or cannot be verified, create or update a single managed JIRA comment containing the PR URL. The comment must start with `[lisa-pr-link]` and include the milestone (`pr-ready` or `pr-merged`) and merge SHA when available.
-3. Keep the fallback idempotent: read existing comments, find the `[lisa-pr-link]` comment for the same PR URL, and update/skip it instead of appending duplicates. If the current access layer cannot update comments in place, skip when an identical managed comment already exists and otherwise add exactly one replacement comment with the stable marker.
+2. Establish the managed backlink comment by running the command that owns it — never by hand, and never by describing the procedure here:
+
+   ```bash
+   node scripts/lisa-work-item.mjs backlink --ref <work-item> --pr-url <url>
+   ```
+
+   It creates the `[lisa-pr-link]` comment or updates the one already present, instead of appending duplicates, so it is safe to run on every milestone. This is **unconditional** — run it whether or not native linkage exists or cannot be verified, because the required Work-Item Traceability check reads this comment and nothing else guarantees one. The comment carries the marker and the PR URL only; the milestone (`pr-ready` / `pr-merged`) and merge SHA belong in the milestone progress note, so that a rerun at a new milestone still converges on one backlink comment.
 
 The PR body/branch issue key is the PR -> ticket side. This step is the required ticket -> PR side.
 

package/plugins/lisa-agy/skills/lisa-linear-sync/SKILL.md

@@ -72,8 +72,13 @@ Call `lisa-linear-access operation: save-comment({issueId: <id>, body: <comment>
 When `$ARGUMENTS` includes `pr_url=<url>` for `pr-ready` or `pr-merged`, ensure the Linear Issue has a durable ticket -> PR link:
 
 1. Prefer Linear's native GitHub attachment / pull request link when the integration has attached the PR through the branch name, PR title, or PR body issue identifier. Verify by re-reading the Issue and its attachments / relations where the Linear access layer exposes them.
-2. If native linkage is unavailable, unconfigured, cross-system, or cannot be verified, create or update a single managed Linear comment containing the PR URL. The comment must start with `[lisa-pr-link]` and include the milestone (`pr-ready` or `pr-merged`) and merge SHA when available.
-3. Keep the fallback idempotent: read existing comments where the access layer exposes them, find the `[lisa-pr-link]` comment for the same PR URL, and update/skip it instead of appending duplicates. If comment update is unavailable, skip when an identical managed comment already exists and otherwise add exactly one replacement comment with the stable marker.
+2. Establish the managed backlink comment by running the command that owns it — never by hand, and never by describing the procedure here:
+
+   ```bash
+   node scripts/lisa-work-item.mjs backlink --ref <work-item> --pr-url <url>
+   ```
+
+   It creates the `[lisa-pr-link]` comment or updates the one already present, instead of appending duplicates, so it is safe to run on every milestone. This is **unconditional** — run it whether or not native linkage exists or cannot be verified, because the required Work-Item Traceability check reads this comment and nothing else guarantees one. The comment carries the marker and the PR URL only; the milestone (`pr-ready` / `pr-merged`) and merge SHA belong in the milestone progress note, so that a rerun at a new milestone still converges on one backlink comment.
 
 The PR branch/title/body identifier is the PR -> Linear side. This phase is the required Linear -> PR side.
 

package/plugins/lisa-agy/skills/lisa-tracker-sync/SKILL.md

@@ -52,8 +52,13 @@ When `$ARGUMENTS` includes `pr_url=<url>` with milestone `pr-ready` or `pr-merge
 
 1. Prefer the provider's native development-link primitive when Lisa can write and verify it for that provider.
 2. Verify the native link using the provider read surface when available.
-3. If the native link is unavailable, unconfigured, cross-system, or cannot be verified, create or update one managed backlink comment on the work item containing the PR URL and current milestone.
-4. Keep the comment idempotent by using a stable marker such as `[lisa-pr-link]`; reruns update or skip the existing managed comment rather than appending duplicates.
+3. Whether or not the native link exists or cannot be verified, establish the managed backlink comment with the one command that owns it:
+
+   ```bash
+   node scripts/lisa-work-item.mjs backlink --ref <work-item> --pr-url <url>
+   ```
+
+4. That command is idempotent by construction — it updates the existing `[lisa-pr-link]` comment rather than appending duplicates — and it refuses loudly for a tracker it cannot write. Do not restate its procedure in a vendor skill; the file that writes the comment is the file that checks it, and that is what stops the two from drifting.
 
 This is the reverse half of `lisa-git-submit-pr`'s PR body linkage. A PR that mentions a ticket is not considered fully synced until the ticket also has either a verified native PR link or the managed fallback comment.
 

package/plugins/lisa-cdk/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "3.33.6",
+  "version": "3.33.8",
   "description": "AWS CDK-specific plugin",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-cdk/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "3.33.6",
+  "version": "3.33.8",
   "description": "AWS CDK-specific Lisa plugin.",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-cdk-agy/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "3.33.6",
+  "version": "3.33.8",
   "description": "AWS CDK-specific plugin",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-cdk-copilot/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "3.33.6",
+  "version": "3.33.8",
   "description": "AWS CDK-specific plugin",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-cdk-cursor/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "3.33.6",
+  "version": "3.33.8",
   "description": "AWS CDK-specific plugin",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-copilot/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa",
-  "version": "3.33.6",
+  "version": "3.33.8",
   "description": "Universal governance — agents, skills, commands, hooks, and rules for all projects",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-copilot/skills/lisa-git-submit-pr/SKILL.md

@@ -66,10 +66,17 @@ When updating an existing PR, preserve any existing linkage line unless the new
 After creating or updating the PR, always make the reverse link durable on the source work item when `work_item_ref` is available:
 
 1. Resolve the live PR URL with `gh pr view <pr-number> --json url --jq .url`.
-2. Invoke `lisa-tracker-sync` with the original work item ref, milestone `pr-ready`, `pr_url=<url>`, and `tracker_provider=<provider>` when known.
-3. The vendor sync skill must prefer the provider's native development-link primitive where one is available and verifiable.
-4. If native linkage is unavailable, unconfigured, or cannot be verified, the vendor sync skill must create or update a single managed `[lisa-pr-link]` comment on the work item containing the PR URL. The fallback comment is not optional; it is the ticket-side half of the two-way link.
-5. When the PR later merges, invoke `lisa-tracker-sync` again with milestone `pr-merged`, the same `pr_url`, and the merge SHA when available, so the managed backlink reflects the final state.
+2. Run the backlink command. It is the executable form of this requirement — it writes the managed `[lisa-pr-link]` comment on the work item, or updates the one already there, for every tracker Lisa supports:
+
+   ```bash
+   node scripts/lisa-work-item.mjs backlink --ref <work_item_ref> --pr-url <url>
+   ```
+
+   It is idempotent, so run it on every push rather than deciding whether it is needed. It refuses loudly for a tracker it cannot write, and never silently no-ops. Do not hand-post the comment, and do not describe the posting procedure anywhere: the same file that writes it is the file that checks it, which is what keeps producer and consumer from drifting.
+3. Invoke `lisa-tracker-sync` with the original work item ref, milestone `pr-ready`, `pr_url=<url>`, and `tracker_provider=<provider>` when known. That is the progress-note and status side; it is not what satisfies the traceability check.
+4. When the PR later merges, invoke `lisa-tracker-sync` again with milestone `pr-merged`, the same `pr_url`, and the merge SHA when available.
+
+**Why step 2 exists — do not "simplify" it away as redundant with the `Refs` line.** Under the non-closing rule above, GitHub never creates a native development link at all: that surface *is* the closing-reference mechanism, so no non-closing form can populate it. A PR carrying a perfectly correct `Refs` line still fails the required Work-Item Traceability check without the comment. The managed comment is the ticket-side half of the link, not a fallback for when native linkage happens to be absent.
 
 Do not report PR submission as fully synced while the PR body references the ticket but the ticket has neither a verified native PR link nor the managed backlink comment.