@gcunharodrigues/wrxn 0.21.0 → 0.22.0

package/manifest.json

@@ -558,6 +558,11 @@
       "class": "managed",
       "profile": "project"
     },
+    {
+      "path": ".wrxn/tracker-target.cjs",
+      "class": "managed",
+      "profile": "project"
+    },
     {
       "path": ".wrxn/wiki.cjs",
       "class": "managed",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gcunharodrigues/wrxn",
-  "version": "0.21.0",
+  "version": "0.22.0",
   "description": "WRXN Kernel — installable AI operating system. Two profiles (project | workspace), pull-based updates, managed/seeded/state file classes.",
   "bin": {
     "wrxn": "bin/wrxn.cjs"

package/payload/.claude/skills/chat-search/SKILL.md

@@ -17,7 +17,7 @@ user-invocable: true
 - **Event log** — `.wrxn/events/*.jsonl`, the per-session, secret-redacted **user prompts** emit-event.cjs appends.
 - **Harness transcript** — `~/.claude/projects/<slug>/*.jsonl`, the only source of **assistant** turns and full user/assistant **message content**. The `<slug>` is the project's absolute path with every non-alphanumeric character replaced by `-` (how the harness names the dir). The transcript arm is **hygiene-cleaned** before matching (see below).
 
-A prompt that appears in **both** arms is de-duplicated — by `(session, timestamp, text)` — so it surfaces once. If the transcript dir is **missing or unreadable**, the search **degrades loudly to events-only** and says so in the output (it never crashes).
+A prompt that appears in **both** arms is de-duplicated — by `(session, whitespace-normalized text, timestamp within a tight window)` — so a single turn surfaces once even when its two arms stamp it ms apart or differ by whitespace. If the transcript dir is **missing, unreadable, or wholesale-drifted** (present but every line an unknown type, so it yields no usable turn), the search **degrades loudly to events-only** and says so in the output (it never crashes).
 
 Three optional flags refine a search — `--session` (scope to one session), `--since` (a time floor), and `--regex` (pattern match instead of substring). They compose with each other and with both arms. See **Scoping & match flags** below.
 
@@ -51,8 +51,8 @@ When the operator references an earlier moment ("like we discussed", "the decisi
 
 All three are optional, compose with each other, and apply across **both arms** (so scoping/filtering also covers assistant turns), preserving recency order and cross-arm dedup.
 
-- **`--session <id>`** — scope results to a single session (exact match on the session id). The id is the harness/event session id (letters, digits, `-`, `_`); a malformed id is rejected. Scoped rows render as `this session`.
-- **`--since <when>`** — keep only hits at or after a timestamp floor. `<when>` is either `today` (from 00:00 **UTC** of the current day — record stamps are UTC) or an ISO-8601 date/datetime (e.g. `2026-06-26` or `2026-06-26T12:00:00Z`). An undatable hit is excluded.
+- **`--session <id>`** — scope results to a single session (exact match on the session id). The id is the harness/event session id (letters, digits, `-`, `_`); a malformed id is rejected. Scoping only *narrows* the rows — it does **not** relabel them: the `this session` label tracks the genuinely-live session (`CLAUDE_SESSION_ID`), so scoping to a **past** session shows its real id, not `this session`.
+- **`--since <when>`** — keep only hits at or after a timestamp floor. `<when>` is either `today` (from 00:00 **UTC** of the current day — record stamps are UTC) or an ISO-8601 date/datetime (e.g. `2026-06-26` or `2026-06-26T12:00:00Z`). A datetime **without an explicit zone** is read as **UTC** (matching the record stamps), not machine-local time. An undatable hit is excluded.
 - **`--regex`** — match the search term as a **regular expression** instead of a case-insensitive substring. Regex mode is **case-sensitive** (the universal regex default; the substring default stays case-insensitive).
 
 ```bash
@@ -71,9 +71,9 @@ Hits are **most-recent-first**, one per line:
 ```
 
 - `role` is `user` (event log or a user transcript turn) or `assistant` (a transcript turn).
-- The session column collapses to `this session` for hits from the active session.
+- The session column collapses to `this session` for hits from the genuinely-live session (`CLAUDE_SESSION_ID`), independent of any `--session` scope.
 - No match → an explicit `chat-search: nothing found for "<term>" ...` line (never silence, never a crash).
-- If the transcript arm is unavailable, a trailing `chat-search: transcript arm unavailable — showing event-log results only.` line is appended (loud degrade).
+- If the transcript arm is unavailable (missing, unreadable, or wholesale-drifted), a trailing `chat-search: transcript arm unavailable — showing event-log results only.` line is appended (loud degrade).
 
 ## Boundaries
 

package/payload/.claude/skills/to-issues/SKILL.md

@@ -83,3 +83,34 @@ Or "None - can start immediately" if no blockers.
 </issue-template>
 
 Do NOT close or modify any parent issue.
+
+## `--repo` / cross-repo targeting
+
+By default this skill publishes the slices to the project's configured tracker (see
+`docs/agents/issue-tracker.md`). Passing **`--repo owner/repo`** instead targets a named **GitHub** repo
+for this one invocation (e.g. the kernel or `recon-wrxn`), so you can slice a sibling repo from this
+session without leaving the pipeline. Resolve the target through the ONE shared helper —
+`.wrxn/tracker-target.cjs` — never hand-roll the parsing:
+
+```bash
+# WITH --repo present: pass the owner/repo value as the trailing argument.
+node -e 'console.log(JSON.stringify(require("./.wrxn/tracker-target.cjs").resolveTarget(process.argv[1])))' "owner/repo"
+# WITHOUT --repo: OMIT the argument entirely (process.argv[1] is undefined → resolves to local).
+# NEVER pass "" — resolveTarget("") THROWS (empty is malformed, not "absent"), which would break the local path.
+node -e 'console.log(JSON.stringify(require("./.wrxn/tracker-target.cjs").resolveTarget(process.argv[1])))'
+```
+
+It returns `{ mechanism, repo, ghBaseArgs }` and **throws loud** on a malformed / empty / trailing
+`--repo` BEFORE any publish — let that refusal surface; never proceed on a bad target.
+
+- **`mechanism: "local"`** (no `--repo`) → publish exactly as today, to `.scratch/` — unchanged.
+- **`mechanism: "github"`** → publish via `gh`, prepending the returned **`ghBaseArgs`** (`-R owner/repo`)
+  to every `gh` call, e.g. `gh issue create -R owner/repo --title "…" --body "…" --label ready-for-agent`.
+  Slices are AFK-ready, so apply `ready-for-agent` from the shared wrxn triage vocab
+  (`ready-for-agent` / `backlog` / `epic`). `gh` fails loud if the target lacks the label; do not work
+  around it. The helper's `publishIssue({ target, title, body, label }, gh)` builds that exact argv and
+  refuses an off-vocab label — use it as the create boundary.
+
+**Target the SAME `owner/repo` the PRD was published to** (via `to-prd --repo`), so each slice's "Parent"
+references a real PRD issue number on that tracker. Publish slices in dependency order so the "Blocked by"
+field can cite real issue identifiers.

package/payload/.claude/skills/to-prd/SKILL.md

@@ -72,3 +72,34 @@ A description of the things that are out of scope for this PRD.
 Any further notes about the feature.
 
 </prd-template>
+
+## `--repo` / cross-repo targeting
+
+By default this skill publishes the PRD to the project's configured tracker (see
+`docs/agents/issue-tracker.md`). Passing **`--repo owner/repo`** instead targets a named **GitHub** repo
+for this one invocation (e.g. the kernel or `recon-wrxn`), so you can spec a sibling repo from this
+session without leaving the pipeline. Resolve the target through the ONE shared helper —
+`.wrxn/tracker-target.cjs` — never hand-roll the parsing:
+
+```bash
+# WITH --repo present: pass the owner/repo value as the trailing argument.
+node -e 'console.log(JSON.stringify(require("./.wrxn/tracker-target.cjs").resolveTarget(process.argv[1])))' "owner/repo"
+# WITHOUT --repo: OMIT the argument entirely (process.argv[1] is undefined → resolves to local).
+# NEVER pass "" — resolveTarget("") THROWS (empty is malformed, not "absent"), which would break the local path.
+node -e 'console.log(JSON.stringify(require("./.wrxn/tracker-target.cjs").resolveTarget(process.argv[1])))'
+```
+
+It returns `{ mechanism, repo, ghBaseArgs }` and **throws loud** on a malformed / empty / trailing
+`--repo` BEFORE any publish — let that refusal surface; never proceed on a bad target.
+
+- **`mechanism: "local"`** (no `--repo`) → publish exactly as today, to `.scratch/` — unchanged.
+- **`mechanism: "github"`** → publish via `gh`, prepending the returned **`ghBaseArgs`** (`-R owner/repo`)
+  to every `gh` call, e.g. `gh issue create -R owner/repo --title "…" --body "…" --label backlog`. Apply a
+  label from the shared wrxn triage vocab (`ready-for-agent` / `backlog` / `epic`) — a PRD is the parent
+  epic, so use `backlog` (or `epic`), not `ready-for-agent`. `gh` fails loud if the target lacks the
+  label; do not work around it. The helper's `publishIssue({ target, title, body, label }, gh)` builds
+  that exact argv and refuses an off-vocab label — use it as the create boundary.
+
+**Remember the published PRD's issue number.** When you later run `to-issues --repo`, point it at the
+**SAME** `owner/repo` so each slice's "Parent" is a real issue number on that tracker (not a dangling
+reference).

package/payload/.claude/skills/triage/SKILL.md

@@ -102,3 +102,31 @@ Capture everything resolved during grilling under "established so far" so the wo
 ## Resuming a previous session
 
 If prior triage notes exist on the issue, read them, check whether the reporter has answered any outstanding questions, and present an updated picture before continuing. Don't re-ask resolved questions.
+
+## `--repo` / cross-repo targeting
+
+By default this skill triages issues on the project's configured tracker (see
+`docs/agents/issue-tracker.md`). Passing **`--repo owner/repo`** instead targets a named **GitHub** repo
+for this one invocation (e.g. the kernel or `recon-wrxn`), so you can manage a sibling repo's backlog
+from this session without leaving the pipeline. Resolve the target through the ONE shared helper —
+`.wrxn/tracker-target.cjs` — never hand-roll the parsing:
+
+```bash
+# WITH --repo present: pass the owner/repo value as the trailing argument.
+node -e 'console.log(JSON.stringify(require("./.wrxn/tracker-target.cjs").resolveTarget(process.argv[1])))' "owner/repo"
+# WITHOUT --repo: OMIT the argument entirely (process.argv[1] is undefined → resolves to local).
+# NEVER pass "" — resolveTarget("") THROWS (empty is malformed, not "absent"), which would break the local path.
+node -e 'console.log(JSON.stringify(require("./.wrxn/tracker-target.cjs").resolveTarget(process.argv[1])))'
+```
+
+It returns `{ mechanism, repo, ghBaseArgs }` and **throws loud** on a malformed / empty / trailing
+`--repo` BEFORE any side-effect — let that refusal surface; never proceed on a bad target.
+
+- **`mechanism: "local"`** (no `--repo`) → triage exactly as today, editing the `Status:` line in
+  `.scratch/` — unchanged.
+- **`mechanism: "github"`** → manage via `gh`, prepending the returned **`ghBaseArgs`** (`-R owner/repo`)
+  to every `gh` call: relabel with `gh issue edit -R owner/repo --add-label … --remove-label …`, close
+  with `gh issue close -R owner/repo …`, comment with `gh issue comment -R owner/repo …`, and create with
+  the helper's `publishIssue({ target, title, body, label }, gh)`. Apply only labels from the shared wrxn
+  triage vocab (`ready-for-agent` / `backlog` / `epic`); `gh` fails loud if the target lacks a label — do
+  not work around it (no silent mis-label).

package/payload/.wrxn/chat-search.cjs

@@ -38,10 +38,12 @@ function snippetFor(text, matchesLine) {
 }
 
 // ── render: one hit → "timestamp · session (or 'this session') · role · snippet" ──
-// The session column collapses to "this session" when the hit is from the caller's active session
-// (opts.session), so a result set reads as scrollback relative to where the operator stands now.
+// The session column collapses to "this session" when the hit is from the caller's genuinely-LIVE session
+// (opts.activeSession — the CLI wires it from CLAUDE_SESSION_ID), so a result set reads as scrollback relative
+// to where the operator stands now. This is DECOUPLED from the --session SCOPE filter (opts.session): scoping
+// to a PAST session narrows the rows but never relabels them "this session" (#98).
 function renderHit(hit, opts) {
-  const active = opts && opts.session;
+  const active = opts && opts.activeSession;
   const sessionLabel = active && hit.session === active ? 'this session' : hit.session;
   return `${hit.ts} · ${sessionLabel} · ${hit.role} · ${hit.snippet}`;
 }
@@ -89,7 +91,8 @@ const INJECTED_STRIP_MAX = 65536;
 // Strip hook-injected framework-context blocks from one text part BEFORE matching. Two phases: (1) every
 // well-delimited <tag>…</tag> block anywhere; (2) a part-LEADING unclosed <tag>… (transcript truncated
 // mid-block) to end-of-part — anchored so a sentinel merely MENTIONED mid-prose keeps its tail. PURE and
-// FAIL-OPEN: any fault returns the input unchanged. Byte-faithful copy of memory-synth.cjs (#62).
+// FAIL-OPEN: any fault returns the input unchanged. Logic-identical to memory-synth.cjs's stripInjectedContext
+// (#62) — same strip semantics, not a byte-for-byte copy (and the 64KB strip cap is the inherited #62 tradeoff).
 function stripInjectedContext(text) {
   try {
     let out = String(text || '');
@@ -223,7 +226,12 @@ function parseSince(raw) {
     d.setUTCHours(0, 0, 0, 0);
     return d.getTime();
   }
-  const t = Date.parse(s);
+  // N3 (#99): record stamps are UTC, but Date.parse reads an ISO datetime WITH a time component and NO zone
+  // designator ("2026-06-26T12:00:00") as MACHINE-LOCAL time — silently shifting the floor by the host offset.
+  // Normalize it to UTC by appending Z. A date-only form (no 'T') is already UTC under Date.parse, and an
+  // explicit zone (trailing Z or a ±HH[:MM] offset) is honored as written — both pass through untouched.
+  const normalized = /[tT]/.test(s) && !/[zZ]$/.test(s) && !/[+-]\d{2}(:?\d{2})?$/.test(s) ? `${s}Z` : s;
+  const t = Date.parse(normalized);
   if (Number.isNaN(t)) {
     throw inputError(`chat-search: --since value "${raw}" is not a date — use "today" or an ISO-8601 date (e.g. 2026-06-26)`);
   }
@@ -314,6 +322,23 @@ function compileUserRegex(pattern) {
   }
 }
 
+// ── cross-arm dedup identity (#97) ─────────────────────────────────────────────
+// The SAME prompt reaches both arms stamped by DIFFERENT processes: emit-event.cjs writes the event ts at
+// hook-fire, the harness writes the transcript timestamp when it persists the turn — they differ by ms — and
+// the transcript text can differ from the event text by whitespace (hygiene strip, soft-wrap). So the dedup
+// identity is (session, whitespace-normalized text, ts within a TIGHT ±window), NOT an exact triple. The
+// window is 2s: a single turn's two stamps land within ~1s in practice, while two genuinely-distinct prompts
+// are seconds-to-minutes apart AND (almost always) differ in text — so the window only ever collapses what is
+// really one turn. The normalized text is the primary discriminator; the window only absorbs the writer
+// clock-skew on an otherwise-identical turn (two distinct prompts inside the window keep their distinct text,
+// so they never merge; the same text outside the window stays two distinct moments).
+const DEDUP_WINDOW_MS = 2000;
+// Normalize a message's text for the dedup key: trim the ends and collapse every interior whitespace run
+// (spaces, tabs, newlines) to a single space, so an event/transcript pair that differs only in spacing keys alike.
+function normalizeForDedup(text) {
+  return String(text).trim().replace(/\s+/g, ' ');
+}
+
 // ── the engine seam ───────────────────────────────────────────────────────────
 // searchConversationalLog(query, opts, roots): scan BOTH arms across the given roots' sessions and return
 // the turns that match `query` — a case-insensitive substring by default, or (opts.regex) the compiled
@@ -325,7 +350,7 @@ function searchConversationalLog(query, opts, roots) {
   const q = String(query == null ? '' : query);
   const needle = q.toLowerCase();
   const hits = [];
-  const seen = new Set(); // a prompt present in BOTH arms (same session+ts+text) must surface only once.
+  const seen = new Map(); // dedup index (#97): `${session}${normText}` → [{ tsMs, ts }] already surfaced; a near-stamp match collapses cross-arm duplicates.
   let degraded = false; // set when the transcript arm could not be consulted → loud events-only degrade (#84).
 
   // ── slice-3 filters (#85): each is an opts field applied per-record inside consider(), so it composes
@@ -344,9 +369,21 @@ function searchConversationalLog(query, opts, roots) {
     if (sessionScope != null && session !== sessionScope) return; // --session: exact-match a single session
     if (typeof text !== 'string' || !lineMatches(text)) return; // --regex pattern, else case-insensitive substring
     if (sinceThreshold != null && !(Date.parse(ts) >= sinceThreshold)) return; // --since: drop hits before the floor (an undatable ts → NaN → dropped)
-    const key = `${session}${ts}${text}`; // the AC dedup key — NUL-joined so the parts can't bleed.
-    if (seen.has(key)) return;
-    seen.add(key);
+    // Cross-arm dedup (#97): same session + whitespace-normalized text + a ts within the tight window = the
+    // same turn → surface once. NUL-joined so session and text can't bleed. An undatable or exactly-equal
+    // stamp falls back to ts-string equality, so an unparseable ts still collapses its exact twin.
+    const key = `${session}${normalizeForDedup(text)}`;
+    const tsMs = Date.parse(ts);
+    const prior = seen.get(key);
+    if (prior) {
+      const dup = prior.some(
+        (e) => (Number.isFinite(tsMs) && Number.isFinite(e.tsMs) && Math.abs(e.tsMs - tsMs) <= DEDUP_WINDOW_MS) || e.ts === ts,
+      );
+      if (dup) return; // a near-identical turn from the other arm (or an exact twin) already surfaced
+      prior.push({ tsMs, ts });
+    } else {
+      seen.set(key, [{ tsMs, ts }]);
+    }
     hits.push({ ts, session, role, snippet: snippetFor(text, lineMatches) });
   }
 
@@ -388,6 +425,7 @@ function searchConversationalLog(query, opts, roots) {
     if (!tfiles) {
       degraded = true;
     } else {
+      let recognizedTurns = 0; // user/assistant turns this dir yielded; zero across a non-empty dir = wholesale drift (#99 F3)
       for (const file of tfiles) {
         let lines;
         try {
@@ -404,12 +442,17 @@ function searchConversationalLog(query, opts, roots) {
             continue; // skip a malformed transcript line, never crash the scan
           }
           if (!rec || (rec.type !== 'user' && rec.type !== 'assistant')) continue; // only user/assistant turns; unknown line types (summary/system/…) skipped
+          recognizedTurns++; // a recognized turn (matchable or not) → this dir is NOT wholesale-drifted (#99 F3)
           // hygiene pipeline: flatten → strip injected framework context (a block holding the term is not a
           // hit) → redact secrets (raw chat can echo a credential; scrub BEFORE it can surface in a snippet).
           const text = redactSecrets(stripInjectedContext(transcriptText(rec)));
           consider(rec.timestamp, rec.sessionId, rec.type, text);
         }
       }
+      // F3 (#99): a present, readable dir whose EVERY line is an unknown type yielded zero usable turns — the
+      // arm is effectively unavailable → loud events-only degrade. Per-RECORD drift (some good turns) stays
+      // silent, and a present-but-empty dir ([]) is reachable-but-nothing and stays silent, both as before.
+      if (tfiles.length > 0 && recognizedTurns === 0) degraded = true;
     }
   }
 
@@ -446,13 +489,16 @@ function findInstallRoot(start) {
   return null;
 }
 
-// Value of a --name <value> flag. A following token that is itself a --flag (or a missing value) is NOT
-// consumed as the value — so `--session --regex` can't silently swallow --regex as the session id.
+// Value of a --name <value> flag, or undefined when the flag is ABSENT (optional). A PRESENT flag whose value
+// is missing or is itself a --flag fails LOUD (N2, #99) — parity with `--session ""`, never a silent
+// scope-widening drop: so `--session --regex` can't swallow --regex as the id and a trailing `--since` can't
+// vanish. The throw is userFacing, so main()'s catch prints one clean line and exits non-zero.
 function flag(name) {
   const i = process.argv.indexOf(`--${name}`);
   if (i < 0) return undefined;
   const val = process.argv[i + 1];
-  return val == null || val.startsWith('--') ? undefined : val;
+  if (val == null || val.startsWith('--')) throw inputError(`chat-search: --${name} requires a value`);
+  return val;
 }
 
 // Presence of a boolean --name flag (e.g. --regex), which carries no value.
@@ -476,34 +522,39 @@ function main() {
     process.stdout.write('Usage: node .wrxn/chat-search.cjs <search-term...> [--root <dir>] [--session <id>] [--since <when>] [--regex]\n');
     process.exit(2);
   }
-  const root = flag('root') || findInstallRoot();
-  if (!root) {
-    process.stderr.write('chat-search: cannot resolve the install root — run inside a wrxn install or pass --root <dir>\n');
-    process.exit(2);
-  }
-  // Wire the slice-3 flags (#85) into engine opts. The engine validates them (it throws a clean, user-facing
-  // error on a bad regex / unparseable --since); the CLI catch below prints that one line and exits non-zero.
-  const opts = {};
-  const session = flag('session');
-  if (session !== undefined) opts.session = session;
-  const since = flag('since');
-  if (since !== undefined) opts.since = since;
-  if (hasFlag('regex')) opts.regex = true;
-
-  let result;
+  // Flag parsing AND the engine call live inside ONE user-facing try: a value-flag with a missing/--prefixed
+  // value (flag(), N2 #99) and a bad regex / unparseable --since (the engine) both throw a clean userFacing
+  // error → the catch prints that one line and exits non-zero (never a Node stack or absolute path).
   try {
-    result = searchConversationalLog(terms.join(' '), opts, root);
+    const root = flag('root') || findInstallRoot();
+    if (!root) {
+      process.stderr.write('chat-search: cannot resolve the install root — run inside a wrxn install or pass --root <dir>\n');
+      process.exit(2);
+    }
+    // Wire the slice-3 flags (#85) into engine opts.
+    const opts = {};
+    const session = flag('session');
+    if (session !== undefined) opts.session = session;
+    const since = flag('since');
+    if (since !== undefined) opts.since = since;
+    if (hasFlag('regex')) opts.regex = true;
+    // The "this session" label tracks the genuinely-LIVE session (Claude Code exports CLAUDE_SESSION_ID), NOT
+    // the --session SCOPE filter — so scoping to a PAST session never relabels its rows "this session" (#98).
+    const activeSession = process.env.CLAUDE_SESSION_ID;
+    if (activeSession) opts.activeSession = activeSession;
+
+    const result = searchConversationalLog(terms.join(' '), opts, root);
+    process.stdout.write(result.rendered + '\n');
+    process.exit(0);
   } catch (err) {
     if (err && err.userFacing) {
-      // invalid flag input (bad/catastrophic regex, unparseable --since): fail LOUD with the one clean line
-      // the engine already built — never a Node stack or path — and exit non-zero (usage error).
+      // invalid flag input (missing flag value, bad/catastrophic regex, unparseable --since): fail LOUD with
+      // the one clean line — never a Node stack or path — and exit non-zero (usage error).
       process.stderr.write(err.message + '\n');
       process.exit(2);
     }
     throw err; // an unexpected fault → the entrypoint wrap turns it into a clean path-free diagnostic
   }
-  process.stdout.write(result.rendered + '\n');
-  process.exit(0);
 }
 
 // Belt-and-suspenders fail-loud (mirrors emit-event.cjs's entrypoint wrap): the per-file read and root

package/payload/.wrxn/tracker-target.cjs

@@ -0,0 +1,76 @@
+'use strict';
+
+// WRXN cross-repo tracker targeting — the ONE shared resolver behind `to-prd --repo`,
+// `to-issues --repo`, and `triage --repo` (PRD #114 / issue #115). It closes the cross-repo seam ADR
+// 0009 only documented (refs #81 AC#4): from a workspace-install session, `--repo owner/repo` lets the
+// HITL skills spec / slice / triage a sibling GitHub repo (the kernel, recon-wrxn) onto that repo's
+// GitHub tracker — without leaving the four-phase pipeline or hand-filing past the adherence guard.
+//
+// Self-contained: this ships INTO an install and MUST NOT import the kernel lib (node stdlib only).
+// The seam mirrors lib/release-cut.cjs: the decision is a PURE core (resolveTarget — parse / validate /
+// select-mechanism), and the gh create/label/close side-effects run through an INJECTED `gh` boundary,
+// so the decision + emitted spec are unit-testable with NO live gh.
+
+// owner/repo: a GitHub-legal ALLOWLIST, not a slash/space blocklist — this is the security chokepoint.
+// The skill wirings steer the agent to hand-compose `gh -R owner/repo` Bash, so the validator is the one
+// place that must reject anything that could change the meaning of that command. Allow ONLY what GitHub
+// itself permits: owner = alphanumerics + hyphens but NOT a leading hyphen (a leading `-` would let `gh`
+// read the whole value as a flag — argument injection); repo = alphanumerics + `.` `_` `-`. This refuses
+// every shell metacharacter (`;` `$()` backtick `|` `&` `>`), embedded whitespace, a trailing slash, an
+// extra path segment, and an empty value by construction — all must refuse loud BEFORE any publish.
+// (Reviewer/security convergent finding — FIX 1.)
+const OWNER_REPO = /^[A-Za-z0-9][A-Za-z0-9-]*\/[A-Za-z0-9._-]+$/;
+
+// The shared wrxn triage label vocab — the states already carried on the kernel and recon-wrxn. A label
+// means the same thing across repos; there is NO per-target label config (YAGNI for GitHub siblings).
+// gh fails loud if a target lacks one of these (free remote validation) — publishIssue never swallows it.
+const TRIAGE_LABELS = ['ready-for-agent', 'backlog', 'epic'];
+
+/**
+ * Resolve the tracker target for an invocation. PURE — the whole cross-repo decision, no side effect.
+ *   - `--repo` ABSENT (rawRepo nullish) → the install's configured default tracker (today's local-md
+ *     `.scratch/` path, unchanged). `defaultConfig` IS that default descriptor; the kernel default is
+ *     local-md (reconfiguring the default is out of scope — the override is per-invocation).
+ *   - `--repo owner/repo` (valid) → `{ mechanism:'github', repo, ghBaseArgs:['-R', repo] }`. GitHub by
+ *     construction; NO git-remote inference — tracker TYPE is a config choice, not derivable from a remote
+ *     (the install proves it: GitHub remote, local-md tracker).
+ *   - `--repo` PRESENT but malformed / empty / whitespace / trailing → THROW a loud, user-facing Error
+ *     BEFORE any side-effect, so a bad invocation never half-files (US-5).
+ * @param {string|undefined|null} rawRepo  the raw `--repo` value (absent ⇒ nullish)
+ * @param {{mechanism:string}} [defaultConfig]  the install's default tracker descriptor (local-md today)
+ * @returns {{mechanism:'local'}|{mechanism:'github',repo:string,ghBaseArgs:string[]}}
+ */
+function resolveTarget(rawRepo, defaultConfig = { mechanism: 'local' }) {
+  if (rawRepo == null) return defaultConfig; // --repo omitted → the configured default tracker
+  if (typeof rawRepo !== 'string' || !OWNER_REPO.test(rawRepo)) {
+    throw new Error(
+      `--repo must be "owner/repo" (got ${JSON.stringify(rawRepo)}) — e.g. gcunharodrigues/wrxn-kernel`,
+    );
+  }
+  return { mechanism: 'github', repo: rawRepo, ghBaseArgs: ['-R', rawRepo] };
+}
+
+/**
+ * Publish an issue onto a resolved GitHub target, applying ONE label drawn from the shared wrxn vocab.
+ * The `gh` runner is an INJECTED boundary (it executes the built argv) — mirroring release-cut's injected
+ * `deps`, so this is unit-testable with no live gh and the emitted spec is asserted over a fake. Guards
+ * refuse LOUD before the boundary (a non-github target, or an off-vocab label → no silent mis-label); a
+ * gh failure (e.g. the target repo lacks the label) is NOT swallowed — it propagates so a mis-labeled or
+ * unfiled issue never lands silently (US-6, US-7).
+ * @param {{target:object,title:string,body:string,label:string}} spec
+ * @param {(argv:string[])=>any} gh  the injected gh runner (the real impl shells `gh` with these args)
+ * @returns whatever the gh runner returns
+ */
+function publishIssue({ target, title, body, label } = {}, gh) {
+  if (!target || target.mechanism !== 'github') {
+    throw new Error(`publishIssue targets a github tracker (got mechanism "${target && target.mechanism}")`);
+  }
+  if (!TRIAGE_LABELS.includes(label)) {
+    throw new Error(`label "${label}" is off the shared wrxn vocab — expected one of ${TRIAGE_LABELS.join(' | ')}`);
+  }
+  if (typeof gh !== 'function') throw new Error('publishIssue requires an injected gh runner');
+  const argv = ['issue', 'create', ...target.ghBaseArgs, '--title', title, '--body', body, '--label', label];
+  return gh(argv); // the side-effect lives at the boundary; a gh failure propagates loud (no swallow)
+}
+
+module.exports = { resolveTarget, publishIssue, TRIAGE_LABELS, OWNER_REPO };

package/payload/docs/agents/issue-tracker.md

@@ -23,3 +23,23 @@ Read the file at the referenced path. The user will normally pass the path or th
 
 To use GitHub or GitLab issues instead, re-run `setup-matt-pocock-skills` and pick the
 matching tracker — it will rewrite this file from the right template.
+
+## Per-invocation override: `--repo owner/repo` (cross-repo targeting)
+
+`to-prd`, `to-issues`, and `triage` accept an optional `--repo owner/repo` flag that targets a
+named **GitHub** repo for that one invocation, instead of this install's default tracker above. It
+exists so the operator can spec / slice / triage a sibling GitHub repo (e.g. the kernel or
+`recon-wrxn`) end-to-end from a workspace-install session, without leaving the four-phase pipeline.
+
+- **Absent `--repo`** → the default tracker described above (local-markdown `.scratch/`), unchanged.
+  Existing install-local workflows are untouched.
+- **`--repo owner/repo`** → publish/manage on that GitHub repo via `gh`, using the shared wrxn triage
+  vocab (`ready-for-agent` / `backlog` / `epic`). The repo is passed explicitly to `gh -R owner/repo`
+  — it is **not** inferred from a git remote (the tracker TYPE is a config choice, not the remote).
+- **Malformed / empty / trailing `--repo`** (anything not exactly `owner/repo`) → the skill refuses
+  loud *before* any publish, so a bad invocation never half-files.
+
+The override is per-invocation only; it never reconfigures this install's default tracker. All three
+skills resolve the target through the one shared `.wrxn/tracker-target.cjs` helper (see those skills'
+"`--repo` / cross-repo targeting" sections), so validation, label handling, and `gh`-arg construction
+are identical across them.