openplanr 2.2641.1 → 2.2641.2

package/lib/host-packages/claude/openplanr/skills/delegate/scripts/credentials.mjs

@@ -0,0 +1,167 @@
+// Credential classification for delegated context. Findings never carry the matched value.
+import { createHash } from 'node:crypto';
+
+/**
+ * Recognizable credential formats; rejected everywhere, including tests and placeholders.
+ * Case-sensitive: each prefix has a fixed case, and `github_pat_` and `sk-` bodies need an
+ * uppercase letter or digit.
+ */
+export const CREDENTIAL_FORMAT =
+  /-----BEGIN (?:[A-Z ]* )?PRIVATE KEY(?: BLOCK)?-----|"private_key"\s*:\s*"-----BEGIN|(?<![A-Za-z0-9])AKIA[0-9A-Z]{16}\b|(?<![A-Za-z0-9])gh[pousr]_[A-Za-z0-9]{20,}(?![A-Za-z0-9])|(?<![A-Za-z0-9])github_pat_(?=[A-Za-z0-9_]*[A-Z0-9])[A-Za-z0-9_]{20,}\b|(?<![A-Za-z0-9])sk-(?:proj-)?(?=[A-Za-z0-9_-]*[A-Z0-9])[A-Za-z0-9_-]{24,}\b|(?<![A-Za-z0-9])xox[baprs]-[A-Za-z0-9-]{20,}/u;
+
+// `word` is the credential word findings report as `key`; the rest of a name may hold a value.
+const CREDENTIAL_NAME =
+  '(?<name>(?:[A-Za-z_][A-Za-z0-9_-]*?)?(?<word>API[_-]?KEY|ACCESS[_-]?TOKEN|AUTH[_-]?TOKEN|CLIENT[_-]?SECRET|PRIVATE[_-]?KEY|PASSWORD|TOKEN|SECRET(?:[_-]?KEY)?))';
+const QUOTED_ASSIGNMENT = new RegExp(
+  `(?:^|[^A-Za-z0-9_])${CREDENTIAL_NAME}["']?\\s*[:=]\\s*(?<quote>["'\`])(?<value>(?:(?!\\k<quote>|\\$\\{)[^\\r\\n\\\\]|\\\\.){16,})\\k<quote>`,
+  'giu',
+);
+const UNQUOTED_ASSIGNMENT = new RegExp(
+  `^[ \\t]*(?<exported>export[ \\t]+)?${CREDENTIAL_NAME}(?<before>[ \\t]*)(?<operator>[:=])(?<after>[ \\t]*)(?!process\\.env(?:\\.|\\[)|import\\.meta\\.env(?:\\.|\\[)|Deno\\.env\\.|os\\.environ|env\\.)(?<value>[^\\s"'\`#()\\[\\]{}$]{16,})[ \\t]*(?:#[^\\r\\n]*)?\\r?$`,
+  'gimu',
+);
+const PLACEHOLDER =
+  /^(?:example(?:[-_].*)?|placeholder(?:[-_].*)?|your[-_].*|(?:change|replace)[-_]me(?:[-_].*)?|(?:dummy|fake|mock|test|never[-_]return)[-_](?:api[-_]?key|access[-_]?token|auth[-_]?token|client[-_]?secret|password|token|secret(?:[-_]?key)?))$/iu;
+// A lowercase marker followed only by words and short numbers, one of them a credential noun.
+const DESCRIBED_PLACEHOLDER =
+  /^(?:dummy|fake|mock|test|fixture|synthetic|never[-_]return)(?:[-_. ](?:[a-z]+|\d{1,4}))+[-_.]?$/u;
+const CREDENTIAL_NOUN = /[-_. ](?:secret|key|token|password|credential)s?(?=[-_. ]|$)/u;
+const SHELL_NAME = /^[A-Z][A-Z0-9_]*$/u;
+const IDENTIFIER_WORD = /[A-Z]{2,}(?![a-z])\d{0,2}|[A-Z]?[a-z]+\d{0,2}|[A-Z]\d{0,2}|\d{1,2}/gu;
+
+const CODE_EXTENSIONS = new Set(
+  'c cc cjs cpp cs cts dart go groovy h hpp java js jsx kt kts lua m mjs mm mts php py rb rs scala svelte swift ts tsx vue'.split(
+    ' ',
+  ),
+);
+const CONFIG_EXTENSIONS = new Set(
+  'bash cfg conf env fish hcl ini json json5 jsonc properties ps1 sh tf toml xml yaml yml zsh'.split(
+    ' ',
+  ),
+);
+const CONFIG_NAMES = new Set(['dockerfile', 'makefile', 'procfile']);
+
+/** The syntax that decides whether an unquoted value is a literal: code, config, or free text. */
+export function credentialSyntax(path) {
+  if (typeof path !== 'string' || !path) return 'text';
+  const name = path.split('/').at(-1).toLowerCase();
+  if (CONFIG_NAMES.has(name) || name.startsWith('.env')) return 'config';
+  const extension = name.includes('.') ? name.split('.').at(-1) : '';
+  if (CODE_EXTENSIONS.has(extension)) return 'code';
+  if (CONFIG_EXTENSIONS.has(extension)) return 'config';
+  return 'text';
+}
+
+function sha256(value) {
+  return createHash('sha256').update(value).digest('hex');
+}
+
+function position(content, index) {
+  const before = content.slice(0, index);
+  return { line: before.split('\n').length, column: index - before.lastIndexOf('\n') };
+}
+
+// Reads like a code identifier: whole words, digits only at word ends, at most one one-letter word.
+function codeIdentifier(value) {
+  if (!/^[A-Za-z_$][\w$]*$/u.test(value) || value.length > 64) return false;
+  let singleLetters = 0;
+  for (const part of value.split(/[_$]+/u).filter(Boolean)) {
+    const words = part.match(IDENTIFIER_WORD) ?? [];
+    if (words.join('') !== part) return false;
+    singleLetters += words.filter((word) => word.replace(/\d+$/u, '').length <= 1).length;
+  }
+  return singleLetters <= 1;
+}
+
+function memberPath(value) {
+  const segments = value.replace(/!$/u, '').split(/[!?]?\./u);
+  return segments.length > 1 && segments.every(codeIdentifier);
+}
+
+// An unquoted value is a literal unless its syntax makes it a reference, type or expression.
+// Multi-line strings in code read like text, so an unterminated identifier stays a literal.
+function unquotedLiteral(raw, operator, syntax) {
+  if (syntax === 'config' || (syntax === 'text' && operator === '=')) return true;
+  const terminated = /[;,]$/u.test(raw);
+  const value = terminated ? raw.slice(0, -1) : raw;
+  if (memberPath(value)) return !(terminated || syntax === 'code');
+  return !(terminated && codeIdentifier(value));
+}
+
+// `export NAME=` is a shell line in any file, and so is an uppercase `NAME=value` without spaces
+// unless it ends in `,` like a keyword argument.
+function shellAssignment({ exported, name, before, operator, after, value }) {
+  if (exported) return true;
+  return operator === '=' && !before && !after && SHELL_NAME.test(name) && !value.endsWith(',');
+}
+
+function placeholder(value) {
+  return (
+    PLACEHOLDER.test(value) || (DESCRIBED_PLACEHOLDER.test(value) && CREDENTIAL_NOUN.test(value))
+  );
+}
+
+/**
+ * Classifies credential material in `bytes` from `origin` ({ path?, label?, syntax?, resolvable? }).
+ * Findings report location, rule, classification, confidence and explanation, never values.
+ * `resolvable: false` marks text that no resolution can admit, such as a correction.
+ */
+export function classifyCredentials(bytes, origin = {}) {
+  const buffer = Buffer.isBuffer(bytes) ? bytes : Buffer.from(String(bytes), 'utf8');
+  const content = buffer.toString('utf8');
+  const label = origin.label ?? origin.path ?? 'text';
+  const syntax = origin.syntax ?? credentialSyntax(origin.path);
+  const resolvable = origin.resolvable !== false;
+  const findings = [];
+  const add = (rule, index, key, details) => {
+    const { line, column } = position(content, index);
+    findings.push({
+      id: `cred_${sha256(`${label}\n${rule}\n${line}:${column}\n${key ?? ''}`).slice(0, 16)}`,
+      rule,
+      ...details,
+      location: { ...(origin.path ? { path: origin.path } : {}), line, column },
+      ...(key ? { key } : {}),
+    });
+  };
+  for (const match of content.matchAll(new RegExp(CREDENTIAL_FORMAT.source, 'gu')))
+    add('credential-format', match.index, null, {
+      classification: 'credential',
+      confidence: 'high',
+      resolvable: false,
+      explanation:
+        'A recognizable credential or private key format cannot be delegated; remove it from the source.',
+    });
+  const literal = ({ index, 0: text, groups: { name, word } }) =>
+    add('credential-assignment', index + text.indexOf(name), word, {
+      classification: 'possible-credential',
+      confidence: 'medium',
+      resolvable,
+      explanation: `${word} is assigned a literal that is neither a reference nor a recognized placeholder; ${resolvable ? 'resolve this finding only if the value is not a credential' : 'remove the value or replace it with a reference'}.`,
+    });
+  for (const match of content.matchAll(QUOTED_ASSIGNMENT))
+    if (!placeholder(match.groups.value)) literal(match);
+  for (const match of content.matchAll(UNQUOTED_ASSIGNMENT)) {
+    const { operator, value } = match.groups;
+    const lineSyntax = shellAssignment(match.groups) ? 'config' : syntax;
+    if (unquotedLiteral(value, operator, lineSyntax) && !placeholder(value.replace(/[;,]$/u, '')))
+      literal(match);
+  }
+  return { contentDigest: `sha256:${sha256(buffer)}`, syntax, findings };
+}
+
+/**
+ * Splits findings into those an explicit resolution covers and the rest. A resolution names one
+ * resolvable finding and the exact content digest it was recorded for; changed bytes invalidate it.
+ */
+export function resolveFindings(classification, resolutions = []) {
+  const accepted = new Set(
+    resolutions
+      .filter((resolution) => resolution?.contentDigest === classification.contentDigest)
+      .map((resolution) => resolution.id),
+  );
+  const applied = [];
+  const remaining = [];
+  for (const finding of classification.findings)
+    (finding.resolvable && accepted.has(finding.id) ? applied : remaining).push(finding);
+  return { applied, remaining };
+}

package/lib/host-packages/claude/openplanr/skills/delegate/scripts/presentation.mjs

@@ -39,7 +39,7 @@ export function preparationPresentation(preview) {
   return {
     phase: 'preview',
     headline: `${taskLabel(preview.selector)} is ready for review before dispatch.`,
-    context: `${preview.inventory.length} copied file(s); ${preview.omissions.length} omission(s).`,
+    context: `${preview.inventory.length} copied file(s); ${preview.omissions.length} omission(s); ${preview.credentialResolutions?.length ?? 0} accepted credential resolution(s).`,
     writableRepository: preview.writableRepository,
     worktreePath: preview.worktreePath,
     selectedPaths: preview.selectedPaths,
@@ -49,6 +49,7 @@ export function preparationPresentation(preview) {
       : 'Legacy run has no recorded integration scope; supply explicit paths at review. The worktree is not a filesystem sandbox.',
     inventory: preview.inventory,
     omissions: preview.omissions,
+    credentialResolutions: preview.credentialResolutions ?? [],
     blockers: preview.blockers ?? [],
     planning: preview.planning ?? null,
     helper: preview.helper ?? null,
@@ -61,7 +62,7 @@ export function preparationPresentation(preview) {
     destination: preview.destination,
     ...(preview.executionPolicy ? { executionPolicy: preview.executionPolicy } : {}),
     nextAction:
-      'Review required sources, optional omissions, planning location, integration scope, and destination before dispatch.',
+      'Review required sources, optional omissions, accepted credential resolutions, planning location, integration scope, and destination before dispatch.',
   };
 }
 

package/lib/host-packages/claude/openplanr/skills/delegate/scripts/run-contract.mjs

@@ -2,6 +2,7 @@
 import { createHash } from 'node:crypto';
 import { isAbsolute, sep } from 'node:path';
 import { assertCredentialFreeText } from './context.mjs';
+import { CREDENTIAL_FORMAT } from './credentials.mjs';
 import { updateRunRecord } from './run-record.mjs';
 
 const MAX_HANDOFF_TEXT = 4096;
@@ -16,9 +17,6 @@ export const SHA256 = /^[a-f0-9]{64}$/u;
 
 const RESULT_STATES = new Set(['completed', 'blocked', 'question']);
 
-const CREDENTIAL =
-  /-----BEGIN (?:[A-Z ]* )?PRIVATE KEY-----|\bAKIA[0-9A-Z]{16}\b|\bgh[pousr]_[A-Za-z0-9_]{20,}\b|\bgithub_pat_[A-Za-z0-9_]{20,}\b|\bsk-(?:proj-)?[A-Za-z0-9_-]{24,}\b|\bxox[baprs]-[A-Za-z0-9-]{20,}/iu;
-
 export class DelegateRunError extends Error {
   constructor(code, message, runId = null, details = null) {
     super(message);
@@ -68,7 +66,7 @@ export function boundedText(value, label) {
     typeof value !== 'string' ||
     !value.trim() ||
     Buffer.byteLength(value, 'utf8') > MAX_HANDOFF_TEXT ||
-    CREDENTIAL.test(value)
+    CREDENTIAL_FORMAT.test(value)
   ) {
     throw new DelegateRunError(
       'E_DELEGATE_INPUT',
@@ -152,7 +150,7 @@ function validQuestion(question) {
     typeof question.text !== 'string' ||
     !question.text.trim() ||
     Buffer.byteLength(question.text, 'utf8') > MAX_HANDOFF_TEXT ||
-    CREDENTIAL.test(question.text) ||
+    CREDENTIAL_FORMAT.test(question.text) ||
     (question.options !== undefined &&
       (!Array.isArray(question.options) ||
         question.options.length > 12 ||
@@ -160,7 +158,7 @@ function validQuestion(question) {
           (option) =>
             typeof option !== 'string' ||
             Buffer.byteLength(option, 'utf8') > 256 ||
-            CREDENTIAL.test(option),
+            CREDENTIAL_FORMAT.test(option),
         )))
   )
     return false;
@@ -181,7 +179,7 @@ export function resultShape(result, expectedSessionId = null) {
   ) {
     return null;
   }
-  if (CREDENTIAL.test(result.summary)) return null;
+  if (CREDENTIAL_FORMAT.test(result.summary)) return null;
   if (result.status === 'blocked' && !result.summary.trim()) return null;
   if (result.status === 'question' && !validQuestion(result.question)) return null;
   if (

package/lib/host-packages/claude/openplanr/skills/delegate/scripts/run-preparation.mjs

@@ -143,6 +143,7 @@ export async function prepareDelegateRun({
   selectedFiles = [],
   optionalFiles = [],
   readOnlyRepositories = [],
+  credentialResolutions = [],
   selectedPaths,
   scopePaths,
   preservePaths = [],
@@ -199,6 +200,7 @@ export async function prepareDelegateRun({
     selectedFiles,
     optionalFiles,
     readOnlyRepositories,
+    credentialResolutions,
   });
   const integrationScopePaths = scopePaths === undefined ? null : integrationPaths(scopePaths);
   let identity = profileIdentity(prepared);

package/lib/host-packages/claude/openplanr/skills/delegate/scripts/run-record.mjs

@@ -14,6 +14,7 @@ import {
 import { homedir } from 'node:os';
 import { join, resolve, sep } from 'node:path';
 import { promisify } from 'node:util';
+import { CREDENTIAL_FORMAT } from './credentials.mjs';
 import { captureFileState } from './custody.mjs';
 
 export const RUN_RECORD_SCHEMA_VERSION = '2.0.0';
@@ -21,8 +22,6 @@ export const MAX_RUN_RECORD_BYTES = 64 * 1024;
 export const CLOSED_RETENTION_MS = 30 * 24 * 60 * 60 * 1000;
 
 const RUN_ID = /^[a-zA-Z0-9][a-zA-Z0-9-]{0,99}$/u;
-const CREDENTIAL =
-  /-----BEGIN (?:[A-Z ]* )?PRIVATE KEY-----|\bAKIA[0-9A-Z]{16}\b|\bgh[pousr]_[A-Za-z0-9_]{20,}\b|\bgithub_pat_[A-Za-z0-9_]{20,}\b|\bsk-(?:proj-)?[A-Za-z0-9_-]{24,}\b|\bxox[baprs]-[A-Za-z0-9-]{20,}/iu;
 
 const execute = promisify(execFile);
 
@@ -74,7 +73,7 @@ function encoded(record) {
   if (bytes.length > MAX_RUN_RECORD_BYTES) {
     throw new RunRecordError('E_RUN_LIMIT', 'Delegated run record exceeds its private size limit.');
   }
-  if (CREDENTIAL.test(bytes.toString('utf8'))) {
+  if (CREDENTIAL_FORMAT.test(bytes.toString('utf8'))) {
     throw new RunRecordError('E_RUN_CREDENTIAL', 'Credential material cannot enter a run record.');
   }
   return bytes;

package/lib/host-packages/claude/openplanr/skills/diagram/references/diagram-sharing.md

@@ -13,7 +13,7 @@ review. Preview the exact diagram title, source revision, elements, connections,
 destination and retention before creating it. Use `--yes` only when the user has
 already authorized that publication. The stable URL and generated access token
 are separate; copy the token through the local studio's **Share diagram** dialog,
-never into a URL, prompt, ordinary output or repository file. Owner credentials
+never into a URL, prompt, ordinary output or repository file. Owner keys
 are saved privately outside the project. The review remains available until the
 owner revokes or deletes it and works while the local studio is stopped.
 

package/lib/host-packages/claude/openplanr/skills/operate/SKILL.md

@@ -47,9 +47,11 @@ matches. Never overwrite a prior cycle implicitly.
 ```
 
 `cycle.md` records the effective scope, roster, repository revision when relevant, and the outcome
-of each lens. If the directory is ignored by Git, continue locally and mention that in the report;
-do not ask the user to change ignore rules. Report an exact filesystem error only when the cycle
-workspace cannot be created or written.
+of each lens. An advisor lens run on its own creates the same layout with a one-lens roster and an
+unsynthesized `board-report.md`, so every review the dashboard lists has one shape.
+If the directory is ignored by Git, continue locally and mention that in the report; do not ask the
+user to change ignore rules. Report an exact filesystem error only when the cycle workspace cannot be
+created or written.
 
 ## Build shared context once
 

package/lib/host-packages/claude/openplanr/skills/plan/SKILL.md

@@ -79,8 +79,14 @@ Write stories and tasks directly in the repository's active planning mode.
   deleted ID. The packaged [planning ID helper](scripts/planning-ids.mjs) may
   inspect or reserve IDs; it never generates content.
 - Give each story stable acceptance IDs starting at `AC-001`.
-- Create one Tech task when no design surface applies; create one UI and one
-  Tech task when it does. Never exceed two tasks for one story.
+- Split each story into tasks that are coherent and independently verifiable.
+  Separate by ownership first: UI work is a `UI` task for the frontend role and
+  server, data, or integration work is a `Tech` task for the backend role.
+  Within one owner, split further only for a real output dependency, a distinct
+  verification surface, or reviewable size. Most stories need one Tech task,
+  plus one UI task when a design surface applies; never fragment one coherent
+  change into tasks that cannot be verified alone, and never fold unrelated work
+  into one task.
 - Map every acceptance ID through `acceptanceRefs` and name it with a concrete
   verification statement under `## Test Requirements`.
 - Set `reviewRisks` and `browserSurfaces` from repository evidence; use empty

package/lib/host-packages/claude/openplanr/skills/sprint/SKILL.md

@@ -36,7 +36,7 @@ capability; it never blocks the run. Name every degraded input in `Issues`.
 | Capacity (engineers × working days) | Fit the list and name the overflow | Ask once; default 1 engineer × 10 days, stated in the return |
 | Previous sprint or refinement note (`.planr/sprints/SPRINT-NNN/refinement.json`) | Carry `leftovers`; `openplanr sprint diff` is possible | First run, no diff |
 | Last Operate cycle | Rank its unfinished actions alongside | Skipped silently |
-| Linear or GitHub connector | Push statuses on approval, read PR state | Local files only; report the external step as not run |
+| Linear or GitHub connection ([tracker connections](references/tracker-connections.md)) | Update linked issues on approval, read PR state | Local files only; report the external step as not run and name the connection to add |
 
 ## Step 0: Frame the run
 
@@ -135,9 +135,10 @@ openplanr sprint apply SPRINT-NNN --dry-run          # show the status and prior
 openplanr sprint apply SPRINT-NNN --yes --commit     # one commit: chore(planr): refine backlog for SPRINT-NNN
 ```
 
-Where a connector is configured, push each changed item afterwards
-(`openplanr linear push <id>`, `openplanr github push <id>`) and report the ones that
-were not pushed. When the CLI is unavailable, apply the same status changes with
+Then update the issue linked to each changed item through the host's Linear or
+GitHub connection, with the status mapping in
+[tracker connections](references/tracker-connections.md), and report the items that
+were not updated. When the CLI is unavailable, apply the same status changes with
 the repository's own vocabulary and commit them with the same message.
 
 Close a finished sprint with `openplanr sprint close SPRINT-NNN`; it records the

package/lib/host-packages/claude/openplanr/skills/sprint/references/tracker-connections.md

@@ -0,0 +1,70 @@
+# GitHub and Linear connections
+
+These skills store and read no GitHub or Linear credentials. Remote steps run through a
+connection the host already has; the planning files stay the source of truth.
+
+## Use the host's connection
+
+- **Linear:** the host's Linear connection, whose tools read, create and update issues.
+- **GitHub:** the host's GitHub connection, or the GitHub CLI when
+  `gh auth status --hostname github.com` succeeds.
+
+Never ask the user for a token, read one from the environment or a file, or put one in a
+command, URL or file.
+
+## When a connection is missing
+
+Finish the local work first. Then report the remote step as not run and give the one
+line for the current host:
+
+| Host | Linear | GitHub |
+| --- | --- | --- |
+| Claude Code | Run `/plugin install linear@claude-plugins-official`, then sign in to Linear from `/mcp`. | Install the GitHub CLI (cli.github.com) and run `gh auth login`. |
+| Codex | Run `codex mcp add linear --url https://mcp.linear.app/mcp`, then `codex mcp login linear`. | Install the GitHub plugin from `/plugins`, or run `gh auth login`. |
+| Cursor | Add Linear from the Cursor Marketplace and sign in to Linear. | Install the GitHub CLI (cli.github.com) and run `gh auth login`. |
+
+Ask the user to try again once connected; never retry the remote step on your own.
+
+## Status mapping
+
+| Local status | Linear workflow state | GitHub issue |
+| --- | --- | --- |
+| `planning`, `pending` | Unstarted (for example Todo) | open |
+| `in-progress` | Started (for example In Progress) | open |
+| `done` | Completed (for example Done) | closed |
+| Backlog `open` | Backlog, else Unstarted | open |
+| Backlog `closed` | Completed | closed |
+| Backlog `promoted` | Leave as it is | Leave as it is |
+
+When reading state back, write only a status the item's type allows. A backlog item takes
+`open` or `closed` and keeps `promoted`.
+
+- Linear Completed or Canceled sets `done`, or `closed` for a backlog item. Started sets
+  `in-progress`, and Triage, Backlog or Unstarted sets `planning` for features and stories
+  and `pending` for quick tasks; a backlog item takes `open` from any of these. Epics and
+  task files keep their status.
+- A closed GitHub issue sets `done`, or `closed` for a backlog item. An open issue sets
+  `in-progress` for a `done` item and `open` for a `closed` backlog item; other statuses
+  stay as they are.
+
+## Links
+
+A linked item records its tracker identity in frontmatter. Update a linked item through
+that identity instead of creating another, and record the identity of everything you
+create.
+
+- **GitHub:** each item is one issue, recorded as `githubIssue`.
+- **Linear:** use the shapes the OpenPlanr CLI uses, so its later pushes reuse what you
+  create:
+  - An epic is a Linear project (`linearProjectId`, `linearProjectIdentifier`,
+    `linearProjectUrl`). When its `linearMappingStrategy` is `milestone-of` or `label-on`,
+    it is a milestone in an existing project (`linearMilestoneId`) or a team label
+    (`linearLabelId`) instead, and every issue under it carries that milestone
+    (`linearProjectMilestoneId`) or label (`linearLabelIds`).
+  - A feature, quick task or backlog item is one issue (`linearIssueId`,
+    `linearIssueIdentifier`, `linearIssueUrl`). A story is a sub-issue of its feature's
+    issue (`linearParentIssueId`).
+  - All task files of one feature share one task-list issue: a sub-issue of the feature's
+    issue whose checklist merges every task file, recorded in each task file. Its state is
+    Completed when every task file is `done`, Unstarted when every one is `pending`, and
+    Started otherwise.

package/lib/host-packages/claude/openplanr/skills/status/SKILL.md

@@ -11,9 +11,10 @@ planning artifacts, task statuses, dependency graph, current branch, and relevan
 runtime markers directly. Use the optional deterministic `openplanr status --json`
 utility when available, but do not require it or a semantic subprocess.
 
-Add GitHub or Linear lookups only when the user requests live remote state. Keep
-local results useful when credentials or connectors are unavailable. Report
-counts, ready and blocked work, dependency problems, and the most useful next
+Add GitHub or Linear lookups only when the user requests live remote state, through
+the host's connections as described in [tracker connections](references/tracker-connections.md).
+Keep local results useful when a connection is unavailable, and name the one to add.
+Report counts, ready and blocked work, dependency problems, and the most useful next
 action. Do not repair artifacts, start Plan or Ship, or change lifecycle state.
 
 When the OpenPlanr dashboard is running (`planr-dashboard`), the same delivery

package/lib/host-packages/claude/openplanr/skills/status/references/tracker-connections.md

@@ -0,0 +1,70 @@
+# GitHub and Linear connections
+
+These skills store and read no GitHub or Linear credentials. Remote steps run through a
+connection the host already has; the planning files stay the source of truth.
+
+## Use the host's connection
+
+- **Linear:** the host's Linear connection, whose tools read, create and update issues.
+- **GitHub:** the host's GitHub connection, or the GitHub CLI when
+  `gh auth status --hostname github.com` succeeds.
+
+Never ask the user for a token, read one from the environment or a file, or put one in a
+command, URL or file.
+
+## When a connection is missing
+
+Finish the local work first. Then report the remote step as not run and give the one
+line for the current host:
+
+| Host | Linear | GitHub |
+| --- | --- | --- |
+| Claude Code | Run `/plugin install linear@claude-plugins-official`, then sign in to Linear from `/mcp`. | Install the GitHub CLI (cli.github.com) and run `gh auth login`. |
+| Codex | Run `codex mcp add linear --url https://mcp.linear.app/mcp`, then `codex mcp login linear`. | Install the GitHub plugin from `/plugins`, or run `gh auth login`. |
+| Cursor | Add Linear from the Cursor Marketplace and sign in to Linear. | Install the GitHub CLI (cli.github.com) and run `gh auth login`. |
+
+Ask the user to try again once connected; never retry the remote step on your own.
+
+## Status mapping
+
+| Local status | Linear workflow state | GitHub issue |
+| --- | --- | --- |
+| `planning`, `pending` | Unstarted (for example Todo) | open |
+| `in-progress` | Started (for example In Progress) | open |
+| `done` | Completed (for example Done) | closed |
+| Backlog `open` | Backlog, else Unstarted | open |
+| Backlog `closed` | Completed | closed |
+| Backlog `promoted` | Leave as it is | Leave as it is |
+
+When reading state back, write only a status the item's type allows. A backlog item takes
+`open` or `closed` and keeps `promoted`.
+
+- Linear Completed or Canceled sets `done`, or `closed` for a backlog item. Started sets
+  `in-progress`, and Triage, Backlog or Unstarted sets `planning` for features and stories
+  and `pending` for quick tasks; a backlog item takes `open` from any of these. Epics and
+  task files keep their status.
+- A closed GitHub issue sets `done`, or `closed` for a backlog item. An open issue sets
+  `in-progress` for a `done` item and `open` for a `closed` backlog item; other statuses
+  stay as they are.
+
+## Links
+
+A linked item records its tracker identity in frontmatter. Update a linked item through
+that identity instead of creating another, and record the identity of everything you
+create.
+
+- **GitHub:** each item is one issue, recorded as `githubIssue`.
+- **Linear:** use the shapes the OpenPlanr CLI uses, so its later pushes reuse what you
+  create:
+  - An epic is a Linear project (`linearProjectId`, `linearProjectIdentifier`,
+    `linearProjectUrl`). When its `linearMappingStrategy` is `milestone-of` or `label-on`,
+    it is a milestone in an existing project (`linearMilestoneId`) or a team label
+    (`linearLabelId`) instead, and every issue under it carries that milestone
+    (`linearProjectMilestoneId`) or label (`linearLabelIds`).
+  - A feature, quick task or backlog item is one issue (`linearIssueId`,
+    `linearIssueIdentifier`, `linearIssueUrl`). A story is a sub-issue of its feature's
+    issue (`linearParentIssueId`).
+  - All task files of one feature share one task-list issue: a sub-issue of the feature's
+    issue whose checklist merges every task file, recorded in each task file. Its state is
+    Completed when every task file is `done`, Unstarted when every one is `pending`, and
+    Started otherwise.

package/lib/host-packages/claude/openplanr/skills/sync/SKILL.md

@@ -7,31 +7,22 @@ license: MIT
 # OpenPlanr Sync
 
 Reconcile local planning artifacts and, when requested, GitHub or Linear state.
-Reason about conflicts in this active session; deterministic mapping and GitHub
-transport may use a host connector or the packaged [sync helper](scripts/sync.mjs).
-Local and GitHub work never require the OpenPlanr CLI.
+Reason about conflicts in this active session. Local and GitHub work never require
+the OpenPlanr CLI.
 
-Resolution order:
+Remote steps run through the host's own connections, as described in
+[tracker connections](references/tracker-connections.md), which also holds the status
+mapping and what to tell the user when a connection is missing:
 
-1. use a host-native GitHub or Linear connector when available;
-2. otherwise, for GitHub, use the packaged deterministic helper;
-3. otherwise, for Linear, use the `openplanr linear` terminal utility when the user has
-   installed it; `openplanr github` and `openplanr sync` are optional equivalents for the rest.
-
-Linear through the CLI:
-
-- the user runs `openplanr linear init` in a terminal once; it prompts for a personal
-  access token, which the CLI stores;
-- audit with `openplanr linear sync --dry-run`, which reads Linear without writing;
-- before a real `openplanr linear sync`, ask how conflicts should resolve and pass
-  `--on-conflict local` or `--on-conflict linear`; without a prompt it favors Linear;
-- `openplanr linear push <artifact-id>` creates or updates Linear issues; preview with
-  `--dry-run`. Quick tasks and backlog items need `linear.standaloneProjectId` in the
-  project config when no terminal prompt is available.
+- GitHub: the host's GitHub connection, or, when the GitHub CLI is signed in, the
+  packaged [sync helper](scripts/sync.mjs), which creates and edits issues through `gh`;
+  close or reopen an issue with `gh issue close` or `gh issue reopen`. `openplanr github`
+  is an optional equivalent; `openplanr sync` only repairs local cross-references.
+- Linear: the host's Linear connection.
 
 Audit is read-only by default. Apply local changes only when the request asks for
 reconciliation, and push remote changes only when the request asks for external
-synchronization. If credentials are unavailable, complete local reconciliation
+synchronization. If a connection is unavailable, complete local reconciliation
 and report only the external step that could not run.
 
 ## Return

package/lib/host-packages/claude/openplanr/skills/sync/references/tracker-connections.md

@@ -0,0 +1,70 @@
+# GitHub and Linear connections
+
+These skills store and read no GitHub or Linear credentials. Remote steps run through a
+connection the host already has; the planning files stay the source of truth.
+
+## Use the host's connection
+
+- **Linear:** the host's Linear connection, whose tools read, create and update issues.
+- **GitHub:** the host's GitHub connection, or the GitHub CLI when
+  `gh auth status --hostname github.com` succeeds.
+
+Never ask the user for a token, read one from the environment or a file, or put one in a
+command, URL or file.
+
+## When a connection is missing
+
+Finish the local work first. Then report the remote step as not run and give the one
+line for the current host:
+
+| Host | Linear | GitHub |
+| --- | --- | --- |
+| Claude Code | Run `/plugin install linear@claude-plugins-official`, then sign in to Linear from `/mcp`. | Install the GitHub CLI (cli.github.com) and run `gh auth login`. |
+| Codex | Run `codex mcp add linear --url https://mcp.linear.app/mcp`, then `codex mcp login linear`. | Install the GitHub plugin from `/plugins`, or run `gh auth login`. |
+| Cursor | Add Linear from the Cursor Marketplace and sign in to Linear. | Install the GitHub CLI (cli.github.com) and run `gh auth login`. |
+
+Ask the user to try again once connected; never retry the remote step on your own.
+
+## Status mapping
+
+| Local status | Linear workflow state | GitHub issue |
+| --- | --- | --- |
+| `planning`, `pending` | Unstarted (for example Todo) | open |
+| `in-progress` | Started (for example In Progress) | open |
+| `done` | Completed (for example Done) | closed |
+| Backlog `open` | Backlog, else Unstarted | open |
+| Backlog `closed` | Completed | closed |
+| Backlog `promoted` | Leave as it is | Leave as it is |
+
+When reading state back, write only a status the item's type allows. A backlog item takes
+`open` or `closed` and keeps `promoted`.
+
+- Linear Completed or Canceled sets `done`, or `closed` for a backlog item. Started sets
+  `in-progress`, and Triage, Backlog or Unstarted sets `planning` for features and stories
+  and `pending` for quick tasks; a backlog item takes `open` from any of these. Epics and
+  task files keep their status.
+- A closed GitHub issue sets `done`, or `closed` for a backlog item. An open issue sets
+  `in-progress` for a `done` item and `open` for a `closed` backlog item; other statuses
+  stay as they are.
+
+## Links
+
+A linked item records its tracker identity in frontmatter. Update a linked item through
+that identity instead of creating another, and record the identity of everything you
+create.
+
+- **GitHub:** each item is one issue, recorded as `githubIssue`.
+- **Linear:** use the shapes the OpenPlanr CLI uses, so its later pushes reuse what you
+  create:
+  - An epic is a Linear project (`linearProjectId`, `linearProjectIdentifier`,
+    `linearProjectUrl`). When its `linearMappingStrategy` is `milestone-of` or `label-on`,
+    it is a milestone in an existing project (`linearMilestoneId`) or a team label
+    (`linearLabelId`) instead, and every issue under it carries that milestone
+    (`linearProjectMilestoneId`) or label (`linearLabelIds`).
+  - A feature, quick task or backlog item is one issue (`linearIssueId`,
+    `linearIssueIdentifier`, `linearIssueUrl`). A story is a sub-issue of its feature's
+    issue (`linearParentIssueId`).
+  - All task files of one feature share one task-list issue: a sub-issue of the feature's
+    issue whose checklist merges every task file, recorded in each task file. Its state is
+    Completed when every task file is `done`, Unstarted when every one is `pending`, and
+    Started otherwise.

package/lib/host-packages/claude/openplanr/skills/sync/scripts/sync.mjs

@@ -5,7 +5,7 @@ import { access, readFile } from 'node:fs/promises';
 import { resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { promisify } from 'node:util';
-import { CLI_COMMAND, PLANNING_FOLDER } from './names.mjs';
+import { PLANNING_FOLDER } from './names.mjs';
 
 const execFileAsync = promisify(execFile);
 const LINEAR_UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/iu;
@@ -147,7 +147,7 @@ export async function runPortableSync(
   } else if (args.provider === 'linear') {
     throw new IntegrationError(
       'E_SYNC_USAGE',
-      `Linear synchronization runs through a Linear connector or the ${CLI_COMMAND} CLI (${CLI_COMMAND} linear push, ${CLI_COMMAND} linear sync).`,
+      "Linear synchronization runs through the host's Linear connection.",
     );
   } else {
     throw new IntegrationError(