openplanr 2.1.1 → 2.2.0

package/lib/host-packages/openai/openplanr/skills/sprint/references/refinement-contract.md

@@ -0,0 +1,154 @@
+# Refinement contract
+
+The refinement document is the durable record of one run: what was read, how
+each item was judged, what was selected and what the refuters changed. The CLI
+validates it (`planr sprint refinement <id> --data`), stores it as
+`.planr/sprints/SPRINT-NNN/refinement.json`, renders `refinement.md` from it
+and fills the sprint body from its batches. `planr sprint diff`, `planr sprint
+close` and `planr sprint apply` read it back.
+
+## Item record
+
+One entry per open item, whether or not it is selected.
+
+| Field | Meaning |
+| --- | --- |
+| `id` | Artifact id (`BL-012`, `QT-034`, `TASK-007`). Only artifacts; file non-artifact work as a quick task first. |
+| `title` | The item's title as written. |
+| `claim` | What the item says is wrong or wanted, in one sentence. |
+| `evidenceDate` | The latest dated evidence for the claim (`YYYY-MM-DD`), or `null` when none exists. |
+| `codePath` / `codePathExists` | The code path the item names and whether it still exists on the default branch as described. `null` when the item names none. |
+| `stale` | `true` when the evidence is older than the cadence allows or the code has moved on. |
+| `blockedBy` | The named blockers: `partner: …`, `team decision: …`, `BL-045`. Empty when nothing blocks it. |
+| `unblockQuestion` | The one question whose answer unblocks the item. |
+| `effort` | `hours`, `day`, `days` or `week+`. |
+| `score` | Production impact this month × tractability now. Any consistent scale; only the order matters. |
+| `bucket` | `inProgress`, `planNext`, `blocked` or `closeOrDemote`. |
+| `reason` | One clause: why the item sits in that bucket. |
+| `evidence` | For close-or-demote rows: `file:line`, PR number or date. |
+| `targetStatus` / `targetPriority` | What `planr sprint apply` writes, in the repository's own vocabulary (`planr update --help`). Priority applies to backlog items only. |
+
+## Scoring
+
+Score = production impact this month × tractability now.
+
+- Impact counts users hit, money or compliance at stake, and whether the
+  release cut depends on it. An item nobody is hit by this month scores low
+  regardless of its label.
+- Tractability counts whether the fix is known, whether the code path exists,
+  whether a migration or a partner is needed, and whether the item is already
+  half done.
+- Evidence date beats priority label. A P0 from months ago with no fresh
+  evidence is a candidate for close-or-demote, not for in progress.
+
+## Buckets
+
+| Bucket | Rule |
+| --- | --- |
+| `inProgress` | Fits the stated capacity to the cut. Ordered for execution and grouped into `batches` (PR batches by product, or sessions). Includes the release cut itself as work. |
+| `planNext` | Real and tractable, but after the cut. |
+| `blocked` | Blocked on a partner, a team decision or another item. Never in progress. Carries `blockedBy` and `unblockQuestion`. |
+| `closeOrDemote` | Dead, duplicated, overtaken or already delivered. Carries `evidence` and the `targetStatus` or `targetPriority` the write-back applies. |
+
+Every item is in exactly one bucket; `buckets.<name>` lists the ids and each
+item's `bucket` field agrees. `batches[].itemIds` partition `buckets.inProgress`
+exactly.
+
+## Refuter lenses
+
+Run all three over every in-progress pick before the buckets are shown.
+
+| Lens | Question | Typical corrections |
+| --- | --- | --- |
+| `evidence` | Is it still real on the default branch? Is the premise true? Was it already fixed? | Dropped picks, moves to close-or-demote |
+| `capacity` | Does the list fit the days? Are migrations, partner dependencies, PR batching and CI cost per PR accounted for? | Splits, reorders, moves to plan-next |
+| `impact` | Who is hit this month if it is not done? Which higher-impact item was omitted for it? | Swaps, moves to plan-next |
+
+A pick that fails a lens moves or drops, and the correction is recorded in
+`refuted[]` as `{ itemId, lens, change, from, to }`. Nothing is deleted from
+`items[]`; the item keeps its new bucket and reason.
+
+## `refinement.json`
+
+```json
+{
+  "schemaVersion": 1,
+  "sprintId": "SPRINT-004",
+  "refinedAt": "2026-09-17",
+  "inputs": {
+    "capacityDays": 6,
+    "releaseCut": "2026-09-25",
+    "gitRevision": "a1b2c3d",
+    "previousSprintId": "SPRINT-003",
+    "operateCycleId": "OP-2026-09-A",
+    "sources": ["backlog", "quick", "git", "release-profile"],
+    "defaulted": ["capacity"],
+    "notes": "Connector not configured; statuses stay local."
+  },
+  "items": [
+    {
+      "id": "BL-345",
+      "title": "CRM callback silent since 10 Sep",
+      "claim": "Callbacks from the CRM stopped landing on 10 Sep",
+      "evidenceDate": "2026-09-16",
+      "codePath": "apps/apply/src/crm/callback.ts",
+      "codePathExists": true,
+      "stale": false,
+      "blockedBy": [],
+      "effort": "hours",
+      "score": 9.5,
+      "bucket": "inProgress",
+      "reason": "39 applications stuck at Received"
+    },
+    {
+      "id": "BL-295",
+      "title": "Importer drops trailing rows",
+      "evidenceDate": "2026-05-02",
+      "stale": true,
+      "blockedBy": [],
+      "effort": "days",
+      "score": 0.5,
+      "bucket": "closeOrDemote",
+      "reason": "delivered by #569",
+      "evidence": "PR #569 merged 2026-09-08",
+      "targetStatus": "closed"
+    },
+    {
+      "id": "BL-167",
+      "title": "Dynamics id for the Austrian Matura",
+      "evidenceDate": "2026-08-30",
+      "stale": false,
+      "blockedBy": ["partner: Dynamics team"],
+      "unblockQuestion": "Which Dynamics id represents the Austrian Matura?",
+      "effort": "day",
+      "score": 4,
+      "bucket": "blocked",
+      "reason": "needs the partner mapping"
+    }
+  ],
+  "buckets": {
+    "inProgress": ["BL-345"],
+    "planNext": [],
+    "blocked": ["BL-167"],
+    "closeOrDemote": ["BL-295"]
+  },
+  "batches": [
+    { "title": "VM read session", "effortDays": 0.5, "itemIds": ["BL-345"] }
+  ],
+  "refuted": [
+    {
+      "itemId": "BL-295",
+      "lens": "evidence",
+      "change": "delivered 8 Sep, moved to close",
+      "from": "inProgress",
+      "to": "closeOrDemote"
+    }
+  ]
+}
+```
+
+`inputs.sources` names what was read; `inputs.defaulted` names every value
+taken from a default instead of the repository or the user. The CLI adds
+`leftovers[]` on `planr sprint close` and `applied` on `planr sprint apply`;
+never write those yourself. Unknown fields are rejected, so keep notes in
+`inputs.notes` or in the item's `reason`.

package/lib/host-packages/openai/openplanr/skills/sprint/references/sprint-formats.md

@@ -0,0 +1,146 @@
+# Sprint formats
+
+Three durable outputs and one chat return. The CLI writes the first three from
+the two JSON inputs below; when it is unavailable, write the same files by hand.
+
+## `sprint.json` (input to `planr sprint create --data`)
+
+```json
+{
+  "title": "Cut 25 Sep 2026",
+  "startDate": "2026-09-17",
+  "releaseCut": "2026-09-25",
+  "capacityDays": 6,
+  "goals": ["Unblock stuck applications", "Ship the cut"]
+}
+```
+
+`endDate` defaults to `releaseCut`, or to `startDate` plus the duration when no
+cut is known. `status` may be `planned` or `active` (default). Omit `taskIds`
+and `batches`; `planr sprint refinement` fills them from the refinement
+document.
+
+## Sprint artifact
+
+`.planr/sprints/SPRINT-NNN-<slug>.md`: the existing frontmatter plus three
+fields, and the In-progress bucket as checkboxes grouped by batch.
+
+```markdown
+---
+id: "SPRINT-004"
+name: "Cut 25 Sep 2026"
+startDate: "2026-09-17"
+endDate: "2026-09-25"
+duration: "8d"
+status: "active"
+releaseCut: "2026-09-25"
+capacityDays: 6
+created: "2026-09-17"
+updated: "2026-09-17"
+taskIds: ["BL-345", "BL-348", "QT-194"]
+refinedAt: "2026-09-17"
+---
+
+# SPRINT-004: Cut 25 Sep 2026
+
+## Sprint Details
+
+- **Duration:** 8d
+- **Start:** 2026-09-17
+- **End:** 2026-09-25
+- **Status:** ACTIVE
+- **Release cut:** 2026-09-25
+- **Capacity:** 6 engineer-days
+
+## Tasks
+
+### VM read session · 0.5d
+
+- [ ] **BL-345** CRM callback silent since 10 Sep · hours · [view](../backlog/BL-345-crm-callback-silent.md)
+
+### PR 1 · MUVi Apply · 1d
+
+- [ ] **BL-348** rag-api cannot reach the department API · day · [view](../backlog/BL-348-rag-api.md)
+- [ ] **QT-194** Release cut 25 Sep · hours · [view](../quick/QT-194-release-cut-25-sep.md)
+
+## Retrospective
+_Complete this section when closing the sprint with `planr sprint close SPRINT-004`._
+```
+
+Each task line is `- [ ] **ID** title · effort · [view](relative path)`.
+`planr status`, `planr sprint close` and the dashboard read these lines; tick a
+box when the item ships. `releaseCut` is absent when no release profile exists;
+`capacityDays` and `refinedAt` are absent until a refinement is recorded.
+
+## Refinement note
+
+`.planr/sprints/SPRINT-NNN/refinement.md`, rendered from the JSON so the next
+run can diff against it:
+
+- **Inputs**: capacity, release cut, git revision, previous sprint, Operate
+  cycle, sources read, values defaulted.
+- **Items**: one table row per open item: `ID · score · evidence date · stale?
+  · blocked by · effort · bucket`.
+- **Refuter verdicts**: every correction verbatim, with its lens.
+- **In progress** by batch, then **Plan next**, **Blocked** and **Close or
+  demote** in full, since only In progress goes into the sprint.
+- **Leftovers** (after `planr sprint close`) and **Applied** (after
+  `planr sprint apply`).
+
+## Machine-readable copy
+
+`.planr/sprints/SPRINT-NNN/refinement.json`: the document described in
+[the refinement contract](refinement-contract.md), validated against the JSON
+Schema packaged as `schemas/refinement.schema.json` (linked from the skill
+entrypoint). The dashboard, `planr sprint diff` and `planr sprint apply` consume
+it.
+
+## Status write-back
+
+Only on approval through the structured question. `planr sprint apply
+SPRINT-NNN --yes --commit` writes each close, demote or blocked row's
+`targetStatus`, `targetPriority` and `blockedBy` to the artifacts and commits the
+sprint, the note, the JSON and the changed artifacts as one commit:
+
+```
+chore(planr): refine backlog for SPRINT-NNN
+```
+
+## Example chat return
+
+```
+Outcome:  proposed · 5.8 of 6 engineer-days used · SPRINT-004 (cut 25 Sep)
+Sprint:   .planr/sprints/SPRINT-004-cut-25-sep-2026.md
+
+In progress (execution order)
+  VM read session · 0.5d
+    BL-345  CRM callback silent since 10 Sep, 39 applications stuck at Received
+    BL-348  rag-api cannot reach the department API (+ missing api key)
+  PR 1 · MUVi Apply · 1d
+    BL-282  self-healing where clause
+    BL-229  write-side GUID check only (rest 9 Oct)
+  PR 2 · Connect residuals · 0.75d
+    BL-360, BL-364, BL-368, BL-056 (D3 only)
+  Ops readiness · 1.5d   ·   QT-194 the cut · 0.5d
+
+Plan next (9 Oct)   BL-224, BL-043, BL-283, BL-014, BL-349 code, …   (14 items)
+Blocked             BL-167 partner: Dynamics id for Austrian Matura?
+                    BL-272 team: which English tests carry a score?   (31 items)
+Close or demote     BL-295 done by #569 · BL-327 done by #590 · BL-197 P1 dead 14 Sep …  (42 items)
+
+Refuted   BL-342 evidence: no server actions in muvi-apply, dropped
+          BL-229 impact: no applicant hit this month, split
+          BL-295 evidence: delivered 8 Sep, moved to close
+Issues    none
+Next      approve write-back: planr sprint apply SPRINT-004 --yes --commit
+```
+
+## Hand-written fallback
+
+Without the CLI, create the three files above yourself: allocate the next
+`SPRINT-NNN`, write the frontmatter and the batched checkboxes exactly as shown,
+write `refinement.json` to the schema and `refinement.md` from it, and apply the
+status changes with the repository's own vocabulary in one commit with the same
+message. Never store notes as `.planr/sprints/SPRINT-NNN-*.md` siblings; graph
+readers treat every `.md` in `sprints/` as a sprint and skip only the
+`SPRINT-NNN/` directory.

package/lib/host-packages/openai/openplanr/skills/sprint/schemas/refinement.schema.json

@@ -0,0 +1,140 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openplanr.dev/schemas/skills/planr-sprint/refinement.schema.json",
+  "title": "OpenPlanr sprint refinement document",
+  "description": "One backlog refinement run: inputs, every open item's judgement, the four buckets, the in-progress batches and the refuter corrections. Written by the planr-sprint skill and validated by planr sprint refinement.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "sprintId", "refinedAt", "inputs", "items", "buckets"],
+  "$defs": {
+    "isoDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" },
+    "artifactId": { "type": "string", "pattern": "^[A-Z]+-\\d+$" },
+    "sprintId": { "type": "string", "pattern": "^SPRINT-\\d+$" },
+    "text": { "type": "string", "minLength": 1 },
+    "bucket": { "enum": ["inProgress", "planNext", "blocked", "closeOrDemote"] },
+    "effort": { "enum": ["hours", "day", "days", "week+"] },
+    "lens": { "enum": ["evidence", "capacity", "impact"] },
+    "idList": { "type": "array", "items": { "$ref": "#/$defs/artifactId" } }
+  },
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "sprintId": { "$ref": "#/$defs/sprintId" },
+    "refinedAt": { "$ref": "#/$defs/isoDate" },
+    "inputs": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "capacityDays": { "type": "number", "exclusiveMinimum": 0 },
+        "releaseCut": { "$ref": "#/$defs/isoDate" },
+        "gitRevision": { "$ref": "#/$defs/text" },
+        "previousSprintId": { "$ref": "#/$defs/sprintId" },
+        "operateCycleId": { "$ref": "#/$defs/text" },
+        "sources": { "type": "array", "items": { "$ref": "#/$defs/text" }, "default": [] },
+        "defaulted": { "type": "array", "items": { "$ref": "#/$defs/text" }, "default": [] },
+        "notes": { "$ref": "#/$defs/text" }
+      }
+    },
+    "items": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "title", "effort", "score", "bucket", "reason"],
+        "properties": {
+          "id": { "$ref": "#/$defs/artifactId" },
+          "title": { "$ref": "#/$defs/text" },
+          "claim": { "$ref": "#/$defs/text" },
+          "evidenceDate": { "oneOf": [{ "$ref": "#/$defs/isoDate" }, { "type": "null" }], "default": null },
+          "codePath": { "oneOf": [{ "$ref": "#/$defs/text" }, { "type": "null" }] },
+          "codePathExists": { "type": ["boolean", "null"] },
+          "stale": { "type": "boolean", "default": false },
+          "blockedBy": { "type": "array", "items": { "$ref": "#/$defs/text" }, "default": [] },
+          "unblockQuestion": { "$ref": "#/$defs/text" },
+          "effort": { "$ref": "#/$defs/effort" },
+          "score": { "type": "number" },
+          "bucket": { "$ref": "#/$defs/bucket" },
+          "reason": { "$ref": "#/$defs/text" },
+          "evidence": { "$ref": "#/$defs/text" },
+          "targetStatus": { "$ref": "#/$defs/text" },
+          "targetPriority": { "$ref": "#/$defs/text" }
+        }
+      }
+    },
+    "buckets": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["inProgress", "planNext", "blocked", "closeOrDemote"],
+      "properties": {
+        "inProgress": { "$ref": "#/$defs/idList" },
+        "planNext": { "$ref": "#/$defs/idList" },
+        "blocked": { "$ref": "#/$defs/idList" },
+        "closeOrDemote": { "$ref": "#/$defs/idList" }
+      }
+    },
+    "batches": {
+      "type": "array",
+      "default": [],
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["title", "itemIds"],
+        "properties": {
+          "title": { "$ref": "#/$defs/text" },
+          "effortDays": { "type": "number", "exclusiveMinimum": 0 },
+          "itemIds": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/artifactId" } }
+        }
+      }
+    },
+    "refuted": {
+      "type": "array",
+      "default": [],
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["itemId", "lens", "change"],
+        "properties": {
+          "itemId": { "$ref": "#/$defs/artifactId" },
+          "lens": { "$ref": "#/$defs/lens" },
+          "change": { "$ref": "#/$defs/text" },
+          "from": { "$ref": "#/$defs/bucket" },
+          "to": { "enum": ["inProgress", "planNext", "blocked", "closeOrDemote", "dropped"] }
+        }
+      }
+    },
+    "leftovers": {
+      "description": "Written by planr sprint close.",
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "reason"],
+        "properties": {
+          "id": { "$ref": "#/$defs/artifactId" },
+          "reason": { "enum": ["unchecked", "not-done"] }
+        }
+      }
+    },
+    "applied": {
+      "description": "Written by planr sprint apply.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["at", "updates"],
+      "properties": {
+        "at": { "$ref": "#/$defs/text" },
+        "updates": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["id", "type", "fields"],
+            "properties": {
+              "id": { "$ref": "#/$defs/artifactId" },
+              "type": { "$ref": "#/$defs/text" },
+              "fields": { "type": "object", "additionalProperties": { "type": "string" } }
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openplanr",
-  "version": "2.1.1",
+  "version": "2.2.0",
   "description": "Deterministic OpenPlanr utilities for planning storage, validation, rendering, setup, diagnostics, and GitHub/Linear synchronization",
   "type": "module",
   "main": "./dist/cli/index.js",
@@ -115,7 +115,7 @@
     "zod": "^4.3.6"
   },
   "optionalDependencies": {
-    "planr-pipeline": "0.45.1"
+    "planr-pipeline": "0.45.2"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.9",