Portable Goals and Todos for Pi

This repository contains two independent Pi extensions:

• @fractaal/pi-goal-x - one branch-local Goal with confirmed proposal/tweak, relentless autonomous continuation, strict model-owned blocking, native human pause/resume, abandonment, independent completion audit, final prose settlement, replay, a native widget, and structured events.
• @fractaal/pi-todo in packages/todo — one revisioned branch-local working plan with omission protection, dependency validation, context salience, replay, a native widget, and structured state.

They have no runtime dependency on each other and do not import Symphony, Aria, ALR, IPC, RTDB, Gateway, React, or product-specific types.

Goal

Model tools:

• propose_goal({ objective })
• tweak_goal({ objective })
• set_goal_blocked({ blocker, evidence, whyNoAutonomousPathRemains, unblockCondition })
• resume_goal()
• abandon_goal({ reason })
• complete_goal({ summary })

Events:

• pi-goal:state — complete GoalState snapshot
• pi-goal:proposal — complete current proposal snapshot
• pi-goal:transcript-event — bounded lifecycle receipt
• pi-goal:request-state — asks the producer to replay current state and proposal

Goal state lives only in Pi session custom entries. It is replayed on session start, tree navigation, and compaction. Autonomous continuation appends the generic durable message Continue the Goal. after each normal settled run while the Goal remains active. The model can stop continuation only by making the fully evidenced set_goal_blocked claim. That transition emits goal_blocked and maps into the existing internal paused state by encoding the complete proof in the compatible pause.reason and pause.suggestedAction fields. The native /goal-pause command remains a genuine human pause and emits goal_paused. At the start of each run, Goal adds one deterministic semantic block to Pi's system prompt; accounting revisions, timestamps, usage, and active-time changes do not alter those prompt bytes. Pi core owns provider retry and compaction recovery. The completion auditor receives an OS-sandboxed read-only shell when Bubblewrap is available; on platforms without that boundary, it receives only Pi's read/grep/find/ls tools.

Todo

get_todo() reads the exact current revision and task list without mutation. The todo tool replaces the complete retained plan:

todo({
  baseRevision: 3,
  tasks: [
    { key: "implement", subject: "Implement the bridge", status: "in_progress" },
    { key: "verify", subject: "Verify it", status: "pending", dependsOn: ["implement"] }
  ],
  remove: []
})

An existing unfinished task cannot disappear unless remove names its key and gives a non-empty reason. Completed work may leave the current working plan. Stale revisions, normalized dependency collisions, invalid dependency graphs, and plans above the 16 KiB serialized UTF-8 budget leave state unchanged.

Todo contents are never floated into every provider request. Pi's stable system instructions tell the model when to use get_todo. When unfinished state becomes distant in context, after restoration, or after compaction, Todo queues one hidden durable checkpoint into an already-required provider call or the next external turn. Checkpoints never wake an idle model by themselves and stop when no unfinished work remains.

Events:

• pi-todo:state — complete TodoState snapshot
• pi-todo:request-state — asks the producer to replay current state

Development

npm test
npm run check
npm run check:todo
npm run build
npm pack --dry-run
(cd packages/todo && npm pack --dry-run)
PI_ACCEPTANCE_BIN="$(command -v pi)" npm run test:installed

Installed-package acceptance builds and packs both tarballs, installs each alone under a temporary PI_CODING_AGENT_DIR, verifies real Pi package discovery/replay and deterministic lifecycle behavior, then removes the temporary profiles. It never touches the normal Personal Pi profile.

Releases

Maintainers publish both packages from one verified fractaal-vX.Y.Z tag through npm trusted publishing. The Goal package version names the tag; Todo keeps its own stable version. The workflow checks the exact tag commit, runs the package checks and builds, and skips any package version already on npm so a retry safely resumes a partial release.

See docs/releasing.md for the GitHub environment, npm trusted-publisher settings, first-release command, and recovery command.