@gcunharodrigues/wrxn 0.21.1 → 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.1",
+  "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/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/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.