goalbuddy 0.2.10

package/examples/extend-catalog-workflow/state.yaml

@@ -0,0 +1,327 @@
+# Goal Maker v2 state.yaml
+# Board truth lives here. goal.md is the editable charter; notes/ holds long receipts only.
+
+version: 2
+
+goal:
+  title: "Extend Catalog Workflow"
+  slug: "extend-catalog-workflow"
+  kind: open_ended
+  tranche: "Design and implement the extension catalog workflow, root extend surface, and clean package/skill layout."
+  status: done
+
+rules:
+  pm_owns_state: true
+  one_active_task: true
+  max_write_workers: 1
+  no_implementation_without_worker_or_pm_task: true
+  no_completion_without_judge_or_pm_audit: true
+
+agents:
+  scout: installed
+  worker: installed
+  judge: installed
+
+active_task: null
+
+tasks:
+  - id: T001
+    type: scout
+    assignee: Scout
+    status: done
+    reasoning_hint: high
+    objective: "Map the product vocabulary, extension surfaces, catalog strategy, and repo boundaries for optional Goal Maker extensions."
+    inputs:
+      - README.md
+      - package.json
+      - goal-maker/SKILL.md
+      - goal-maker/scripts/check-goal-state.mjs
+      - docs/goals/board-publishing-surfaces/goal.md
+    constraints:
+      - "Read-only."
+      - "Do not implement."
+      - "Treat external services as generated views, not board truth."
+      - "Use extend as the high-level concept and extensions as item names."
+    expected_output:
+      - "Recommended vocabulary."
+      - "Catalog and extension repo shape."
+      - "Candidate implementation tasks."
+    receipt:
+      result: done
+      note: notes/T001-extension-model-map.md
+      summary: "Mapped `extend/` as the optional extension surface, `extend/catalog.json` as the GitHub-hosted catalog, and package/dev internals as separate from the installable skill payload."
+      evidence:
+        - README.md
+        - package.json
+        - goal-maker/SKILL.md
+        - goal-maker/scripts/check-goal-state.mjs
+      spawned_tasks:
+        - T002
+  - id: T002
+    type: judge
+    assignee: Judge
+    status: done
+    reasoning_hint: high
+    objective: "Choose the extension vocabulary, catalog source, CLI shape, and repo layout before implementation."
+    inputs:
+      - "T001 receipt"
+      - examples/extend-catalog-workflow/notes/T001-extension-model-map.md
+    constraints:
+      - "Do not implement."
+      - "Preserve Goal Maker's local-first model."
+      - "Keep the root relatively clean."
+      - "Avoid browse/list/show as separate user concepts."
+    expected_output:
+      - "Decision on extension language."
+      - "Decision on catalog hosting."
+      - "First implementation tranche."
+    receipt:
+      result: done
+      decision: "Use root `extend/`, `extend/catalog.json`, and `goal-maker extend` as the single discovery/details command; group package-only CLI and tests under `internal/` while keeping skill runtime scripts inside `goal-maker/scripts/`."
+      note: notes/T002-architecture-decision.md
+      evidence:
+        - examples/extend-catalog-workflow/notes/T001-extension-model-map.md
+        - README.md
+        - package.json
+      next_allowed_task: T003
+  - id: T003
+    type: worker
+    assignee: Worker
+    status: done
+    reasoning_hint: medium
+    objective: "Implement the first catalog-backed `goal-maker extend` workflow."
+    allowed_files:
+      - README.md
+      - catalog.json
+      - goal-maker/bin/goal-maker.mjs
+      - goal-maker/test/goal-maker-cli.test.mjs
+      - package.json
+    verify:
+      - npm run check
+      - git diff --check
+      - node goal-maker/bin/goal-maker.mjs extend --catalog-url catalog.json --json
+      - npm publish --dry-run --json
+    stop_if:
+      - "Need provider credentials."
+      - "Need files outside allowed_files."
+      - "Catalog or extension semantics become ambiguous."
+      - "Verification fails twice."
+    receipt:
+      result: done
+      changed_files:
+        - README.md
+        - catalog.json
+        - goal-maker/bin/goal-maker.mjs
+        - goal-maker/test/goal-maker-cli.test.mjs
+        - package.json
+      commands:
+        - cmd: npm run check
+          status: pass
+        - cmd: git diff --check
+          status: pass
+        - cmd: node goal-maker/bin/goal-maker.mjs extend --catalog-url catalog.json --json
+          status: pass
+        - cmd: npm publish --dry-run --json
+          status: pass
+      summary: "Implemented catalog-backed `goal-maker extend`, root `catalog.json`, checksum-verified extension install, extension doctor checks, and CLI test coverage."
+      note: notes/T003-implementation-summary.md
+      commits:
+        - 105850e
+      spawned_tasks:
+        - T004
+  - id: T004
+    type: pm
+    assignee: PM
+    status: done
+    reasoning_hint: medium
+    objective: "Add a visible root `extend/` folder without bundling placeholder extensions."
+    inputs:
+      - "T002 decision"
+      - "T003 receipt"
+      - "Owner feedback that the repo should show an `/extend` folder."
+    constraints:
+      - "Do not add fake bundled extensions."
+      - "Keep extensions as subfolders under root `extend/`."
+      - "Keep npm catalog behavior GitHub-hosted."
+    expected_output:
+      - "Root extend folder with documentation."
+      - "README wording that points to the extension surface."
+    receipt:
+      result: done
+      summary: "Added root `extend/README.md` so the repo has a visible extension surface while keeping the catalog empty until real extensions ship."
+      note: notes/T004-root-extend-folder.md
+      changed_files:
+        - README.md
+        - extend/README.md
+      commands:
+        - cmd: npm run check
+          status: pass
+      commits:
+        - 17c65c9
+      spawned_tasks:
+        - T005
+  - id: T005
+    type: worker
+    assignee: Worker
+    status: done
+    reasoning_hint: medium
+    objective: "Move package-only CLI/tests out of the installable skill folder and add repo-specific agent guidance."
+    allowed_files:
+      - AGENTS.md
+      - CONTRIBUTING.md
+      - README.md
+      - extend/README.md
+      - goal-maker/SKILL.md
+      - goal-maker/bin/goal-maker.mjs
+      - goal-maker/test/check-goal-state.test.mjs
+      - goal-maker/test/goal-maker-cli.test.mjs
+      - internal/cli/goal-maker.mjs
+      - internal/test/check-goal-state.test.mjs
+      - internal/test/goal-maker-cli.test.mjs
+      - package.json
+    verify:
+      - npm run check
+      - git diff --check
+      - tmp=$(mktemp -d); node internal/cli/goal-maker.mjs install --codex-home "$tmp"; node internal/cli/goal-maker.mjs doctor --codex-home "$tmp"; rm -rf "$tmp"
+      - npm publish --dry-run --json
+    stop_if:
+      - "Need to move skill runtime scripts out of `goal-maker/scripts/`."
+      - "Need root folders beyond `internal/`."
+      - "Verification fails twice."
+    receipt:
+      result: done
+      changed_files:
+        - AGENTS.md
+        - CONTRIBUTING.md
+        - README.md
+        - extend/README.md
+        - goal-maker/SKILL.md
+        - internal/cli/goal-maker.mjs
+        - internal/test/check-goal-state.test.mjs
+        - internal/test/goal-maker-cli.test.mjs
+        - package.json
+      commands:
+        - cmd: npm run check
+          status: pass
+        - cmd: git diff --check
+          status: pass
+        - cmd: tmp=$(mktemp -d); node internal/cli/goal-maker.mjs install --codex-home "$tmp"; node internal/cli/goal-maker.mjs doctor --codex-home "$tmp"; rm -rf "$tmp"
+          status: pass
+        - cmd: npm publish --dry-run --json
+          status: pass
+      summary: "Moved package-only CLI/tests under `internal/`, removed `goal-maker/bin` and `goal-maker/test` from the skill payload, added root `AGENTS.md`, and updated docs/package paths."
+      note: notes/T005-layout-cleanup.md
+      commits:
+        - 6faa5de
+      spawned_tasks:
+        - T006
+  - id: T006
+    type: worker
+    assignee: Worker
+    status: done
+    reasoning_hint: low
+    objective: "Move the hosted catalog into `extend/` and update the CLI/default docs to match."
+    allowed_files:
+      - AGENTS.md
+      - README.md
+      - extend/README.md
+      - catalog.json
+      - extend/catalog.json
+      - internal/cli/goal-maker.mjs
+      - package.json
+      - examples/extend-catalog-workflow
+    verify:
+      - npm run check
+      - git diff --check
+      - node internal/cli/goal-maker.mjs extend --catalog-url extend/catalog.json --json
+      - npm publish --dry-run --json
+    stop_if:
+      - "Need to add bundled extensions."
+      - "Need a separate extension registry."
+      - "Verification fails twice."
+    receipt:
+      result: done
+      changed_files:
+        - AGENTS.md
+        - README.md
+        - extend/README.md
+        - extend/catalog.json
+        - internal/cli/goal-maker.mjs
+        - package.json
+        - examples/extend-catalog-workflow/goal.md
+        - examples/extend-catalog-workflow/state.yaml
+        - examples/extend-catalog-workflow/notes/T006-catalog-location.md
+      commands:
+        - cmd: npm run check
+          status: pass
+        - cmd: git diff --check
+          status: pass
+        - cmd: node internal/cli/goal-maker.mjs extend --catalog-url extend/catalog.json --json
+          status: pass
+        - cmd: npm publish --dry-run --json
+          status: pass
+      summary: "Moved the GitHub-hosted catalog into `extend/catalog.json`, updated the CLI default raw URL, and adjusted docs/example references."
+      note: notes/T006-catalog-location.md
+      commits:
+        - "this example/catalog-location commit"
+      spawned_tasks:
+        - T999
+  - id: T999
+    type: judge
+    assignee: Judge
+    status: done
+    reasoning_hint: high
+    objective: "Audit whether the extension catalog and layout cleanup tranche is complete."
+    inputs:
+      - "All done task receipts"
+      - "Last verification"
+      - "Current package dry run"
+    constraints:
+      - "Do not implement."
+      - "Completion requires evidence from actual commits and verification commands."
+    expected_output:
+      - "complete | not_complete"
+      - "missing evidence"
+      - "next task if not complete"
+    receipt:
+      result: done
+      decision: complete
+      note: notes/T999-completion-audit.md
+      summary: "The tranche is complete: extension vocabulary, GitHub-hosted catalog, `extend` CLI workflow, root extension surface, package layout cleanup, and repo agent guidance are implemented and verified."
+      evidence:
+        - examples/extend-catalog-workflow/goal.md
+        - examples/extend-catalog-workflow/notes/T001-extension-model-map.md
+        - examples/extend-catalog-workflow/notes/T002-architecture-decision.md
+        - examples/extend-catalog-workflow/notes/T003-implementation-summary.md
+        - examples/extend-catalog-workflow/notes/T004-root-extend-folder.md
+        - examples/extend-catalog-workflow/notes/T005-layout-cleanup.md
+        - examples/extend-catalog-workflow/notes/T006-catalog-location.md
+        - AGENTS.md
+        - extend/catalog.json
+        - extend/README.md
+        - internal/cli/goal-maker.mjs
+        - package.json
+      verification:
+        - cmd: npm run check
+          status: pass
+        - cmd: git diff --check
+          status: pass
+        - cmd: npm publish --dry-run --json
+          status: pass
+        - cmd: node goal-maker/scripts/check-goal-state.mjs examples/extend-catalog-workflow/state.yaml
+          status: pass
+
+checks:
+  dirty_fingerprint: unknown
+  last_verification:
+    result: pass
+    task: T999
+    commands:
+      - cmd: npm run check
+        status: pass
+      - cmd: git diff --check
+        status: pass
+      - cmd: npm publish --dry-run --json
+        status: pass
+      - cmd: node goal-maker/scripts/check-goal-state.mjs examples/extend-catalog-workflow/state.yaml
+        status: pass

package/examples/github-pr-workflow-extension/pr-handoff.md

@@ -0,0 +1,46 @@
+# PR Handoff: Add GitHub PR Workflow Extension
+
+## Suggested Title
+
+Add GitHub PR workflow extension
+
+## Summary
+
+- Adds `github-pr-workflow` as a cataloged Goal Maker extension.
+- Documents a local-first workflow for turning goal receipts into GitHub PR handoff text.
+- Keeps `state.yaml` authoritative and treats GitHub PR content as generated review context.
+
+## Goal Context
+
+- Original request: `$goal-maker add a new extension to goal-maker`
+- Target outcome: a discoverable GitHub PR workflow integration extension with catalog metadata, docs, and example proof.
+- Completion proof: catalog entry, extension documentation, example artifact, and local checks.
+
+## Changed Files
+
+- `extend/catalog.json`
+- `extend/README.md`
+- `extend/github-pr-workflow/README.md`
+- `extend/github-pr-workflow/extension.yaml`
+- `examples/github-pr-workflow-extension/pr-handoff.md`
+- `README.md`
+
+## Verification
+
+```bash
+node internal/cli/goal-maker.mjs extend --catalog-url extend/catalog.json --json
+node internal/cli/goal-maker.mjs extend github-pr-workflow --catalog-url extend/catalog.json --json
+node internal/cli/goal-maker.mjs extend install github-pr-workflow --catalog-url extend/catalog.json --dry-run --json
+npm run check
+git diff --check
+```
+
+## Review Notes
+
+- This is a local handoff workflow, not live GitHub automation.
+- No GitHub token is required for discovery, details, or install dry-run.
+- Future live PR creation should be a separate extension or explicitly approved follow-up task.
+
+## Follow-Up
+
+- Consider a later command or template generator only after the cataloged workflow proves useful.

package/examples/improve-goal-maker/goal.md

@@ -0,0 +1,51 @@
+# Improve Goal Maker
+
+## Objective
+
+Improve the local Goal Maker skill by discovering the highest-leverage repo-backed changes, completing the first safe implementation tranche, and leaving a reviewable handoff for anything larger.
+
+## Goal Kind
+
+`open_ended`
+
+## Current Tranche
+
+Map the current Goal Maker implementation, identify concrete improvement candidates with verification paths, select one small and reversible tranche, implement it, verify it, and finish with an audit receipt.
+
+## Non-Negotiable Constraints
+
+- Keep Goal Maker v2 control-file semantics intact: `goal.md`, `state.yaml`, and `notes/` only at each goal root.
+- Do not implement from assumptions; Scout evidence or Judge selection must precede Worker edits.
+- Preserve compatibility with Codex agent roles and the existing checker unless a Judge task explicitly chooses otherwise.
+- Keep changes small, reviewable, and backed by local verification commands.
+- Do not use destructive git operations or require credentials.
+
+## Stop Rule
+
+Stop when the tranche audit passes, all safe local work is blocked, or continuing would require owner input, credentials, destructive operations, or strategy the board cannot decide.
+
+## Canonical Board
+
+Machine truth lives at:
+
+`examples/improve-goal-maker/state.yaml`
+
+If this charter and `state.yaml` disagree, `state.yaml` wins for task status, active task, receipts, verification freshness, and completion truth.
+
+## Run Command
+
+```text
+/goal Follow examples/improve-goal-maker/goal.md
+```
+
+## PM Loop
+
+On every `/goal` continuation:
+
+1. Read this charter.
+2. Read `state.yaml`.
+3. Work only on the active board task.
+4. Assign Scout, Judge, Worker, or PM according to the task.
+5. Write a compact task receipt.
+6. Update the board.
+7. Select the next active task or finish with a Judge/PM audit receipt.

package/examples/improve-goal-maker/notes/T001-repo-map.md

@@ -0,0 +1,59 @@
+# T001: Goal Maker Repo Map
+
+Task: `T001`
+Kind: `scout`
+Status: `current`
+
+## Summary
+
+Goal Maker is a small dependency-free npm package that installs a Codex skill, three agent role definitions, templates, and a v2 board checker. The core verification path is healthy: syntax checks and all current checker tests pass, a temporary install plus doctor run succeeds, and the package dry run includes the expected runtime files. The highest-leverage next investigation is not packaging correctness; it is workflow reliability around checker blind spots, agent-installation assumptions, and template/skill contract drift.
+
+## Repo Map
+
+- `README.md` describes the package purpose, install commands, board model, repository layout, and status caveats.
+- `CONTRIBUTING.md` defines the local verification contract: `npm run check`, temporary install/doctor, and `npm pack --dry-run`.
+- `package.json` exposes the `goal-maker` bin, keeps runtime dependency-free, packages the skill runtime plus docs/assets, and defines `check`, `test`, and `pack:dry-run`.
+- `goal-maker/SKILL.md` is the installed skill contract: direct `$goal-maker` creates or repairs a v2 board, stops for user choice, and `/goal` owns the PM loop.
+- `goal-maker/bin/goal-maker.mjs` installs the skill and bundled `goal_*.toml` agents into a Codex home and supports `install`, `update`, `agents`, `doctor`, and help.
+- `goal-maker/scripts/check-goal-state.mjs` validates v2 board shape with a lightweight line-oriented parser.
+- `goal-maker/scripts/install-agents.mjs` is a secondary agent copy helper.
+- `goal-maker/templates/goal.md`, `state.yaml`, and `note.md` seed new goal control files.
+- `goal-maker/agents/goal_scout.toml`, `goal_worker.toml`, and `goal_judge.toml` define the intended role constraints.
+- `goal-maker/test/check-goal-state.test.mjs` covers key checker invariants.
+
+## Verification Commands
+
+- `npm run check` passed: Node syntax checks and 7 node:test cases passed.
+- Temporary install plus doctor passed: `skill_installed: true`; installed agents were `goal_judge.toml`, `goal_scout.toml`, and `goal_worker.toml`.
+- `npm pack --dry-run` passed and listed the expected package files, including `README.md`, `CONTRIBUTING.md`, `internal/assets/`, `package.json`, and `goal-maker/` runtime files.
+- `node goal-maker/scripts/check-goal-state.mjs examples/improve-goal-maker/state.yaml` passed with `ok: true`.
+
+## Health Signals
+
+- Current tests cover a valid Scout board, active Worker requirements, legacy v1 rejection, one-active-task enforcement, done-task receipt requirements, unexpected root entries, and final audit completion.
+- The checker intentionally avoids dependencies, but it parses YAML with regular expressions and line indentation. This is acceptable for the template subset but creates likely blind spots for richer valid YAML or misleading strings inside quoted values.
+- The package has two agent-installation paths: the CLI in `goal-maker/bin/goal-maker.mjs` and the helper in `goal-maker/scripts/install-agents.mjs`. They are similar but not identical.
+- The direct skill contract says `$goal-maker` must verify Scout, Worker, and Judge agents are installed or explain what is missing; current templates mark them `installed`, while actual verification is behavior implemented by the PM thread, not the CLI/checker.
+
+## Ranked Improvement Candidates
+
+1. Add checker tests and fixes for root-path robustness and YAML parsing edge cases, especially misleading legacy markers inside quoted values or comments.
+2. Reconcile or document the two agent-installation paths so CLI behavior, helper behavior, and README guidance cannot drift.
+3. Make agent installation status less assumption-driven in generated boards or add checker warnings when agent status values are placeholders.
+4. Add tests for the CLI install/doctor/package path so the contributor verification contract is covered by `npm run check`, not just manual commands.
+5. Tighten docs/templates around what `/goal` PM may do in Codex environments where actual subagent dispatch is unavailable and roles are simulated in-thread.
+
+## Candidate Next Tasks
+
+- Investigate checker blind spots with focused failing test candidates before choosing a fix.
+- Compare `goal-maker/bin/goal-maker.mjs` and `goal-maker/scripts/install-agents.mjs` and decide whether to consolidate, test, or document the helper.
+- Judge the first implementation tranche after the risk map, preferring a small test-backed checker or CLI reliability fix.
+
+## Board Receipt Snippet
+
+```yaml
+receipt:
+  result: done
+  note: notes/T001-repo-map.md
+  summary: "Repo map completed; verification is green, install/package checks work, and the top improvement area is Goal Maker workflow reliability around checker blind spots, agent installation assumptions, and template/skill drift."
+```

package/examples/improve-goal-maker/notes/T002-risk-map.md

@@ -0,0 +1,37 @@
+# T002: Workflow Risk Map
+
+Task: `T002`
+Kind: `scout`
+Status: `current`
+
+## Summary
+
+The highest-confidence risks are small and testable. First, `goal-maker doctor` reports success when one of the required bundled agents is missing, which weakens the "verify Scout, Worker, and Judge agents" contract. Second, the board checker accepts mismatched task `type` and `assignee` values, even though Goal Maker semantics depend on those fields agreeing. A lower-priority drift risk is that `update` does not overwrite stale existing agent definitions unless `--force` is supplied, despite README wording that says install or update the skill and bundled agents.
+
+## Evidence
+
+- `goal-maker/bin/goal-maker.mjs` `doctor()` exits based only on whether `skills/goal-maker/SKILL.md` exists. In a temp Codex home with `goal_worker.toml` removed, `doctor` exited 0 and reported only `goal_judge.toml` and `goal_scout.toml`.
+- `goal-maker/scripts/check-goal-state.mjs` independently validates `task.type` and `task.assignee`, but does not validate pairs. A temp board with `type: scout` and `assignee: Worker` passed with `ok: true`.
+- `goal-maker/scripts/check-goal-state.mjs` does not require or validate the `agents:` section. A temp board with the section omitted passed with `ok: true`.
+- `goal-maker/bin/goal-maker.mjs` `installAgents()` skips existing `goal_*.toml` files unless `--force` is present. In a temp Codex home with a stale `goal_scout.toml`, `goal-maker update` left the stale file unchanged.
+- `goal-maker/scripts/install-agents.mjs` copies any `.toml` except names containing `config-snippet`, while the CLI copies only `goal_*.toml`. Current files make this harmless, but it is a drift point.
+
+## Small Safe Implementation Candidates
+
+1. Add CLI tests for `doctor` and make `doctor` fail when any required agent file is missing. Allowed files would likely be `goal-maker/bin/goal-maker.mjs` and a new focused CLI test file.
+2. Add checker tests for task type/assignee mismatch and fix the checker to reject mismatches. Allowed files would be `goal-maker/scripts/check-goal-state.mjs` and `goal-maker/test/check-goal-state.test.mjs`.
+3. Add checker tests for missing or invalid `agents:` statuses and reject or warn. This is slightly more policy-heavy because templates currently treat agent status as PM-populated board metadata.
+4. Decide whether `update` should overwrite existing bundled agents or whether README/CLI wording should clarify that `--force` is required for agent refresh.
+
+## Recommended First Tranche
+
+Prefer the `doctor` missing-agent fix. It directly supports the `$goal-maker` requirement to verify Scout, Worker, and Judge availability, has tight behavior, and can be verified with a new CLI test plus existing checks. The checker mismatch fix is also small, but it is less directly connected to the user-visible setup flow.
+
+## Board Receipt Snippet
+
+```yaml
+receipt:
+  result: done
+  note: notes/T002-risk-map.md
+  summary: "Risk map completed; doctor exits green with missing agents, checker accepts type/assignee mismatches, and update leaves stale agents unless forced."
+```