@matthewfl/pi-jtodo 0.0.1

package/LICENSE

@@ -0,0 +1,19 @@
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,83 @@
+# @matthewfl/pi-jtodo
+
+A quality-gated `todo` tool for the [pi](https://github.com/earendil-works/pi-coding-agent) coding agent.
+
+Most harness todo tools are checklists: the agent writes items, ticks them off, and nothing checks that "completed" meant *verified*. pi-jtodo ports the todo quality machinery from the **jcode** harness — confidence scores with tool-owned histories, plan and per-goal assessments, write-time ownership rejection, and turn-end validation gates — and adds pi-native reliability, recovery, and display features on top.
+
+```
+pi install npm:@matthewfl/pi-jtodo
+```
+
+> Registers the `todo` tool. If you use another todo extension (e.g. `@juicesharp/rpiv-todo`), remove it first — two extensions registering `todo` collide.
+
+## Inspiration and lineage
+
+The todo-tool family tree, as verified from each implementation's source:
+
+| | Claude Code `TodoWrite` | opencode `todowrite` | jcode `todo` | typical pi todo extensions | **pi-jtodo** |
+|---|---|---|---|---|---|
+| **Lineage** | invented the concept + usage prose (2025) | copied Claude's prose verbatim, added `priority` + `cancelled` | opencode's schema/semantics, none of the prose — plus the whole quality layer | lightweight list trackers | **jcode's quality layer, ported to pi** |
+| **Item schema** | `content`, `status` (3 states), `activeForm` | + `priority`, `cancelled` | + required `id`, `group`, `confidence`, `completion_confidence` | `content`/`status`/`priority` | = jcode (plus field-merge updates) |
+| **What enforces "done"?** | nothing — prose only | nothing — prose only | ownership gate rejects the write; turn-end completion/spike gates; deferred quality digest | nothing | **full port** + early-stop + watchdog |
+| **Pokes the agent when it stops early?** | no | no | auto-poke cycle, `/poke` re-arm | no | **port** + re-arm on new work + starvation watchdog |
+| **Survives reload / tree jumps / compaction?** | n/a (single turn) | yes (SQLite) | app state, lost across restarts | session state | **replayed from the branch log**, including gate flags |
+| **Tells the agent what its write actually changed?** | no | no | plan/goal assessment diffs only | no | **item-level `Changes:` digest** (names removed ids, cleared groups) |
+
+What each layer contributed, concretely:
+
+- **Claude Code** — the TodoWrite concept and the "when to use / when not to use" prose manual (opencode's 2025 description was a word-for-word copy of it).
+- **opencode** — `content`/`status`/`priority`, full-replace write semantics, and the full-list JSON echo.
+- **jcode** — everything that makes the list *load-bearing*: model-supplied ids, groups, the two confidence scores with tool-owned append-only histories, the `plan`/`goals` assessment objects, the whole-write ownership rejection, the deferred quality digest, and the auto-poke cycle. jcode deliberately carries no system-prompt guidance and keeps its calibration thresholds out of model-visible text; pi-jtodo keeps both disciplines.
+- **@juicesharp/rpiv-todo** — the compact above-editor list display this extension's widget is modeled on.
+
+pi-specific additions (not in any of the above): branch-log recovery of todo state *and* gate cycle flags across `/reload`, `/tree` jumps, and compaction; re-arm on new work (pi has no poke hotkey); a starvation watchdog that re-pokes when a follow-up was lost; the unchanged-signature early stop that halts a gate loop when the agent's scores aren't moving; update-style field inheritance with a `Changes:` digest; and the enriched widget strip (per-item confidence tails, per-goal table, poke-target fingers).
+
+Deliberately **not** ported from jcode: the `/overnight` mission mode (presumes a supervisor/manifest apparatus), the guardrail and credential circuit breakers (pi and pi-robust-provider own that territory), and jcode's `/poke` hotkey (replaced by `/todos poke`).
+
+## How it behaves
+
+- **Writes are replace-on-membership, merge-on-fields**: `todos` present = the new list (omitted ids are deleted); omit the array to read. On an existing id, omitted optional fields (`group`, `completion_confidence`) are inherited; `group: ""` clears. Accepted writes append `Changes: 2 updated; 1 new; removed #x; group cleared on #y`.
+- **Plan and goals are field-merged**: `plan` carries `user_intention` + `understands_user_intent`; each goal (one per group) carries `closed_feedback_loop` + `feedback_loop` + `end_to_end_ownership`. Omitted groups/fields are retained. All four histories are tool-owned — model-supplied history values are discarded.
+- **Write-time gate**: a write that closes a group (or the implicit ungrouped list) without an honest `end_to_end_ownership` claim is **rejected whole** — stored state is returned unchanged with an actionable message naming the failing groups. A first plan write with severely low intent gets an immediate in-band continuation.
+- **Turn-end gates** (when the agent settles): incomplete todos → auto-poke ("You have N incomplete todos. Continue working, or update the todo tool."). Fully settled → the deferred quality digest (intent/feedback-loop weak points), then the completion-confidence and confidence-spike gates — each naming the flagged `#id`s — with an attempt budget, an unchanged-signature early stop, and a done notice when validation passes.
+- **Follow-ups are attributed**: pokes, digests, and gate challenges travel as custom messages (LLM-visible as user-role text, transcript-visible as `pi-jtodo/followup`), so reload/resume never re-renders them as user prompts.
+
+## Display
+
+- **Above-editor strip**: intention header, value-ranked item lines (in_progress → pending → completed → cancelled) with status icons and `· conf N` tails, and a per-goal table (`Todo Goal | Settled | Conf | Own | Feedback`) with threshold-colored scores; `👉` marks the items that caused the most recent poke.
+- **`/todos`** overlay: full list with plan, goals, and feedback-loop texts. `**/todos export**`, `**/todos clear**`, `**/todos poke on|off|status|trigger**`.
+
+## Configuration
+
+`~/.pi/agent/state/pi-jtodo/config.json` (all keys optional):
+
+```json
+{
+	"enabled": true,
+	"autoPoke": true,
+	"completionGateMaxAttempts": 5,
+	"maxGateObservations": 256,
+	"maxConsecutivePokesWithoutProgress": 0,
+	"idleNudge": true,
+	"idleNudgeAfterAssistantTurns": 50,
+	"watchdog": true,
+	"watchdogIdleMs": 90000,
+	"watchdogTickMs": 30000,
+	"watchdogMaxRePokes": 3,
+	"widgetMaxLines": 6
+}
+```
+
+Gate calibration (the 96/60/15 thresholds and the 5-attempt budget) is intentionally **not** configurable — jcode keeps its calibration private from the model, and a knob the agent can turn is a knob the agent will turn.
+
+## Development
+
+```sh
+npm test        # 34 tests: write-time gates (Suite A) + turn-end e2e via a scripted mock provider (Suite B)
+```
+
+Layout: `src/` (extension modules — `index.ts` is the entry), `tests/test-todo.cjs`.
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/package.json

@@ -0,0 +1,48 @@
+{
+	"name": "@matthewfl/pi-jtodo",
+	"version": "0.0.1",
+	"description": "Quality-gated todo tool for Pi: confidence scores with tool-owned histories, plan and per-goal assessments, write-time ownership rejection, turn-end completion/spike gates, deferred quality digests, auto-poke continuation, starvation watchdog, and a live todo strip.",
+	"type": "module",
+	"scripts": {
+		"test": "node tests/test-todo.cjs"
+	},
+	"license": "MIT",
+	"author": "matthewfl",
+	"homepage": "https://github.com/matthewfl/pi-plugins/tree/master/extensions/pi-jtodo",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/matthewfl/pi-plugins.git",
+		"directory": "extensions/pi-jtodo"
+	},
+	"bugs": {
+		"url": "https://github.com/matthewfl/pi-plugins/issues"
+	},
+	"keywords": [
+		"pi-package",
+		"pi-extension",
+		"todo",
+		"quality-gates",
+		"agent",
+		"planning"
+	],
+	"files": [
+		"src",
+		"tests",
+		"README.md",
+		"LICENSE"
+	],
+	"publishConfig": {
+		"access": "public"
+	},
+	"peerDependencies": {
+		"@earendil-works/pi-ai": "*",
+		"@earendil-works/pi-tui": "*",
+		"@earendil-works/pi-coding-agent": "*",
+		"@sinclair/typebox": "*"
+	},
+	"pi": {
+		"extensions": [
+			"./src/index.ts"
+		]
+	}
+}

package/src/config.ts

@@ -0,0 +1,71 @@
+/**
+ * Optional per-user configuration: ~/.pi/agent/state/pi-jtodo/config.json
+ * Missing or unreadable config falls back to defaults. Gate thresholds are
+ * calibration constants (see constants.ts) and deliberately NOT configurable.
+ */
+
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { MAX_GATE_OBSERVATIONS, TODO_COMPLETION_GATE_MAX_ATTEMPTS } from "./constants.js";
+
+export interface TodoConfig {
+	enabled: boolean;
+	/** Arm the auto-poke cycle when each session starts (TUI/RPC only). */
+	autoPoke: boolean;
+	/** Turn-end re-validation budget before the gate stalls and disarms. */
+	completionGateMaxAttempts: number;
+	/** Cap on the turn-scoped observation log; oldest dropped first. */
+	maxGateObservations: number;
+	/**
+	 * 0 = disabled (pure jcode: poke until the list settles). >0 disarms after
+	 * N consecutive settles with no todo-state change (token-burn safety).
+	 */
+	maxConsecutivePokesWithoutProgress: number;
+	idleNudge: boolean;
+	idleNudgeAfterAssistantTurns: number;
+	/** Line budget for the above-editor todo widget (header included). */
+	widgetMaxLines: number;
+	/** Idle starvation watchdog: re-fire the poke when the agent sits idle
+	 *  with open todos (armed) longer than watchdogIdleMs. */
+	watchdog: boolean;
+	watchdogIdleMs: number;
+	watchdogTickMs: number;
+	/** Dead re-pokes without any activity before the cycle disarms. */
+	watchdogMaxRePokes: number;
+}
+
+export const DEFAULT_CONFIG: TodoConfig = {
+	enabled: true,
+	autoPoke: true,
+	completionGateMaxAttempts: TODO_COMPLETION_GATE_MAX_ATTEMPTS,
+	maxGateObservations: MAX_GATE_OBSERVATIONS,
+	maxConsecutivePokesWithoutProgress: 0,
+	idleNudge: true,
+	idleNudgeAfterAssistantTurns: 50,
+	widgetMaxLines: 6,
+	watchdog: true,
+	watchdogIdleMs: 90_000,
+	watchdogTickMs: 30_000,
+	watchdogMaxRePokes: 3,
+};
+
+export function loadConfig(): TodoConfig {
+	try {
+		const p = path.join(
+			os.homedir(),
+			".pi",
+			"agent",
+			"state",
+			"pi-jtodo",
+			"config.json",
+		);
+		const parsed = JSON.parse(fs.readFileSync(p, "utf8"));
+		if (typeof parsed === "object" && parsed !== null) {
+			return { ...DEFAULT_CONFIG, ...parsed };
+		}
+	} catch {
+		// missing or unreadable config -> defaults
+	}
+	return { ...DEFAULT_CONFIG };
+}

package/src/constants.ts

@@ -0,0 +1,78 @@
+/**
+ * Constants — thresholds and model-visible texts, verbatim from
+ * jcode-base/src/todo.rs. These are private calibration: never interpolate
+ * them into schema descriptions, continuations, digests, or notices, so the
+ * model cannot learn to target the evaluator instead of reporting honestly.
+ */
+
+export const TODO_TOOL_NAME = "todo";
+
+/** Minimum passing score for 0-100 quality assessments. */
+export const QUALITY_GATE_THRESHOLD = 96;
+/** Goals scoring below this are considered open-loop. */
+export const LOW_CLOSED_FEEDBACK_LOOP = QUALITY_GATE_THRESHOLD;
+/** Below this the agent does not yet understand the user's intent. */
+export const LOW_INTENT_UNDERSTANDING = QUALITY_GATE_THRESHOLD;
+/**
+ * Below this score on the very first plan write the agent is admitting it
+ * does not know the task; worth one immediate nudge. Every other write-time
+ * check is deferred to the turn-end digest.
+ */
+export const SEVERE_INTENT_MISUNDERSTANDING = 60;
+/** A completed todo whose final recorded confidence jump is at least this. */
+export const TODO_CONFIDENCE_SPIKE = 15;
+/** Turn-end re-validation budget before the gate gives up and disarms. */
+export const TODO_COMPLETION_GATE_MAX_ATTEMPTS = 5;
+/** Upper bound on retained turn-scoped observations; oldest dropped first. */
+export const MAX_GATE_OBSERVATIONS = 256;
+
+/** customType for all synthetic gate follow-ups (custom session messages). */
+export const FOLLOWUP_CUSTOM_TYPE = "pi-jtodo/followup";
+
+// Display-hidden session entries marking auto-poke arm/disarm transitions.
+// The branch walker replays these so reload / tree navigation reset the
+// gate cycle exactly where the live machine reset it — without them,
+// transcript flags are monotone and a post-rearm reload would inherit the
+// previous cycle's digestDelivered/spikeChallenged.
+export const CYCLE_CUSTOM_TYPE = "pi-jtodo/cycle";
+
+// ----------------------------------------------------------------------------
+// Model-visible continuations — verbatim from jcode-base/src/todo.rs
+// ----------------------------------------------------------------------------
+
+/** Immediate nudge for a severely low first intent assessment (in-band). */
+export const TODO_INTENT_UNDERSTANDING_CONTINUATION_MESSAGE =
+	"Your understanding of the user's intent is not high enough. Re-read the request and think harder about what the user actually wants and left implicit, using the conversation and codebase as evidence. Do not ask the user; resolve the ambiguity yourself, then update the plan's user intention and understands_user_intent.";
+
+/** Ownership gate rejection. Names the field to raise and discloses the rejection. */
+export const TODO_OWNERSHIP_CONTINUATION_MESSAGE =
+	"Your end-to-end ownership is not high enough to complete this goal. Take ownership of the full user outcome, not just the immediate implementation. Follow the work through every relevant integration and runtime path, resolve consequential gaps, validate the complete workflow, and finish the necessary follow-through. Then call the todo tool again, setting a higher `end_to_end_ownership` on the goal for this group; until that field is raised the write is rejected and the stored todo list is left unchanged.";
+
+/** Turn-end completion-confidence gate. */
+export const TODO_COMPLETION_CONTINUATION_MESSAGE =
+	"[automated todo completion gate - not a user message] Your completion confidence is missing or not high enough. Do not reply conversationally or wait for the user. Instead: Validate the completed result more thoroughly with concrete evidence, address any remaining issues, then call the todo tool again with updated completion_confidence values that reflect the validation you performed.";
+
+/** Turn-end confidence-spike gate. */
+export const TODO_CONFIDENCE_SPIKE_CONTINUATION_MESSAGE =
+	"[automated todo completion gate - not a user message] Your completion confidence rose too sharply to count as independently validated. Do not reply conversationally or wait for the user. Instead: recheck the completed result using concrete evidence, address any issues you find, then call the todo tool again with completion_confidence values that reflect the validation you performed.";
+
+/** Turn-end digest header. Framed as "double-check", never a refusal. */
+export const TODO_GATE_DIGEST_PREFIX =
+	"[automated todo quality review - not a user message] Before you treat this turn as finished, double-check the weak points it surfaced. Do not reply conversationally or wait for the user.";
+
+// ----------------------------------------------------------------------------
+// Display-only notices (jcode DisplayMessage::system strings; /poke adapted
+// to /todos poke). Shown via ctx.ui.notify, never sent to the model.
+// ----------------------------------------------------------------------------
+
+export const NOTICE_POKE_OFF_HINT = "/todos poke off to stop.";
+export const NOTICE_DIGEST_QUEUED =
+	"🔎 We asked the agent to double-check this turn's weak points.";
+export const NOTICE_COMPLETION_CHALLENGED =
+	"🛑 The agent marked its work done without strong enough validation. We asked it to double-check.";
+export const NOTICE_SPIKE_CHALLENGED =
+	"🛑 The agent's confidence jumped suddenly. We asked it to verify that independently.";
+export const NOTICE_GATE_STALLED =
+	"⚠️ We nudged the agent several times but its validation still isn't holding up. We stopped poking; review the remaining todos yourself.";
+export const NOTICE_GATE_UNCHANGED =
+	"⚠️ The agent re-validated but its completion confidence did not move, so further nudges would only repeat themselves. We stopped poking; review the completed todos yourself. /todos poke on to resume.";