openplanr 3.5.0 → 3.6.0

package/lib/host-packages/openai/openplanr/skills/ship/references/findings.md

@@ -31,9 +31,8 @@ Merge duplicates within the run. Sort by severity, highest first, and number fro
 
 ## Check what is already tracked
 
-Before showing findings, list open backlog items with the backlog helper
-linked from SKILL.md, resolved relative to that file: `node <helper> list
---project <repository-root> --open`. A finding about the same problem as an open item,
+Before showing findings, list open backlog items as
+[backlog filing](backlog-filing.md) describes. A finding about the same problem as an open item,
 normally the same evidence file and an equivalent title, is `tracked`. Never file
 it again and never edit the existing item.
 
@@ -52,26 +51,19 @@ rule that applies. File only what it allows.
    example a print or exec mode), another skill or a delegate runner started this
    run, or the user said not to ask. Read `findings.unattended` in
    `.planr/config.json`. Only `file` files every untracked finding. With
-   `report`, or no setting, do not run `add` at all: mark the findings `reported`.
+   `report`, or no setting, do not file at all: mark the findings `reported`.
 
 Never ask per finding, never ask mid-run, and never file or drop a finding
 silently.
 
 ## File
 
-Send each item as one JSON object (`title`, `priority`, `tags`, `description`)
-on stdin. Never pass `acceptanceCriteria`.
+File each item from its `title`, `priority`, `tags` and `description` as
+[backlog filing](backlog-filing.md) describes. Never add acceptance criteria.
+When the `openplanr` command files it and the result says
+`templateOverrideIgnored`, say the default format was used.
 
-- When an `openplanr` CLI resolves (the project's `node_modules/.bin`, then
-  `PATH`; never `npx`): `openplanr --project-dir <repository-root> backlog add
-  --data - --json`.
-- Otherwise: `node <helper> add --project <repository-root> --data -`. Its
-  result can carry `cliHint`; end the result with that line, word for word,
-  once. Install only if the user says yes then, by running exactly the command in
-  the line. If the result says `templateOverrideIgnored`, say the default format
-  was used.
-
-If filing fails, report the command and its error, and leave the finding
+If filing fails, report the step and its error, and leave the finding
 `reported`.
 
 ## Report

package/lib/host-packages/openai/openplanr/skills/ship/references/return-contract.md

@@ -0,0 +1,10 @@
+# Return rules
+
+Shared by Spec, Plan, Plan Review, Ship, Operate and Release. Each skill lists its own fields.
+
+- Lead with the outcome: what is ready, prepared or released, then what is partial or blocked.
+- Link durable artifacts by purpose. Keep inventories, command output and transcripts in their files.
+- Report only checks you ran, with their result. Name each check you could not run and what stays unverified.
+- Omit empty fields. Give each open issue its impact and the smallest recovery action.
+- The summary is a human view, not a schema. Different wording never calls for a rerun or a correction pass.
+- Keep any machine-readable field a skill defines unchanged.

package/lib/host-packages/openai/openplanr/skills/spec/SKILL.md

@@ -12,10 +12,10 @@ another model process.
 
 ## Ground the specification
 
-Read the request, repository instructions, ADRs, product documentation,
-existing planning artifacts, relevant implementation code and tests, stack
-configuration, design inputs, database context, and current behavior. Infer
-facts the repository already answers.
+Read the files the request names, plus `AGENTS.md` and `CLAUDE.md` when tracked,
+in one batch. Expand only for a missing contract, a dependency or a contradiction,
+and stop when each claim has evidence or a named gap. Infer facts the repository
+already answers.
 
 When a missing decision materially changes scope or observable behavior, use
 the host's structured question interface. Ask no more than three short,
@@ -45,9 +45,10 @@ out-of-scope boundaries. Record concrete repository paths and verification
 signals when they are known. Keep unresolved questions out of the saved
 contract when a repository-backed default exists.
 
-Validate the completed artifact before returning. If a helper is unavailable,
-perform the same deterministic checks directly; never fall back to a
-model-backed CLI.
+Validate the completed artifact before returning: run `openplanr spec validate <SPEC-ID>`
+when `command -v openplanr` succeeds, otherwise check the path, frontmatter,
+headings and acceptance IDs against the specification contract directly. Never
+fall back to a model-backed CLI.
 
 ## Return
 
@@ -62,5 +63,4 @@ If the specification is partial or blocked, name the missing decision and its im
   none remains.
 - **Next:** a copy-ready host-native `planr-plan` invocation for the saved spec.
 
-The summary is a human view of the specification, not another schema or a reason
-to rerun a completed operation for different wording.
+Follow [the shared return rules](references/return-contract.md).

package/lib/host-packages/openai/openplanr/skills/spec/openplanr.skill.json

@@ -3,7 +3,7 @@
   "schemaVersion": "1.0.0",
   "protocolVersion": "1.8.0",
   "skillId": "planr-spec",
-  "skillVersion": "1.0.2",
+  "skillVersion": "1.1.0",
   "entrypoint": "SKILL.md",
   "hosts": [
     "claude-code",
@@ -32,6 +32,17 @@
         "cursor"
       ],
       "executable": false
+    },
+    {
+      "path": "references/return-contract.md",
+      "kind": "reference",
+      "hosts": [
+        "claude-code",
+        "codex",
+        "chatgpt",
+        "cursor"
+      ],
+      "executable": false
     }
   ]
 }

package/lib/host-packages/openai/openplanr/skills/spec/references/return-contract.md

@@ -0,0 +1,10 @@
+# Return rules
+
+Shared by Spec, Plan, Plan Review, Ship, Operate and Release. Each skill lists its own fields.
+
+- Lead with the outcome: what is ready, prepared or released, then what is partial or blocked.
+- Link durable artifacts by purpose. Keep inventories, command output and transcripts in their files.
+- Report only checks you ran, with their result. Name each check you could not run and what stays unverified.
+- Omit empty fields. Give each open issue its impact and the smallest recovery action.
+- The summary is a human view, not a schema. Different wording never calls for a rerun or a correction pass.
+- Keep any machine-readable field a skill defines unchanged.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openplanr",
-  "version": "3.5.0",
+  "version": "3.6.0",
   "description": "The openplanr CLI: validates plans in your repo, lists the checks a change needs, renders diagrams, installs 25+ skills into Claude Code, Codex and Cursor, and syncs GitHub Issues and Linear. No model calls.",
   "type": "module",
   "main": "./dist/cli/index.js",

package/lib/host-packages/claude/openplanr/.claude-plugin/icon.svg

@@ -1,11 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 160 160" role="img" aria-labelledby="title desc">
-  <title id="title">OpenPlanr application icon</title>
-  <desc id="desc">The Open Decision mark on a rounded near-black tile.</desc>
-  <rect width="160" height="160" rx="35" fill="#08080C"/>
-  <g transform="translate(24 24) scale(.7)">
-    <g transform="rotate(-45 80 80)">
-      <path d="M125 50A52 52 0 1 0 125 110" fill="none" stroke="#5EEAD4" stroke-width="10" stroke-linecap="round" stroke-linejoin="round"/>
-      <rect x="127" y="71" width="18" height="18" rx="3" fill="#5EEAD4"/>
-    </g>
-  </g>
-</svg>

package/lib/host-packages/claude/openplanr/runtime/operate/scripts/errors.mjs

@@ -1,8 +0,0 @@
-export class SkillRuntimeError extends Error {
-  constructor(code, message, details = {}) {
-    super(message);
-    this.name = 'SkillRuntimeError';
-    this.code = code;
-    this.details = details;
-  }
-}

package/lib/host-packages/claude/openplanr/runtime/operate/scripts/operate-review-contract.mjs

@@ -1,428 +0,0 @@
-const deepFreeze = (value) => {
-  if (value && typeof value === 'object' && !Object.isFrozen(value)) {
-    for (const child of Object.values(value)) deepFreeze(child);
-    Object.freeze(value);
-  }
-  return value;
-};
-
-/**
- * Historical Operate Markdown contract.
- *
- * This remains available only so notes written by released 1.x guidance can be
- * identified and read. Canonical skills must use the current v2 contract below.
- */
-export const OPERATE_REVIEW_NOTE_PROFILES_V1 = deepFreeze({
-  advisor: {
-    maxBytes: 16 * 1024,
-    sections: [
-      'Findings',
-      'Recommended next move',
-      'Decision-changing gaps',
-      'Evidence index',
-      'Review coverage',
-      'Audit note',
-    ],
-    summaryFields: ['Signal', 'Bottom line'],
-    summaryValues: {
-      Signal: ['action', 'watch', 'insufficient evidence'],
-    },
-    item: {
-      section: 'Findings',
-      idPrefix: 'F',
-      maxItems: 5,
-      emptyText: 'No decision-relevant finding was established.',
-      fields: [
-        'Priority',
-        'Status',
-        'Why it matters',
-        'Evidence',
-        'Confidence',
-        'Decision implication',
-      ],
-      fieldValues: {
-        Priority: ['P0', 'P1', 'P2', 'unranked'],
-        Status: ['observed', 'inferred'],
-      },
-    },
-    sectionFields: {
-      'Recommended next move': [
-        'Recommendation',
-        'Proposed owner',
-        'First step',
-        'Expected result',
-        'Verification',
-        'Reversible / revisit when',
-        'Evidence',
-      ],
-      'Review coverage': ['Questions answered', 'Questions not established', 'Evidence boundary'],
-    },
-    sectionEmptyStates: {
-      'Recommended next move': 'No recommendation from current evidence.',
-    },
-    sectionItemLimits: {
-      'Decision-changing gaps': 3,
-    },
-  },
-  challenger: {
-    maxBytes: 12 * 1024,
-    sections: [
-      'Material exceptions',
-      'Decisions that still hold',
-      'Material dissent',
-      'Decision-changing gaps',
-      'Audit note',
-    ],
-    summaryFields: ['Verdict', 'Bottom line'],
-    summaryValues: {
-      Verdict: ['holds', 'holds with exceptions', 'not decision-ready'],
-    },
-    item: {
-      section: 'Material exceptions',
-      idPrefix: 'X',
-      maxItems: 5,
-      emptyText: 'No material exception found.',
-      fields: ['Target', 'Type', 'Decision impact', 'Challenge', 'Evidence', 'Resolution'],
-      fieldValues: {
-        Type: [
-          'unsupported',
-          'contradicted',
-          'correlated reasoning',
-          'missing alternative',
-          'unpriced downside',
-          'overconfident',
-        ],
-      },
-    },
-    sectionFields: {
-      'Material dissent': ['Dissent', 'Resolution condition'],
-    },
-    sectionItemLimits: {
-      'Decision-changing gaps': 3,
-    },
-  },
-  chair: {
-    maxBytes: 24 * 1024,
-    sections: [
-      'Decision queue',
-      'Action plan',
-      'Material risks and dissent',
-      'Decision-changing gaps',
-      'Review trail',
-      'Evidence index',
-      'Human gate',
-    ],
-    summaryFields: ['Overall signal', 'Executive call'],
-    summaryValues: {
-      'Overall signal': ['act now', 'decide next', 'watch', 'insufficient evidence'],
-    },
-    item: {
-      section: 'Decision queue',
-      idPrefix: 'D',
-      maxItems: 5,
-      emptyText: 'No decision-ready proposal was established.',
-      headingSuffixPattern: /^\[(?:P0|P1|P2|unranked)\]\s+\S/u,
-      fields: [
-        'Recommendation',
-        'Why now',
-        'Owner',
-        'Confidence',
-        'Alternative',
-        'First step',
-        'Expected result',
-        'Verification',
-        'Dependencies',
-        'Reversible / revisit when',
-        'Evidence',
-        'Dissent',
-      ],
-    },
-    sectionFields: {},
-    sectionItemLimits: {
-      'Decision-changing gaps': 5,
-    },
-  },
-  'board-report': {
-    maxBytes: 24 * 1024,
-    sections: [
-      'Scope and custody',
-      'Executive call',
-      'Decision queue',
-      'Action plan',
-      'Material risks and dissent',
-      'Decision-changing gaps',
-      'Review trail',
-      'Human gate',
-    ],
-    summaryFields: [],
-    item: {
-      section: 'Decision queue',
-      idPrefix: 'D',
-      maxItems: 5,
-      emptyText: 'No decision-ready proposal was established.',
-      headingSuffixPattern: /^\[(?:P0|P1|P2|unranked)\]\s+\S/u,
-      fields: [
-        'Recommendation',
-        'Why now',
-        'Owner',
-        'Confidence',
-        'Alternative',
-        'First step',
-        'Expected result',
-        'Verification',
-        'Dependencies',
-        'Reversible / revisit when',
-        'Evidence',
-        'Dissent',
-      ],
-    },
-    sectionFields: {
-      'Scope and custody': [
-        'Subject',
-        'Evidence window',
-        'Pending decision',
-        'Cycle owner',
-        'Custody',
-      ],
-    },
-    sectionItemLimits: {
-      'Decision-changing gaps': 5,
-    },
-  },
-});
-
-export const OPERATE_REVIEW_NOTE_PROFILES = deepFreeze({
-  advisor: {
-    maxBytes: 16 * 1024,
-    sections: ['Findings', 'Recommended next move', 'Decision-changing gaps', 'Sources consulted'],
-    summaryFields: ['Signal', 'Bottom line'],
-    summaryValues: {
-      Signal: ['action', 'watch', 'insufficient context'],
-    },
-    item: {
-      section: 'Findings',
-      idPrefix: 'F',
-      maxItems: 5,
-      emptyText: 'No decision-relevant finding was established.',
-      fields: ['Priority', 'Status', 'Why it matters', 'Sources', 'Confidence', 'Decision impact'],
-      fieldValues: {
-        Priority: ['P0', 'P1', 'P2', 'unranked'],
-        Status: ['observed', 'inferred'],
-      },
-    },
-    sectionFields: {
-      'Recommended next move': [
-        'Recommendation',
-        'Suggested owner',
-        'First step',
-        'Expected result',
-        'Check',
-        'Revisit when',
-      ],
-    },
-    sectionEmptyStates: {
-      'Recommended next move': 'No recommendation from current context.',
-    },
-    sectionItemLimits: {
-      'Decision-changing gaps': 3,
-    },
-  },
-  challenger: {
-    maxBytes: 12 * 1024,
-    sections: [
-      'Material exceptions',
-      'Decisions that still hold',
-      'Risks and dissent',
-      'Decision-changing gaps',
-    ],
-    summaryFields: ['Verdict', 'Bottom line'],
-    summaryValues: {
-      Verdict: ['holds', 'holds with exceptions', 'not decision-ready'],
-    },
-    item: {
-      section: 'Material exceptions',
-      idPrefix: 'X',
-      maxItems: 5,
-      emptyText: 'No material exception found.',
-      fields: ['Target', 'Type', 'Decision impact', 'Challenge', 'Sources', 'Resolution'],
-      fieldValues: {
-        Type: [
-          'unsupported',
-          'contradicted',
-          'correlated reasoning',
-          'missing alternative',
-          'unpriced downside',
-          'overconfident',
-        ],
-      },
-    },
-    sectionFields: {
-      'Risks and dissent': ['Dissent', 'Resolution condition'],
-    },
-    sectionItemLimits: {
-      'Decision-changing gaps': 3,
-    },
-  },
-  chair: {
-    maxBytes: 24 * 1024,
-    sections: [
-      'Decision queue',
-      'Action plan',
-      'Risks and dissent',
-      'Decision-changing gaps',
-      'Review coverage',
-    ],
-    summaryFields: ['Overall signal', 'Executive call'],
-    summaryValues: {
-      'Overall signal': ['act now', 'decide next', 'watch', 'insufficient context'],
-    },
-    item: {
-      section: 'Decision queue',
-      idPrefix: 'D',
-      maxItems: 5,
-      emptyText: 'No decision-ready proposal was established.',
-      headingSuffixPattern: /^\[(?:P0|P1|P2|unranked)\]\s+\S/u,
-      fields: [
-        'Recommendation',
-        'Why now',
-        'Suggested owner',
-        'Confidence',
-        'Alternative',
-        'First step',
-        'Expected result',
-        'Check',
-        'Dependencies',
-        'Revisit when',
-        'Sources',
-        'Dissent',
-      ],
-    },
-    sectionFields: {},
-    sectionItemLimits: {
-      'Decision-changing gaps': 5,
-    },
-  },
-  'board-report': {
-    maxBytes: 24 * 1024,
-    sections: [
-      'Scope',
-      'Executive summary',
-      'Decision queue',
-      'Action plan',
-      'Risks and dissent',
-      'Decision-changing gaps',
-      'Review coverage',
-      'Issues',
-    ],
-    summaryFields: [],
-    item: {
-      section: 'Decision queue',
-      idPrefix: 'D',
-      maxItems: 5,
-      emptyText: 'No decision-ready proposal was established.',
-      headingSuffixPattern: /^\[(?:P0|P1|P2|unranked)\]\s+\S/u,
-      fields: [
-        'Recommendation',
-        'Why now',
-        'Suggested owner',
-        'Confidence',
-        'Alternative',
-        'First step',
-        'Expected result',
-        'Check',
-        'Dependencies',
-        'Revisit when',
-        'Sources',
-        'Dissent',
-      ],
-    },
-    sectionFields: {
-      Scope: ['Subject', 'Window', 'Requested decision', 'Custody'],
-    },
-    sectionItemLimits: {
-      'Decision-changing gaps': 5,
-    },
-  },
-});
-
-export const OPERATE_REVIEW_NOTE_PROFILES_V2 = OPERATE_REVIEW_NOTE_PROFILES;
-export const OPERATE_REVIEW_CONTRACT_VERSION = '2.0.0';
-export const OPERATE_REVIEW_CONTRACT_VERSIONS = Object.freeze(['1.0.0', '2.0.0']);
-
-/**
- * Additive human-note rubric overlay for Operate's five executive advisors.
- *
- * The closed Operate 2.0 machine registry remains the runtime contract. These
- * questions govern concise Markdown projections produced by canonical skills.
- */
-export const OPERATE_ADVISOR_REVIEW_RUBRICS = deepFreeze({
-  'strategy-finance': {
-    skillId: 'planr-ceo-review',
-    requiredQuestions: [
-      'What current evidence changes or constrains company direction?',
-      'Which objectives appear mis-resourced relative to evidenced expected value?',
-      'What runway, margin, or cost consequence is established, and what remains unknown?',
-      'Which decisions carry an evidenced cost of delay, and which remain unranked?',
-    ],
-  },
-  'technology-risk': {
-    skillId: 'planr-cto-review',
-    requiredQuestions: [
-      'Which technical constraints now block a stated objective?',
-      'Which technical risks are decision-relevant, and which remain unranked?',
-      'Which architectural decision, if any, is being made implicitly by in-flight work?',
-      'How reversible are the evidenced high-impact changes?',
-    ],
-  },
-  'product-activation': {
-    skillId: 'planr-cpo-review',
-    requiredQuestions: [
-      'Where does current evidence show users failing to reach value?',
-      'Which product bets remain unvalidated, and what bounded next test is supported?',
-      'Is committed scope ordered by evidenced value and risk?',
-      'Which committed scope, if any, should be cut to protect the activation path?',
-      'Are acceptance criteria testable and tied to a customer or product outcome?',
-    ],
-  },
-  'growth-market': {
-    skillId: 'planr-cmo-review',
-    requiredQuestions: [
-      'What current evidence changes or constrains demand and positioning?',
-      'Which acquisition-channel evidence is strong, weak, or absent?',
-      'Which explicit market or positioning claim, if any, is unsupported?',
-      'Which growth loop is evidenced as repeatable rather than merely proposed?',
-    ],
-  },
-  'operations-customer': {
-    skillId: 'planr-coo-review',
-    requiredQuestions: [
-      'Can the organization deliver current commitments at evidenced capacity?',
-      'Where, if anywhere, is customer health degrading, and what operational cause is evidenced?',
-      'Which process, if any, is a single point of failure or single-person dependency?',
-      'Which operational commitment, if any, should be renegotiated before it is missed?',
-    ],
-  },
-});
-
-export const OPERATE_REVIEW_CONTRACT_V1 = deepFreeze({
-  kind: 'operate-human-review-contract',
-  schemaVersion: '1.0.0',
-  protocolBaseline: { id: 'operate', version: '2.0.0' },
-  profiles: OPERATE_REVIEW_NOTE_PROFILES_V1,
-  advisorRubrics: OPERATE_ADVISOR_REVIEW_RUBRICS,
-});
-
-export const OPERATE_REVIEW_CONTRACT_V2 = deepFreeze({
-  kind: 'operate-review-quality-contract',
-  schemaVersion: '2.0.0',
-  protocolBaseline: { id: 'operate', version: '2.0.0' },
-  profiles: OPERATE_REVIEW_NOTE_PROFILES,
-  advisorRubrics: OPERATE_ADVISOR_REVIEW_RUBRICS,
-});
-
-export const OPERATE_REVIEW_CONTRACTS = deepFreeze({
-  '1.0.0': OPERATE_REVIEW_CONTRACT_V1,
-  '2.0.0': OPERATE_REVIEW_CONTRACT_V2,
-});
-
-export const OPERATE_REVIEW_CONTRACT = OPERATE_REVIEW_CONTRACT_V2;