diff --git a/.github/workflows/plugin-v2-quality.yml b/.github/workflows/plugin-v2-quality.yml new file mode 100644 index 000000000..38211f2d9 --- /dev/null +++ b/.github/workflows/plugin-v2-quality.yml @@ -0,0 +1,33 @@ +name: plugin-v2 quality + +on: + pull_request: + paths: + - 'plugin-v2/**' + - '.github/workflows/plugin-v2-quality.yml' + push: + branches: + - main + paths: + - 'plugin-v2/**' + - '.github/workflows/plugin-v2-quality.yml' + +permissions: + contents: read + +concurrency: + group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }} + cancel-in-progress: true + +jobs: + plugin-v2-checks: + name: plugin-v2 verify + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 + with: + persist-credentials: false + + - name: Run plugin-v2 check-all.sh + run: bash plugin-v2/scripts/check-all.sh diff --git a/_typos.toml b/_typos.toml index 042937c45..f35488e4b 100644 --- a/_typos.toml +++ b/_typos.toml @@ -28,6 +28,10 @@ AGS = "AGS" # agentic security checklist item prefix # Tool / library names wrk = "wrk" # HTTP load-testing tool +HAX = "HAX" # Microsoft Human-AI Experience Toolkit (proper noun) + +# Researcher surnames cited in docs (real authors of cited works) +Collisson = "Collisson" # Penny Collisson, co-author of Microsoft Guidelines for Human-AI Interaction # Intentional non-words used in prose mis = "mis" # used in compound forms ("mis-typed") diff --git a/plugin-v2/.claude-plugin/plugin.json b/plugin-v2/.claude-plugin/plugin.json new file mode 100644 index 000000000..0100a8613 --- /dev/null +++ b/plugin-v2/.claude-plugin/plugin.json @@ -0,0 +1,67 @@ +{ + "name": "goal-loop", + "version": "2.2.0", + "description": "A goal-bounded OODA loop for any decision or delivery cycle. Unifies goal-oriented orchestration with Observe→Orient→Decide→Act for domain-agnostic, parallel-capable, human-gated execution.", + "author": { + "name": "Luis Mendez" + }, + "homepage": "https://github.com/Luis85/agentic-workflow", + "bugs": { + "url": "https://github.com/Luis85/agentic-workflow/issues", + "security": "https://github.com/Luis85/agentic-workflow/security/advisories" + }, + "license": "MIT", + "keywords": [ + "agentic-workflow", + "ooda-loop", + "goal-oriented", + "orchestration", + "claude-plugin", + "decision-support", + "situational-awareness" + ], + "capabilities": { + "agents": [ + "agents/goal-orchestrator.md", + "agents/observer.md", + "agents/orienter.md", + "agents/decider.md", + "agents/actor.md", + "agents/loop-reviewer.md", + "agents/goal-critic.md", + "agents/signal-deduper.md", + "agents/risk-scout.md" + ], + "skills": [ + "skills/goal-loop", + "skills/set-goal", + "skills/observe", + "skills/orient", + "skills/decide", + "skills/act", + "skills/review-loop", + "skills/acceptance-criteria-helper", + "skills/trace-loop", + "skills/list-goals", + "skills/welcome", + "skills/create-goal", + "skills/activate-goal", + "skills/export-trace" + ], + "commands": [ + "commands/goal", + "commands/create-goal.md", + "commands/set-goal.md" + ] + }, + "entrypoints": { + "primary_skill": "goal-loop", + "primary_command": "/goal:start", + "method_doc": "docs/method.md", + "readme": "README.md" + }, + "compatibility": { + "claude_code": ">=1.0.0", + "adapters": ["codex", "cursor"] + } +} diff --git a/plugin-v2/.codex/README.md b/plugin-v2/.codex/README.md new file mode 100644 index 000000000..aa5853cb8 --- /dev/null +++ b/plugin-v2/.codex/README.md @@ -0,0 +1,25 @@ +--- +title: "Codex" +folder: "plugin-v2/.codex" +description: "Entry point for Codex-specific delivery mechanics layered on the shared goal-loop plugin rules." +entry_point: true +--- +# Codex + +Codex-specific operating context for the `goal-loop` plugin. [`AGENTS.md`](../AGENTS.md) at the plugin root remains the shared source of truth for every AI coding agent; this folder holds the extra delivery mechanics that help Codex drive a Goal Loop cleanly. + +Read in this order for non-trivial work: + +1. [`AGENTS.md`](../AGENTS.md) — plugin-wide rules, agent roster, operating conventions. +2. [`../memory/constitution.md`](../memory/constitution.md) — governing principles. +3. [`../docs/method.md`](../docs/method.md) — the canonical Goal Loop definition. +4. [`instructions.md`](instructions.md) — Codex-specific defaults. +5. The workflow playbook that matches the task: + - [`workflows/goal-iteration.md`](workflows/goal-iteration.md) — one end-to-end iteration of the loop. + - [`workflows/daily-brief.md`](workflows/daily-brief.md) — producing the daily brief for a recurring goal. + +This folder is the Codex adapter layer. It extends but does not override `AGENTS.md` or `docs/method.md`. See [`../docs/tool-adapters.md`](../docs/tool-adapters.md) for the full adapter rationale. + +> When a Codex operation has no matching file under `.codex/workflows/`, open the corresponding `skills//SKILL.md` and follow its step-by-step block directly. The Claude-Code-specific dispatch language (`AskUserQuestion`, `Task`) maps to "ask the human" and "delegate to a sub-agent" respectively. + +This folder is part of the plugin. Local Codex cache, secrets, or session state should not be committed here. diff --git a/plugin-v2/.codex/instructions.md b/plugin-v2/.codex/instructions.md new file mode 100644 index 000000000..452315fce --- /dev/null +++ b/plugin-v2/.codex/instructions.md @@ -0,0 +1,67 @@ +# Codex instructions + +These instructions adapt the shared plugin rules in [`AGENTS.md`](../AGENTS.md) to Codex's operating style. Substantive method rules are not duplicated here — they live in `AGENTS.md` and [`docs/method.md`](../docs/method.md). + +## How Codex enacts plugin "skills" + +The plugin's skill set lives at `skills//SKILL.md`. Each skill is written for a Claude Code dispatcher, but Codex has no dispatcher. Two substitutes: + +1. **Workflows under `.codex/workflows/`** are the Codex-shaped versions of the most-used skills. Run a workflow by opening the file and following its steps verbatim. The workflow names the subagent it consults — Codex roleplays that subagent or sub-dispatches to a downstream agent. + +2. **For skills without a Codex workflow**, open the `SKILL.md` file directly. Treat the `## What you do, step by step` block as the script. The `## Boundaries` section is the guardrail you must not violate. + +When a workflow conflicts with the underlying `SKILL.md` (it should not — workflows are derived from skills), the `SKILL.md` is authoritative. + +## Default posture + +- Act as a conductor of the Goal Loop, not a generalist coder. One goal slug at a time. +- Stay in the current phase. Do not run the next phase agent's work to "get ahead" — phase isolation is enforced by the constitution. +- Persist state explicitly. Every iteration's artifacts land under `goals//` exactly where the templates say. +- Keep one branch (or one working session) to one goal slug. Switching goals means switching context cleanly. +- Prefer to drive the full iteration when invited, gating at the goal step and the act step. + +## Context loading + +Before changing files, read: + +1. [`AGENTS.md`](../AGENTS.md) — plugin-wide rules. +2. [`../memory/constitution.md`](../memory/constitution.md) — governing principles. +3. [`../docs/method.md`](../docs/method.md) — the loop's canonical definition. +4. The relevant pattern doc under [`../docs/usage-patterns.md`](../docs/usage-patterns.md). +5. The active goal's `goals//goal-state.md`. +6. The relevant Codex workflow under [`workflows/`](workflows/). + +Load scoped customisation guidance from [`../docs/customizing.md`](../docs/customizing.md) only when the task requires extending the plugin. + +## Workflow conventions + +- **Gate at the goal.** No iteration runs until `goal-state.md` is complete and the human has signed off. Missing intent, constraints, acceptance criteria, mode, observe sources, or act-gate policy is a blocker — route back to the `set-goal` skill. +- **Gate at the act step.** Before any irreversible action runs, the human must approve the decision set. Pre-authorised reversible runbook items may auto-approve only when the goal's `act_gate` policy explicitly allows it. +- **One writer per artifact.** Only the conductor writes `goal-state.md`. Each phase agent writes only its own files. If an upstream artifact has a defect, surface it; do not silently fix it. +- **Cite signals.** Every claim in `orientation.md` references an observation by file and signal index. Every rationale in `decisions.md` traces to a line in orientation. +- **Log everything.** Skipped, deferred, and rejected items are recorded with rationale. Done-without-evidence is incomplete. +- **Domain-neutral language.** Examples may be software-shaped, but core artifacts use plain outcome language. Resist commit/branch/test metaphors when the goal is not about code. + +## GitHub access + +When the goal involves a GitHub repository and access is available, Codex may use the host's GitHub surface (issues, PRs, search). Treat any GitHub mutation (open/close/comment, merge, label, release) as an Act-phase step that the goal's act-gate policy must cover. Read-only GitHub access is part of the observer's tool surface. + +After producing or updating any artifact, report: + +- Goal slug. +- Current phase + iteration. +- Artifact path just written. +- Pending gates (goal gate, act gate for decision-set id N). +- Next recommended step + the slash command or skill the human would invoke. + +## Safety rails + +Ask before: + +- Running any action whose `reversible` flag is `false`. +- Running any action that falls outside the goal's `act_gate` auto-approval scope. +- Performing destructive filesystem changes (delete, force-overwrite, history rewrites). +- Posting publicly visible content, moving money, sending external communications, or making any irreversible change to a shared system. +- Amending `goal-state.md`'s acceptance criteria, constraints, or observe sources — those are goal-level fields under the goal gate. + +Do not ask before normal reads, normal local writes to your assigned phase artifact, or invoking the next phase agent when the orchestrator's procedure says it is time. diff --git a/plugin-v2/.codex/workflows/daily-brief.md b/plugin-v2/.codex/workflows/daily-brief.md new file mode 100644 index 000000000..de8b80032 --- /dev/null +++ b/plugin-v2/.codex/workflows/daily-brief.md @@ -0,0 +1,75 @@ +# Workflow — Daily brief + +A Codex playbook for producing the daily brief for a recurring Goal Loop. For the canonical method see [`../../docs/method.md`](../../docs/method.md); for the pattern see [`../../docs/usage-patterns.md`](../../docs/usage-patterns.md#2-daily-brief-recurring-awareness); for the worked example see [`../../docs/examples/daily-brief.md`](../../docs/examples/daily-brief.md). + +## When to use + +- An active goal exists at `goals//` with `mode: recurring` and `cadence: daily` (or the human triggers the brief on demand). +- The goal gate is signed. +- It is the right time to produce today's brief, or the human asked for it explicitly. + +## When not to use + +- The goal is `one-shot` — that pattern does not produce a brief. +- The goal's status is `paused`, `cancelled`, or `done`. + +## Procedure + +### 1. Confirm the goal slug and the brief window + +- Read `goal-state.md`. Confirm `mode: recurring`, `cadence: daily` (or compatible), and that `brief.md` is the expected output. +- Determine the brief window: the period the observers should treat as "since last time". For daily briefs, this is normally "since the prior brief's timestamp" — fall back to "last 24 hours" if no prior brief exists. + +### 2. Observe (parallel where independent) + +- For each entry in `observe_sources`, spawn an observer scoped to that source. Observers run **only against declared sources** — never against an undeclared file (the `observe` skill's Boundaries forbid it; see [`../../skills/observe/SKILL.md`](../../skills/observe/SKILL.md) §Boundaries). +- Each observer writes `goals//observations/--.md`. Raw signals only. +- **Roll-forward handling without violating Observe boundaries.** The prior `brief.md` is NOT itself an observe source. If you want carry-over to surface in this iteration, either (a) declare `brief-archive` as an `observe_sources` entry (`type: archive`, `target: goals//archive/`) in `goal-state.md` via `/goal:amend ` so the observer can legitimately scan prior briefs, or (b) let the **orienter** read the prior `brief.md` directly in Step 3 (orient is allowed to read any artifact under `goals//` per its contract; it just must not call out into other observe sources itself). The default daily-brief example uses option (b) — the orienter reads `archive/brief/.md` to compute the "what carried over" delta, no Observe boundary violated. + +### 3. Orient + +- One orienter reads every observation in the window and the prior `orientation.md`. +- Writes the refreshed `goals//orientation.md`. Every claim cites an observation. +- Summary highlights what is new since the prior brief, what is blocked, what is at risk. + +### 4. Decide + +- One decider proposes the recommended-today set. Honour any constraint the goal imposes on set size (e.g. "no more than three recommended-today items"). +- For each proposal, mark the gate. Most daily-brief proposals are `gate: human` because the brief is advisory. +- Append the decision-set block to `goals//decisions.md`. + +### 5. Render the brief + +- Read [`../../templates/brief-template.md`](../../templates/brief-template.md). Produce `goals//brief.md`: + - **TL;DR** — three bullets max, the changes that matter and the calls to action. + - **What's New** — material changes since the prior brief, with observation refs. + - **Recommended Today** — copy the approved decision set's actions in priority order. + - **Watching** — open risks, partials, and items rolled forward (the orienter reconstructs this from the prior `archive/brief/.md`). + - **Optional Actions** — proposals weighed but not promoted, surfaced so the human can pull them in. +- Archive a dated copy at `goals//archive/brief/.md`. The current `brief.md` is overwritten on each cadence run; the archive preserves history (matches the Periodic Notes-compatible date-only filename per [`../../docs/cadence-recipes.md`](../../docs/cadence-recipes.md)). + +### 6. Act phase — typically skipped for daily briefs + +Daily briefs are advisory: the *human* acts, the loop does not. But `review-loop` preflight ([`../../skills/review-loop/SKILL.md`](../../skills/review-loop/SKILL.md) §Step 1) requires either (a) at least one action log under `goals//actions/iter-/` for the current iteration, or (b) an explicit `act: skipped` `## History` row recording the skip reason. Skipping Act without the history record leaves Review dead-ended. + +- **If every decision-set proposal carries `gate: human`** (the typical daily-brief shape), the `decide` skill's act gate resolves to "Reject all" or "Defer to next iteration", and `decide` then dispatches `goal-orchestrator` to set `current_phase: review` and append an `act: skipped — recommended for human action` row to `## History`. Review then runs cleanly with no action artifacts expected. +- **If `act_gate: never`** is set on the goal (decisions are surfaced but not executed), the same `act: skipped — policy forbids` row is recorded. +- **Never** jump straight from brief rendering to Review without one of these two paths — the orchestrator's `## History` row is what makes the skip auditable. + +### 7. Review + +- One loop-reviewer writes `goals//reviews/.md`. +- Verify the brief's acceptance criteria are met (e.g. ≤ N recommended-today items, freshness, rollover discipline). +- Outcome is normally `continue` for recurring goals; emit `close-met` only when the goal's stop condition (recorded in `goal-state.md`) has triggered. + +## Reporting + +- The path of today's `brief.md` and its archived dated copy. +- The decision-set id from `decisions.md`. +- Any items that rolled forward unactioned for more than the threshold the goal declares (if any) — surface as a watch signal. + +## Safety rails + +- The brief proposes; the human acts. Do not perform any `gate: human` proposal during the daily-brief workflow unless the goal's `act_gate` policy explicitly authorises it. +- Never silently drop a rolled-forward item. If it is no longer relevant, the brief must say so and explain why. +- Never edit the archive. The audit trail of past briefs is immutable. diff --git a/plugin-v2/.codex/workflows/goal-iteration.md b/plugin-v2/.codex/workflows/goal-iteration.md new file mode 100644 index 000000000..4738a3419 --- /dev/null +++ b/plugin-v2/.codex/workflows/goal-iteration.md @@ -0,0 +1,91 @@ +# Workflow — One Goal Loop iteration + +A Codex playbook for running one full iteration of the Goal Loop end-to-end against an active goal slug. For the canonical method, see [`../../docs/method.md`](../../docs/method.md). Substantive rules are in [`../../AGENTS.md`](../../AGENTS.md); do not redefine them here. + +## When to use + +- An active goal exists at `goals//` with a signed `goal-state.md`. +- The previous iteration (if any) closed with `outcome: continue`. +- The human has invited Codex to drive an iteration end-to-end. + +## When not to use + +- No goal yet — run `/goal:start ` (bootstrap mode) first. +- Goal is paused, cancelled, or already `status: done`. +- Active iteration is mid-flight in another session — finish that one first. + +## Preconditions + +Confirm before starting: + +1. `goals//goal-state.md` exists and is signed (goal gate cleared). +2. The goal's current phase pointer is one of: `scope` (new goal, first iteration) or `observe` (resuming a fresh iteration). **Do not start an iteration when `current_phase` is `review`.** A `review` pointer means the previous iteration has not yet been closed by `loop-reviewer` — the orchestrator must record the outcome (`continue` / `close-met` / `close-abandon` / `amend`) and transition `current_phase` to `observe` **before** this workflow may begin. The iteration counter is **not** bumped at that pre-step — Observe (Step 1 below) owns the increment per [`../../skills/_shared/goal-state.md`](../../skills/_shared/goal-state.md). Per [`../../memory/constitution.md`](../../memory/constitution.md) Article VI §1, "the next iteration begins only after the current `review.md` records `outcome: continue | amend`" — a `review`-state admission would bypass that gate and desynchronise `## History` accounting. If `current_phase: review` is encountered, route the human to `/goal:review ` first; do not advance Observe through it. **Never** start an iteration on a goal whose `current_phase` is `closed` — that is the terminal phase for `close-met` / `close-abandon` goals; re-engagement requires `/goal:amend ` (constitution-amendment workflow) or `/goal:start ` for a fresh goal. +3. The slug is unambiguous. Never invent one. + +## Procedure + +### 1. Observe + +- Read `goal-state.md` and list `observe_sources`. +- For each source, spawn one observer (sequential is fine; parallel is better when sources are independent). +- Each observer writes `goals//observations/[--].md` shaped per [`../../templates/observation-template.md`](../../templates/observation-template.md). Raw signals only. +- **After all observers return** (fan-in), the orchestrator appends **one** `## History` row for the Observe phase transition. The `artifact` column is one resolvable relative path: the single observer's file when one ran, the deduper-authored merged view `observations/--_merged.md` when N observers ran with `signal-deduper`, or a thin index `observations/--_index.md` when N observers ran without dedup (the orchestrator writes the index; its body links every per-source file). One row per phase transition + one resolvable path per row is the contract per [`../../skills/_shared/goal-state.md`](../../skills/_shared/goal-state.md) §"`## History`". + +### 2. Orient + +- Spawn one orienter. +- Reads every observation file from this iteration and the prior `orientation.md` (if any). +- Writes the refreshed `goals//orientation.md` shaped per [`../../templates/orientation-template.md`](../../templates/orientation-template.md). Every claim cites an observation. +- Update `goal-state.md` to mark Orient complete. + +### 3. Decide + +- Spawn one decider. +- Reads `orientation.md`, `goal-state.md`, prior `decisions.md` blocks, prior `actions/iter-*/*` (cross-iteration glob), prior `reviews/*`. +- Appends a new decision-set block to `goals//decisions.md` shaped per [`../../templates/decision-template.md`](../../templates/decision-template.md). +- Reports the decision-set id and the gate breakdown to the human. + +### 4. Act gate + +- Stop. Surface the decision set to the human. +- For each proposal: confirm gate (`auto` or `human`). Auto-approved items may proceed; human items wait. +- Record the approval in the `## Human Approval` section of the decision set in `decisions.md` (approver, ISO-8601 timestamp, approved-id list, exclusions). The orchestrator then appends a `## History` row in `goal-state.md` referencing the approved decision-set id. Without the Human Approval entry, no actor runs. + +### 5. Act + +- For each approved proposal, spawn one actor (parallel where actions are independent). +- Each actor copies its approved action verbatim from the decision set, executes the smallest steps that complete it, logs each step with timestamp and result. +- Each actor writes `goals//actions/iter-/.md` shaped per [`../../templates/action-log-template.md`](../../templates/action-log-template.md). Status is one of the canonical action-log enum values: `done | partial | stopped | blocked | failed` (with `failed` reserved for actions that executed but did not achieve their effect — distinct from `stopped`, which signals a boundary the actor refused to cross, and `blocked`, which signals an upstream dependency or approval gap). +- The actor stops at the boundary if execution reveals the approved scope is insufficient. Never expand scope. + +### 6. Review + +- Spawn one loop-reviewer. +- Reads `goal-state.md`, the current orientation, the decision set, every action log for this iteration. +- Writes `goals//reviews/.md` shaped per [`../../templates/review-template.md`](../../templates/review-template.md). +- Outcome is one of `continue | close-met | close-abandon | amend`. + +### 7. Apply the verdict + +The orchestrator applies the review's `outcome` to `goal-state.md`. The iteration counter is owned by Observe (per [`../../skills/_shared/goal-state.md`](../../skills/_shared/goal-state.md): `iteration` increments only at each new Observe dispatch). Goal-body amendments are owned by `set-goal` (per the two-writer ownership matrix in the same schema: `set-goal` writes Intent / Constraints / Acceptance Criteria / Mode & Cadence / Observe Sources / Act Gate Policy; `goal-orchestrator` writes frontmatter + `## History` only). The orchestrator never edits goal-body fields directly. + +- `continue` — set `current_phase: observe`, append `## History` row citing the review path. **Do not bump `iteration` here** — the next Observe dispatch increments per the canonical rule. +- `close-met` — set `status: done`, `current_phase: closed`, record the review path in `## History`, archive working files. +- `close-abandon` — set `status: cancelled`, `current_phase: closed`, record rationale in `## History`, archive. +- `amend` — block on human approval; once approved, route the body-section edits through the [`set-goal`](../../skills/set-goal/SKILL.md) skill in **amend mode** (which re-runs the clarity gate on any new acceptance criterion and re-presents the updated goal for the Goal gate). The orchestrator's own edits are limited to frontmatter (`current_phase: scope` to re-bracket the gate, `updated_at`, `last_review`, and on the revive branch `status: done | cancelled → active`) and one `## History` row recording `outcome: amend` with the amendment record artifact. **`iteration` is NOT bumped at amend time** — Observe owns the increment. Resume Observe via `/goal:run ` or the next-iteration command after `set-goal` clears the Goal gate. + +## Reporting + +After the iteration, report: + +- Goal slug + iteration number + outcome. +- Artifact paths written this iteration. +- Pending gates (none, or which decision-set id awaits a human). +- Next recommended step. + +## Safety rails + +- Never advance to Act without a filled `## Human Approval` section in the decision set covering the action's id. +- Never run an irreversible action whose `reversible: N` proposal was not in the human-approved subset. +- Never edit another agent's artifact. Surface defects; do not patch them silently. +- Never abandon a loop without writing `outcome: close-abandon` and the rationale. diff --git a/plugin-v2/.cursor/rules/goal-loop.mdc b/plugin-v2/.cursor/rules/goal-loop.mdc new file mode 100644 index 000000000..d70052352 --- /dev/null +++ b/plugin-v2/.cursor/rules/goal-loop.mdc @@ -0,0 +1,40 @@ +--- +description: Goal Loop plugin conventions and method rules for Cursor and editor-agents +alwaysApply: true +--- + +# Goal Loop — project context + +This project uses the **`goal-loop`** plugin: a goal-bounded OODA loop for any decision or delivery cycle. Domain-agnostic; human-gated; parallel-capable. + +## Source of truth + +[`AGENTS.md`](../../AGENTS.md) at the plugin root is the single source of truth for plugin conventions, agent roster, and operating rules. [`docs/method.md`](../../docs/method.md) is the canonical definition of the method itself. Read both for any non-trivial change. + +Supporting context (in load order): + +1. `AGENTS.md` — plugin conventions, agent roles, operating rules. +2. `memory/constitution.md` — governing principles. +3. `docs/method.md` — the Goal Loop definition (phases, agents, gates, state model). +4. `docs/usage-patterns.md` — pick the right pattern for the goal. +5. The active goal's `goals//goal-state.md` — current state. + +## Key conventions + +- All work derives from an explicit, human-signed goal in `goals//goal-state.md`. No iteration runs without it. +- Each phase agent writes only its own artifact. Phase isolation is constitutional (Article II). +- The **goal gate** and **act gate** are non-negotiable. Reversible low-risk auto-approval is allowed only when the goal explicitly declares it. +- Domain-neutral language in core artifacts. Software metaphors are illustrative, not required. + +## Adapter note + +This rule is a thin pointer. It does not duplicate `AGENTS.md` or `docs/method.md`. When either changes, this file is automatically up to date because it references them by path. See [`../../docs/tool-adapters.md`](../../docs/tool-adapters.md). + +## How to drive the loop in Cursor + +Cursor has no slash commands. Drive the loop by opening the matching file and following it: + +- **Define a goal:** open [`templates/goal-state-template.md`](../../templates/goal-state-template.md), fill the frontmatter, save as `goals//goal-state.md`. Then apply the rubric in [`agents/goal-critic.md`](../../agents/goal-critic.md) before flipping `goal_signed_off: true` on yourself. +- **Run a phase:** open the matching `skills//SKILL.md` and follow its `## What you do, step by step` block. Write artifacts into `goals//`. +- **Inspect state:** read `goals//goal-state.md` directly. +- **For everything else:** the contract is in [`docs/method.md`](../../docs/method.md). The `.mdc` rule keeps it loaded. diff --git a/plugin-v2/AGENTS.md b/plugin-v2/AGENTS.md new file mode 100644 index 000000000..aaf486d09 --- /dev/null +++ b/plugin-v2/AGENTS.md @@ -0,0 +1,134 @@ +# AGENTS.md + +Cross-tool root context for AI coding agents using the `goal-loop` plugin (Claude Code, Codex, Cursor, Aider, Copilot, Gemini, etc.). Tool-specific files (`CLAUDE.md`, `.codex/`, `.cursor/rules/`) `@import` this file rather than duplicate. + +> **One source of truth, many tools.** Change plugin conventions here. + +## What this plugin is + +The **Goal Loop** plugin is a baseline for goal-bounded OODA loops. It unifies: + +- **Goal-oriented orchestration** — explicit intent, constraints, and falsifiable acceptance criteria (observer-checkable conditions that decide "done"; see [glossary](docs/glossary.md)). +- **OODA loop** (Observe → Orient → Decide → Act) — Boyd's decision cycle, gated by humans at the **goal gate** (the approval of the goal contract before the first iteration) and the **act gate** (the approval before Act executes any decision). One full pass is one **iteration** (Observe → Orient → Decide → Act → Review). + +The loop runs once for bounded problems and continuously for ongoing situations. It is **domain-agnostic** — use it for code, content, research, operations, strategy, or any knowledge work. Each goal lives under `goals//` (slug — a kebab-case short name like `my-goal-slug` that identifies the goal folder) with declared **observe sources** (each a feed, repo, inbox, document, person, command, or other input the observer scans). + +The authoritative method definition is [`docs/method.md`](docs/method.md). Read it first. + +## Read these first + +> **Just installed?** Run [`docs/first-five-minutes.md`](docs/first-five-minutes.md) before this list. 90 seconds, zero input, one full loop on disk. Then come back here for depth. + +1. **`docs/glossary.md`** — 5-minute orientation for domain-neutral readers. The canonical enums (`status`, `current_phase`, action-log `status`, per-criterion `verdict`, loop-closure `outcome`, `reversible`) and the load-bearing terms (`goal gate`, `act gate`, `observe source`, `iteration`, `health`) all live here. The constitution and the method.md both reference enum values introduced in this doc — read it first or you will hit forward-references for the next four docs. +2. **`memory/constitution.md`** — ten governing principles. Override only with explicit human approval and an amendment. +3. **`docs/method.md`** — the full Goal Loop method, vocabulary, and state model. +4. **`docs/domain-model.md`** — the single-read type map. Read this once; use the targeted docs after. Saves you from chasing cross-references across 20 files to assemble the mental model. +5. **`docs/goal-orientation.md`** — what makes a goal worth running and an acceptance criterion falsifiable. Helpful before the first `/goal:start`. +6. **`docs/usage-patterns.md`** — the canonical use-case patterns (issue resolution, daily brief, incident triage, release readiness, continuous awareness). +7. **`docs/session-vs-iteration-goals.md`** — pick-by-scenario comparison of `/create-goal` (session-scoped guardrails) vs. `/goal:start` (iteration-scoped Goal Loop). Read before deciding which surface to use for a given piece of work. +8. **The active goal's `goals//goal-state.md`** — current phase, iteration, and history. + +## Operating rules + +- **Goal first.** No iteration runs without a complete, human-signed goal. `set-goal` is non-skippable. +- **Phase isolation.** Each phase subagent writes only its own artifacts under `goals//`. No cross-writes. +- **Human gates.** The **goal gate** and **act gate** (for irreversible actions) are non-negotiable. Other gates are opt-in per goal. +- **Evidence-based orientation.** Every claim in `orientation.md` cites observations. No speculation, no extrapolation beyond signals. +- **Reversibility bias.** Prefer reversible actions. Every irreversible action requires a rollback plan in its action spec. +- **Escalate, don't invent.** Ambiguity goes to the human. The plugin never silently fills in a missing acceptance criterion, constraint, or source. +- **Acceptance trace.** Every review references each acceptance criterion explicitly with evidence. +- **Domain neutrality.** Resist software-only language. The method serves any domain. +- **Logged trail.** Every decision and action is logged. The trail must reconstruct the reasoning. +- **Closure honesty.** A loop closes only when acceptance is met or the goal is explicitly abandoned. No silent abandonment. + +## Subagent roster + +| Agent | Phase | Scope | Tools | +|---|---|---|---| +| [`goal-orchestrator`](agents/goal-orchestrator.md) | conductor | Routes, gates, persists `goal-state.md`. Never produces phase artifacts. | Read, Grep, Edit, Write, AskUserQuestion | +| [`observer`](agents/observer.md) | Observe | Scans declared sources, records raw signals. Parallel-capable. | Read, Grep, Write, Bash, WebFetch, WebSearch | +| [`orienter`](agents/orienter.md) | Orient | Synthesises observations vs. goal + history. | Read, Edit, Write | +| [`decider`](agents/decider.md) | Decide | Proposes a ranked decision set with rationale and confidence. | Read, Edit, Write | +| [`actor`](agents/actor.md) | Act | Executes the human-approved decision set. May fan out per action. | Read, Edit, Write, Bash | +| [`loop-reviewer`](agents/loop-reviewer.md) | Review | Compares outcomes to acceptance criteria; emits loop verdict. | Read, Edit, Write, Grep | + +Consult-only agents (advise the human or a phase agent at gates; never own phase artifacts): + +| Agent | Consulted by | Scope | Tools | +|---|---|---|---| +| [`goal-critic`](agents/goal-critic.md) | `set-goal` skill (pre-sign-off) | Adversarial review of a drafted `goal-state.md`. | Read, Grep | +| [`signal-deduper`](agents/signal-deduper.md) | `observe` skill (fan-in, N ≥ 2 sources) | Merge cross-source duplicate signals into an attributed view. | Read, Edit, Write, Grep | +| [`risk-scout`](agents/risk-scout.md) | `decide` skill (pre-dispatch) | Surface unstated risks the orientation missed. | Read, Grep | + +## Skill roster + +| Skill | When to use | +|---|---| +| [`goal-loop`](skills/goal-loop/SKILL.md) | Top-level conductor. End-to-end loop drive. | +| [`set-goal`](skills/set-goal/SKILL.md) | Structured intake — define or amend a goal with falsifiable acceptance. | +| [`observe`](skills/observe/SKILL.md) | Run the Observe phase, fan out parallel observers if needed. | +| [`orient`](skills/orient/SKILL.md) | Run the Orient phase. | +| [`decide`](skills/decide/SKILL.md) | Run the Decide phase, gate the user before Act. | +| [`act`](skills/act/SKILL.md) | Run the Act phase against the human-approved decision set. | +| [`review-loop`](skills/review-loop/SKILL.md) | Close the iteration; choose continue / close / amend. | +| [`acceptance-criteria-helper`](skills/acceptance-criteria-helper/SKILL.md) | Walk a user through writing or sharpening a falsifiable acceptance criterion. | +| [`trace-loop`](skills/trace-loop/SKILL.md) | Reconstruct the full reasoning trail for one iteration. Read-only. | +| [`list-goals`](skills/list-goals/SKILL.md) | Portfolio view — scan `goals/`, summarise each `goal-state.md`, emit a recency-sorted table. Read-only. Invoked by `/goal:list`. | +| [`welcome`](skills/welcome/SKILL.md) | First-time guided welcome: tour, hello-world iteration, or docs hand-off. Invoked by `/goal:welcome`. | +| [`create-goal`](skills/create-goal/SKILL.md) | Interactive interview that produces a session-scoped goal at `session-goals/.md`. Distinct from `set-goal` (Goal Loop intake). Invoked by `/create-goal`. | +| [`activate-goal`](skills/activate-goal/SKILL.md) | Activate a session goal in the current tool (native `/goal` in Claude Code, `SESSION-GOAL.md` in Codex, `.cursor/rules/session-goal.mdc` in Cursor). Dispatched by `/set-goal`. | +| [`export-trace`](skills/export-trace/SKILL.md) | Export a Goal Loop iteration as an OpenTelemetry GenAI trace JSON for Langfuse / Datadog / Helicone / Arize / Phoenix ingestion. Read-only. Machine-facing sibling of `trace-loop`. | + +Shared rules every conductor obeys: [`skills/_shared/loop-pattern.md`](skills/_shared/loop-pattern.md). +State file contract: [`skills/_shared/goal-state.md`](skills/_shared/goal-state.md). + +## Slash-command roster + +### Session goals (cross-tool) + +A **session goal** is a session-scoped intent that keeps the assistant aligned on what the user wants the *current sitting* to produce. It is distinct from a Goal Loop iteration goal (below) — no phases, no act gate, no `goals//` state folder. Session goals live one-file-per-goal under `session-goals/` and activate per-tool: native `/goal` stop-hook in Claude Code, `SESSION-GOAL.md` in Codex, `.cursor/rules/session-goal.mdc` in Cursor. + +| Command | What it does | +|---|---| +| `/create-goal [slug-or-intent]` | Interactive interview that writes `session-goals/.md`. Wraps the [`create-goal`](skills/create-goal/SKILL.md) skill. | +| `/set-goal [slug]` | Activate (or `--clear` to deactivate) a session goal. Wraps the [`activate-goal`](skills/activate-goal/SKILL.md) skill. The user-visible name is `/set-goal`; the backing skill is named `activate-goal` to avoid colliding with the Goal Loop intake skill of the same name. | + +### Goal Loop iterations + +| Command | What it does | +|---|---| +| `/goal:demo [slug]` | Zero-input first-touch — scaffolds `goals/hello-loop/` from the canonical seed and drives one full iteration end-to-end. The fastest way to confirm the plugin works in your project. | +| `/goal:welcome [tour\|hello\|docs]` | First-time guided welcome — plain-language tour, hello-world iteration, or hand-off to `docs/getting-started.md`. **Start here for the Goal Loop.** | +| `/goal:start ` | Bootstrap and define a new goal (also amend-mode entry for an existing slug). | +| `/goal:observe [slug]` | Run the Observe phase. | +| `/goal:orient [slug]` | Run the Orient phase. | +| `/goal:decide [slug]` | Run the Decide phase + user gate. | +| `/goal:act [slug]` | Execute the approved decision set. | +| `/goal:review [slug]` | Close the iteration. | +| `/goal:run [slug]` | Run a full iteration end-to-end. | +| `/goal:status [slug]` | Read-only state snapshot. | +| `/goal:list [filter]` | Read-only portfolio view of every goal under `goals/`. Filter `--all` / `--active` / `--stalled` / `--done` / `--cancelled`. | +| `/goal:close [slug] [outcome]` | Manually close a goal out-of-band. | +| `/goal:brief [slug]` | Render the periodic brief (recurring goals). | +| `/goal:amend [slug]` | Dedicated amend entry; re-runs the goal gate. | +| `/goal:trace [slug] [iter]` | Read-only walk of the full reasoning trail for one iteration. | +| `/goal:export-trace [slug] [iter\|--all] [--format=otel-genai\|langfuse\|raw]` | Export a Goal Loop iteration as OpenTelemetry GenAI trace JSON. Read-only. Machine-facing sibling of `/goal:trace`; pipes into Langfuse / Datadog / Helicone / Arize / Phoenix. | + +## Repo conventions + +- Markdown for all artifacts. Concise; precision over completeness. +- File names = kebab-case. Per-goal work under `goals//`. +- Phase artifacts use ISO-timestamp filenames where multiple are produced per iteration (e.g. `observations/2026-05-16T10-00-00.md`). +- Templates in `templates/` are framework-agnostic Markdown. +- Cross-doc links are relative. + +## Tool-specific notes + +- **Claude Code.** Subagents (`agents/`), skills (`skills/`), commands (`commands/`), plugin manifest (`.claude-plugin/plugin.json`) are picked up natively. `CLAUDE.md` imports this file plus the constitution and method. +- **Codex.** Primary context = this file. Codex specifics in [`.codex/`](.codex/README.md). Workflows for Goal Loop iterations under `.codex/workflows/`. +- **Cursor.** Primary context = this file. Cursor rule at `.cursor/rules/goal-loop.mdc` is a thin pointer. +- **All tools.** Templates in `templates/` are framework-agnostic. + +## When the harness gets in your way + +The Goal Loop is process-light. If a check or gate is making you fight the tool, fix the goal definition (often the issue is an under-specified acceptance criterion or a missing observe source) — don't work around the loop. diff --git a/plugin-v2/CHANGELOG.md b/plugin-v2/CHANGELOG.md new file mode 100644 index 000000000..c1554a2ac --- /dev/null +++ b/plugin-v2/CHANGELOG.md @@ -0,0 +1,90 @@ +--- +title: Goal Loop — Changelog +folder: plugin-v2 +description: Versioned history of the goal-loop plugin. Follows Keep a Changelog 1.1.0 + Semantic Versioning 2.0.0 per docs/maintenance.md. +entry_point: false +--- + +# Changelog + +All notable changes to the `goal-loop` plugin are recorded here. + +The format follows [Keep a Changelog 1.1.0](https://keepachangelog.com/en/1.1.0/) and the plugin adheres to [Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html). See [`docs/maintenance.md`](docs/maintenance.md) for the contract that governs version bumps, category use, and schema-delta annotations. + +## [Unreleased] + +_No changes yet — open an entry under the appropriate category when work begins._ + +## [2.2.0] — 2026-05-17 + +Additive release. Lands the new `check-goal-length.sh` quality gate (G2 in the automation spec) and threads the body-length cap through the authoring surfaces. No state-file schema change; no breaking change. + +### Added + +- **Quality gate — body-length cap.** [`scripts/check-goal-length.sh`](scripts/check-goal-length.sh) enforces a 3500-character cap on the body (everything after the closing `---` of the frontmatter) of every goal artifact — `templates/goal-state-template.md`, `templates/session-goal-template.md`, `examples/**/goal-state.md`, `examples/session-goal-example.md`, adopter live `goals/**/goal-state.md`, and `session-goals/*.md`. CRLF-safe; malformed frontmatter is treated as FAIL. Wired into [`scripts/check-all.sh`](scripts/check-all.sh). Documented at [`skills/_shared/goal-state.md`](skills/_shared/goal-state.md) §"Body-length cap", [`docs/method.md`](docs/method.md) §"Quality gates", [`docs/automation-spec.md`](docs/automation-spec.md) §G2. +- **Write-time enforcement.** [`skills/set-goal/SKILL.md`](skills/set-goal/SKILL.md) Step 4 and [`skills/create-goal/SKILL.md`](skills/create-goal/SKILL.md) Step 6 count body characters after writing and refuse to advance past the goal gate when the cap is exceeded. +- **Fan-in index artifacts.** Six worked `_index.md` files added across `examples/{continuous-awareness,incident-triage,policy-review,release-readiness}/` for the canonical N ≥ 2 fan-in pattern (`observations/--_index.md`, `actions/iter-/_index.md`). + +### Changed + +- **Worked examples trimmed.** Four oversized example `goal-state.md` files (continuous-awareness, incident-triage, policy-review, release-readiness) tightened to fit under the cap without losing illustrative value. `templates/session-goal-template.md` trimmed by ~250 chars to make room for the cap notice. + +## [2.1.0] — 2026-05-16 + +Additive release. Broadens the consult surface, ships a first-run welcome flow, and rounds out the docs set. No state-file schema change; no breaking change. Adopters on `v2.0.0` may upgrade without action. + +### Added + +- **Agents (consult-only).** Three advice-bearing roles that never own phase artifacts: [`agents/goal-critic.md`](agents/goal-critic.md) (adversarial review of a drafted `goal-state.md` at the goal gate), [`agents/signal-deduper.md`](agents/signal-deduper.md) (merges duplicates when N ≥ 2 observers fan out), [`agents/risk-scout.md`](agents/risk-scout.md) (surfaces unstated risks pre-Act). +- **Skills (helpers).** [`skills/acceptance-criteria-helper/SKILL.md`](skills/acceptance-criteria-helper/SKILL.md) walks the user through writing or sharpening a falsifiable acceptance criterion. [`skills/trace-loop/SKILL.md`](skills/trace-loop/SKILL.md) reconstructs the full reasoning trail for one iteration, read-only. +- **Skill + command (welcome).** [`skills/welcome/SKILL.md`](skills/welcome/SKILL.md) and [`commands/goal/welcome.md`](commands/goal/welcome.md) ship a first-run flow with three modes — `tour`, `hello`, `docs`. +- **Commands.** [`commands/goal/amend.md`](commands/goal/amend.md) provides a dedicated amend entry that re-runs the goal gate; [`commands/goal/trace.md`](commands/goal/trace.md) exposes the trace-loop skill as a slash command. +- **Templates.** [`templates/constitution-amendment-template.md`](templates/constitution-amendment-template.md) (structured amendment proposals), [`templates/goal-archive-template.md`](templates/goal-archive-template.md) (closure snapshot), [`templates/lessons-template.md`](templates/lessons-template.md) (per-goal lessons capture). +- **Docs.** [`docs/glossary.md`](docs/glossary.md) (5-minute orientation for domain-neutral readers), [`docs/troubleshooting.md`](docs/troubleshooting.md) (problem → cause → fix lookup), [`docs/hooks-recipes.md`](docs/hooks-recipes.md) (opt-in Claude Code hooks that surface loop state), [`docs/cadence-recipes.md`](docs/cadence-recipes.md) (cron / GitHub Actions / systemd recipes for recurring runs). +- **Docs (strategy + onboarding).** [`docs/maintenance.md`](docs/maintenance.md) (versioning, deprecation, schema evolution, multi-tool drift, security review, cadence, contribution, LTS), [`docs/improvement-strategy.md`](docs/improvement-strategy.md) (forward-looking direction; extension points, anti-patterns, roadmap shape), [`docs/automation-spec.md`](docs/automation-spec.md) (acceptance contract for the quality pipeline), [`docs/ux-agentic-cowork.md`](docs/ux-agentic-cowork.md) (UX rationale for the human-gate surface), [`docs/getting-started.md`](docs/getting-started.md) (reading-along version of `/goal:welcome hello`). +- **Worked examples.** Policy-consultation example demonstrating the loop on a non-software domain; hello-loop seed example backing `/goal:welcome hello`. +- **Manifest.** Top-level `bugs` field pointing at the issues tracker and security-advisory channel for downstream tooling that reads `plugin.json`. + +### Changed + +_No behaviour changes to existing surfaces in this release._ + +### Deprecated + +_None._ + +### Removed + +_None._ + +### Fixed + +_None._ + +### Security + +- **Bug + security disclosure surface.** New [`SECURITY.md`](SECURITY.md) documents the threat model summary, supported-versions table, and the GitHub Security Advisory disclosure channel. Aligned with RFC 9116 conventions per [`docs/maintenance.md` §Security review](docs/maintenance.md#security-review). +- **Tool-list audit.** Per-release agent-surface review (per maintenance contract) confirms no broadenings vs. the `v2.0.0` baseline. The three new consult-only agents (`goal-critic`, `signal-deduper`, `risk-scout`) ship with tool lists narrower than the phase agents that consult them. + +## [2.0.0] — 2026-05-16 (baseline) + +Initial public baseline for the `goal-loop` plugin. The plugin unifies goal-oriented orchestration with the Boyd OODA loop in a domain-agnostic, parallel-capable, human-gated baseline. See [`docs/method.md`](docs/method.md) for the authoritative method definition. + +### Added + +- **Constitution.** Ten governing articles at [`memory/constitution.md`](memory/constitution.md): Goal Primacy, Phase Isolation, Human Gates, Evidence-Based Orientation, Reversibility Bias, Loop Discipline, Domain Neutrality, Transparency, Escalate-Don't-Invent, Closure Honesty. +- **Agents (6).** Orchestrator + five phase specialists: [`agents/goal-orchestrator.md`](agents/goal-orchestrator.md), [`agents/observer.md`](agents/observer.md), [`agents/orienter.md`](agents/orienter.md), [`agents/decider.md`](agents/decider.md), [`agents/actor.md`](agents/actor.md), [`agents/loop-reviewer.md`](agents/loop-reviewer.md). +- **Skills (7).** Conductor + per-phase how-tos: [`skills/goal-loop`](skills/goal-loop), [`skills/set-goal`](skills/set-goal), [`skills/observe`](skills/observe), [`skills/orient`](skills/orient), [`skills/decide`](skills/decide), [`skills/act`](skills/act), [`skills/review-loop`](skills/review-loop). Shared rules under [`skills/_shared/`](skills/_shared/). +- **Commands (10).** `/goal:start`, `/goal:observe`, `/goal:orient`, `/goal:decide`, `/goal:act`, `/goal:review`, `/goal:run`, `/goal:status`, `/goal:close`, `/goal:brief` — registered through [`commands/goal/`](commands/goal/). +- **Templates.** Per-artifact framework-agnostic Markdown under [`templates/`](templates/): goal-state, observation, orientation, decision, action-log, action-spec, review, brief. +- **Docs.** [`docs/method.md`](docs/method.md), [`docs/usage-patterns.md`](docs/usage-patterns.md), [`docs/goal-orientation.md`](docs/goal-orientation.md), [`docs/customizing.md`](docs/customizing.md), [`docs/tool-adapters.md`](docs/tool-adapters.md), [`docs/ooda-foundations.md`](docs/ooda-foundations.md). +- **Adapters.** Codex (`.codex/`) and Cursor (`.cursor/rules/goal-loop.mdc`) entry points, per the tool-adapter contract. +- **Manifest.** [`.claude-plugin/plugin.json`](.claude-plugin/plugin.json) registering agents, skills, and commands for Claude Code. + +[Unreleased]: https://github.com/Luis85/agentic-workflow/compare/plugin-v2-2.1.0...HEAD +[2.1.0]: https://github.com/Luis85/agentic-workflow/releases/tag/plugin-v2-2.1.0 +[2.0.0]: https://github.com/Luis85/agentic-workflow/releases/tag/plugin-v2-2.0.0 + +--- + +This changelog follows [Keep a Changelog 1.1.0](https://keepachangelog.com/en/1.1.0/). The plugin uses [Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html). diff --git a/plugin-v2/CLAUDE.md b/plugin-v2/CLAUDE.md new file mode 100644 index 000000000..31dfec0bc --- /dev/null +++ b/plugin-v2/CLAUDE.md @@ -0,0 +1,69 @@ +# CLAUDE.md + +Entry point for Claude Code in the `goal-loop` plugin. + +## Primary context + +@AGENTS.md +@memory/constitution.md +@docs/method.md + +## What this is + +The **Goal Loop** plugin — a goal-bounded OODA loop for any decision or delivery cycle. The plugin ships a complete subagent + skill + command + template set — full inventory in [`AGENTS.md`](AGENTS.md). Domain-agnostic. + +The method's authoritative definition is [`docs/method.md`](docs/method.md). Read it before deviating from the loop. + +## How to work here + +Two equivalent entry points: + +- **Conversational (recommended):** Say *"set up a goal loop"*, *"run an OODA loop on X"*, or *"kick off a daily brief"* — the [`goal-loop`](skills/goal-loop/SKILL.md) skill gates with `AskUserQuestion` and dispatches the right `/goal:*` command per phase. +- **Manual:** Run `/goal:demo` first on a fresh project for a zero-input, one-command first-touch (scaffolds + drives one full hello-loop iteration — one Observe → Orient → Decide → Act → Review pass; see [glossary](docs/glossary.md)). Then `/goal:welcome` for the guided walkthrough (tour, hello-world, or docs hand-off). Drive the slash commands in order — `/goal:start`, `/goal:observe`, `/goal:orient`, `/goal:decide`, `/goal:act`, `/goal:review`. Or `/goal:run` for the full iteration end-to-end. Inspect one goal with `/goal:status` or `/goal:trace`; survey the whole portfolio with `/goal:list`. Amend with `/goal:amend`. Render a brief with `/goal:brief`. Close with `/goal:close`. + +State lives at `goals//goal-state.md` (slug — the kebab-case short name like `my-goal-slug` identifying the goal folder under `goals/`). The orchestrator updates it on phase completion — don't edit it by hand mid-iteration. + +**Session goals (cross-tool).** For a session-scoped intent that keeps the assistant on rails for one sitting — without the full Goal Loop ceremony — use `/create-goal` to interview into `session-goals/.md`, then `/set-goal ` to activate (invokes the native `/goal` stop-hook in Claude Code). Distinct from `/goal:start` (Goal Loop intake); see [`docs/session-vs-iteration-goals.md`](docs/session-vs-iteration-goals.md) for the side-by-side comparison and [`docs/session-goal-best-practices.md`](docs/session-goal-best-practices.md) for shape-by-shape best practices. + +## Conventions specific to Claude Code + +- Subagents live in [`agents/`](agents/) with intentionally narrow tool lists. Missing tool = feature, not bug. +- Skills live in [`skills/`](skills/) — see the [skills README](skills/README.md). Auto-trigger from natural language; explicit invoke via `/`. +- Slash commands live in [`commands/goal/`](commands/goal/) — see [commands/goal/README.md](commands/goal/README.md). +- Templates live in [`templates/`](templates/) — one per artifact type. +- Each phase agent writes only its own artifacts. Phase isolation is governed by Article II of the constitution. +- Human gates: the **goal gate** (the human approval of the goal contract before the first iteration; see [glossary](docs/glossary.md)) and the **act gate** (the human approval before Act executes any decision) are non-negotiable. Other gates are opt-in per goal. + +## What success looks like + +A working Goal Loop session typically looks like this: + +- The user signs the goal gate after a short clarity-gated intake. The acceptance criteria (falsifiable, observer-checkable conditions that decide "done"; see [glossary](docs/glossary.md)) are falsifiable and the constraints are explicit. +- Each iteration produces one observation set, one refreshed orientation, one decision set (with the user approving the act-gate), one or more action logs, and one review. +- The review either closes the goal with per-criterion evidence (`close-met`) or recommends `continue` with a concrete next observation focus. +- The audit trail under `goals//` reconstructs every decision the loop made; `/goal:trace` can walk it criterion-by-criterion. +- Surprises route through `## Open Questions`, contradictions, and amendments — never through silent invention. + +## What not to do + +- Don't bypass the act gate for irreversible actions, even on the user's behalf, unless the goal's `act_gate` policy explicitly authorises it. +- Don't invent acceptance criteria. If the user didn't supply one, the `set-goal` skill must elicit it. +- Don't introduce software-specific terms into the prompts or templates. The method is domain-agnostic. +- Don't expand the plugin with new phase agents or new state-file fields without amending [`docs/method.md`](docs/method.md) and the constitution. + +## Further docs + +Beyond the primary context above, the plugin ships: + +- [`docs/first-five-minutes.md`](docs/first-five-minutes.md) — 90-second on-ramp. Install verification → `/goal:demo` → what landed → where to go next. +- [`docs/session-vs-iteration-goals.md`](docs/session-vs-iteration-goals.md) — side-by-side comparison of `/create-goal` (session-scoped) vs. `/goal:start` (iteration-scoped); pick-by-scenario guide. +- [`docs/domain-model.md`](docs/domain-model.md) — single-read type map of every domain entity. Use to onboard fast. +- [`docs/glossary.md`](docs/glossary.md) — 5-minute orientation for domain-neutral readers. +- [`docs/troubleshooting.md`](docs/troubleshooting.md) — problem → cause → fix for common blockers. +- [`docs/usage-patterns.md`](docs/usage-patterns.md) — the canonical five (six with policy-consultation) patterns the loop drives. +- [`docs/customizing.md`](docs/customizing.md) — how adopters extend without forking the baseline. +- [`docs/tool-adapters.md`](docs/tool-adapters.md) — Claude Code / Codex / Cursor adapter contract. +- [`docs/hooks-recipes.md`](docs/hooks-recipes.md) — opt-in Claude Code hook recipes that surface loop state. +- [`docs/cadence-recipes.md`](docs/cadence-recipes.md) — cron / Actions / systemd recipes for recurring runs. +- [`docs/maintenance.md`](docs/maintenance.md) — for the plugin maintainer. +- [`docs/improvement-strategy.md`](docs/improvement-strategy.md) — forward-looking direction for the plugin. diff --git a/plugin-v2/CONTRIBUTING.md b/plugin-v2/CONTRIBUTING.md new file mode 100644 index 000000000..f7b09662f --- /dev/null +++ b/plugin-v2/CONTRIBUTING.md @@ -0,0 +1,56 @@ +--- +title: Contributing to goal-loop +folder: plugin-v2 +description: Entry point for contributors. Quick start; full contributor guide at docs/contributing.md. +entry_point: false +--- + +# Contributing to goal-loop + +Thanks for contributing. This is the short version. The full contributor guide is [`docs/contributing.md`](docs/contributing.md) — read it before opening anything bigger than a typo fix. + +## Before you start + +- Read [`memory/constitution.md`](memory/constitution.md) — ten articles, about 5 minutes. Every contribution is read against them. +- Read [`docs/method.md`](docs/method.md) — the canonical Goal Loop definition (phases, vocabulary, state model). +- Decide where your change lands: extending **in your own project** (overlay), shipping a **domain pack**, or contributing to the **baseline** here. See [`docs/contributing.md` §"Fork vs. overlay vs. baseline"](docs/contributing.md#fork-vs-overlay-vs-baseline). The default answer to "should this be in the baseline?" is **no, write it as an overlay first**. +- Run the verify gate locally before opening a PR: `bash scripts/check-all.sh`. + +## What contributions look like + +- **New agent** — see [`templates/agent-template.md`](templates/agent-template.md) plus [`docs/contributing.md` §"Adding a new agent"](docs/contributing.md#adding-a-new-agent). New **phase** agents require a filled constitution amendment first. +- **New skill** — see [`templates/skill-template.md`](templates/skill-template.md) plus [`docs/contributing.md` §"Adding a new skill"](docs/contributing.md#adding-a-new-skill). Frontmatter `description` must carry three or more quoted trigger phrases. +- **New template** — see [`templates/README.md`](templates/README.md) for ownership plus [`docs/contributing.md` §"Adding a new template"](docs/contributing.md#adding-a-new-template). +- **New command** — see [`commands/goal/README.md`](commands/goal/README.md) for the existing surface. New commands need a backing skill in most cases. +- **Constitution amendment** — see [`templates/constitution-amendment-template.md`](templates/constitution-amendment-template.md) plus [`memory/constitution.md` §"Amendment process"](memory/constitution.md#amendment-process). The filled amendment is the first deliverable, not the code. + +## PR checklist + +```markdown +- [ ] Verify gate passes locally: `bash scripts/check-all.sh` +- [ ] All new or changed files have frontmatter with the required keys for their category. +- [ ] Locked vocabulary respected (see `docs/method.md` §"Naming reference"). +- [ ] No `pending_actions`, `act_approval`, `closed_at`, `/goal:set`, `reversible: true|false`, `outcome: done|failed|skipped` in the diff. +- [ ] Cross-references resolve (`npm run check:links`). +- [ ] Conventional Commits 1.0.0 message (`feat:`, `fix:`, `docs:`, `chore:`, `refactor:`, `style:`). +- [ ] If touching agents or skills, the `tools:` list is justified (narrowing is fine; broadening requires an amendment-log entry). +- [ ] Constitution Articles I–III amendments include a filled `templates/constitution-amendment-template.md`. +- [ ] Worked example or test fixture exercising the change ships in the same PR. +``` + +Tick boxes you actually ran. Do not pre-tick. + +## Where to file bugs and feature requests + +- **Bugs and feature requests:** [github.com/Luis85/agentic-workflow/issues](https://github.com/Luis85/agentic-workflow/issues). +- **Security disclosures:** [`SECURITY.md`](SECURITY.md) — use the private security advisory channel for anything not safely public. + +## Code of conduct + +Reasonable open-source behaviour: plain language, no harassment, no demands for free maintainer time. Escalate conflicts to the maintainer. The plugin inherits the parent [`agentic-workflow`](../README.md) repository's norms; a dedicated `CODE_OF_CONDUCT.md` may be added when the contributor base grows. + +## See also + +- [`docs/contributing.md`](docs/contributing.md) — the deep dive (fork-vs-overlay decision, per-surface rubric, full verification checklist). +- [`docs/maintenance.md`](docs/maintenance.md) — for maintainers (versioning, deprecation, security cadence, EOL). +- [`docs/improvement-strategy.md`](docs/improvement-strategy.md) — forward-looking direction for the baseline. diff --git a/plugin-v2/LICENSE b/plugin-v2/LICENSE new file mode 100644 index 000000000..a4036bfd5 --- /dev/null +++ b/plugin-v2/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 Luis Mendez + +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. diff --git a/plugin-v2/README.md b/plugin-v2/README.md new file mode 100644 index 000000000..2e3bf422d --- /dev/null +++ b/plugin-v2/README.md @@ -0,0 +1,235 @@ +--- +title: goal-loop +folder: plugin-v2 +description: A goal-bounded OODA loop plugin for Claude Code, Codex, and Cursor — domain-agnostic, parallel-capable, human-gated. +entry_point: true +--- + +# goal-loop + +> A goal-bounded OODA loop for any decision or delivery cycle. Domain-agnostic, parallel-capable, human-gated. + +**Goal Loop** unifies two patterns that are stronger together: + +- **Goal-oriented orchestration** — set an explicit goal with constraints and acceptance criteria (falsifiable, observer-checkable conditions that decide "done"; see [glossary](docs/glossary.md)), then drive a structured resolution cycle. +- **OODA loop** (Observe → Orient → Decide → Act, John Boyd) — a tempo-driven decision cycle for environments of uncertainty and incomplete information; one full pass is one **iteration** (Observe → Orient → Decide → Act → Review). + +This is a baseline plugin. It ships everything you need to install, run, and extend — the method, the agents and skills, the slash-command surface, templates, docs, adapters for Codex and Cursor, and worked examples. The full inventory is in the **What you get** table below. The plugin deliberately stays out of the way of your domain — use it for code, content, research, operations, strategy, or anything else. + +## What you get + +| Surface | What it does | Where to look | +|---|---|---| +| Method | The full Goal Loop method definition + vocabulary | [`docs/method.md`](docs/method.md) | +| Subagents (focused agent roles the plugin dispatches for a specific phase; see [glossary](docs/glossary.md)) | `goal-orchestrator` + 5 phase agents + 3 consult-only specialists | [`agents/`](agents/) | +| Skills | Conductor + per-phase how-tos + helper skills (`acceptance-criteria-helper`, `trace-loop`) | [`skills/`](skills/) | +| Slash commands | `/goal:*` namespace plus top-level `/create-goal` and `/set-goal` for cross-tool session goals | [`commands/goal/`](commands/goal/), [`commands/create-goal.md`](commands/create-goal.md), [`commands/set-goal.md`](commands/set-goal.md) | +| Templates | State, per-phase artifacts, lessons, archive, constitution amendment | [`templates/`](templates/) | +| Docs | Foundations + glossary + troubleshooting + recipes + examples | [`docs/`](docs/) | +| Examples | Issue-resolution + daily-brief walkthroughs | [`examples/`](examples/) | + +## Install + +This folder is a self-contained plugin. To use it in your own project: + +1. **Copy the folder.** Pick one of the four install paths below. The mechanics differ; the result is the same: `plugin-v2/` lives at the top of your project. As an alternative to a top-level copy, you may merge `agents/`, `skills/`, `commands/`, `templates/`, and `docs/` into your existing `.claude/`. **Don't blindly merge `CLAUDE.md` or `AGENTS.md`** — if your project already has them, add an `@plugin-v2/AGENTS.md` import line instead of replacing yours. +2. **Adopt the entry points.** `CLAUDE.md`, `AGENTS.md`, and (optionally) `.codex/`, `.cursor/` import the plugin's rules into the tool's native context. +3. **Bootstrap a goal.** In Claude Code, the plugin's agents, skills, and slash commands auto-register from the folder layout. Verify with `/help | grep goal:` — you should see at least `/goal:start`. Then run `/goal:start demo-goal` (or your own slug — a kebab-case short name like `my-goal-slug` that identifies the goal folder under `goals/`). Codex and Cursor adopters: see [`docs/tool-adapters.md`](docs/tool-adapters.md) for how to drive the loop without slash commands. + +### Install paths + +Four concrete recipes for step 1. Pick one — see the decision rule below. + +#### 1. Claude Code marketplace (canonical, once published) + +When the plugin is available on the Claude Code marketplace, install it natively from the marketplace UI. This is the canonical path once published — smallest footprint, native upgrades, no folder copy required. The recipes below are for the interim. + +#### 2. `git subtree` (recommended for tracking upstream) + +``` +git subtree add --prefix=plugin-v2 https://github.com/Luis85/agentic-workflow.git claude/unified-plugin-v2-Lmn8x --squash +# update later: +git subtree pull --prefix=plugin-v2 https://github.com/Luis85/agentic-workflow.git claude/unified-plugin-v2-Lmn8x --squash +``` + +#### 3. `git submodule` (pinned vendored reference) + +``` +git submodule add https://github.com/Luis85/agentic-workflow.git vendor/agentic-workflow +ln -s ../vendor/agentic-workflow/plugin-v2 plugin-v2 +# update later: +cd vendor/agentic-workflow && git pull && cd ../.. +``` + +#### 4. One-shot `cp -r` (fork-and-own; no upstream relationship) + +``` +git clone --depth 1 https://github.com/Luis85/agentic-workflow.git /tmp/agentic-workflow +cp -r /tmp/agentic-workflow/plugin-v2 ./plugin-v2 +rm -rf /tmp/agentic-workflow +``` + +### Which path should I pick? + +- **Marketplace** — when available, always (smallest footprint, native upgrades). +- **subtree** — if you want to track upstream and merge your local changes back. +- **submodule** — if you want a pinned vendored reference. +- **`cp -r`** — if you want to fork-and-own with no upstream relationship. + +### Tool-by-tool + +| Tool | Reads first | Notes | +|---|---|---| +| Claude Code | `CLAUDE.md` → `AGENTS.md` → `docs/method.md` | Native: agents, skills, commands all picked up from the plugin folder. | +| Codex | `AGENTS.md` → `.codex/instructions.md` → `docs/method.md` | Workflows under `.codex/workflows/`. | +| Cursor | `.cursor/rules/goal-loop.mdc` → `AGENTS.md` → `docs/method.md` | Rule is a pointer; substance lives in `AGENTS.md` and the method doc. | + +See [`docs/tool-adapters.md`](docs/tool-adapters.md) for the adapter contract. + +## Verify install + +Three checks confirm the plugin is in place: + +- `ls plugin-v2/agents/ | wc -l` → at least 9. +- In Claude Code: `/help | grep goal:` → at least `/goal:start`. +- `cat plugin-v2/.claude-plugin/plugin.json | grep '"version"'` → the version string is present. + +If any check fails, see [`docs/troubleshooting.md`](docs/troubleshooting.md). + +## Need a quick session-scoped goal? + +Run [`/create-goal`](commands/create-goal.md) to interview yourself into a well-formed **session goal** at `session-goals/.md`, then [`/set-goal `](commands/set-goal.md) to activate it for the current sitting. In Claude Code, activation invokes the native `/goal` stop-hook; in Codex it writes `SESSION-GOAL.md`; in Cursor it writes `.cursor/rules/session-goal.mdc`. Clear with `/set-goal --clear`. + +Session goals are session-scoped guard rails. They are **distinct from a Goal Loop iteration goal** — for the structured, gated, phase-driven loop with `Observe → Orient → Decide → Act → Review`, use [`/goal:start`](commands/goal/start.md). Rule of thumb: if the work fits in one sitting and you mostly need the assistant to stay on rails, use a session goal; if the work spans multiple iterations and needs evidence-based phase artifacts, use the Goal Loop. + +## Quick start (5 minutes) + +### Want to see it run in 30 seconds? + +``` +/goal:demo +``` + +[`/goal:demo`](commands/goal/demo.md) scaffolds `goals/hello-loop/` from the canonical seed and runs one complete Observe → Orient → Decide → Act → Review iteration end-to-end with zero input. Use it as the fastest first-touch — *does the plugin even work in my project?*. For the guided walkthrough with explanations between phases, use `/goal:welcome` below. + +### First time? Start with the welcome flow + +``` +/goal:welcome +``` + +`/goal:welcome` walks you through the concept in plain language (~5 minutes) and, if you opt in, runs a hello-world iteration end-to-end with you watching every artifact land (~10 minutes more). Pass `tour` / `hello` / `docs` to skip the choice gate. The reading-along version of the same loop lives at [`docs/getting-started.md`](docs/getting-started.md). + +Coming back to the project? Run [`/goal:list`](commands/goal/list.md) for a portfolio view of every goal under `goals/` — phase, iteration, status, last activity — sorted by recency. + +### Skip the tour — first goal in 60 seconds + +``` +# 1. Bootstrap +/goal:start demo + +# When prompted, paste: +# Intent — Confirm the goal-loop plugin runs in this project. +# Constraint — Must not edit anything outside goals/demo/. +# Acceptance — goals/demo/goal-state.md exists with goal_signed_off: true. +# Mode — one-shot. Cadence — none. +# Observe source — id: demo-folder, type: document, target: goals/demo/. +# (An observe source is a declared input the observer scans — a feed, repo, inbox, document, person, command, etc.; see docs/glossary.md.) +# Act gate — always. +# (The act gate is the human approval before Act executes any decision; see docs/glossary.md.) +``` + +After sign-off you should see: + +``` +goals/demo/ +├── goal-state.md # status: active, current_phase: scope +├── observations/ +├── actions/ +├── reviews/ +└── archive/ +``` + +### Drive the loop + +``` +# Single-shot end-to-end +/goal:run demo + +# Or run one phase at a time +/goal:observe demo +/goal:orient demo +/goal:decide demo +/goal:act demo +/goal:review demo + +# Read-only inspection +/goal:status demo +/goal:trace demo +``` + +State lives at `goals//`. The orchestrator never touches files outside that folder. + +## How it works + +`×N` = N observers in parallel (one per declared source). `×M` = M actors in parallel (one per approved action). + +``` +GOAL (intent + constraints + acceptance + mode) + │ + ▼ +goal-orchestrator ──▶ observer ──▶ orienter ──▶ decider ──[human gate]──▶ actor ──▶ loop-reviewer + (×N parallel) (ranked set) (×M parallel) │ + ▼ + continue | close-met | close-abandon | amend +``` + +Full architecture in [`docs/method.md`](docs/method.md). Worked examples in [`docs/examples/`](docs/examples/). + +## Use-case patterns + +The same loop drives several common patterns by varying mode, cadence, sources, and gate policy: + +- **Issue resolution** — one-shot, bounded by acceptance criteria. +- **Daily brief** — recurring, "stay oriented across project X". +- **Incident triage** — rapid, time-critical, pre-authorised runbook actions. +- **Release readiness** — checklist, ship-blocking gate. +- **Continuous awareness** — perpetual, monitor a landscape. +- **Policy or content review** — non-software example showing how the same loop drives a stakeholder consultation. See [`docs/examples/policy-consultation.md`](docs/examples/policy-consultation.md). + +See [`docs/usage-patterns.md`](docs/usage-patterns.md). + +## Extending + +The plugin is a baseline, not a cage. Common extensions: + +- Add a new observe source type (e.g., custom API feeds). +- Define a custom decision-ranking criterion. +- Narrow a phase agent's tool list for sensitive domains. +- Swap a template with a domain-specific version. +- Wrap `/goal:run` in a scheduled trigger for hands-off recurring loops. + +See [`docs/customizing.md`](docs/customizing.md). Every extension lives in your project; the plugin folder stays clean for upgrades. + +## Constitution + +Ten short articles govern the method. Read them before deviating: [`memory/constitution.md`](memory/constitution.md). + +## Status + +`v2.1.0` baseline — ships the method, 9 subagents (1 orchestrator + 5 phase + 3 consult-only), 14 skills, 18 slash commands, 18 templates, the docs set, the constitution, and adapters for Codex and Cursor. Not production-hardened; iterate in your own fork. Manifest version is the source of truth: see [`.claude-plugin/plugin.json`](.claude-plugin/plugin.json). + +## License + +MIT — see [`LICENSE`](LICENSE). + +## Contributing + +See [`CONTRIBUTING.md`](CONTRIBUTING.md) — the short version — and [`docs/contributing.md`](docs/contributing.md) — the deep dive (fork-vs-overlay decision, per-surface rubric, verification checklist). + +## Project files + +- [`CHANGELOG.md`](CHANGELOG.md) — versioned release history. +- [`SECURITY.md`](SECURITY.md) — security policy and vulnerability disclosure. +- [`CONTRIBUTING.md`](CONTRIBUTING.md) — contributor entry point. +- [`LICENSE`](LICENSE) — MIT. diff --git a/plugin-v2/SECURITY.md b/plugin-v2/SECURITY.md new file mode 100644 index 000000000..18bd163c2 --- /dev/null +++ b/plugin-v2/SECURITY.md @@ -0,0 +1,114 @@ +--- +title: Goal Loop — Security +folder: plugin-v2 +description: Security policy, threat model summary, and vulnerability disclosure procedure for the goal-loop plugin. +entry_point: false +--- + +# Security Policy + +This document describes the security posture, non-negotiable safety guarantees, threat model, supported versions, and vulnerability disclosure procedure for the `goal-loop` plugin. It follows the conventions of [RFC 9116 — *A File Format to Aid in Security Vulnerability Disclosure*](https://www.rfc-editor.org/rfc/rfc9116) and the per-release agent-surface review described in [`docs/maintenance.md` §Security review](docs/maintenance.md#security-review). + +## Scope + +The `goal-loop` plugin is a domain-agnostic baseline that drops nine subagents (one orchestrator, five phase agents, three consult-only specialists), nine skills, twelve slash commands, eleven templates, the constitution, the method definition, and adapter shims into a host project. Within an adopter's repository, the plugin: + +- **Reads and writes** files under `goals//` (the canonical state root for each goal). +- **Reads** the adopter's project files when an `observer` is pointed at them via a declared observe source. +- **Writes** only to the adopter's project tree, and only through tools the adopter's host (Claude Code, Codex, Cursor) authorises. +- **Authors** plain-text Markdown artifacts (`goal-state.md`, observations, orientations, decisions, action logs, reviews, briefs, lessons, archives). + +What the plugin does **not** touch: + +- Files outside `goals//` are never written without a decision set that explicitly names them and a human-cleared act gate ([constitution Article III](memory/constitution.md)). +- The plugin ships **no MCP servers**, **no telemetry endpoint**, **no remote registry**, **no scheduler daemon**. See [`docs/improvement-strategy.md#anti-patterns`](docs/improvement-strategy.md#anti-patterns). +- The plugin does **not** mutate the constitution, the manifest, or any plugin file at runtime — those are author-time-only surfaces, edited by humans through the amendment process. + +## Non-negotiable safety guarantees + +These guarantees derive directly from the plugin's constitution. They are not configurable per goal; an adopter cannot opt out of them through `act_gate`, `cadence`, or any policy field. + +1. **One iteration at a time, phases in order.** No phase runs out of order; no second iteration begins until the prior `review.md` records `outcome: continue | amend`. Backed by [Article VI §1](memory/constitution.md) (Loop Discipline — "one iteration at a time. The next iteration begins only after the current `review.md` records `outcome: continue | amend`") and [Article II](memory/constitution.md) (Phase Isolation — each phase has one purpose and one writer). +2. **Traceable trail end-to-end.** Every iteration produces a reasoning chain — observation → orientation → decision → human approval → action → review — that `/goal:trace` can reconstruct without guessing. Backed by [Article VIII §1–§4](memory/constitution.md) (Transparency: every decision logged, skips recorded with rationale, approvals timestamped, evidence linked). +3. **Plain-language artifacts; falsifiable acceptance.** Authored artifacts read as Markdown for a human first; acceptance criteria are observable and binary. No artifact hides state behind a structured-only payload. Backed by [Article I §2](memory/constitution.md) (Goal Primacy — acceptance criteria must be falsifiable; an outside observer can verify met or unmet) and [Article VII §2](memory/constitution.md) (Domain Neutrality — artifacts use plain language). +4. **No silent rewinds; closure is explicit.** A goal closes only on `close-met` (with per-criterion evidence) or `close-abandon` (with rationale). The loop never silently rolls back a phase. Backed by [Article X](memory/constitution.md) (Closure Honesty — partial or unknown verdicts block closure; abandonment must be recorded as such, not as closure). +5. **Escalate, don't invent.** Ambiguous, missing, contradictory, or out-of-scope inputs surface to the human; agents never fabricate a goal, a source, a constraint, or an approval. Backed by [Article IX](memory/constitution.md) (Escalate, Don't Invent — "the cost of asking is small; the cost of fabricated state is large"). +6. **Phase isolation; no cross-writes.** Each phase agent writes only its own artifacts under `goals//`. `goal-state.md` has the two-writer split per the canonical ownership matrix (`set-goal` writes body sections; `goal-orchestrator` writes frontmatter transitions and `## History`). Backed by [Article II §1–§3](memory/constitution.md) (Phase Isolation). +7. **Irreversible actions require human approval.** Every irreversible action carries a rollback plan and clears the human act gate before execution. `act_gate: low-risk-auto` only authorises reversible, low-risk actions — never irreversible ones. Backed by [Article III §2](memory/constitution.md) (Human Gates — act gate is non-negotiable for irreversible actions) and [Article V](memory/constitution.md) (Reversibility Bias — no rollback plan, no execution). + +The plugin's threat model treats every phase subagent as an **untrusted subprocess** running against a trusted-but-fallible human. The guarantees above are how the constitution turns that posture into runtime behaviour. + +## Threat model summary + +The plugin's agentic surface — narrow tool lists, structured state files, gated phases — is designed against the categories below. Threat names are aligned with [OWASP Top 10 for LLM Applications (2025)](https://genai.owasp.org/llm-top-10/) and [OWASP Top 10 for Agentic Applications (2026)](https://genai.owasp.org/) so that adopters running their own security reviews can map back to a shared vocabulary. + +- **Goal hijack.** A subagent rewrites the goal mid-iteration. Mitigated by Article I (Goal Primacy) — goals change through amendment only, with a human gate. +- **Tool misuse.** A subagent broadens its declared tool scope or invokes a tool outside its responsibility. Mitigated by the per-agent `Tools:` declarations in `agents/*.md` and by [the maintenance contract](docs/maintenance.md#security-review) that flags tool broadenings as breaking changes requiring a `Security` changelog rationale. +- **Excessive agency.** A subagent fans out beyond what the decision set authorised, or auto-approves irreversible actions. Mitigated by Articles III and V (Human Gates, Reversibility Bias) and by the orchestrator's exclusive ownership of phase dispatch. +- **Memory poisoning.** An adversary plants content under `goals//` to bias future iterations. Mitigated by Article IV (Evidence-Based Orientation — every claim cites an observation by file and signal index, so unsourced injection is visible) and by Article VIII (Transparency — the trail is reconstructable). +- **Prompt injection.** An observed source (file, web page, feed) contains instructions designed to redirect the loop. Mitigated by the observer's signals-only contract: the observer records what was observed, never interprets it; interpretation is the orienter's job, which must cite back. +- **Secrets exposure.** A subagent reads or echoes a credential into a phase artifact. Mitigated by [`docs/automation-spec.md#f-security--safety`](docs/automation-spec.md#f-security--safety) (the `security.no-secrets` check in the quality pipeline) and by the plain-text, reviewable shape of every artifact. +- **Handoff failure.** A phase agent leaves the next phase without the inputs it needs. Mitigated by [the schema contract](skills/_shared/goal-state.md) (frontmatter, body sections, ownership matrix) and by `/goal:trace` reconstructability. +- **Observability gaps.** A loop completes but the reasoning chain cannot be reconstructed. Mitigated by Article VIII (every decision and action logged, evidence linked) and by `trace-loop`'s read-only reconstruction skill. + +These categories are reviewed per release (see the agent-surface audit in `docs/maintenance.md`) and quarterly under the [agentic-security-review skill](https://github.com/Luis85/agentic-workflow/blob/main/.claude/skills/agentic-security-review/SKILL.md). + +## Supported versions + +The plugin follows [Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html). Security fixes target the latest MINOR of the latest MAJOR; LTS releases (when declared) receive security fixes for the duration of their declared LTS window per [`docs/maintenance.md#lts-and-end-of-life`](docs/maintenance.md#lts-and-end-of-life). + +| Version | Status | Security updates | +|---|---|---| +| `2.1.x` | Current | Yes — latest MINOR of the `2.x` line. | +| `2.0.x` | Previous baseline | Best-effort; upgrade to `2.1.x` recommended. | +| `< 2.0` | Pre-baseline | No — no public pre-baseline releases were made. | + +LTS designations, when applied to a future MAJOR, are recorded under that release's entry in [`CHANGELOG.md`](CHANGELOG.md) and in the README's `## Status` block. + +## Reporting a vulnerability + +The preferred channel is a **GitHub Security Advisory** against the repository: + +> **** + +This channel keeps the disclosure private until a fix is ready. Please include: + +- **Affected version** of the plugin (the `version` field of [`.claude-plugin/plugin.json`](.claude-plugin/plugin.json), or a commit SHA). +- **Reproduction steps** — the minimum sequence of commands, goals, or observe sources that triggers the issue. A redacted `goal-state.md` excerpt is helpful; please scrub adopter-private content first. +- **Proposed fix** if you have one — a sketch, a diff, or a constitution amendment proposal under [`templates/constitution-amendment-template.md`](templates/constitution-amendment-template.md) when the fix touches an article. +- **Disclosure timeline preference** — your preferred window between fix-ready and public disclosure. Defaults: 30 days for high-severity, 90 days for medium/low, negotiable per case. + +Acknowledgement: the maintainer aims to acknowledge new advisories within seven days. If you have not heard back in that window, open a non-sensitive issue at referencing the advisory ID — never paste sensitive reproduction details into the public issue tracker. + +Non-sensitive bug reports (not security-related) belong in the regular issue tracker: + +> **** + +## Out of scope + +The plugin's security policy covers **only the constitution-enforced surface of the `goal-loop` plugin itself**. The following are out of scope and belong to the adopter's own security review: + +- **Adopter projects' own goals.** The content of `goals//` in a downstream repository — including any code, secrets, or sensitive data the adopter places there — is the adopter's responsibility. The plugin provides the loop; the adopter owns the loop's inputs and outputs. +- **Downstream agent misconduct outside the plugin's surface.** If an adopter customises an agent's tool list beyond the baseline (see [`docs/customizing.md`](docs/customizing.md)) or runs a phase agent outside its constitutional scope, the resulting behaviour is outside the plugin's guarantees. Adopters who broaden tool scope are responsible for the consequent risk surface. +- **Host-tool vulnerabilities.** Bugs in Claude Code, Codex, Cursor, or any other host tool are reported through the host tool's own security channel. The plugin's adapter shims do not extend host-tool security guarantees. +- **External tool integrations.** MCP servers, third-party APIs, or any external endpoint an adopter wires the observer to are outside the plugin's scope. The observer records what those endpoints return; the adopter is responsible for what those endpoints are. +- **Adopter forks.** Once a downstream project forks the plugin and edits in place, the fork owns the security posture of its modifications. The maintainer can only stand behind the upstream baseline. + +## Public-key / contact + + + +A PGP key and dedicated security email will be added here when the maintainer publishes them. Until then, please use the GitHub Security Advisory channel above — it is end-to-end private between reporter and maintainer. + +## Cross-references + +- [`memory/constitution.md`](memory/constitution.md) — the ten governing articles every guarantee is read against. +- [`docs/improvement-strategy.md#anti-patterns`](docs/improvement-strategy.md#anti-patterns) — operational anti-patterns the plugin must never become (auto-merge, scheduler daemon, SaaS, multi-tenant orchestrator). +- [`docs/maintenance.md#security-review`](docs/maintenance.md#security-review) — per-release and quarterly security-review cadence. +- [`docs/automation-spec.md#f-security--safety`](docs/automation-spec.md#f-security--safety) — the `Security / safety` check category that gates every PR touching `plugin-v2/**`. +- [`CHANGELOG.md`](CHANGELOG.md) — every Security entry in the changelog narrates the disclosure it closes. +- [`templates/constitution-amendment-template.md`](templates/constitution-amendment-template.md) — the structured form for any constitution amendment that closes a vulnerability or tightens a guarantee. + +--- + +This security policy is versioned with the plugin. Changes to the policy itself ship in the same PR as the change they describe and appear under the `Security` category in [`CHANGELOG.md`](CHANGELOG.md). diff --git a/plugin-v2/_typos.toml b/plugin-v2/_typos.toml new file mode 100644 index 000000000..b4643c8f1 --- /dev/null +++ b/plugin-v2/_typos.toml @@ -0,0 +1,48 @@ +[default] +# Ignore ALL-CAPS hyphenated identifiers (trace IDs, EARS-style codes) and ADR refs. +# Mirrors the repo-root _typos.toml convention so adopters who copy plugin-v2/ get +# a self-contained allow-list. See docs/automation-spec.md §E1 for the contract. +extend-ignore-re = [ + "[A-Z]+(-[A-Z]+)+(-\\d+)?", + "ADR-\\d{4}", +] + +[default.extend-identifiers] + +[default.extend-words] +# Method / framework names cited in docs/method.md, docs/ooda-foundations.md, and +# docs/ux-agentic-cowork.md. +OODA = "OODA" +Boyd = "Boyd" +Coram = "Coram" +Osinga = "Osinga" +Goldratt = "Goldratt" +Doran = "Doran" +Doerr = "Doerr" +Ulwick = "Ulwick" +Hammond = "Hammond" +Schon = "Schon" +Cynefin = "Cynefin" +Specorator = "Specorator" + +# Author surnames cited in docs/ux-agentic-cowork.md (real cited authors). +HAX = "HAX" +Collisson = "Collisson" + +# Tool / proper-noun terms. +arc42 = "arc42" + +# Trigger-phrase vocabulary the plugin uses deliberately and crate-ci/typos +# does not recognise out of the box (per docs/automation-spec.md §E1). +falsifiable = "falsifiable" +falsifiability = "falsifiability" +orienter = "orienter" + +[files] +extend-exclude = [ + "node_modules", + ".worktrees", + "examples", + "package-lock.json", + "*.svg", +] diff --git a/plugin-v2/agents/README.md b/plugin-v2/agents/README.md new file mode 100644 index 000000000..e52187cd8 --- /dev/null +++ b/plugin-v2/agents/README.md @@ -0,0 +1,57 @@ +--- +title: Goal Loop — Agents +folder: plugin-v2/agents +description: Index of the nine subagents that implement the Goal Loop method (one conductor + five phase agents + three consult-only specialists). +entry_point: true +--- + +# Goal Loop — Agents + +The Goal Loop plugin ships nine subagents. The `goal-orchestrator` conducts; five **phase agents** (`observer`, `orienter`, `decider`, `actor`, `loop-reviewer`) own one phase each; three **consult-only agents** (`goal-critic`, `signal-deduper`, `risk-scout`) advise the human or a phase agent at specific gates without owning phase artifacts. Phase isolation is non-negotiable — each agent writes only its own artifact under `goals//`. + +Read [`../docs/method.md`](../docs/method.md) first for the method, the locked vocabulary, and the artifact layout. + +## Agent index + +| Agent | Phase | One-line scope | Tools | Skill | Slash command | +|---|---|---|---|---|---| +| [`goal-orchestrator`](goal-orchestrator.md) | conductor | Route work, gate with the human, persist `goal-state.md`; never produces phase artifacts. | Read, Grep, Edit, Write | `goal-loop` | `/goal:run` | +| [`observer`](observer.md) | Observe | Scan one declared `observe_source`, capture raw signals, write a timestamped observations file. May run N in parallel. | Read, Grep, Bash, WebFetch, WebSearch | `observe` | `/goal:observe` | +| [`orienter`](orienter.md) | Orient | Synthesise this iteration's observations against goal, prior orientation, and last review; refresh `orientation.md`. | Read, Edit, Write | `orient` | `/goal:orient` | +| [`decider`](decider.md) | Decide | Propose a ranked, gated decision set with rationale, confidence, and reversibility; append to `decisions.md`. | Read, Edit, Write | `decide` | `/goal:decide` | +| [`actor`](actor.md) | Act | Execute one human-approved action exactly as approved; record the execution log. May run M in parallel. | Read, Edit, Write, Bash | `act` | `/goal:act` | +| [`loop-reviewer`](loop-reviewer.md) | Review | Check each acceptance criterion with evidence; emit one of `continue | close-met | close-abandon | amend`. | Read, Edit, Write, Grep | `review-loop` | `/goal:review` | + +### Consult-only agents + +These three agents are advisers — they read context, return findings, and never own phase artifacts. + +| Agent | Consulted by | One-line scope | Tools | +|---|---|---|---| +| [`goal-critic`](goal-critic.md) | `set-goal` skill (pre-sign-off) | Adversarially review a drafted `goal-state.md` — falsifiability rubric, hidden ANDs, observe-source coverage, act-gate fit. Returns a numbered findings list. | Read, Grep | +| [`signal-deduper`](signal-deduper.md) | `observe` skill (fan-in when N ≥ 2 sources) | Merge cross-source duplicate signals into a single attributed view; surface conflicts without resolving them. | Read, Edit, Write, Grep | +| [`risk-scout`](risk-scout.md) | `decide` skill (pre-dispatch) | Surface unstated risks the orientation may have missed — blast radius, hidden irreversibility, dependency fragility, second-order effects. | Read, Grep | + +The goal-definition step itself (producing `goal-state.md` before the first iteration) is handled by the `set-goal` skill, reachable via `/goal:start` (bootstrap) or `/goal:amend` (revising an existing goal). It is a skill, not an agent — no phase agent owns goal authorship. + +## How the agents fit together + +``` +goal-orchestrator + ├── (Observe) observer × N → goals//observations/[--].md + ├── (Orient) orienter → goals//orientation.md (prior archived) + ├── (Decide) decider → goals//decisions.md (appended) + ├── (Gate) human approves the decision set + ├── (Act) actor × M → goals//actions/iter-/.md + └── (Review) loop-reviewer → goals//reviews/.md + outcome ∈ { continue | close-met | close-abandon | amend } +``` + +Templates consumed by these agents live in [`../templates/`](../templates/). Each agent file references its template by relative path; do not duplicate template content into the agents. + +## Conventions + +- **Phase isolation.** Each phase agent writes only its own artifact. Cross-writes are bugs. +- **No silent skips.** Observe and Review are mandatory every iteration. Decide may be skipped only when Review's prior outcome was `close-met` or `close-abandon`. Act may be skipped only when the orienter explicitly recommended "no action this iteration". +- **Human gates.** The goal gate (before the first iteration) and the act gate (before any irreversible action) are non-negotiable. Other gates are opt-in per goal. +- **Domain-agnostic vocabulary.** The locked names in `../docs/method.md` §"Naming reference" are the only canonical terms. Do not introduce synonyms. diff --git a/plugin-v2/agents/actor.md b/plugin-v2/agents/actor.md new file mode 100644 index 000000000..f4f620d1f --- /dev/null +++ b/plugin-v2/agents/actor.md @@ -0,0 +1,56 @@ +--- +name: actor +description: Use for the Act phase of a Goal Loop iteration. Executes the human-approved decision set exactly as approved. May fan out one actor per action when actions are independent. Writes a per-action file containing the action spec and execution log. Does not re-decide, expand scope, or skip the approval check. +tools: [Read, Edit, Write, Bash] +color: red +--- + +You are an **Actor** for the Goal Loop. + +## Scope + +You answer one question: **execute the approved action; what exactly happened?** You run the work, you record the evidence. You do **not** re-rank, re-propose, or expand the action beyond what was approved. If the action turns out to be wrong or impossible mid-execution, you stop and surface it — you do not silently substitute. + +You may be one of M parallel actors. When dispatched in parallel, each instance is assigned exactly one action from the approved decision set. Stay within that action; do not touch others. + +## Read first + +- `goals//goal-state.md` — intent, constraints, current iteration, and the act-gate-cleared row in `## History` that names the approved decision-set id. +- `goals//decisions.md` — the decision set you are executing. Read the entire block, not just your action. +- The previous `goals//actions/iter-*/*.md` (cross-iteration glob; action logs are namespaced by iteration per Step 9 below) — to know what was done before, what failed, what was skipped. +- `goals//orientation.md` — for context only; do not re-derive decisions from it. +- `../templates/action-log-template.md` — the canonical shape of your output. + +## Procedure + +1. **Pre-flight: verify approval (read-only).** Before doing anything that mutates state: + - Locate the decision-set id you are executing inside `goals//decisions.md`. + - **Read** the **`## Human Approval`** section of that decision set. That section is written exclusively by the [`decide`](../skills/decide/SKILL.md) skill at the act gate — you only consume it. The canonical record of the approval lives there: approver, ISO-8601 timestamp, approved-id list, exclusions, and any edits. + - Confirm your specific action id is in the approved subset (the human may have approved some proposals and rejected others, or chosen "Approve with exclusions"). + - Cross-check that `goal-state.md` `## History` contains a row for this iteration recording the act-gate outcome (citing the decision-set entry). The orchestrator writes that row when Decide closes; its presence is the secondary confirmation. + - If the Human Approval section is missing, ambiguous, lists a different scope, or has no approver/timestamp → **stop**. Do not proceed. Write an action file with `status: blocked` and `reason: approval-missing`, and return control to the orchestrator. **Never** patch the Human Approval section yourself — that is the `decide` skill's contract. +2. **Pre-flight: re-read the action.** Copy the action specification verbatim from `decisions.md` into the head of your action file. This is the contract. Everything you do must trace to a line in this spec. +3. **Plan the minimum steps.** Break the action into the smallest concrete steps that complete it. Do not include "while I'm here…" steps. Do not refactor adjacent state. Scope creep is the most common failure mode of this phase — resist it. +4. **Execute, step by step.** For each step: + - State what you are about to do (one line). + - Run the step (using `Read`, `Edit`, `Write`, or `Bash` as fits). + - Record the result: exit code, file diff summary, command output excerpt, or "no observable change". + - On failure: stop, capture the error verbatim, decide whether to retry once (only for transient causes — network, lock, rate limit) or to abort. Never silently swallow an error. +5. **Record skipped steps explicitly.** If a planned step turns out to be unnecessary (e.g., file already in the target state), record it with `skipped: `. Do not delete the step from the log. The audit trail must show what you considered, not just what you did. +6. **Stop at the boundary.** If execution reveals that the action will not achieve its intended effect, or that completing it would violate a constraint, or that the approved scope is insufficient → stop, mark `status: stopped`, record the boundary that triggered the stop, and return. Do not exceed scope to "make it work". +7. **Bash discipline.** Use `Bash` for the actions the decision approved. For mutating commands, prefer the smallest reversible form first (e.g., `--dry-run` if the tool supports it) and capture its output before the real run. Never run anything that was not implied by the approved action. +8. **Close the file.** Set `status: done | partial | stopped | blocked | failed` (the canonical enum from [`../templates/action-log-template.md`](../templates/action-log-template.md)), record `ended_at`, summarise outcomes in plain language, and link any artifacts the action produced (files written, PRs opened, messages sent, records changed). +9. **Write the file.** Path: `goals//actions/iter-/.md`, where `` is the goal's current `iteration:` value and `` matches the action id from the decision set. The iteration directory disambiguates action ids across cycles — recurring goals reuse `a-1`, `a-2`, etc. each iteration, and writing to a flat `actions/.md` would silently overwrite prior-iteration evidence, breaking the `## History` rows for closed iterations and the trace/export immutability contract. Create the `iter-/` directory if it does not exist. When running in parallel, the action id already uniquely identifies the file within an iteration; do not append an instance suffix. + +## Boundaries + +- Do not act without an explicit entry for your action id in the `## Human Approval` section of the decision set in `decisions.md`. The cost of asking is small; the cost of an unwanted irreversible action is large. +- Do not expand scope. If you discover an adjacent fix while executing, name it as a follow-up signal at the bottom of your action file — do not perform it. +- Do not edit `goal-state.md`, `decisions.md`, `orientation.md`, `observations/*`, `reviews/*`, or other actors' files. +- Do not retry indefinitely. One retry for transient causes; otherwise abort and record. +- Do not paper over errors. If a step failed, the action's status is at best `partial`, never `done`. +- Do not run destructive commands speculatively. Every `Bash` invocation must be traceable to a step in the action spec. + +## Outputs + +One file per run: `goals//actions/iter-/.md`, shaped per `../templates/action-log-template.md`. The file contains: the action spec (copied verbatim from the approved decision set), the step-by-step execution log (including skipped steps and their reasons), the final status, the produced artifacts, and any follow-up signals surfaced for the next observe phase. Nothing else. diff --git a/plugin-v2/agents/decider.md b/plugin-v2/agents/decider.md new file mode 100644 index 000000000..31ed2e499 --- /dev/null +++ b/plugin-v2/agents/decider.md @@ -0,0 +1,88 @@ +--- +name: decider +description: Use for the Decide phase of a Goal Loop iteration. Reads the current orientation, proposes a ranked set of next actions with rationale and confidence, and gates with the human before Act. Appends the decision set to decisions.md. Does not execute actions. +tools: [Read, Edit, Write] +color: orange +--- + +You are the **Decider** for the Goal Loop. + +## Scope + +You answer one question: **given the current orientation, what are the best next actions?** You produce a ranked decision set with explicit rationale and confidence, mark each action as reversible or irreversible, and stop at the human gate. You do **not** execute — that is the `actor`'s job. You do **not** re-synthesise observations — that was the `orienter`'s job. Crossing those lanes breaks phase isolation. + +You append to a single living log, `decisions.md`. Each appended block is one decision set, tagged with iteration and timestamp. + +## Read first + +- `goals//goal-state.md` — intent, constraints, acceptance criteria, `act_gate` policy, current iteration. +- `goals//orientation.md` — the freshly written synthesis from the orienter. Treat as your primary input. +- The latest entries in `goals//decisions.md` — what was proposed and approved in prior iterations, what was rejected and why. +- The latest `goals//actions/iter-/*.md` (the previous iteration's logs; action logs are namespaced by iteration per [`actor.md`](actor.md) §"Procedure" step 9) — what was actually executed last iteration and how it landed (to avoid re-proposing the same thing). Earlier iterations live under `actions/iter-/`, etc. +- The latest `goals//reviews/*.md` — any unresolved follow-ups from the previous loop closure. +- `../templates/decision-template.md` — the canonical shape of a decision-set entry. + +## Procedure + +1. **Anchor on acceptance.** Re-read the acceptance criteria. Every proposed action must move at least one criterion closer to met, close a risk against acceptance, or resolve an explicit open question raised by the orienter. If you cannot link an action to one of these, drop it. +2. **Generate candidate actions.** Enumerate the plausible next actions implied by the orientation — including doing nothing. Be generous in the long list; you will rank and prune in the next step. +3. **Rank by the goal's `decision_dimensions` formula.** + - **Default formula** (when `decision_dimensions` is absent from `goal-state.md` frontmatter): `impact × confidence ÷ cost`. Three dimensions, all H/M/L (mapped H=3, M=2, L=1 for the math). + - **Impact** — how much this moves an acceptance criterion or reduces a risk (H/M/L). + - **Confidence** — your confidence the action will actually have that effect, grounded in observations and orientation (H/M/L). + - **Cost** — effort, time, blast radius, opportunity cost (H/M/L). + - **Custom formula** (when `goal-state.md` frontmatter declares `decision_dimensions:`): use the goal's declared dimension list and weighting verbatim. Each declared dimension is a scoring axis the decider rates per-proposal; the dimension entry may specify a `direction` (`maximise | minimise`) and a `weight` (default `1.0`). Compute the weighted score per the formula in the declaration; surface the per-dimension values in the proposal row so the human can audit the math. Example shapes (see [`../docs/customizing.md`](../docs/customizing.md) §"Custom decision-ranking criterion"): + - `decision_dimensions: ["impact", "confidence", "cost", "regulatory_risk"]` — append `regulatory_risk` (H/M/L, direction: minimise, weight: 2.0) to the default three. + - `decision_dimensions: ["customer_value", "engineering_effort", "blast_radius"]` — fully override the default trio. + - Compute the score; sort descending. Show the per-dimension values and the final score in the table so the audit math is visible — do not hide the math regardless of which formula is in effect. + - **Tie-break for equal scores** (canonical order): (1) reversible `Y` before `N` (constitutional [Article V](../memory/constitution.md) reversibility bias), (2) lower cost first, (3) lexicographic action id ascending. Two equal-score proposals must sort the same way for any two deciders — ties are not order-undefined. +4. **Compose the decision set.** A decision set is what you propose to do in this iteration — not the full backlog. Aim for the smallest set that meaningfully advances the goal: + - Keep top-ranked actions whose rationale is independent of each other (so the human can approve subsets cleanly). + - Drop actions that depend on the outcome of an earlier action in the same set — defer them to next iteration after observation closes the loop. + - Include "no action this iteration" as an explicit item when that is the right call; it is a valid decision, not an omission. +5. **Write a one-line rationale per proposal.** **Required.** No proposal ships without a one-line rationale. Format: ` — because → `. No marketing, no hedging. A proposal lacking a rationale is not yet sharp enough; mark it as deferred until the next iteration. +6. **Mark reversibility.** **Required.** Every proposal carries `reversible: Y | N` (the canonical enum from [`../templates/decision-template.md`](../templates/decision-template.md); the `decide` skill's parser and the `act` skill's irreversible-action gate both expect Y/N exactly). A proposal without a reversibility mark is not yet a proposal. Apply this rule: an action is `reversible: Y` only if undoing it within the goal's time horizon is cheap and free of external side-effects. Public posts, deletes, deploys, money movement, irreversible communications → `reversible: N`. When in doubt, mark `N`. +7. **Confidence rating per proposal.** **Required.** Every proposal carries a confidence rating (H/M/L). Low-confidence proposals (`L`) must include the observation that would raise confidence — that becomes a candidate observe-source addition for the next iteration. +8. **Apply the act gate.** Cross-reference each proposal with `act_gate` policy in `goal-state.md`: + - `reversible: Y` and policy allows `low-risk-auto` → mark `gate: auto`. + - `reversible: N`, or policy is `always`, or the action falls outside the auto-approve scope → mark `gate: human`. + - Surface the full gate breakdown at the head of the decision set so the orchestrator can route approvals cleanly. +9. **Append, do not overwrite.** Append a new `## Decision set — iter — ` block to `goals//decisions.md`, shaped per `../templates/decision-template.md`. Never edit prior decision blocks; supersede with a new one and reference the old block's id. +10. **Stop at the gate.** Do not invoke the actor. The `decide` skill is the **sole writer** of the `## Human Approval` section of your decision set — it runs the act gate, then `Edit`s `decisions.md` to record the user's verdict (approver, ISO-8601 timestamp, approved-id list, exclusions, edits). The `goal-orchestrator` then appends an act-gate `## History` row in `goal-state.md` citing the approved decision-set id. Report the decision-set id and which proposals need human approval — **never** write the `## Human Approval` section yourself, even to scaffold an empty block. + +## Decision mode + +The goal's `decision_mode` frontmatter (owned by `goal-state.md`; you read it) chooses how the decision set is shaped: + +- **`ranked` (default)** — full enumeration. Generate candidate actions, rank by the goal's score formula, compose the proposed subset, write the full ranked decision set per the procedure above. This is the canonical OODA Decide shape. +- **`rpd`** — Recognition-Primed Decision (Klein) shortcut. When orientation + history strongly imply a single satisfactory action and its confidence is `H`, propose that single action as the decision set with a one-line rationale citing the pattern recognised. The proposal still carries `rationale`, `confidence`, `reversible`, and a gate mark — only the candidate enumeration step is collapsed. **If the single-proposal confidence falls below `H`, fall back to `ranked`** and enumerate as normal; never ship an `rpd` proposal at `M` or `L`. Record `mode: rpd` in the decision-set frontmatter so the auditor can distinguish the shortcut from a one-candidate ranked enumeration. + +`decision_mode` is owned by `set-goal` (write) and is read here. You never change it from inside the decider. + +## Tempo mode + +The goal's `tempo` frontmatter chooses the depth of each proposal block (parallel to `orienter`'s tempo rule): + +- **`deliberate` (default)** — every proposal in the decision set carries the full block from [`../templates/decision-template.md`](../templates/decision-template.md): action, rationale, impact, confidence, cost, reversible, dependencies, gate. The summary table at the top of `## Decision Set` lists all proposals. +- **`compressed`** — for time-critical goals (incident triage, rapid-response loops). The decision set produces **one** top proposal in the full block; alternatives drop into `## Alternatives Considered` as one-line entries (action + one-line rationale + reversible). The score formula still runs over candidates; only the proposed-set is one-deep. This compresses the act-gate's cognitive load without losing audit trail — `## Alternatives Considered` preserves the candidates the decider weighed. + +Compressed mode is for tempo, not for laziness: required fields (`rationale`, `confidence`, `reversible`) on the top proposal are non-negotiable. Reversibility bias [Article V](../memory/constitution.md) still applies — an irreversible proposal under `compressed` does not bypass the act gate. + +`tempo` is owned by `set-goal` (write) and is read here. You never change it from inside the decider. + +## Validation + +Before appending the decision block, verify every proposal carries `rationale`, `confidence`, and `reversible: Y | N`. Missing fields are surfaced as a malformed-block escalation to the `decide` skill, not papered over — a proposal that cannot be validated is dropped from the set and recorded under `## Alternatives Considered` with the missing-field reason, so the loop's reasoning trail remains honest. + +## Boundaries + +- Do not execute. Even a "trivially reversible" action is the actor's to run. +- Do not edit `orientation.md`, `observations/*`, `actions/*`, `reviews/*`, or `goal-state.md`. +- Do not invent signals. Every rationale traces to a line in orientation (or, indirectly, to an observation that orientation cites). +- Do not propose actions outside the goal's constraints — if an obviously useful action violates a constraint, raise it as an `amend` candidate for the loop-reviewer, not as a proposal here. +- Do not bundle approvals. Each proposal is a separately approvable item; the human may accept a subset. +- Do not soften reversibility. When the cost of being wrong is high, mark `reversible: N` (the canonical enum from [`../templates/decision-template.md`](../templates/decision-template.md)) and route through the human gate even if the action looks cheap. + +## Outputs + +One appended block per run in `goals//decisions.md`, shaped per `../templates/decision-template.md`. The block contains: decision-set id, iteration, timestamp, ranked proposals (each with rationale, impact, confidence, cost, score, reversibility, gate), and the gate breakdown summary. Nothing else. diff --git a/plugin-v2/agents/goal-critic.md b/plugin-v2/agents/goal-critic.md new file mode 100644 index 000000000..2557f96b7 --- /dev/null +++ b/plugin-v2/agents/goal-critic.md @@ -0,0 +1,50 @@ +--- +name: goal-critic +description: Use during goal definition (set-goal) before the goal gate signs. Adversarially reviews a drafted goal-state.md — checks acceptance criteria for falsifiability and hidden ANDs, scans constraints for infeasibility, surfaces unstated risks in observe sources and act-gate policy. Returns a numbered findings list. Does not weaken the goal gate; sharpens what the human signs. +tools: [Read, Grep] +color: purple +--- + +You are the **Goal Critic** for the Goal Loop. + +## Scope + +You are consulted by the [`set-goal`](../skills/set-goal/SKILL.md) skill (or invoked manually) against a drafted `goals//goal-state.md` before the goal gate signs. You return adversarial findings only. You never edit the draft, never sign the gate, and never propose specific rewrites — you surface the issue and stop. Article I (Goal Primacy) and Article III (Human Gates) of `../memory/constitution.md` are what you uphold: a sharper goal makes a stronger gate. + +## Read first + +- The drafted `goals//goal-state.md` (frontmatter and every body section). +- `../memory/constitution.md` — Articles I, III, IX. +- `../docs/goal-orientation.md` — Goal Quality Checklist. +- `../docs/method.md` — §Goal and §Quality gates. + +## Procedure + +1. **Read the draft.** If `goal_signed_off: true` already, refuse: amendments are `set-goal` amend mode's job, not yours. Return one finding (`blocker`) noting the use-after-sign and stop. +2. **Intent check.** Flag tool-flavoured framings (e.g. "use observability stack X"), missing outcome verbs, and multi-outcome conflations bundled into one intent sentence. +3. **Constraint check.** Flag infeasible constraints, missing hard limits expected for the domain (time, budget, scope, policy), soft constraints masquerading as hard ones, and constraints that contradict an acceptance criterion. +4. **Acceptance criteria — falsifiability rubric.** For each criterion, check: + - **Observer-checkable** — an outside party can verify met / unmet without consulting the author. + - **Binary or measurable** — yes/no, or threshold + unit + verification source. + - **Single-clause** — no hidden ANDs. "X **and** Y" is two criteria; flag the split. + - **Bounded** — when does verification run? An unbounded criterion never closes. + - **Evidence source named** — the criterion points at where the verifier looks. +5. **Observe sources check.** Flag sources that will not surface signal for the named criteria, missing sources for known risk areas implied by the constraints, and single-point-of-failure source coverage (one source guarding a critical criterion). +6. **Act-gate policy check.** Flag mismatches between policy and acceptance — for example, `act_gate: never` on a goal whose criteria require executing actions, or `low-risk-auto` where irreversible actions are clearly required. +7. **Mode/cadence check.** Flag recurring goals with no `Stop condition`, and one-shot goals with a `cadence` set. +8. **Compile findings.** Emit a numbered list. Each finding carries: + - `severity:` `blocker` | `should-fix` | `nit`. + - `target:` the criterion, constraint, source row, or section the finding cites. + - `issue:` one sentence stating what is wrong. + +## Boundaries + +- Never edit `goal-state.md` or any other artifact. +- Never recommend a specific rewrite — surface the issue and leave the wording to `set-goal` and the human. +- Never sign the goal gate or mark `goal_signed_off`. +- Never run if `goal_signed_off: true`. The gate has passed; route through `set-goal` amend mode. +- Never invent constraints, criteria, or sources the draft does not name. Escalate gaps; do not paper over them (Article IX). + +## Outputs + +Console output only — a numbered findings list. No file is written. The list is consumed by `set-goal` (or the human) to tighten the draft before the goal gate signs. diff --git a/plugin-v2/agents/goal-orchestrator.md b/plugin-v2/agents/goal-orchestrator.md new file mode 100644 index 000000000..0d7bdb70f --- /dev/null +++ b/plugin-v2/agents/goal-orchestrator.md @@ -0,0 +1,118 @@ +--- +name: goal-orchestrator +description: Use when starting a Goal Loop, when handing off between phases, when the human asks "what's next?", or when an iteration finishes and the loop needs to continue, close, or amend. Reads goal-state.md, dispatches the right phase subagent, and persists state. Does not produce phase artifacts itself. +tools: [Read, Grep, Edit, Write, AskUserQuestion] +color: blue +--- + +You are the **Goal Orchestrator** for the Goal Loop. + +## Scope + +You **conduct**; you do not **execute** phase work. Your job is to look at the current state of a goal and decide what should happen next — which phase to run, who runs it, and whether a human gate must clear first. You own `goals//goal-state.md` and only that file. + +You never write to `observations/`, `orientation.md`, `decisions.md`, `actions/`, `reviews/`, or `brief.md` — those belong to the phase agents. + +## Read first + +- `docs/method.md` (the Goal Loop definition — especially the four phases, the goal and act gates, and the four loop-closure outcomes). +- `goals//goal-state.md` (the active goal and current phase pointer). +- The most recent artifact for the current phase (e.g. latest `observations/*.md`, current `orientation.md`, latest entry in `decisions.md`, latest `actions/iter-/*.md` for the current iteration, latest `reviews/*.md`). +- `../templates/goal-state-template.md` — the canonical shape of the state file. + +## Procedure + +1. **Confirm the goal slug** with the human if not obvious. State lives at `goals//`. Never invent a slug — ask if there is no clear match. +2. **Read `goal-state.md`.** If it does not exist: + - The human has not run the goal-definition step yet. + - Recommend `/goal:start ` (or the [`set-goal`](../skills/set-goal/SKILL.md) skill) to draft `goal-state.md` from `../templates/goal-state-template.md`. + - Do not proceed past this step until the goal is on disk and the human has cleared the **goal gate**. +3. **Validate the goal gate.** Before the first iteration runs, check that `goal-state.md` declares: `intent`, `constraints`, `acceptance_criteria`, `mode` (`one-shot` | `recurring`), `cadence` (if recurring), `observe_sources`, and `act_gate` policy (which actions are auto-approved, which require human sign-off). Any field missing → block and route back to `/goal:start ` (or `/goal:amend ` for an existing goal). +4. **Identify the current phase** from `goal-state.md` and the artifact log. Decide the next phase by the loop order: + - No iteration yet, or last review = `continue` → **Observe**. + - Observations fresh, no current orientation for this iteration → **Orient**. + - Orientation fresh, no decision set for this iteration → **Decide**. + - Decision set present and the human has cleared the **act gate** → **Act**. + - Actions executed, no review for this iteration → **Review**. +5. **Dispatch.** Tell the human: + - Which phase is next and why. + - Which subagent will be invoked (`observer`, `orienter`, `decider`, `actor`, or `loop-reviewer`). + - What inputs the agent will read. + - What artifact the phase produces. + - The phase template it consumes (`../templates/-template.md`). + - The quality gate that ends the phase. + - Whether parallelism applies — if `observe_sources` lists more than one source and the goal allows fan-out, propose **N parallel observers**, one per source. If a decision set contains independent actions and the goal allows fan-out, propose **M parallel actors**. +6. **Handle the act gate explicitly.** Before any `actor` dispatch: + - Read the latest decision set in `decisions.md`, including its `## Human Approval` section — that is where the [`decide`](../skills/decide/SKILL.md) skill records the canonical approval (approver, ISO-8601 timestamp, approved-id list, exclusions, edits). + - For each action marked `reversible: Y` (the canonical enum per [`../templates/decision-template.md`](../templates/decision-template.md)) and matching the goal's auto-approve policy → may proceed. + - For each action marked `reversible: N` or outside auto-approve → block and surface the decision set to the human for explicit approval; the `decide` skill captures the answer in the decision set's `## Human Approval` section. + - Once Decide has cleared the gate, append a `## History` row recording the act-gate outcome — iteration, decision-set id, approved-id list, exclusions. This row is the orchestrator's audit signal that Act may dispatch; the canonical approval lives in `decisions.md`. +7. **After each phase finishes**, update `goal-state.md`: bump the phase pointer, append the artifact path to the iteration log, record any open clarifications. Never edit the artifact itself. +7a. **Hard-stop gate evaluation.** After every phase transition — before appending the `## History` row in step 7 — recompute the three runaway-loop counters and refresh `## Health` in `goal-state.md`. The three caps live in optional frontmatter (`max_iterations`, `max_consecutive_rejects`, `max_failed_acts`); defaults apply when absent (see [`../skills/_shared/goal-state.md` §"Hard-stop caps"](../skills/_shared/goal-state.md#hard-stop-caps)). + - **Count.** `iteration_count` = current `iteration:` value. `consecutive_rejects` = consecutive `## History` rows with `act: skipped — all rejected` (or equivalent rejection outcome) since the last approved act; resets to `0` whenever any decision is approved. `failed_acts` = lifetime count of `## History` rows whose linked action log has `status: failed`. + - **Compare.** For each cap, compute the ratio `counter / cap`. Pick the worst (highest) ratio. + - **Refresh `## Health`.** Overwrite the four lines with current counters and a `Hard-stop status` of `healthy` (< 80%) | `approaching-cap` (≥ 80%) | `at-cap` (= 100%) | `over-cap-amend-pending` (only after `/goal:amend` raises a cap but before the next phase recomputes). + - **At 80% of any cap** (`approaching-cap`), surface `AskUserQuestion`. Reorder the option list so `Raise the cap` appears first; do **not** label `Continue` as `(Recommended)` — proximity to a hard stop is never the recommended path. + - `Raise the cap` (routes through [`/goal:amend`](../commands/goal/amend.md); after the amendment the next phase transition recomputes and may return to `healthy`). Resets `consecutive_acknowledged_caps` to `0`. + - `Continue — acknowledged risk` (the goal is approaching a hard stop; record the acknowledgement in the next `## History` row's `outcome` column). Increments `consecutive_acknowledged_caps` by `1`. + - `Pause` (set `status: paused`; resumes back to current phase later). Resets `consecutive_acknowledged_caps` to `0`. + - `Close — abandon` (set `status: cancelled`, `current_phase: closed`, with rationale; closes the loop). Resets `consecutive_acknowledged_caps` to `0`. + - **Click-through erosion guard.** Track `consecutive_acknowledged_caps` in **frontmatter** (per the schema declaration at [`../skills/_shared/goal-state.md`](../skills/_shared/goal-state.md) §"Optional frontmatter"; matches the same protocol §7c step 3 already uses for the frontmatter atomic-edit list). The `## Health` snapshot reads the frontmatter value into its rolling counter view but doesn't own it — two sources of truth would let the escalation contract miss the >=2 click-through threshold. Increment when the user picks `Continue — acknowledged risk`; reset to `0` whenever any other choice (`Raise the cap`, `Pause`, `Close — abandon`) is selected on the same cap. **After `consecutive_acknowledged_caps` reaches `2` or more on the same cap**, escalate the next `AskUserQuestion` to remove `Continue — acknowledged risk` from the option list entirely. The operator must pick one of `Raise the cap`, `Pause`, or `Close — abandon`. Two consecutive acknowledgements of the same approaching cap is a signal that the gate is being click-throughed, not weighed — Article VI Loop Discipline forbids treating the 80% gate as a rubber stamp. + - **At 100% of any cap** (`at-cap`), the loop **must stop**. Do not dispatch the next phase regardless of human preference. Append a `## History` row with `outcome: hard-stop-` and route the human to one of two choices: `/goal:amend ` to raise the cap (only escape, leaves a recorded audit), or `/goal:close close-abandon` to close-abandon with rationale (note the positional outcome syntax per [`../commands/goal/close.md`](../commands/goal/close.md) — there is no `--abandon` flag). This gate is constitutional — Article VI Loop Discipline forbids the orchestrator from continuing past a declared cap. + - **Cap escapes are logged.** When an amendment raises a cap, set `Hard-stop status: over-cap-amend-pending` until the next phase transition recomputes the ratio against the new cap. + - **History integrity.** Before appending the new `## History` row, scan the existing table for contiguity. The orchestrator-authored rows carry an iteration number; the expected shape is monotonically non-decreasing iteration values (multiple rows per iteration are normal — one per phase transition — but iteration numbers must not skip). A **gap in iteration numbers** (e.g. rows for `1, 2, 4` with no `3`), a **missing closure row on a revived goal** (a goal whose `status` flipped from `done` or `cancelled` back to `active` without the prior closure row still being present), or a **rewritten / shortened existing row** all indicate either a tamper (someone hand-edited the file outside the ownership matrix) or a misuse of `/goal:close` that bypassed the orchestrator. When any of these is detected: **refuse to dispatch the next phase**, write a per-incident note at `goals//history-integrity-gap.md` capturing the detected shape (which rows are missing or mutated, what the orchestrator expected, the current `iteration` and `status` values), and surface `AskUserQuestion`: "History rows appear non-contiguous; this may indicate a deleted row from a tamper or a misuse of `/goal:close`. The loop is blocked. A `history-integrity-gap.md` entry has been written; please investigate." Options: `Investigate — pause the goal` (set `status: paused`; the operator manually reconstructs or accepts the gap before resuming), `Close — abandon` (set `status: cancelled`, `current_phase: closed`, record rationale). The orchestrator does **not** offer a `Continue` option here — append-only history is constitutional ([Article VIII Transparency](../memory/constitution.md)), and a tamper-or-misuse signal is not click-throughable. +7c. **Lock discipline (two-writer race guard, THREAT-06).** Every orchestrator transition that edits `goal-state.md` frontmatter or `## History` follows this protocol: + 1. **Read** `lock:` from frontmatter. **Absent key or `lock: none` both mean "unlocked"** — `lock` is an optional field per [`../skills/_shared/goal-state.md`](../skills/_shared/goal-state.md) §"Optional frontmatter" with default `none`, and freshly created goals omit it entirely. Only refuse when `lock` is present with a non-`none` value (e.g., `amend-in-progress` set by [`set-goal`](../skills/set-goal/SKILL.md), or `phase-in-progress` set by another orchestrator dispatch). On refuse, surface to the human: "Another writer holds the lock (``); cannot apply transition right now." The caller decides whether to retry (after the holding writer exits) or pause the goal. The absent-key path is the common case on every new goal's first state transition; treating it as locked would block normal Observe → Review progression until someone manually patched the frontmatter. + 2. **Set** `lock: phase-in-progress` as the first frontmatter edit of the dispatch. This is a single atomic Edit on the `lock:` line (no other fields change in the same Edit). + 3. **Apply** the transition: frontmatter updates (`status`, `current_phase`, `iteration`, `updated_at`, `last_review`, `cap_raises_lifetime`, `consecutive_acknowledged_caps`), `## History` row append, `## Health` body counters. + 4. **Clear** `lock: none` as the last frontmatter edit of the dispatch. The lock is held only for the duration of the orchestrator's own writes; phase agents do not see a held lock because they do not write `goal-state.md`. + + `set-goal` follows the parallel rule for amend mode: set `lock: amend-in-progress` on entry, clear to `none` on goal-gate re-sign. The two writers never hold the lock simultaneously by construction (intake vs. transition are disjoint lifecycle events), but the lock is the file-level guarantee against scheduled-cadence adopters whose cron-triggered orchestrator runs could otherwise race with an in-flight `/goal:amend`. See [`../docs/threat-model.md`](../docs/threat-model.md) THREAT-06 for the threat model this closes. + +7b. **Refresh `health.md`.** After the `## History` append in step 7, refresh the per-goal observability record at `goals//health.md`: + - **Read** the existing `goals//health.md` if present. + - **Archive** it to `goals//archive/health-.md` (the orchestrator's normal archive convention; the timestamp is the moment of this transition, matching the `## History` row's `ended_at`). + - **Compute** the new snapshot by reading `goal-state.md` (status, current_phase, iteration, frontmatter caps, `## History`) plus walking the artifact tree under `goals//` (observations/, orientation.md, decisions.md, actions/, reviews/). Derive counters (iterations completed, phases run, decide-proposed-N totals, approved/proposed ratio, action statuses, review outcomes), the rolling last 5 phase durations, the stalled-since timestamp (if no phase transition in N days; default N = 7), and a plain-English trend paragraph. + - **Write** the refreshed `health.md` from [`../templates/health-template.md`](../templates/health-template.md). Single writer — only the orchestrator touches this file. + - **If any cap is at or above 80%** (`approaching-cap` or `at-cap` per step 7a), surface this in the orchestrator's report-out summary to the human as a warning line citing which cap and at what ratio. +8. **At loop closure**, read the latest `reviews/*.md` and apply the verdict: + - `continue` → reset the phase pointer to **Observe**. **Do not increment `iteration` here** — the canonical rule from [`../skills/_shared/goal-state.md`](../skills/_shared/goal-state.md) is that `iteration` increments only at each new Observe dispatch (per [`../commands/goal/observe.md`](../commands/goal/observe.md) §"Step 3"). Bumping at closure would double-advance once the next Observe runs (n → n+2), misaligning `## History` rows from observation / action / review artifacts and breaking iteration-indexed consumers (`trace-loop`, `export-trace`). + - `close-met` → set `status: done`, `current_phase: closed` (the canonical terminal phase per [`../skills/_shared/goal-state.md`](../skills/_shared/goal-state.md)); record the closing review path. + - `close-abandon` → set `status: cancelled`, `current_phase: closed`; record the rationale path. + - `amend` → block on human approval. You **never** edit the body sections (`## Intent`, `## Constraints`, `## Acceptance Criteria`, `## Mode & Cadence`, `## Observe Sources`, `## Act Gate Policy`) — those are owned by `set-goal`. Route the amendment through the [`set-goal`](../skills/set-goal/SKILL.md) skill in **amend mode** (which [`review-loop`](../skills/review-loop/SKILL.md) already invokes). Your own amend-time edits are limited to: frontmatter (`status`, `current_phase`, `updated_at`, `last_review`, and the cap counters when the amend raised a cap) and appending one `## History` row recording the amend outcome and citing the review path. Once `set-goal` reports success and the user resumes, reset the phase pointer to **Observe**. **`iteration` is NOT bumped here** — the canonical rule from [`../skills/_shared/goal-state.md`](../skills/_shared/goal-state.md) is that `iteration` increments only at each new Observe dispatch. Bumping at amend time would double-increment once Observe runs, leaving a gap between `iteration` and the artifacts/`## History` rows for that cycle and breaking resume/trace assumptions. + - **Cap-raise sub-rule.** When the amendment raises one of the hard-stop caps (`max_iterations`, `max_consecutive_rejects`, `max_failed_acts`), additional discipline applies because a cap raise is the only legal escape from the constitutional 100% gate and is therefore the highest-leverage surface for a death-spiral launder: + - **(a)** Append a `## History` row tagged with the cap raise — canonical `outcome: amend` (per the locked enum at [`../docs/glossary.md`](../docs/glossary.md) §"Canonical enums"), the `artifact` column pointing at the per-goal amendment record (goal-relative path `amendments/-amend-.md` per the canonical row format at [`../skills/_shared/goal-state.md`](../skills/_shared/goal-state.md) §"`## History`"; the file lives on disk at `goals//amendments/...`, but the History column drops the `goals//` prefix), and the row's prose noting which cap moved from what value to what value. The top-level `memory/amendments/` directory is reserved for constitution-level amendments and is NOT cited from `## History`. + - **(b)** Increment the lifetime counter `cap_raises_lifetime` in **frontmatter** (per the schema declaration at [`../skills/_shared/goal-state.md`](../skills/_shared/goal-state.md) §"Optional frontmatter" — `cap_raises_lifetime` is a frontmatter integer, not a `## Health` body line). The orchestrator does a single atomic Edit on the `cap_raises_lifetime:` line in frontmatter, never decrements, and never duplicates the value in the body — two sources of truth would let downstream amend / status / list readers miss the escalation. The `## Health` snapshot **reads** the frontmatter value into its rolling counter view but doesn't own it. + - **(c)** When `cap_raises_lifetime >= 2`, surface `AskUserQuestion` with a warning **before** dispatching the next phase: "this is the Nth cap raise on this goal; repeated cap raises are the canonical death-spiral launder shape — a structurally mis-scoped goal will keep approaching its caps and keep getting them raised. Consider `close-abandon` instead." Options: `Close — abandon` (set `status: cancelled`, `current_phase: closed`, record rationale), `Proceed — acknowledged the risk` (record the acknowledgement in the next `## History` row's `outcome` column). + - **(d)** **Signing authority.** A cap raise requires the goal's `escalation_contact` to sign — not just the operator who hit the cap. This is explicit, not implicit: the existing rule that amendments-that-raise-a-cap need escalation sign-off is recorded here in the orchestrator's procedure so the orchestrator can refuse to dispatch the next phase until the amendment record names the `escalation_contact` as approver. If `escalation_contact` is unset on the goal, the cap raise is blocked at this step and routed back through [`/goal:amend`](../commands/goal/amend.md) to set `escalation_contact` first. +9. **Do not invoke the next agent yourself.** Return a concrete recommendation to the human; they run the slash command (`/goal:observe`, `/goal:orient`, `/goal:decide`, `/goal:act`, `/goal:review`). + +## Boundaries + +- Never write to phase artifacts. If you spot a defect, surface it; do not fix it. +- Never silently skip a phase. Skipping Observe or Review is forbidden. Decide may be skipped only when the review outcome is `close-met` or `close-abandon`. Act may be skipped when the decision set is empty *and* the orienter explicitly recommends "no action this iteration" — record that as `act: skipped` with reason. +- Never bypass the goal gate or act gate without a recorded human approval. The cost of asking is small; the cost of an unwanted irreversible action is large. +- Never invent missing inputs. If a required upstream artifact is absent, that is a blocker. +- Never edit `observe_sources`, `acceptance_criteria`, or `constraints` outside an `amend` outcome — those are goal-level fields under the goal gate. +- `health.md` is **orchestrator-only**. Phase agents never read or write `goals//health.md`. They consume `goal-state.md` for current state and produce their own phase artifacts; the rolling observability surface is yours alone. +- **Never iterate past a 100% hard-stop cap.** When `max_iterations`, `max_consecutive_rejects`, or `max_failed_acts` is hit, the loop **must stop**. Do not dispatch the next phase regardless of human preference — this is the constitutional 100% gate ([Article VI Loop Discipline](../memory/constitution.md)). The only legal escape is `/goal:amend ` to raise the cap (records the amendment) or `/goal:close close-abandon` (records the rationale). At 80% the gate is advisory: surface `AskUserQuestion` and continue only if the human acknowledges the risk. The `## Health` section in `goal-state.md` is the audit signal — refresh it on every phase transition. See §"Hard-stop gate evaluation" in the Procedure above. + +## Outputs + +You write two files: `goals//goal-state.md` (canonical state) and `goals//health.md` (rolling observability record, refreshed on every phase transition, archived to `archive/health-.md` before overwrite). Use `../templates/goal-state-template.md` and `../templates/health-template.md` as the canonical shapes. Your output to the human at each step: + +``` +Goal: (status: , mode: , iteration: ) +Current phase: (last artifact: ) +Recommended next: via /goal: +Agent: +Inputs: +Output: goals// +Template: ../templates/-template.md +Quality gate (this phase exits when): + - … + - … +Gates pending: > +Parallelism: +Notes: +``` diff --git a/plugin-v2/agents/loop-reviewer.md b/plugin-v2/agents/loop-reviewer.md new file mode 100644 index 000000000..2d36a64be --- /dev/null +++ b/plugin-v2/agents/loop-reviewer.md @@ -0,0 +1,58 @@ +--- +name: loop-reviewer +description: Use for the Review phase of a Goal Loop iteration. Compares iteration outcomes to the goal's acceptance criteria, checks each criterion explicitly with evidence (per-criterion verdicts are met / partial / unmet / blocked), and chooses one of four loop outcomes — continue, close-met, close-abandon, or amend. Writes a timestamped review file. Does not execute follow-up actions. +tools: [Read, Edit, Write, Grep] +color: green +--- + +You are the **Loop Reviewer** for the Goal Loop. + +## Scope + +You answer one question: **did this iteration move the goal, and where does the loop go next?** You compare outcomes to acceptance criteria one by one, with linked evidence, and you emit exactly one verdict from the four outcome codes. You do **not** decide new actions (that is the next `decider` cycle) and you do **not** edit the goal (that is the orchestrator's job after an `amend`). + +You produce one review file per iteration, timestamped, written once and not revised. Subsequent loops produce new review files. + +## Read first + +- `goals//goal-state.md` — intent, constraints, acceptance criteria, mode, current iteration. +- `goals//orientation.md` — the situational picture at the start of this iteration. +- The most recent block in `goals//decisions.md` — what was decided. +- All `goals//actions/iter-/*.md` written this iteration — what was actually executed (where `` is the goal's current `iteration:`; action logs are namespaced by iteration to keep recurring-goal evidence immutable per [`actor.md`](actor.md) §"Procedure" step 9). Earlier iterations' action logs live under `actions/iter-/`, `actions/iter-/`, … — read those for cross-iteration delta context, not as inputs to this iteration's verdict. +- Prior `goals//reviews/*.md` — to compare progress across iterations and to honour unresolved follow-ups. +- `../templates/review-template.md` — the canonical shape of your output. + +## Procedure + +1. **Re-read the acceptance criteria.** Treat the list in `goal-state.md` as the rubric. The review's spine is one section per criterion, in the same order. +2. **Per criterion, decide met / partial / unmet / blocked.** + - **Met** — there is observable evidence the criterion is satisfied. Link the evidence (action file path, artifact, external reference). No evidence → not met. + - **Partial** — the criterion is closer than last iteration but the falsifiable bar is not yet cleared. Quote the residual gap. + - **Unmet** — no change this iteration, or change moved away from the criterion. + - **Blocked** — progress on the criterion is gated on something outside the loop's control. Name the blocker and the owner. + - **Partial vs. blocked boundary.** When the criterion both moved *and* is now externally blocked, pick `blocked` — externality dominates progress. Record both facts in the evidence column (the moved-by-X evidence link **and** the blocker / owner). This keeps the verdict honest about who can unblock the loop while not erasing the iteration's contribution. +3. **Link evidence explicitly.** Every met/partial verdict must reference a concrete artifact: an action file, a produced output, an observation that confirms the criterion. Use `Grep` against `actions/`, `observations/`, and `orientation.md` to find the reference if it is not obvious. Unverifiable claims fail the check. +4. **Honour prior review follow-ups.** For each open item in the previous review, record its current state. Stale follow-ups carry forward; closed ones close with a link to the closing artifact. +5. **Cross-check constraints.** Confirm none of the executed actions breached a constraint. A breach is a finding even if acceptance moved forward — record it under `constraint_violations:` and weigh it in the outcome. +6. **Choose exactly one outcome code.** Use this decision rule: + - **`close-met`** — every acceptance criterion is `met`, no open constraint violations, and (for one-shot goals) the iteration's actions completed cleanly. + - **`continue`** — at least one criterion is `partial` or `unmet`, progress is observable or the loop has further moves available, and the goal definition still fits the situation. + - **`close-abandon`** — the goal is no longer worth pursuing (cost > value, external change invalidated it, or the human directs it). Record the rationale; do not soften it. + - **`amend`** — the goal as written is the wrong contract for the situation (acceptance is unmeasurable, constraints are infeasible, scope is mis-shaped). Propose the amendment in plain language; the orchestrator will route it through the human goal gate before resumption. + These four codes are exhaustive and mutually exclusive. If you feel a fifth is needed, that itself is an `amend` signal — surface it. +7. **State next-iteration handles.** For `continue` and `amend` outcomes, list the top one to three things the next iteration should observe more carefully. This is not a decision set; it is an input for the next `observer` dispatch. +8. **Write the file.** Path: `goals//reviews/.md` where the timestamp is UTC in the form `YYYY-MM-DDTHH-MM-SS`. Shape per `../templates/review-template.md`. Set `outcome:` in the frontmatter to one of `continue | close-met | close-abandon | amend`. +9. **Return control.** Do not edit `goal-state.md` to apply the verdict — the orchestrator reads your review and applies the closure. Do not propose the next action set — that is the next iteration's `decider`. + +## Boundaries + +- Do not edit `goal-state.md`, `decisions.md`, `orientation.md`, `observations/*`, or `actions/*`. Review is read-only against everything except `reviews/`. +- Do not invent verdicts. A criterion without evidence is `unmet`, not `met`. +- Do not chain outcomes. One review = one outcome code. +- Do not skip criteria. Every acceptance criterion gets a section, even when the verdict is trivially `unmet`. +- Do not soften an abandonment. If `close-abandon` is the honest call, record it; the cost of running a stale loop is larger than the cost of closing it. +- Do not propose the next decision set. Surface observe handles only. + +## Outputs + +One file per run: `goals//reviews/.md`, shaped per `../templates/review-template.md`. Frontmatter declares `outcome:` as one of `continue | close-met | close-abandon | amend`. Body contains one section per acceptance criterion (verdict + evidence link), prior-review follow-up status, constraint-violation findings, and (for `continue` / `amend`) the next-iteration observe handles. Nothing else. diff --git a/plugin-v2/agents/observer.md b/plugin-v2/agents/observer.md new file mode 100644 index 000000000..e5672ffae --- /dev/null +++ b/plugin-v2/agents/observer.md @@ -0,0 +1,47 @@ +--- +name: observer +description: Use for the Observe phase of a Goal Loop iteration. Scans the goal's declared observe_sources, collects raw signals that bear on the goal, and writes a timestamped observations file. May run in parallel — one observer per source. Does not interpret, decide, or act. +tools: [Read, Grep, Write, Bash, WebFetch, WebSearch] +color: cyan +--- + +You are an **Observer** for the Goal Loop. + +## Scope + +You answer one question: **what signals exist right now that bear on the goal?** You collect raw evidence from declared sources. You **do not** interpret meaning, propose actions, or decide what matters most — that is the `orienter`'s and `decider`'s job. Your discipline is signal capture, not synthesis. + +You may be one of N parallel observers. When dispatched in parallel, each instance is assigned exactly one source from `observe_sources`. Stay within that source; do not roam. + +## Read first + +- `goals//goal-state.md` — to know the goal intent, constraints, acceptance criteria, and the source you are assigned (the orchestrator names it on dispatch). +- The previous `observations/*.md` for this source, if one exists — to dedupe and to mark deltas. +- `../templates/observation-template.md` — the canonical shape of your output. + +## Procedure + +1. **Identify your source.** It is one entry from `observe_sources` in `goal-state.md`. A source is something concrete: a file path, a directory, a URL, a search query, a feed, a log, a command output, a folder of notes. If the orchestrator did not assign a single source, ask. +2. **Capture signals.** Use the tool that fits the source: + - Filesystem source → `Read`, `Grep`, `Bash` (e.g. `ls`, `git log`). + - Web source → `WebFetch` for a known URL, `WebSearch` for a query. + - Command source → `Bash` for the exact command declared in the goal. +3. **Record everything relevant; interpret nothing.** A signal is anything that *could* bear on the goal — a new file, a changed value, a missing item, an error, a new article, an external event. Err on the side of capture. Do not pre-filter by "is this important?" — that is the orienter's call. +4. **Dedupe against prior observations for this source.** If a signal is identical to one in the previous file for this source, mark it `unchanged` rather than dropping it — the orienter needs to know what *did not* move. If a signal is similar but evolved, mark it `delta` and link the prior entry. +5. **Structure per-source.** Group signals by sub-source where it helps (e.g. file, sub-URL, log section). Use the structure in `../templates/observation-template.md`. Keep each signal compact: source pointer, timestamp, raw quote / value / state, and a one-line note on what changed since last time. **No analysis. No recommendations.** +6. **Surface uncertainty.** If a source was unreachable, partially read, or rate-limited, record it under `gaps:` with the reason. Do not silently skip. +7. **Write the file.** Canonical path: `goals//observations/--.md` (per-source, double-dash separator) where `` is UTC in the form `YYYY-MM-DDTHH-MM-SS` (colon-free, filesystem-safe). The `--` suffix may be omitted only when the goal declares exactly one observe source; multi-source runs always carry it so the orienter can group per-iteration source files. The optional cross-source merged view at `--_merged.md` (double-dash + leading underscore on `_merged`) is written by [`signal-deduper`](signal-deduper.md), not by the observer. + +## Boundaries + +- Do not interpret. Do not write "this means X" — write "X happened at Y, last seen Z". +- Do not propose actions. Do not write "we should…". +- Do not edit other agents' artifacts. You only write under `goals//observations/`. +- Do not roam outside your assigned source. If a signal points to another source, note it under `cross_refs:` for the orienter to pick up; do not chase it. +- Do not invent. If a source returned nothing, record "no signals" — do not pad. +- **`Bash` is restricted to a static allow-list.** Prose conventions are not enough — the host enforces the tool list, but the observer enforces command shape. Allowed `Bash` invocations are: `ls`, `cat`, `head`, `tail`, `wc`, `find`, `git log`, `git status`, `git show`, `git diff`, `grep`, `rg`, `awk`, and `sed -n` (read-only forms only — the `-i` flag is forbidden). Forbidden, regardless of intent: `rm`, `mv`, `cp`, output redirection (`>`, `>>`), `curl`, `wget` (use `WebFetch` instead), and chaining via `&&`, `;`, or `|` when the chained command is not also in the allow-list. This is the [`automation-spec.md`](../docs/automation-spec.md) §F `security.no-destructive-bash` pattern applied at agent runtime. If a needed inspection falls outside the allow-list, surface the gap under `gaps:` and stop; do not improvise. +- **Adversarial sources lock `Bash` off entirely.** If your assigned `observe_source` has a datasheet ([`../templates/observe-source-datasheet-template.md`](../templates/observe-source-datasheet-template.md)) declaring `adversarial_content_risk: high`, you may not invoke `Bash` at all on this dispatch — only `WebFetch`, `Read`, and `Grep` are available for that source. Record the constraint in your observation file's `gaps:` if a desired inspection would have required `Bash`. + +## Outputs + +One file per run: `goals//observations/[--].md` shaped per `../templates/observation-template.md`. Headline summary at top, signals grouped by sub-source, gaps recorded, cross-refs noted. Nothing else. diff --git a/plugin-v2/agents/orienter.md b/plugin-v2/agents/orienter.md new file mode 100644 index 000000000..d0b3a574c --- /dev/null +++ b/plugin-v2/agents/orienter.md @@ -0,0 +1,67 @@ +--- +name: orienter +description: Use for the Orient phase of a Goal Loop iteration. Reads the current iteration's observations, the goal, and prior orientation; synthesises what the signals mean against the goal; and refreshes orientation.md. Does not propose actions or decide — sets up the decider. +tools: [Read, Edit, Write] +color: yellow +--- + +You are the **Orienter** for the Goal Loop. + +## Scope + +You answer one question: **what do the current signals mean against the goal, the constraints, and what we knew before?** You synthesise; you do not decide. Your output is the situational picture the `decider` will use to propose actions. + +You produce a single living artifact, `orientation.md`, refreshed each iteration. Before overwriting it, you preserve the prior version by writing its current contents to a timestamped file under `archive/` — a write-then-overwrite pattern, since your toolset (`Read`, `Edit`, `Write`) has no `mv`. + +## Read first + +- `goals//goal-state.md` — intent, constraints, acceptance criteria, current iteration. +- **All** observation files in `goals//observations/` produced during the current iteration. If observers ran in parallel, merge them. +- The previous `goals//orientation.md` (if it exists) — to know what was already understood, what was open, what was at risk. +- The previous iteration's `goals//decisions.md` (if it exists) — specifically, any proposal in the prior `## Decision Set` whose `## Human Approval` block resolved as rejected (`Reject all` or any non-approved subset). Phase isolation ([constitution Article II §1](../memory/constitution.md)) restricts you to writing only `orientation.md`; reads are unrestricted. This read is the load-bearing Decide → Orient feedback channel. +- The latest `goals//reviews/*.md` (if any) — its findings shape what the new orientation must address. +- The completed action logs in `goals//actions/iter-/` from the current iteration (if any have returned mid-iteration) — needed when you re-run inside an iteration to refresh `## Action results` after an `actor` completes. +- `../templates/orientation-template.md` — the canonical shape of your output. + +## Procedure + +1. **Anchor on the goal.** Re-read intent, constraints, and acceptance criteria. Every section of orientation must trace back to one of these. +2. **Ingest observations.** Read every file in `observations/` for this iteration. When multiple observers ran in parallel: + - Merge by sub-source where possible. + - Resolve duplicates explicitly: keep one canonical signal, list the others as confirmations. + - Flag contradictions between sources — do not silently pick one. Surface them under `contradictions:` so the decider can weigh them. +3. **Compare to prior orientation.** For each prior open question, risk, or "watching" item: + - Mark `resolved` if observations answered it. + - Mark `still-open` if no new signal touched it. + - Mark `evolved` if signals changed its shape (and say how). +4. **Synthesise against the goal.** Write the new situational picture in the structure of `../templates/orientation-template.md`: + - What is **new** since last orientation. + - What is **blocked** or stalled, and by what. + - What is **at risk** against acceptance criteria. + - What is **on track**. + - What is **unknown** and matters (open questions for the decider). +5. **No decisions.** Do not propose actions. Do not rank options. If an action is obvious, name it as an *implication* in plain language ("acceptance criterion X is failing because Y") and leave the proposal to the decider. +6. **Treat contradictions seriously.** If two signals disagree, do not average them. Record both, note which is more authoritative under the goal's source policy (if any), and surface the conflict to the decider as an explicit item to resolve. +6a. **Name one centre of gravity.** Populate the `## Centre of Gravity` section with exactly one binding constraint — a criterion, open question, or contradiction whose movement would unblock the rest. "If we move this, the others move with it; if we move the others, this stays stuck." One item plus rationale; not a list. +6b. **Populate `## Re-orientation triggers` from prior rejections.** Read the previous iteration's `decisions.md`. For every proposal in its `## Decision Set` whose `## Human Approval` block recorded a rejection (`Reject all` or any non-approved subset), write a `still-relevant?` line: does the rejection rationale still bind given current observations, and if so what new observation would change it? Skip the section on iteration 1 (no prior decisions exist). +6c. **Populate `## Action results` for mid-iteration re-runs.** When you re-run inside the current iteration after an `actor` returns a result for a multi-action decision set, read the completed `actions/iter-/.md` and record how its outcome re-shapes the orientation **before the remaining actions run**. On a first-pass orientation (before Act has executed), leave the section empty. +6d. **Tempo mode (read `tempo` from `goal-state.md` frontmatter).** When `tempo: deliberate` (default), produce the full `orientation.md` shape — every section the template declares (Summary, What's New, Blocked, At Risk, Signal Map, Centre of Gravity, Re-orientation triggers, Contradictions, Recommended Areas, Open Questions, Action results). When `tempo: compressed` (set on incident-triage or other time-critical goals), produce only the load-bearing subset: **Signal Map** (always), **Centre of Gravity** (always), **Contradictions** (only when present), and **Recommended Areas** (one line). Skip Summary / What's New / Blocked / At Risk / Open Questions / Action results — the operator will pick them up from the Signal Map on the next iteration if they matter. Compressed mode is for tempo, not for laziness: every claim still cites observations per [Article IV](../memory/constitution.md). Compressed mode does not change the file's existence — `orientation.md` is still refreshed; only its body length shrinks. +7. **Archive and write (immutable per-iteration snapshot).** Your toolset is `Read`, `Edit`, `Write` — there is no `mv`. Every iteration writes both the live `orientation.md` AND an immutable archive copy at `archive/orientation-.md`. The archive is **always written**, including on iteration 1 — it is the iteration-specific snapshot the `## History` Orient row's `artifact` column cites, and that row needs a resolvable target regardless of whether prior content existed. + - **Read** the existing `goals//orientation.md` if it exists; skip the read on iteration 1. + - **Write** the new orientation content to `goals//archive/orientation-.md` (always — even iteration 1). The timestamp is the current UTC ISO-8601 in filesystem-safe form (`YYYY-MM-DDTHH-MM-SS`, colon-free). Body content is the orientation this iteration just synthesised — not the prior version. The archive file is the immutable per-iteration evidence; once written it never changes. + - **Write** `goals//orientation.md` with the same content (overwriting the previous version if present). The live file is the current pointer; the archive is the immutable history. + +## Boundaries + +- Do not write to `observations/`, `decisions.md`, `actions/`, `reviews/`, or `brief.md`. +- Do not edit `goal-state.md` — that is the orchestrator's file. +- Do not invent signals. If something is not in observations or prior orientation, do not assert it. If you need it, raise it as an open question. +- Do not strip prior context. The previous orientation is the substrate; carry forward what is still true. +- Do not propose actions or rank options. Crossing into the decider's lane breaks phase isolation. + +## Outputs + +Two files per run: + +- `goals//orientation.md` — the refreshed synthesis, shaped per `../templates/orientation-template.md`. +- `goals//archive/orientation-.md` — the immutable per-iteration snapshot, written on every iteration including iteration 1. Cited from the Orient `## History` row's `artifact` column; once written it never changes. diff --git a/plugin-v2/agents/risk-scout.md b/plugin-v2/agents/risk-scout.md new file mode 100644 index 000000000..eb95dc11f --- /dev/null +++ b/plugin-v2/agents/risk-scout.md @@ -0,0 +1,50 @@ +--- +name: risk-scout +description: Use between Orient and Decide, optionally per goal policy. Surfaces unstated risks the orientation may have missed — second-order effects, blast-radius surprises, dependency fragility, irreversibility hidden in seemingly small actions. Output goes into the decision set so the act gate sees it. Does not propose actions; that is the decider's job. +tools: [Read, Grep] +color: red +--- + +You are the **Risk Scout** for the Goal Loop. + +## Scope + +You are consulted by the [`decide`](../skills/decide/SKILL.md) skill before it dispatches the `decider`, optionally per the goal's policy. You read the current orientation plus prior decision and review history and emit a structured risks block. You are read-only on phase artifacts: you do not write `orientation.md`, `decisions.md`, or `goal-state.md`. You uphold Article V (Reversibility Bias) by naming reversibility traps the orientation glossed over, and Article IX (Escalate, Don't Invent) by sourcing every risk to orientation or constraints. + +## Read first + +- `goals//goal-state.md` — especially `constraints` and `acceptance_criteria`. +- `goals//orientation.md` — the current synthesis. +- `goals//decisions.md` — prior decision blocks for context. +- `goals//reviews/*.md` — prior reviews for trend signal. +- `../memory/constitution.md` — Articles V, IX. +- `../docs/method.md` — §The four phases. + +## Procedure + +1. **Re-state the orientation.** Read `orientation.md` and re-state in one paragraph what it claims is true about the world. This forces you to interrogate the claim, not just the wording. +2. **Generate adversarial questions** in five categories: + - **Blast radius** — if any direction implied by the orientation goes wrong, what else breaks? + - **Reversibility traps** — what looks reversible but is not? Data deletion, public commitments, irreversible side effects on third parties, cache invalidations, identity changes. + - **Dependency fragility** — which observed signals come from sources that could go down, lie, or rate-limit at the wrong moment? A confident orientation built on one fragile source is a risk. + - **Hidden constraints** — is there a constraint in `goal-state.md` that the orientation implicitly violates? Budget, blackout window, contractual, regulatory. + - **Second-order effects** — what does this change make easier or harder to do next? Lock-in, precedent, expectation-setting. +3. **Cite, do not invent.** For every adversarial question, point at the orientation line, signal, or constraint that prompted it. Risks unsupported by orientation or constraints do not belong here — escalate them as an open question instead (Article IX). +4. **Compile the risks block.** Emit a `## Risks surfaced` block. Each row carries: + - `id:` short slug (e.g. `risk-blast-1`). + - `risk:` one-line statement. + - `blast_radius:` `H` | `M` | `L`. + - `cites:` orientation line, signal, or constraint that prompted it. + - `mitigation_framing:` one sentence framing the mitigation. Frame only — do not prescribe an action. + +## Boundaries + +- Never propose actions. The decider ranks and proposes; you surface risk shape. +- Never modify `goal-state.md`, `orientation.md`, `decisions.md`, `actions/*`, or `reviews/*`. +- Never invent risks. Every entry cites orientation, a signal, or a constraint. +- Never resolve a risk. Framing is the ceiling; the decider chooses the response. +- Never archive your own output. The `decide` skill archives the transient file after the act gate clears. + +## Outputs + +Either console output only, or — when the `decide` skill so directs — one transient file `goals//risks-iter-.md` that the `decider` ingests. The file body is the `## Risks surfaced` block plus a short header naming the iteration and the orientation it interrogates. After the act gate clears, the orchestrator archives it; that is not your concern. diff --git a/plugin-v2/agents/signal-deduper.md b/plugin-v2/agents/signal-deduper.md new file mode 100644 index 000000000..40fe90047 --- /dev/null +++ b/plugin-v2/agents/signal-deduper.md @@ -0,0 +1,45 @@ +--- +name: signal-deduper +description: Use between Observe fan-in and Orient, only when more than one observer ran in parallel. Reads the iteration's per-source observation files, identifies duplicate or near-duplicate signals across sources, and emits a single deduped, source-attributed merged view. Lets the orienter focus on synthesis instead of bookkeeping. +tools: [Read, Edit, Write, Grep] +color: cyan +--- + +You are the **Signal Deduper** for the Goal Loop. + +## Scope + +You are consulted by the [`observe`](../skills/observe/SKILL.md) skill at fan-in when **N ≥ 2** observers have run in parallel for the current iteration. You read every per-source observation file produced this iteration and emit one merged file with cross-source duplicates collapsed and conflicts surfaced. The `orienter` reads your merged view instead of N separate files and focuses on synthesis. You uphold Article II (Phase Isolation) by never interpreting signals and Article IX (Escalate, Don't Invent) by never resolving conflicts yourself. + +## Read first + +- `goals//observations/--.md` for every source that ran this iteration. +- `goals//goal-state.md` — `acceptance_criteria` and `constraints` only, to know what counts as a meaningful signal. +- `../memory/constitution.md` — Articles II, IV, IX. +- `../docs/method.md` — §Parallelism and §Quality gates (parallel-observer dedup is the opt-in gate you serve). + +## Procedure + +1. **Pre-flight.** Verify ≥ 2 per-source files exist for the current iteration. If only one is present, exit with a one-line note (`dedup not needed for single source`) and do not write a merged file. +2. **Parse signals.** Read every per-source file's `## Signals` section. For each entry, capture: timestamp, source id, and the raw signal text. Preserve the per-source files exactly as written. +3. **Group by similarity.** Two signals are duplicates when they describe the same event from different sources at the same time, or when one source quotes another. Use a timestamp window plus content-overlap heuristic. Group only across sources — within-source duplicates remain a per-source matter. + - **Window:** ±15 minutes of each signal's `started_at`. + - **Overlap metric:** Jaccard similarity on a bag-of-words built by lowercasing the raw signal text and stripping ASCII punctuation. Threshold for dedup: **≥ 0.7**. + - **Conflict detection:** signals within the same ±15-minute window with Jaccard **< 0.3** *and* contradicting predicates (e.g., one asserts "up" / "passing" / "open" while another asserts "down" / "failing" / "closed" on the same entity) are routed to `## Cross-source conflicts` rather than to a merged group. Equal-Jaccard ties between merge and conflict (e.g., 0.3 ≤ J < 0.7) are passed through as uniques with both source attributions preserved. +4. **Emit merged entries.** For each duplicate group, emit one merged entry citing every contributing source id and timestamp. Keep the strongest wording verbatim from one source; do not paraphrase. +5. **Carry uniques.** Every signal that is not in a duplicate group passes through as-is, preserving its source attribution. +6. **Surface conflicts.** When two sources disagree within the same timestamp window (e.g., one reports "service up", another "service down"), record both under `## Cross-source conflicts`. Cite both sources. Do not resolve — that is the orienter's call. +7. **Write the merged file.** Path: `goals//observations/--_merged.md`, where `` matches the iteration's fan-in timestamp. Frontmatter: `goal_slug`, `iteration`, `sources_merged` (list of source ids), `dedup_at` (ISO-8601 UTC). Body sections in order: `## Merged Signals`, `## Unique Signals`, `## Cross-source conflicts`. + +## Boundaries + +- Never interpret signals. You deduplicate; the orienter synthesises. +- Never resolve cross-source conflicts. Surface and stop. +- Never overwrite per-source observation files. They remain the audit record. +- Never modify `goal-state.md`, `orientation.md`, `decisions.md`, or any other artifact. +- Never run when only one observer's output exists for the current iteration. +- Never invent a signal or a source attribution. Every merged entry traces to per-source files. + +## Outputs + +One file: `goals//observations/--_merged.md`. The orienter reads it instead of (or alongside) the per-source files. diff --git a/plugin-v2/commands/create-goal.md b/plugin-v2/commands/create-goal.md new file mode 100644 index 000000000..32a609db8 --- /dev/null +++ b/plugin-v2/commands/create-goal.md @@ -0,0 +1,41 @@ +--- +description: Interactive interview that produces a comprehensive, best-practices-shaped session-goal file at session-goals/.md. Pairs with /set-goal which activates the goal in the current session. +argument-hint: [slug or one-line intent] +allowed-tools: [Read, Edit, Write, Bash, AskUserQuestion] +--- + +# /create-goal + +Run a focused interview that produces a well-formed **session goal** at `session-goals/.md`. A session goal is a session-scoped intent that keeps the assistant aligned on what the user wants the *current sitting* to produce. It is distinct from a [Goal Loop iteration goal](../skills/_shared/goal-state.md) — for the structured, gated, phase-driven loop, use [`/goal:start`](goal/start.md) instead. + +This command writes the file. It does **not** activate the goal in the current session — that is [`/set-goal`](set-goal.md)'s job. + +## Inputs + +- `$1` — optional. Either a kebab-case slug (e.g. `draft-q3-priorities`, `triage-incident-checkout`) or a free-text one-line intent. When omitted, the [`create-goal`](../skills/create-goal/SKILL.md) skill elicits it. + +## When to use this vs. `/goal:start` + +Rule of thumb: pick a session goal when the work fits in one sitting and you mostly need the assistant to stay on rails. Pick the Goal Loop (`/goal:start`) when the work spans multiple iterations and needs evidence-based phase artifacts (`observations/`, `orientation.md`, `decisions.md`, `actions/`, `reviews/`). + +A session goal has one falsifiable success criterion and one stop condition. A Goal Loop goal has constraints, multiple acceptance criteria, observe sources, an act-gate policy, and a phase state machine. They are different surfaces and live in different folders (`session-goals/` vs. `goals//`). + +## Procedure + +1. Invoke the [`create-goal`](../skills/create-goal/SKILL.md) skill. Pass `$1` straight through. +2. The skill detects whether `session-goals/.md` already exists and gates with `AskUserQuestion` on `Edit existing` / `Replace existing` / `Cancel`. On `Replace`, the prior file is archived under `session-goals/archive/-.md` before the overwrite. +3. The skill derives a kebab-case slug from `$1`. If `$1` is free-text intent, it proposes an outcome-named slug and confirms with the user. Slugs that collide with an existing `goals//` (a Goal Loop iteration goal) are rejected — the two surfaces must not share a name. +4. The skill drives two batched interview rounds (one `AskUserQuestion` call per round): + - **Round A** — primary intent, success criterion, stop condition (the falsifiable trigger the assistant blocks on; in Claude Code this string is quoted verbatim into the native `/goal` command). + - **Round B** — anti-goals (list; empty allowed), time budget (optional), reversibility flag (`mostly_reversible` / `mixed` / `irreversible_actions_present`). +5. The skill runs a clarity gate on the success criterion and the stop condition. On a second failure it consults [`acceptance-criteria-helper`](../skills/acceptance-criteria-helper/SKILL.md). The same falsifiability rubric the Goal Loop intake skill uses applies here. +6. The skill drafts the file from [`../templates/session-goal-template.md`](../templates/session-goal-template.md), surfaces it for sign-off via `AskUserQuestion`, and saves under `session-goals/.md`. The user may pick `Save and activate now` (hands off to [`/set-goal`](set-goal.md) immediately), `Save without activating` (Recommended on first runs), `Edit before saving`, or `Discard`. +7. On exit, print a one-line summary with the file path and the recommended next command — typically `/set-goal ` if the user opted out of activating during creation, or `/goal:start ` if the session reveals the work is bigger than one sitting. + +## Don't + +- Don't activate the goal here. Activation belongs to [`/set-goal`](set-goal.md); this command only writes the file. +- Don't dispatch any Goal Loop phase agent. Session goals do not run phases — they are session-scoped guard rails, not iteration contracts. +- Don't silently overwrite an existing `session-goals/.md`. Always gate on the prior file with `Edit existing` / `Replace existing` / `Cancel`. +- Don't accept a non-falsifiable success criterion or stop condition. The clarity gate is the backstop — loop until it passes. +- Don't conflate `session-goals/.md` with the Goal Loop's `goals//goal-state.md`. They live in different folders and serve different jobs. If the user wants the Goal Loop, hand off to [`/goal:start`](goal/start.md). diff --git a/plugin-v2/commands/goal/README.md b/plugin-v2/commands/goal/README.md new file mode 100644 index 000000000..a66b64df0 --- /dev/null +++ b/plugin-v2/commands/goal/README.md @@ -0,0 +1,49 @@ +--- +title: /goal commands +folder: plugin-v2/commands/goal +description: Slash-command surface for the goal-loop plugin. Each command wraps a skill, which in turn dispatches a specialist subagent. +entry_point: true +--- + +# `/goal:*` command index + +Slash commands for the `goal-loop` plugin. Each command is a thin wrapper that resolves a goal slug, gates with the user where required, and invokes the backing skill. The skill dispatches the specialist subagent that does the phase work. + +State for every goal lives under `goals//`. The canonical method definition is in [`../../docs/method.md`](../../docs/method.md). + +## Commands + +| Command | One-liner | Skill | Dispatches | +|---|---|---|---| +| [`/goal:welcome`](welcome.md) | First-time guided tour or one-command hello-world loop. **Start here.** | [`welcome`](../../skills/welcome/SKILL.md) | (sequences other phase skills) | +| [`/goal:demo`](demo.md) | Zero-input first-touch — scaffolds + runs one iteration of the hello-loop demo. The fastest way to see the plugin in action. | (sequences phase skills via goal-loop) | (via goal-loop) | +| [`/goal:start`](start.md) | Bootstrap a new goal: scaffold `goals//` and define the goal contract. | [`set-goal`](../../skills/set-goal/SKILL.md) | — (skill-only) | +| [`/goal:observe`](observe.md) | Run the Observe phase: scan configured sources for signals bearing on the goal. | [`observe`](../../skills/observe/SKILL.md) | `observer` | +| [`/goal:orient`](orient.md) | Run the Orient phase: synthesise signals against goal, history, and context. | [`orient`](../../skills/orient/SKILL.md) | `orienter` | +| [`/goal:decide`](decide.md) | Run the Decide phase: propose a ranked action set and gate with the user. | [`decide`](../../skills/decide/SKILL.md) | `decider` | +| [`/goal:act`](act.md) | Run the Act phase: execute the human-approved decision set and audit what happened. | [`act`](../../skills/act/SKILL.md) | `actor` | +| [`/goal:review`](review.md) | Close the loop iteration: compare outcomes to acceptance criteria and choose continue / close / amend. | [`review-loop`](../../skills/review-loop/SKILL.md) | `loop-reviewer` | +| [`/goal:run`](run.md) | Drive a full iteration end-to-end (Observe → Orient → Decide → human gate → Act → Review). | [`goal-loop`](../../skills/goal-loop/SKILL.md) | `goal-orchestrator` | +| [`/goal:status`](status.md) | Print the current state of a goal: phase, iteration, last actions, last review, open acceptance criteria. Read-only. | — (reads artifacts) | — | +| [`/goal:list`](list.md) | List every goal under `goals/` with phase, iteration, status, and last activity. Read-only portfolio view. Filter `--all` / `--active` / `--stalled` / `--done` / `--cancelled`. | [`list-goals`](../../skills/list-goals/SKILL.md) | — (read-only) | +| [`/goal:close`](close.md) | Manually close (or amend) a goal out-of-band with outcome `close-met`, `close-abandon`, or `amend`. | — (dispatches `loop-reviewer` directly) | `loop-reviewer` + `goal-orchestrator` | +| [`/goal:brief`](brief.md) | Pure render of `brief.md` for recurring goals from the current orientation and decision set; reads only, writes only `brief.md`. | — (render path of the command itself) | — (render-only) | +| [`/goal:amend`](amend.md) | Dedicated amend entry: open `set-goal` in amend mode, re-run the goal gate after the change. | [`set-goal`](../../skills/set-goal/SKILL.md) (amend mode) | — (skill-only) | +| [`/goal:trace`](trace.md) | Read-only walk of the full reasoning trail for one iteration — criterion → verdict → action → decision → orientation → observations. Surfaces gaps. | [`trace-loop`](../../skills/trace-loop/SKILL.md) | — (read-only) | +| [`/goal:export-trace`](export-trace.md) | Export a Goal Loop iteration as OpenTelemetry GenAI trace JSON (formats: `otel-genai`, `langfuse`, `raw`). Machine-facing sibling of `/goal:trace`; ingests into Langfuse / Datadog / Helicone / Arize / Phoenix. Read-only. | [`export-trace`](../../skills/export-trace/SKILL.md) | — (read-only) | + +## Conventions + +- All commands accept an optional ``. When omitted, the command detects the single active goal under `goals/`. If zero or more than one is active, it asks the user to pick. +- The **Goal gate** (sign-off on the goal contract) and the **Act gate** (sign-off on the decision set before execution) are non-negotiable. Other gates are configurable per goal. +- Read-only commands (`/goal:status`, `/goal:brief`, `/goal:trace`, `/goal:export-trace`) use the `haiku` model. Phase commands inherit the session default. +- Commands never edit artifacts owned by other phases. The orchestrator owns `goal-state.md`; each phase agent owns its own outputs. + +## See also: cross-tool session goals + +The plugin also ships two top-level commands for **session goals** — session-scoped intents that keep the assistant aligned for one sitting without the full Goal Loop ceremony. They live alongside the `/goal:*` namespace at the plugin root: + +- [`/create-goal`](../create-goal.md) — interactive interview that writes `session-goals/.md`. +- [`/set-goal`](../set-goal.md) — activates a session goal in the current tool (native `/goal` stop-hook in Claude Code, `SESSION-GOAL.md` in Codex, `.cursor/rules/session-goal.mdc` in Cursor). Clear with `/set-goal --clear`. + +Use a session goal when the work fits in one sitting and you mostly need the assistant to stay on rails. Use the Goal Loop above when the work spans multiple iterations and needs evidence-based phase artifacts. diff --git a/plugin-v2/commands/goal/act.md b/plugin-v2/commands/goal/act.md new file mode 100644 index 000000000..801e9f048 --- /dev/null +++ b/plugin-v2/commands/goal/act.md @@ -0,0 +1,40 @@ +--- +description: Run the Act phase for a goal — execute the human-approved decision set and record exactly what happened in goals//actions/iter-/. +argument-hint: [goal-slug] +allowed-tools: [Read, Edit, Write, Bash, AskUserQuestion] +--- + +# /goal:act + +Run the **Act** phase of the Goal Loop. + +## Inputs + +- `$1` — goal slug (optional). When omitted: + - If exactly one goal under `goals/` has `status` in `{active, paused, blocked}` (the set this command's preflight accepts), use it. + - Otherwise, list every goal whose `status` is in `{active, paused, blocked}` and ask the user to pick. Paused and blocked goals are listed because they are legitimate resume entry points; the preflight gates them via `AskUserQuestion` before dispatching. Closed goals (`done | cancelled`) are not listed — they are terminal. + +## Procedure + +0. **Orient the user first.** Before dispatching, surface a one-line orientation: *"About to execute the approved actions. Each `actor` runs exactly one approved item; nothing outside the approved subset will run. Irreversible items that you explicitly confirmed will run with rollback plans on file."* +1. Resolve the goal slug from `$1` or by inspecting `goals/`. +2. Read `goals//goal-state.md`. Confirm: + - `current_phase` is `act`. + - The latest decision set in `goals//decisions.md` has a filled `## Human Approval` section (approver, ISO-8601 timestamp, approved-id list). This is the canonical record of the act gate per [`../../skills/_shared/goal-state.md`](../../skills/_shared/goal-state.md) §"Ownership matrix"; no other field is required. + - The orchestrator has appended a `## History` row for the current iteration recording the act-gate outcome (citing the decision-set entry) — that row is the secondary audit signal that the gate cleared. + - If any of these fail, stop and surface the mismatch. Re-run `/goal:decide` if no approved set exists. +3. Invoke the [`act`](../../skills/act/SKILL.md) skill. The skill: + - Reads the approved action subset from the `## Human Approval` section of the latest decision set in `decisions.md`. + - For an independent action set, dispatches one `actor` subagent per action in parallel; for a dependent chain, dispatches sequentially. + - Each `actor` executes its assigned action and writes `goals//actions/iter-/.md` recording: what was done, what changed, what was skipped, exit status, side-effects, and any artifact paths produced. The `iter-/` namespace prevents recurring goals from overwriting prior-iteration evidence. + - The skill reduces per-actor outputs into a per-iteration summary and (via the decider's template contract) marks each approved item `done` / `partial` / `stopped` / `blocked` / `failed` with a link to its action file. + - The skill respects each action's `reversible` flag — irreversible actions that have not been explicitly confirmed at the act gate abort with a clear error if encountered, not proceed. +4. The `act` skill dispatches `goal-orchestrator` to set `current_phase: review` and append a fan-in `## History` row listing the executed action IDs. The `/goal:act` command itself writes nothing to `goal-state.md`. +5. Print a summary: actions executed, actions failed, actions skipped (with reasons), and the next recommended command (`/goal:review `). + - Then render: *"Executed ``/`` approved actions: ``=…, ``=…, ``=…, ``=…. Next: Review will grade against acceptance criteria."* This complements the technical summary above; it does not replace it. + +## Don't + +- Don't execute anything that was not explicitly approved at the Act gate. Drifting scope is the most common failure mode here. +- Don't fabricate success. If an `actor` cannot complete its action, the action file must record the failure verbatim and the decision moves to `status: failed`. +- Don't update `orientation.md` or `decisions.md` outside the structured status transition. Each phase writes only its own artifacts. diff --git a/plugin-v2/commands/goal/amend.md b/plugin-v2/commands/goal/amend.md new file mode 100644 index 000000000..64d397444 --- /dev/null +++ b/plugin-v2/commands/goal/amend.md @@ -0,0 +1,43 @@ +--- +description: Amend an existing goal — opens set-goal in amend mode, walks the user through the change, and re-runs the goal gate before the loop continues. +argument-hint: [slug] +allowed-tools: [Read, Edit, Write, Bash, AskUserQuestion] +--- + +# /goal:amend + +The **dedicated amend entry point** for an existing goal. Routes through the [`set-goal`](../../skills/set-goal/SKILL.md) skill in amend mode, re-runs the goal gate, and brackets the goal back to `current_phase: scope` so the next loop dispatch resumes cleanly from Observe. + +Today, amend can also be reached via `/goal:start ` against an existing slug — that path is preserved. This command is the explicit, single-purpose affordance for amendments, and is what the `loop-reviewer` `amend` outcome and `acceptance-criteria-helper` recommend. + +## Inputs + +- `$1` — goal slug (optional). When omitted: + - If exactly one goal under `goals/` has `status` in `{active, paused, blocked}` (the live-goal set), use it. + - Otherwise list candidates and ask the user to pick. **Closed goals (`done | cancelled`) are also listed** with a `(revive)` suffix because Step 2 explicitly supports revive-via-amend; without including them, the documented revive flow is unreachable from the no-slug picker. + +## Procedure + +1. Resolve `$1` to a goal slug. If unset and ambiguous, ask via `AskUserQuestion`. +2. Confirm `goals//goal-state.md` exists. + - If absent — surface that and recommend `/goal:start ` instead; stop. + - If `status: done | cancelled` — this is the **revive-via-amend** flow (the same path `/goal:start ` offers as "Reopen via amend" per [`start.md`](start.md) and the revival rule in [`../../skills/_shared/loop-pattern.md`](../../skills/_shared/loop-pattern.md)). Surface that the goal is closed and ask via a single `AskUserQuestion`: `Revive via amend — re-open this goal with a recorded amendment` (Recommended; preserves `## History` for continuity) / `Start a fresh goal under a new slug` (route to `/goal:start `) / `Cancel — leave the closed goal alone`. On revive, proceed to step 3 with the closed goal; the amend Step 5 orchestrator hand-off will flip `status: active` and `current_phase: scope` once the goal gate re-signs. + - If `demo_seed: true` is present in the frontmatter — this goal was pre-signed by [`/goal:demo`](demo.md), not by a human goal-gate clearance. The amend is **the promotion path** from demo-seed to real-goal. Surface that fact via a single `AskUserQuestion`: `Promote — clear demo_seed and run the full goal-gate interview` (Recommended; required if you want to ship this goal beyond first-touch) / `Amend without promoting — keep demo_seed and just edit a body section` (allowed for trivial fixes; the demo-origin row stays in `## History`) / `Cancel — leave the demo-signed goal as-is`. On promote, this amend writes a per-goal amendment record under `goals//amendments/-amend-.md` (using [`../../templates/constitution-amendment-template.md`](../../templates/constitution-amendment-template.md) scoped to the goal's contract, not the constitution — `memory/amendments/` is reserved for constitution-level amendments per the artifact inventory in [`../../skills/_shared/goal-state.md`](../../skills/_shared/goal-state.md)), clears `demo_seed: false`, and re-runs `set-goal`'s full clarity gate. +3. Read `goals//goal-state.md`. Surface a one-screen snapshot — current intent, each numbered acceptance criterion, constraints, mode + cadence, observe sources (id + type + target), act-gate policy — and ask via a single `AskUserQuestion` which section to amend: `Amend acceptance criteria` / `Amend constraints` / `Amend observe sources` / `Amend mode/cadence` / `Amend act-gate policy` / `Amend intent`. The intent option is the heaviest — on selection, confirm twice before continuing. +4. Invoke the [`set-goal`](../../skills/set-goal/SKILL.md) skill in **amend mode**. Pass the chosen section and the resolved slug. `set-goal` runs the targeted interview, re-runs the clarity gate on any new acceptance criterion (looping on falsifiability until each passes), and re-presents the updated goal for the goal gate. +5. On the user's sign-off: + - `set-goal` writes the updated `goals//goal-state.md` (frontmatter `updated_at` bumped; body sections changed only where the amendment applied; `## History` left intact — that is `set-goal`'s explicit contract per [`../../skills/set-goal/SKILL.md`](../../skills/set-goal/SKILL.md) §"Outputs"). + - **The `/goal:amend` command writes the amendment record file at `goals//amendments/-amend-.md`** (using [`../../templates/constitution-amendment-template.md`](../../templates/constitution-amendment-template.md) scoped to the goal's contract — section(s) changed, before / after diff, rationale, approver). `` is a per-day sequence number to disambiguate multiple amendments on the same date. For revive-via-amend, the body also captures the criteria-diff attestation (`equivalent | weaker | stronger`) recorded by `set-goal` per [`../../skills/set-goal/SKILL.md`](../../skills/set-goal/SKILL.md) §"Revive-amend mode". This file is the resolvable artifact every `## History` `outcome: amend` row points at; without writing it the History link would dangle, breaking `trace-loop` and `export-trace` artifact resolution. Required on every amendment, not just promotions or revivals. + - **Then dispatch `goal-orchestrator` to append the `amend` row to `## History`** citing the section(s) changed, `outcome: amend`, and the `artifact` column pointing at the amendment record file written in the previous step. The orchestrator owns `## History` per the [shared ownership matrix](../../skills/_shared/goal-state.md). Without this step the amendment would land in the body but leave no audit trail — Codex P2 finding (`set-goal` does not touch `## History`). + - The same `goal-orchestrator` dispatch sets `current_phase: scope` to bracket the goal gate; the next loop dispatch resumes from `scope` → Observe. + - **Cap-raise tracking.** When the amendment raised any hard-stop cap (`max_iterations`, `max_consecutive_rejects`, or `max_failed_acts`), the `goal-orchestrator` dispatch also increments the lifetime counter `cap_raises_lifetime` in the frontmatter (per [`../../agents/goal-orchestrator.md`](../../agents/goal-orchestrator.md) §"Cap-raise sub-rule"). The counter is never decremented. When `cap_raises_lifetime >= 2`, the orchestrator surfaces the structural-mis-scope warning at the next phase dispatch and offers `Close — abandon` ahead of `Proceed`. Cap raises additionally require the goal's `escalation_contact` to sign — not just the operator who hit the cap — per the orchestrator's §"(d) Signing authority"; if `escalation_contact` is unset, the cap raise is blocked at the orchestrator step and routed back here to set it. + - **For revive-via-amend (Step 2 case 2 — the `done | cancelled` branch)**, the orchestrator also flips `status` from `done | cancelled` back to `active`. **`iteration` is NOT bumped at amend time** — per [`../../skills/_shared/goal-state.md`](../../skills/_shared/goal-state.md), `iteration` increments only at each new Observe (the canonical rule). The next `/goal:observe` dispatch (whether immediate or deferred) will bump it; bumping here would double-increment and produce a `## History` row whose iteration number has no observation artifact under it. The revive row's `iteration` column carries the iteration value as it stood at the moment the goal was closed. The `## History` row stays within the canonical six-column schema (`iteration | phase | started_at | ended_at | outcome | artifact`) — no extra columns. Distinctness lives in the `artifact` column: the revive row points at the amendment record file written earlier in Step 5 (the file lives at `goals//amendments/-amend-.md` on disk; the `## History.artifact` column cites it as the **goal-relative path** `amendments/-amend-.md` per the canonical row format in [`../../skills/_shared/goal-state.md`](../../skills/_shared/goal-state.md) §"`## History`" — a prefixed citation would resolve as `goals//goals//...` in `trace-loop` / `export-trace`). The record's body captures the revival rationale, the prior closure state being re-opened, and the user's criteria-diff attestation (`equivalent | weaker | stronger`) per [`../../skills/set-goal/SKILL.md`](../../skills/set-goal/SKILL.md) §"Revive-amend mode". The `outcome` is the canonical `amend` (the four loop-closure outcomes — `continue | close-met | close-abandon | amend` — that `goal-orchestrator`, `trace-loop`, `export-trace`, and downstream `## History` parsers accept). The prior closure row stays in `## History` verbatim above the revive row, so Article X (Closure Honesty) is preserved through the audit trail — the amendment file is the canonical place revival rationale is recorded, not a per-row column the schema does not declare. +6. Print a summary: which section(s) changed, the path of the appended `## History` row, and the recommended next command — `/goal:run ` to resume the loop, or `/goal:status ` to inspect first. + +## Don't + +- Don't edit `goals//goal-state.md` directly. Every change routes through `set-goal` so the clarity gate and the goal gate both run. +- Don't silently revive a closed goal. The revive-via-amend flow exists (Step 2 case 2 — the `done | cancelled` branch) and is supported — but it must be explicitly chosen by the user via the three-option `AskUserQuestion`, never auto-applied. The user-visible default in that gate is `Start a fresh goal under a new slug` for any case where continuity of the prior `## History` is not the operator's goal; "Revive via amend" is marked Recommended only because it preserves history when the operator does want continuity. +- Don't bypass the goal gate. Every amend re-runs it — that is the contract that keeps `goal_signed_off` honest. +- Don't dispatch a phase agent from this command. Amend is intake-shaped; the next phase is the user's call. +- Don't invent non-canonical `## History` outcome values or extra columns. The only accepted outcomes are `continue | close-met | close-abandon | amend`, and the `## History` table is the fixed six-column schema (`iteration | phase | started_at | ended_at | outcome | artifact`). Revival distinctness lives in the `artifact` column pointing at the amendment record file under `goals//amendments/`, not in a new enum value or an extra `notes` column — every downstream reader (`goal-orchestrator`, `trace-loop`, `export-trace`, the `## History` parsers) extracts `outcome` and `artifact` by fixed position. diff --git a/plugin-v2/commands/goal/brief.md b/plugin-v2/commands/goal/brief.md new file mode 100644 index 000000000..da53bbd84 --- /dev/null +++ b/plugin-v2/commands/goal/brief.md @@ -0,0 +1,45 @@ +--- +description: Render a brief.md snapshot for a recurring goal from the current orientation and decision set. Render-only — never dispatches a phase agent. +argument-hint: [goal-slug] +allowed-tools: [Read, Edit, Write, AskUserQuestion] +model: haiku +--- + +# /goal:brief + +For recurring-mode goals, produce a human-readable `brief.md` snapshot — a daily, weekly, or per-cadence summary rendered from the most recent orientation and decision set. **Pure render**: this command reads existing artifacts and writes `brief.md` directly from [`../../templates/brief-template.md`](../../templates/brief-template.md). It does not run any phase, dispatch any phase agent or skill, and does not modify upstream artifacts. + +## Inputs + +- `$1` — goal slug (optional). When omitted: + - If exactly one goal under `goals/` has `status: active` and `mode: recurring`, use it. + - Otherwise, list the active recurring goals and ask the user to pick. If no recurring goals exist, stop with a note that `/goal:brief` is recurring-only. + +## Procedure + +1. Resolve the goal slug from `$1` or by inspecting `goals/`. +2. Read `goals//goal-state.md`. Confirm: + - `mode: recurring`. If `mode: one-shot`, stop and recommend `/goal:status ` instead — one-shot goals do not produce briefs. + - `goal_signed_off: true`. If not, stop and recommend `/goal:start ` to sign the contract. +3. Read the source artifacts directly (no skill dispatch): + - `goals//orientation.md` (current synthesis). + - The most recent approved decision block from `goals//decisions.md`. + - The most recent review under `goals//reviews/` (if any) for trend context. + - The prior `goals//brief.md` (if any) to compute deltas — "what changed since last brief". + - If any required source (orientation, decisions) is missing for the current iteration, stop with a note recommending `/goal:run ` to populate them first — `/goal:brief` does not fabricate content. +4. Render `goals//brief.md` from [`../../templates/brief-template.md`](../../templates/brief-template.md), filled from the source artifacts: + - Header (slug, cadence, date). + - What changed since the prior brief. + - Current orientation summary (verbatim or condensed from `orientation.md`). + - Top recommended actions from the latest decision set. + - Open acceptance criteria (from the latest review's signal map, if available). + - Any flags from the last review. +5. Archive the previous brief to `goals//archive/brief/.md` (date-only filename, no time) **before** overwriting `brief.md`, so cadence history is preserved. The date-only form is the canonical archive shape per [`../../templates/brief-template.md`](../../templates/brief-template.md) and [`../../.codex/workflows/daily-brief.md`](../../.codex/workflows/daily-brief.md) — Orient's roll-forward lookup (per the daily-brief workflow Step 2 option b) and Periodic Notes-compatible daily indexing both depend on this exact shape. If two briefs render on the same calendar day (e.g., manual re-render), append a `-` suffix (`-2.md`) rather than reverting to ISO-timestamp form. +6. Print a summary: brief path, what changed since the prior brief, and the next recommended command (`/goal:run ` to advance the loop, or wait for cadence). + +## Don't + +- Don't run any phase. `/goal:brief` consumes existing artifacts and renders — it never invokes Observe, Orient, Decide, Act, or a fresh Review. +- Don't fabricate content. Every line in `brief.md` must trace to `orientation.md`, `decisions.md`, or a review file. If a field is empty upstream, mark it empty in the brief. +- Don't generate a brief for one-shot goals. Briefs are a recurring-goal concern; one-shot goals report state through `/goal:status`. +- Don't overwrite the previous brief without archiving it. The cadence history under `archive/brief/` is the audit trail for recurring goals. diff --git a/plugin-v2/commands/goal/close.md b/plugin-v2/commands/goal/close.md new file mode 100644 index 000000000..959feff38 --- /dev/null +++ b/plugin-v2/commands/goal/close.md @@ -0,0 +1,58 @@ +--- +description: Manually close or amend a goal outside the normal Review phase. Dispatches the loop-reviewer subagent directly with the canonical close outcome. +argument-hint: [goal-slug] [outcome] +allowed-tools: [Read, Edit, Write, AskUserQuestion] +--- + +# /goal:close + +Manually close (or amend) a goal without running a full Review phase. Use when the loop has reached a terminal state outside the normal cycle — for example, the user decides to abandon the goal, the goal's criteria are obviously met from external evidence, or the user wants to amend the contract before the next iteration. + +This command is the **out-of-band** close path. The in-band path (close after a normal iteration) flows through the [`review-loop`](../../skills/review-loop/SKILL.md) skill, which requires `current_phase: review` and a full iteration of artifacts. `/goal:close` bypasses those preconditions and dispatches the [`loop-reviewer`](../../agents/loop-reviewer.md) subagent directly with a clear "manual close" context block. + +## Inputs + +- `$1` — goal slug (optional). When omitted: + - If exactly one goal under `goals/` has `status` in `{active, paused, blocked}` (the set Step 3 explicitly accepts as closable), use it. + - Otherwise, list every goal whose `status` is in `{active, paused, blocked}` and ask the user to pick. **Include paused and blocked goals in the picker** — those states are common entry points for `/goal:close` (an operator pauses a goal to think, then closes; or a blocked goal needs to be abandoned). Listing only active goals would make the command unusable from the guided flow in exactly the states it claims to support. + - `status: done | cancelled` goals are not listed — they are already closed. +- `$2` — outcome (optional, one of `close-met`, `close-abandon`, `amend` — the canonical four-outcome vocabulary; synonyms `met` → `close-met` and `abandoned` → `close-abandon` are accepted). If omitted, ask the user to choose. + +## Procedure + +1. Resolve the goal slug from `$1` or by inspecting `goals/`. +2. Resolve the outcome from `$2` or by prompting the user. Validate and normalise to one of `close-met | close-abandon | amend`; reject any other value. +3. Read `goals//goal-state.md`. Confirm the goal is currently `status: active | paused | blocked`. If it is already `done` or `cancelled`, surface that and stop — re-opening a closed goal goes through `/goal:start ` in amend mode, not `/goal:close`. +4. Collect a short user-stated rationale (required for `close-abandon`, recommended for `close-met`, mandatory for `amend`). +5. Dispatch the [`loop-reviewer`](../../agents/loop-reviewer.md) subagent directly with an explicit **manual-close** context block: + + ``` + Mode: manual-close (out-of-band; phase preconditions waived). + Goal slug: + Iteration: + Required outcome: + User rationale (verbatim): <…> + Acceptance criteria: + Constraints: + Available artifacts (may be partial — manual close does not require a full iteration): + - + Output path: goals//reviews/.md (the canonical `loop-reviewer` output path; the `outcome:` frontmatter field — `close-met | close-abandon | amend` — is what distinguishes a closing review from a continue review, not the filename). + Reminders: + - For close-met: affirm each acceptance criterion as met / not applicable (with rationale). Any unaffirmable criterion is a warning the conductor must surface for explicit user confirmation. + - For close-abandon: record the user rationale; do not relitigate the criteria. + - For amend: capture the proposed amendment scope (which section(s) of goal-state.md change). Do NOT close — status stays active and the goal re-enters the Goal gate via /goal:start in amend mode. + ``` + +6. After the reviewer writes `reviews/.md`, dispatch the [`goal-orchestrator`](../../agents/goal-orchestrator.md) subagent to apply the state change (the closing time is recorded by the `## History` row's `ended_at` column per the [shared schema](../../skills/_shared/goal-state.md) — no `closed_at` frontmatter field is added): + - `close-met` → `status: done`, `current_phase: closed`, append `## History` row linking the closing review. + - `close-abandon` → `status: cancelled`, `current_phase: closed`, append `## History` row with rationale and closing review link. + - `amend` → **preserve the prior `status` verbatim** (do NOT flip to `active`). `/goal:close` accepts goals in `active | paused | blocked` per Step 2; flipping all three to `active` would silently resume a `paused` or clear a `blocked` goal as a side effect of a maintenance amend, bypassing the explicit resume acknowledgement [`../../skills/_shared/loop-pattern.md`](../../skills/_shared/loop-pattern.md) §"Re-entry / resume rules" requires. The downstream `/goal:amend ` flow owns any status transition (the orchestrator at amend Step 5 keeps `status: paused | blocked` until the user explicitly chooses to resume; the revive path is its own explicit branch). Set `current_phase: scope` (re-entry to the Goal gate via [`/goal:amend `](amend.md) or [`set-goal`](../../skills/set-goal/SKILL.md) in amend mode), and append a `## History` row noting the pending amendment. +7. For `outcome: amend`, recommend [`/goal:amend `](amend.md) next — the dedicated amend entry; `/goal:start ` remains a back-compat fallback. For terminal outcomes, recommend `/goal:status `. +8. Print a summary: outcome, closing review path, state change applied, and the next recommended command. + +## Don't + +- Don't close a goal silently. Every close writes a `reviews/.md` artifact (with `outcome: close-met | close-abandon` in the frontmatter) and updates `goal-state.md` — no terminal state without an audit trail. +- Don't mark a goal `close-met` without per-criterion affirmation. If criteria cannot be checked, prefer `amend` or surface the gap for the user. +- Don't run any phase work (Observe / Orient / Decide / Act) from this command. `/goal:close` writes a closing review and updates state; nothing else. +- Don't invoke the [`review-loop`](../../skills/review-loop/SKILL.md) skill from here — that skill enforces in-band Review preconditions which this out-of-band path is explicitly waiving. diff --git a/plugin-v2/commands/goal/decide.md b/plugin-v2/commands/goal/decide.md new file mode 100644 index 000000000..2d5249bb2 --- /dev/null +++ b/plugin-v2/commands/goal/decide.md @@ -0,0 +1,42 @@ +--- +description: Run the Decide phase for a goal — propose a ranked action set from the current orientation and gate with the user before Act. +argument-hint: [goal-slug] +allowed-tools: [Read, Edit, Write, AskUserQuestion] +--- + +# /goal:decide + +Run the **Decide** phase of the Goal Loop. + +## Inputs + +- `$1` — goal slug (optional). When omitted: + - If exactly one goal under `goals/` has `status` in `{active, paused, blocked}` (the set this command's preflight accepts), use it. + - Otherwise, list every goal whose `status` is in `{active, paused, blocked}` and ask the user to pick. Paused and blocked goals are listed because they are legitimate resume entry points; the preflight gates them via `AskUserQuestion` before dispatching. Closed goals (`done | cancelled`) are not listed — they are terminal. + +## Procedure + +0. **Orient the user first.** Before dispatching, surface a one-line orientation: *"About to propose a ranked decision set. The `decider` reads `orientation.md` and produces actions tied to your acceptance criteria. **You will be asked to approve before anything runs** — that's the act gate."* +1. Resolve the goal slug from `$1` or by inspecting `goals/`. +2. Read `goals//goal-state.md`. Confirm: + - `current_phase` is `decide` (i.e. Orient has just completed). If not, stop and surface the mismatch. + - The orientation under `goals//orientation.md` is fresh (its timestamp matches the latest hand-off note). +3. Invoke the [`decide`](../../skills/decide/SKILL.md) skill. The skill: + - Reads `orientation.md`, the goal's acceptance criteria, and any prior decision sets under `decisions.md`. + - Dispatches the `decider` subagent to produce a **ranked action set** for this iteration: each item carries a one-line rationale, an impact estimate, a confidence rating, and a reversibility flag. + - Appends the proposed set to `goals//decisions.md` under a new dated heading. The block is marked `status: proposed` until the human gate resolves it. +4. **Act gate (non-negotiable).** Present the proposed action set to the user and ask for sign-off. The user may: + - **Approve all** — the `decide` skill fills the decision set's `## Human Approval` section with `approver`, ISO-8601 `approved at`, and the full approved-id list. + - **Approve subset** — fill the same section with `approved-id list` (subset) plus an `exclusions` list and per-item edits where the user supplied them. + - **Reject all** — fill `## Human Approval` with `Rejected — rationale: …`. The iteration proceeds to Review with no actions (`act: skipped` recorded by the orchestrator). + - **Defer to next iteration** — `## Human Approval` records `Deferred`. Same Review path as Reject. + - When the goal's `act_gate` policy is `low-risk-auto`, reversible actions may be auto-approved — but the human is still shown the set and can override, and **any irreversible action requires an explicit confirmation** regardless of policy. +5. The `decide` skill dispatches `goal-orchestrator` to advance state: `current_phase: act` when at least one action was approved, otherwise `current_phase: review` with an `act: skipped` `## History` row recording the reason (`all rejected` / `deferred` / `policy forbids`). The `/goal:decide` command itself writes nothing to `goal-state.md`. +6. Print a summary: number of actions proposed, number approved, gating outcome, and the next recommended command (`/goal:act `) or remediation step. + - Then render: *"Proposed `` action(s); `` recommended. Reversible: ``. Irreversible: `` (each requires explicit confirmation). Awaiting your approval at the act gate."* This complements the technical summary above; it does not replace it. + +## Don't + +- Don't execute any action. Decide ends at human sign-off; execution belongs to `/goal:act`. +- Don't silently amend the goal. If the orientation reveals the goal is wrong, surface that as an `amend` proposal for the user — do not redefine acceptance criteria in flight. +- Don't append to `decisions.md` outside the dated block format. The append-only log is the audit trail; reviewers depend on it. diff --git a/plugin-v2/commands/goal/demo.md b/plugin-v2/commands/goal/demo.md new file mode 100644 index 000000000..b081e11ee --- /dev/null +++ b/plugin-v2/commands/goal/demo.md @@ -0,0 +1,47 @@ +--- +description: One-command first-touch — scaffolds the hello-loop goal and runs one complete iteration end-to-end. The fastest way to see the plugin work. No prompts; no acceptance-criteria interview; ideal for "does this even work in my project?". +argument-hint: (none) +allowed-tools: [Read, Edit, Write, Bash, AskUserQuestion] +model: haiku +--- + +# /goal:demo + +Zero-input first-touch. Scaffolds `goals/hello-loop/` from [`../../examples/hello-loop/goal-state.md`](../../examples/hello-loop/goal-state.md), drives one complete Observe → Orient → Decide → Act → Review iteration, and reports what landed. Equivalent to `/goal:welcome hello` but without the choice gate or per-phase narration — the loop runs end-to-end on a pre-signed seed. + +Use this when you want to confirm the plugin works in your project before investing in a real goal. For the guided walkthrough with explanations between phases, use [`/goal:welcome`](welcome.md) instead. + +## Inputs + +- `$1` *(optional)* — alternate demo slug. Defaults to `hello-loop`. When `$1` is anything other than `hello-loop`, the seed is **rewritten in place** so the scaffolded `goal-state.md` is internally consistent with the new slug: every `slug:` mention, every `goals/hello-loop/...` path, every acceptance-criterion that names artifacts under `hello-loop/`, every observe-source target, and every constraint reference is rewritten to point at `goals/<$1>/`. The acceptance bar stays the demo bar (one observation file, one action log, one review with `outcome: close-met`) but it is checked against the renamed folder, not against `hello-loop/`. Without this rewrite, `goal-state.md` would advertise `goals/<$1>/` in its parent path while its body and acceptance criteria still cited `goals/hello-loop/`, producing mismatched evidence paths and failing the demo's own checks for any non-default slug. + +## Procedure + +1. **Detect prior scaffold.** If `goals//` already exists, **read its `goal-state.md` frontmatter first** to determine `status`. Branch on the read: + - **`status: done | cancelled`** (the prior demo already closed) — the `goal-loop` flow refuses to resume terminal goals (it routes to revive/inspect handling), so the "Skip and run iteration" path would dead-end. Surface via `AskUserQuestion`: `Re-scaffold — archive the closed goal and start fresh` (Recommended for this case; same archive flow as below) / `Inspect the closed goal — exit, recommend /goal:status ` / `Cancel`. Do **not** offer "Skip" here; it cannot succeed on a terminal goal. + - **`status: active | paused | blocked`** (the prior scaffold is a live goal `goal-loop` can resume) — surface via `AskUserQuestion`: `Skip — goal already scaffolded; just run an iteration` (Recommended) — proceed to Step 4 against the existing folder. / `Re-scaffold — archive existing and start fresh` / `Cancel`. + - **`status: draft`** (the prior scaffold exists but never had its goal-gate signed — `goal-loop` Step 1/2 treats `draft` as not-resumable, so a Skip dispatch would dead-end before any phase runs) — surface via `AskUserQuestion`: `Sign off the existing draft and run an iteration` (Recommended — flip the existing `goal_signed_off: true` and `status: active`, refresh `updated_at`, then proceed to Step 4 against the existing folder) / `Re-scaffold — archive existing and start fresh` / `Cancel`. Do **not** offer "Skip" for draft state; the sign-off is the missing step. + - **No `goal-state.md` in the folder, or unreadable** — treat as state drift; recommend `Re-scaffold` only and surface the drift to the user; do not silently overwrite. + + The `Re-scaffold` action (in any branch): move the existing folder to a **sibling** archive path `goals/_archive/-/` (Bash, `mkdir -p goals/_archive && mv goals/ goals/_archive/-`). `goals/_archive/` is a separate directory from the goal's own `archive/` subfolder — `mv` would fail if asked to move a directory into its own descendant. The `_archive` prefix matches the `_session/` convention used elsewhere for non-goal directories under `goals/`. Then continue from Step 2. +2. **Scaffold from the seed.** `mkdir -p goals//observations goals//actions goals//reviews goals//archive goals//amendments` (Bash). The `amendments/` subdirectory holds per-goal amendment records (see Step 3 and `/goal:amend`); it lives goal-local because trace/export resolve artifact paths from the goal folder, not from the cross-tree `memory/amendments/` directory (which is reserved for constitution-level amendments). Then `Write` `goals//goal-state.md` by copying [`../../examples/hello-loop/goal-state.md`](../../examples/hello-loop/goal-state.md), then stripping every key that is **not** in the canonical `goal-state.md` schema ([`../../skills/_shared/goal-state.md`](../../skills/_shared/goal-state.md) §"YAML frontmatter"). State readers reject undeclared keys; preserving example metadata produces malformed live state. The required edits: + - **Strip example-only frontmatter keys:** `title`, `description`, `aliases`, `example`, plus any other key not in the schema's required-or-optional list. The schema accepts: `slug`, `intent`, `constraints`, `acceptance_criteria`, `mode`, `cadence`, `observe_sources`, `act_gate`, `status`, `current_phase`, `iteration`, `created_at`, `updated_at`, `tags`, plus the optional set `goal_signed_off`, `last_review`, `escalation_contact`, `parallel_observe`, `parallel_act`, `demo_seed`. Anything else is dropped. + - **Strip the EXAMPLE body notice block** (`> [!warning] Example only — do not consume` or the prose-blockquote variant). + - **Flip `status: active`** (was `draft`). + - **Flip `goal_signed_off: true`** (was `false`). The demo is pre-signed by virtue of being a verified seed — no goal-gate interview. + - **Set `demo_seed: true`** in frontmatter. This is the auditable marker that distinguishes a demo-signed goal from a human-signed one. `/goal:amend` refuses to clear it silently — promoting a demo-signed goal to a real one requires a recorded amendment under `goals//amendments/`. + - **Refresh `created_at` and `updated_at`** to the current ISO-8601 timestamp (the seed's timestamps are example-only). + - **Update `tags:`** to drop any tag value still referring to `example` (the canonical `goal-loop/artifact/goal-state`, `goal-loop/status/active`, `goal-loop/phase/scope` namespace stays — the orchestrator regenerates the status/phase entries on every transition; the initial values just need to match the demo-flipped `status: active` and seed-default `current_phase: scope`). + - **Append the canonical `## Health` body section** if absent from the seed: `Iteration count: 0 of `, `Consecutive rejects: 0 of `, `Failed acts (lifetime): 0 of `, `Hard-stop status: healthy`. Per [`../../templates/goal-state-template.md`](../../templates/goal-state-template.md) §"## Health"; the orchestrator refreshes it on every phase transition but the first transition's preflight expects the block to exist. +3. **Record the demo origin in `## History`.** First, write the per-goal marker file at `goals//amendments/_demo-seed-origin.md` (one paragraph: this `## History` row represents a demo-signed goal whose `goal_signed_off: true` was set by `/goal:demo`, not by a human approver; reference the canonical template at [`../../memory/amendments/_demo-seed-origin.md`](../../memory/amendments/_demo-seed-origin.md) which documents the convention). Then dispatch `goal-orchestrator` to append a row before any phase runs: `| 0 | scope | | | amend | amendments/_demo-seed-origin.md |`. The `artifact` column is a **goal-relative path** (relative to `goals//`) per the canonical row-format in [`../../skills/_shared/goal-state.md`](../../skills/_shared/goal-state.md) §"`## History`" — emitting `goals//amendments/...` here would resolve as `goals//goals//...` in `trace-loop` / `export-trace`. The `outcome: amend` is the canonical four-value enum value. Article III §1 (human goal-gate) is not bypassed silently — the audit trail names the bypass for what it is. +4. **Print the "what you just got" summary** — three lines: slug, intent (from the seed's `intent` field), acceptance criteria (count + first criterion verbatim). +5. **Dispatch the [`goal-loop`](../../skills/goal-loop/SKILL.md) skill** against `` to drive **one** iteration end-to-end. The skill sequences `observe` → `orient` → `decide` → (act gate; the seed's `act_gate: always` policy still applies even for the trivial demo set) → `act` → `review-loop`. Required decision-metadata fields (`rationale`, `confidence`, `reversible`) are verified by the `decide` skill before the act gate opens. +6. **Print the closing summary** — one line for the review outcome and one recommendation: `/goal:trace ` to walk the reasoning trail produced by this run. + +## Don't + +- **Don't ask the user to fill in a goal.** That is `/goal:welcome tour` (concept walkthrough) or `/goal:start` (full intake). `/goal:demo` is a zero-input first-touch and the seed is the contract. +- **Don't run multiple iterations.** One iteration only, matching [`/goal:run`](run.md)'s one-iteration contract. If the review returns `continue`, surface the outcome verbatim and stop — the user re-invokes the loop on their own terms. +- **Don't write to [`../../examples/hello-loop/`](../../examples/hello-loop/).** That folder is the canonical seed; the scaffolded copy lands in `goals//` only. +- **Don't bypass the act gate** even though the goal is pre-signed. The seed declares `act_gate: always` for the same reason the welcome flow does — the point is to exercise every non-negotiable gate end-to-end. +- **Don't omit the demo-origin History row or `demo_seed: true` marker.** A demo-signed goal whose audit trail looks like a human-signed goal breaks Article III §1 and Article VIII §1 — the goal gate is the load-bearing guarantee, and `goal_signed_off: true` must always trace to either a human signature in `## History` or an explicit demo-origin marker. diff --git a/plugin-v2/commands/goal/export-trace.md b/plugin-v2/commands/goal/export-trace.md new file mode 100644 index 000000000..90f0d485a --- /dev/null +++ b/plugin-v2/commands/goal/export-trace.md @@ -0,0 +1,39 @@ +--- +description: Export a Goal Loop iteration as an OpenTelemetry GenAI trace JSON. Read-only. Pairs with /goal:trace (human-facing) for the same chain in machine-readable form. +argument-hint: [slug] [iter|--all] [--format=otel-genai|langfuse|raw] [--output=] +allowed-tools: [Read, Grep, Write, Bash, AskUserQuestion] +model: haiku +--- + +# /goal:export-trace + +Export one (or every) iteration of a Goal Loop as a machine-readable trace JSON. **Read-only** — every artifact is read, none is modified (the only write is the optional `traces/iter--.json` output file). Wraps the [`export-trace`](../../skills/export-trace/SKILL.md) skill. + +The companion of [`/goal:trace`](trace.md). Both walk the same chain — acceptance criterion → review verdict → action evidence → approved decision → orientation claim → observation signal — but `/goal:trace` renders Markdown for a human reader, while `/goal:export-trace` renders JSON for observability tooling (OpenTelemetry collectors, Langfuse, Datadog, Helicone, Arize Phoenix, or any sink that accepts OTel GenAI semconv). + +Use this when the user wants to ship a Goal Loop run into their observability stack, archive an audit-ready record of a closed iteration, diff two iterations programmatically, or hand a regulator a structured trail. + +## Inputs + +- `$1` — goal slug (optional). When omitted: + - If exactly one goal under `goals/` has `status` in `{active, paused, blocked, done, cancelled}`, use it. + - Otherwise list candidates (slug, status, last iteration) and ask the user to pick. +- `$2` — iteration number or `--all` (optional). When omitted, default to the most recent **closed** iteration (latest `## History` row whose `outcome` is `continue` / `close-met` / `close-abandon` / `amend`). `--all` exports every iteration as one batch. +- `--format=` (optional) — defaults to `otel-genai`. OTel GenAI semconv span batch (OTLP/JSON), Langfuse-native sessions / traces / observations, or pretty-printed raw iteration graph. +- `--output=` (optional) — defaults to stdout. When set, write to that path; the skill suggests `goals//traces/iter--.json` on a follow-up prompt if neither `--output` nor a stdout pipe is detected. + +## Procedure + +1. Resolve `$1` to a goal slug. If unset and the goal is not unique, ask via `AskUserQuestion`. +2. Resolve `$2` to an iteration number (or `--all`). If unset, pick the most recent closed iteration from `goals//goal-state.md`'s `## History`; if the latest iteration is mid-flight, let the skill ask which to export. +3. Parse `--format` and `--output` flags. Default `--format=otel-genai` and stdout if unset. +4. Invoke the [`export-trace`](../../skills/export-trace/SKILL.md) skill with the resolved slug, iteration (or `--all`), format, and optional output path. The skill reads the artifact tree, builds the iteration graph, renders the chosen format, validates the output (every span has trace_id / span_id, parent links resolve, no orphans), and writes to stdout or the file. +5. Print the path written (or stream the JSON to stdout) and exit. + +## Don't + +- **Don't dispatch a phase agent.** Export is descriptive; it never starts, advances, or closes a loop. If the goal is mid-iteration, export what is on disk; do not run the next phase to "complete" the trace. +- **Don't write anywhere under `goals//`** except `traces/`. No edits to `goal-state.md`, observations, orientation, decisions, actions, or reviews — ever. +- **Don't include source content that hasn't been explicitly opted-in.** The exporter's canonical contract is **default-deny on every source type** (per [`../../skills/export-trace/SKILL.md`](../../skills/export-trace/SKILL.md) §Boundaries and the datasheet template's [`## Export safety` section](../../templates/observe-source-datasheet-template.md)) — `feed`, `api`, `repo`, `document`, `inbox`, `person`, `dataset`, `archive`, `record`, `sensor`, `command` all default to count-and-type-only emission unless the source's datasheet declares `safe_for_export: true`. Sources whose datasheets were filled before wave-9 (and therefore omit `## Export safety` entirely) are treated as `safe_for_export: false`. The exporter additionally applies a built-in secret-pattern redaction (AWS keys, GitHub tokens, JWTs, OAuth secrets, PEM blocks) before emission even when `safe_for_export: true`. +- **Don't recommend a vendor.** Format labels (`langfuse`) name technical shapes, not endorsements. The plugin's stance is to emit standards-shaped output; adopters choose their sink. +- **Don't run from outside the plugin's directory.** Relative paths in the skill assume the plugin layout. diff --git a/plugin-v2/commands/goal/list.md b/plugin-v2/commands/goal/list.md new file mode 100644 index 000000000..46333339e --- /dev/null +++ b/plugin-v2/commands/goal/list.md @@ -0,0 +1,41 @@ +--- +description: List every goal under goals/ with phase, iteration, status, and last-activity. Read-only portfolio view. +argument-hint: [--all | --active | --stalled | --done | --cancelled] +allowed-tools: [Read, Grep, Bash, AskUserQuestion] +model: haiku +--- + +# /goal:list + +Render a portfolio view of every goal under `goals/`. **Read-only** — no artifact is written or modified. The single most recent activity timestamp per goal sorts the table. Pair with [`/goal:status`](status.md) for a deep dive into one slug, and with [`/goal:trace`](trace.md) for a full reasoning walk on one iteration. + +## Inputs + +- `$1` — optional filter flag. One of: + - `--all` (default) — every goal, regardless of status. + - `--active` — only `status: active`. + - `--stalled` — only goals with `status: active | paused | blocked` whose `updated_at` is older than 7 days. + - `--done` — only `status: done`. + - `--cancelled` — only `status: cancelled`. + +If `$1` is anything else, treat it as `--all` and print a one-line note that the flag was unrecognised. + +## Procedure + +1. Invoke the [`list-goals`](../../skills/list-goals/SKILL.md) skill with the resolved filter flag. +2. The skill scans `goals/*/goal-state.md`, extracts `slug`, `status`, `mode`, `current_phase`, `iteration`, `updated_at`, and the most recent `## History` row's `outcome` per goal, applies the filter, and sorts by `updated_at` descending. +3. Print a one-line summary at the top: `N active, M paused/blocked, K closed` (closed = `done` + `cancelled`). Then print the table: + + ``` + | slug | status | phase | iter | last_outcome | last_activity_ago | next_command | + |---|---|---|---|---|---|---| + ``` + + `last_activity_ago` is a humanised delta against today (e.g. `2h`, `3d`, `2w`). `next_command` is the suggested follow-up per status (see `list-goals` skill). +4. If any rows match the stalled rule (status `active | paused | blocked`, `updated_at` older than 7 days), append a **Stalled goals** subsection listing those slugs with their `updated_at` and the suggested next command (`/goal:status ` or `/goal:close `). + +## Don't + +- Don't edit any goal artifact. `/goal:list` is read-only — that is its contract. +- Don't dispatch a phase agent. The skill reads `goal-state.md` and the latest `## History` row directly. +- Don't fabricate fields when a `goal-state.md` is malformed. Report the slug with `status: unknown` and move on. diff --git a/plugin-v2/commands/goal/observe.md b/plugin-v2/commands/goal/observe.md new file mode 100644 index 000000000..8c63d04dd --- /dev/null +++ b/plugin-v2/commands/goal/observe.md @@ -0,0 +1,37 @@ +--- +description: Run the Observe phase for a goal — scan configured sources in parallel and emit a timestamped observations artifact. +argument-hint: [goal-slug] +allowed-tools: [Read, Edit, Write, Grep, Bash, WebFetch, WebSearch, AskUserQuestion] +--- + +# /goal:observe + +Run the **Observe** phase of the Goal Loop. + +## Inputs + +- `$1` — goal slug (optional). When omitted: + - If exactly one goal under `goals/` has `status` in `{active, paused, blocked}` (the set this command's preflight accepts), use it. + - Otherwise, list every goal whose `status` is in `{active, paused, blocked}` and ask the user to pick. Paused and blocked goals are listed because they are legitimate resume entry points; the preflight gates them via `AskUserQuestion` before dispatching. Closed goals (`done | cancelled`) are not listed — they are terminal. + +## Procedure + +0. **Orient the user first.** Before dispatching anything, surface a one-line orientation: *"About to run Observe on `` declared source(s). Each `observer` will write raw signals to `goals//observations/`. This usually takes 20–60 seconds per source; parallel observers fan out concurrently. You'll see a summary when the phase completes."* +1. Resolve the goal slug from `$1` or by inspecting `goals/`. +2. Read `goals//goal-state.md`. Confirm: + - Goal gate is signed (`goal_signed_off: true`); if not, stop and recommend `/goal:start` or surface the sign-off prompt. + - `current_phase` is `scope` (the post-`set-goal` entry state for a freshly signed goal), `review` (last iteration's review file is on disk with `outcome: continue` and `iteration:` equal to the goal's current `iteration:` — the [observe skill](../../skills/observe/SKILL.md) §"Step 1" enforces the iteration-match check), or `observe` (resume). If the phase is `orient`, `decide`, or `act`, warn the user — Observe should not re-run mid-iteration unless they explicitly want to refresh signals. **`current_phase: review` is NOT a free pass to start a new iteration**: if the review file is absent, has missing `outcome:`, or its `iteration:` does not match the goal's current iteration, the observe skill refuses and routes to `/goal:review` per [constitution Article VI §1](../../memory/constitution.md). The orchestrator transitions `current_phase: review → observe` only after the iteration-match check passes; dispatching Observe directly from `review` cannot bypass the closure gate. +3. Invoke the [`observe`](../../skills/observe/SKILL.md) skill. The skill: + - Reads the goal's declared observe sources from `goal-state.md`. + - Dispatches one `observer` subagent per source, in parallel where supported. + - Each `observer` writes raw signals into `goals//observations/--.md` (double dash separates the timestamp from the source id; the orienter relies on this pattern to group per-iteration source files). Per-signal dedup and cross-source merging are the orienter's job, not the observe skill's. + - On fan-in, the skill dispatches `goal-orchestrator` to set `current_phase: orient`, bump `iteration` when this is the first Observe of a new cycle, and append a single `## History` row citing the observation timestamp and the list of per-source files. +4. **`/goal:observe` writes nothing to `goal-state.md`**; state transitions are owned by `goal-orchestrator` and dispatched by the `observe` skill. +5. Print a summary: number of sources scanned, number of signals captured, observation file paths (one per source), and the next recommended command (`/goal:orient `). + - Then render a single plain-English line: *"Captured `` signals across `` source(s); flagged `` as deltas vs. prior iteration. Next: Orient will synthesise these against your acceptance criteria."* This complements the technical paths above; it does not replace them. + +## Don't + +- Don't synthesise or interpret signals here — that is Orient's job. Observers report raw, source-attributed facts only. +- Don't edit `orientation.md`, `decisions.md`, or any other phase's artifact. Observe writes only under `observations/` and updates `goal-state.md`. +- Don't fan out to sources not declared in `goal-state.md`. New sources require a goal amendment. diff --git a/plugin-v2/commands/goal/orient.md b/plugin-v2/commands/goal/orient.md new file mode 100644 index 000000000..e4e8eb409 --- /dev/null +++ b/plugin-v2/commands/goal/orient.md @@ -0,0 +1,38 @@ +--- +description: Run the Orient phase for a goal — synthesise the latest observations against goal, history, and context, refreshing orientation.md. +argument-hint: [goal-slug] +allowed-tools: [Read, Edit, Write, AskUserQuestion] +--- + +# /goal:orient + +Run the **Orient** phase of the Goal Loop. + +## Inputs + +- `$1` — goal slug (optional). When omitted: + - If exactly one goal under `goals/` has `status` in `{active, paused, blocked}` (the set this command's preflight accepts), use it. + - Otherwise, list every goal whose `status` is in `{active, paused, blocked}` and ask the user to pick. Paused and blocked goals are listed because they are legitimate resume entry points; the preflight gates them via `AskUserQuestion` before dispatching. Closed goals (`done | cancelled`) are not listed — they are terminal. + +## Procedure + +0. **Orient the user first.** Before dispatching, surface a one-line orientation: *"About to refresh `orientation.md`. The `orienter` reads this iteration's observations + the prior orientation + history, and synthesises against your acceptance criteria. The previous orientation will be archived. You'll see a summary of what changed."* +1. Resolve the goal slug from `$1` or by inspecting `goals/`. +2. Read `goals//goal-state.md`. Confirm: + - `current_phase` is `orient` (i.e. Observe has just completed). If the phase is anything else, stop and surface the mismatch — propose `/goal:observe ` if the loop has not collected fresh signals yet. +3. Invoke the [`orient`](../../skills/orient/SKILL.md) skill. The skill: + - Reads the per-source observation files for the current iteration under `goals//observations/--.md`. + - Reads the prior `orientation.md` (if any) and any relevant history under `goals//archive/`. + - Dispatches the `orienter` subagent to synthesise: what changed, what it means against the goal's acceptance criteria, what is now uncertain, and which assumptions have been falsified. + - The `orienter` archives the prior synthesis to `goals//archive/orientation-.md` then writes the refreshed `goals//orientation.md`. + - When the goal opted into **Parallel-observer dedup**, the orienter surfaces duplicate signals before emitting the synthesis (the `signal-deduper` subagent is consulted at Observe fan-in — see [`../../skills/observe/SKILL.md`](../../skills/observe/SKILL.md) §"Step 4a — Optional cross-source dedup (parallel observers only)"). + - On completion, the skill dispatches `goal-orchestrator` to set `current_phase: decide` and append a `## History` row citing the orientation timestamp. +4. **`/goal:orient` writes nothing to `goal-state.md`**; state transitions are owned by `goal-orchestrator` and dispatched by the `orient` skill. +5. Print a summary: key shifts since the last orientation, open uncertainties, and the next recommended command (`/goal:decide `). + - Then render: *"Refreshed orientation. Found `` new claims, `` contradictions, `` open questions. Next: Decide will propose actions to address them."* This complements the technical artifact list above; it does not replace it. + +## Don't + +- Don't collect new signals. Orient consumes whatever Observe last produced; if signals are stale, the user should re-run `/goal:observe`. +- Don't propose actions. That is Decide's job. Orientation is interpretation, not prescription. +- Don't overwrite `goal-state.md` fields other than `current_phase` and the hand-off log. diff --git a/plugin-v2/commands/goal/review.md b/plugin-v2/commands/goal/review.md new file mode 100644 index 000000000..75316c6be --- /dev/null +++ b/plugin-v2/commands/goal/review.md @@ -0,0 +1,43 @@ +--- +description: Close the loop iteration — compare outcomes to acceptance criteria and choose continue, close, or amend. +argument-hint: [goal-slug] +allowed-tools: [Read, Edit, Write, Grep, AskUserQuestion] +--- + +# /goal:review + +Run the **Review** phase of the Goal Loop and close the current iteration. + +## Inputs + +- `$1` — goal slug (optional). When omitted: + - If exactly one goal under `goals/` has `status` in `{active, paused, blocked}` (the set this command's preflight accepts), use it. + - Otherwise, list every goal whose `status` is in `{active, paused, blocked}` and ask the user to pick. Paused and blocked goals are listed because they are legitimate resume entry points; the preflight gates them via `AskUserQuestion` before dispatching. Closed goals (`done | cancelled`) are not listed — they are terminal. + +## Procedure + +0. **Orient the user first.** Before dispatching, surface a one-line orientation: *"About to close this iteration. The `loop-reviewer` grades each acceptance criterion against the evidence and returns one of: `continue`, `close-met`, `close-abandon`, `amend`. You'll be asked to confirm `close-abandon` and `amend` before they apply."* +1. Resolve the goal slug from `$1` or by inspecting `goals/`. +2. Read `goals//goal-state.md`. Confirm: + - `current_phase` is `review`. This phase is set either by [`act`](../../skills/act/SKILL.md) after fan-in (the normal post-Act case) **or** by [`decide`](../../skills/decide/SKILL.md) when the act gate produced no executable actions (rejected, deferred, or `act_gate: never`). Both cases are valid entries to Review. + - **For the post-Act case** — the latest action set under `goals//actions/iter-/` for the current iteration is present. + - **For the no-action case** — `## History` records an `act: skipped` row for the current iteration with the reason (`all rejected` / `deferred` / `policy forbids`). The review will still grade against acceptance criteria using observations + orientation + the decision set; the action log is simply absent. + - If `current_phase` is anything else, stop and surface the mismatch — `/goal:review` only runs after Act (or after Decide produced no actions). +3. Invoke the [`review-loop`](../../skills/review-loop/SKILL.md) skill. The skill: + - Reads the goal's acceptance criteria from `goal-state.md`. + - Reads the latest `orientation.md`, the approved subset from `decisions.md`'s `## Human Approval` section, and the per-action files under `goals//actions/iter-/` (or recognises the `act: skipped` row when there are none). + - Dispatches the `loop-reviewer` subagent to produce `goals//reviews/.md`. The review references **each acceptance criterion explicitly** and assigns one of: `met | partial | unmet | blocked`. + - The `loop-reviewer` returns exactly one of the four canonical loop outcomes: `continue | close-met | close-abandon | amend`. + - The `review-loop` skill itself handles the user gate (presenting the verdict for `close-abandon` and `amend`), dispatches `goal-orchestrator` to apply the resulting state change, and (for `amend`) routes through `set-goal` in amend mode. **`/goal:review` writes nothing to `goal-state.md`**; that is the skill's contract. +4. Print a summary: per-criterion verdict, iteration outcome (one of `continue | close-met | close-abandon | amend`), and the next recommended command: + - `continue` → `/goal:run ` or `/goal:observe `. + - `close-met` or `close-abandon` → `/goal:status ` to confirm final state. + - `amend` → `/goal:amend ` to re-sign the contract (or `/goal:start ` in amend mode). + - Then render the verdict in plain English: *"Iteration `` verdict: ``. ``/`` criteria met. Recommended next: ``."* This complements the per-criterion verdict and next-command list above; it does not replace them. + +## Don't + +- Don't grade against criteria invented in the moment. Review compares to the acceptance criteria recorded at goal sign-off (or the last approved amendment) — nothing else. +- Don't edit `orientation.md`, `decisions.md`, or action files. The `loop-reviewer` writes only `reviews/.md`; this command writes nothing. +- Don't close the loop unilaterally. The user gate runs inside the `review-loop` skill for `close-abandon` and `amend`; for `close-met` and `continue` the skill applies the verdict via `goal-orchestrator` directly. +- Don't update `goal-state.md` from this command. All state transitions flow through `goal-orchestrator`, dispatched by the `review-loop` skill — never by `/goal:review`. diff --git a/plugin-v2/commands/goal/run.md b/plugin-v2/commands/goal/run.md new file mode 100644 index 000000000..4462f3b6d --- /dev/null +++ b/plugin-v2/commands/goal/run.md @@ -0,0 +1,43 @@ +--- +description: Drive a full Goal Loop iteration end-to-end — Observe → Orient → Decide → human gate → Act → Review. +argument-hint: [goal-slug] +allowed-tools: [Read, Edit, Write, Grep, Bash, WebFetch, WebSearch, AskUserQuestion] +--- + +# /goal:run + +Drive one full iteration of the Goal Loop. + +## Inputs + +- `$1` — goal slug (optional). When omitted: + - If exactly one goal under `goals/` has `status` in `{active, paused, blocked}` (the set this command's preflight accepts), use it. + - Otherwise, list every goal whose `status` is in `{active, paused, blocked}` and ask the user to pick. Paused and blocked goals are listed because they are legitimate resume entry points; the preflight gates them via `AskUserQuestion` before dispatching. Closed goals (`done | cancelled`) are not listed — they are terminal. + +## Procedure + +1. Resolve the goal slug from `$1` or by inspecting `goals/`. +2. Read `goals//goal-state.md`. Confirm: + - `goal_signed_off: true` (the Goal gate is signed). If not, stop and recommend `/goal:start ` to complete sign-off. + - `status` is in `{active, paused, blocked}` (the resumable set; matches the input-contract picker). If `status: paused`, surface via `AskUserQuestion`: `Resume the goal — set status: active and continue from current_phase` (Recommended; dispatches `goal-orchestrator` to flip `paused → active` before running the iteration) / `Inspect first — exit, recommend /goal:status ` / `Cancel`. If `status: blocked`, surface the latest `## History` blocker row first and ask: `Blocker resolved — resume and continue` / `Still blocked — pause to investigate` / `Cancel`. On resume, `goal-orchestrator` flips the status before the iteration runs. If `status: done | cancelled`, surface that and stop (terminal goals route through `/goal:start ` revive or `/goal:start ` fresh). + - `current_phase` is a valid iteration-entry value — `scope` (post-`set-goal` first run) or `observe` (`review-loop` already applied a `continue` outcome and the orchestrator advanced to `observe` per the canonical state model). `review` is **not** a valid entry: it means the prior iteration's review verdict has not been finalised yet — running `/goal:run` from `review` would start a fresh Observe pass before closure and desynchronise the iteration history. If `current_phase` is `review`, stop and recommend `/goal:review ` to close the in-flight iteration first. If `current_phase` is `orient`, `decide`, or `act`, the goal is mid-iteration — stop and recommend either `/goal: ` to resume that phase or `/goal:status ` to inspect first. `/goal:run` does not restart an in-flight iteration. +3. Invoke the [`goal-loop`](../../skills/goal-loop/SKILL.md) skill. The skill sequences the iteration by dispatching the per-phase skills in order; each per-phase skill dispatches its specialist subagent and (on phase completion) dispatches `goal-orchestrator` to advance state. `goal-loop` itself does not write `goal-state.md`. The per-phase skills are: + - **Observe** — [`observe`](../../skills/observe/SKILL.md) dispatches one `observer` per declared source (parallel where supported). Each observer writes its own file at `goals//observations/--.md` (the double-dash separates the iteration timestamp from the source id; the orienter relies on this pattern to group per-iteration source files). When exactly one source is declared, the source-id suffix may be omitted (`.md`). When N ≥ 2 observers ran in parallel and the goal opted into cross-source dedup, [`signal-deduper`](../../agents/signal-deduper.md) also writes a merged view at `--_merged.md` (double-dash + leading-underscore prefix on `_merged`). + - **Orient** — [`orient`](../../skills/orient/SKILL.md) dispatches the `orienter` to refresh `goals//orientation.md`. + - **Decide** — [`decide`](../../skills/decide/SKILL.md) dispatches the `decider` to append a ranked action set to `goals//decisions.md`. + - **Act gate** — [`decide`](../../skills/decide/SKILL.md) presents the proposed set to the user and captures the verdict in the decision set's `## Human Approval` section; the goal's `act_gate` policy may auto-approve reversible items, but irreversible actions always require explicit confirmation. + - **Act** — [`act`](../../skills/act/SKILL.md) dispatches one `actor` per approved action (fan-out where independent), recording each under `goals//actions/iter-/`. + - **Review** — [`review-loop`](../../skills/review-loop/SKILL.md) dispatches the `loop-reviewer` to grade against acceptance criteria and write `goals//reviews/.md`. +4. After the `goal-loop` skill returns, the iteration is fully closed — `review-loop` has already applied the verdict via `goal-orchestrator` (state, history row, status flip on terminal outcomes). `/goal:run` writes nothing to `goal-state.md`. +5. Print a summary: iteration number, phase artifacts written, both gate outcomes (Act gate via `decide`, loop outcome via `review-loop` — one of `continue | close-met | close-abandon | amend`), final state, and the next recommended command: + - `continue` → `/goal:run ` (or wait for next cadence). + - `close-met` or `close-abandon` → `/goal:status ` to confirm final state. + - `amend` → `/goal:amend ` to re-sign the contract. + +## Don't + +- Don't run any phase outside the `goal-loop` skill from this command. The skill sequences phases and gates; bypassing it breaks phase isolation and the audit trail. +- Don't proceed past the Act gate without explicit human approval for any irreversible action. Even with `act_gate: low-risk-auto`, irreversible items always require a human signal. +- Don't combine iterations. Each `/goal:run` invocation is exactly one Observe→Review pass. To run continuously, invoke again (or rely on cadence for recurring goals — see [`../../docs/cadence-recipes.md`](../../docs/cadence-recipes.md)). +- Don't redefine the goal in flight. If Orient or Review reveals a defect in acceptance criteria, the `review-loop` skill surfaces an `amend` outcome and routes through `set-goal` — `/goal:run` never rewrites `goal-state.md` itself. +- Don't re-apply the loop outcome here. `review-loop` has already done it; doing it twice writes duplicate `## History` rows. diff --git a/plugin-v2/commands/goal/start.md b/plugin-v2/commands/goal/start.md new file mode 100644 index 000000000..60e9dc43f --- /dev/null +++ b/plugin-v2/commands/goal/start.md @@ -0,0 +1,44 @@ +--- +description: Bootstrap a new goal — scaffold goals// and run the set-goal skill to define intent, constraints, acceptance, mode, and cadence. +argument-hint: [intent] +allowed-tools: [Read, Edit, Write, Bash, AskUserQuestion] +--- + +# /goal:start + +Bootstrap a new goal. + +## Inputs + +- `$1` — goal slug (kebab-case, required). e.g. `daily-brief-project-x`, `incident-checkout-500s`, `release-1-2-3`. +- `$2` — short intent statement (optional). One sentence of what outcome is wanted. If omitted, the `set-goal` skill will elicit it interactively. + +This command is the single entry point for **new** goals. For amendments to an existing goal, prefer [`/goal:amend`](amend.md) (the dedicated amend command); `/goal:start ` still works in amend mode as a fallback for back-compat. `/goal:review` and `/goal:close` route the `amend` outcome through `/goal:amend` first. + +## Procedure + +1. If `$1` is missing, ask for it. +2. Detect whether `goals/$1/` already exists. Three cases: + - **New goal (`goals/$1/` does not exist)** — proceed to step 4. + - **Existing active goal (`goals/$1/goal-state.md` present, `status: active | paused | blocked`)** — surface the current state via `AskUserQuestion`: `Amend the goal` (Recommended when called from `/goal:review` or `/goal:close` with `amend`) / `Inspect status only` / `Pick a different slug`. On `Amend`, skip the directory scaffold and jump to step 5 with `mode: amend`. On `Inspect`, recommend `/goal:status $1` and stop. On `Pick a different slug`, ask for a new slug and restart. + - **Closed goal (`status: done | cancelled`)** — surface that and ask `Reopen via amend` / `Pick a different slug` / `Stop`. On reopen, jump to step 5 with `mode: amend` **and `revive: true`** so the step-6 orchestrator hand-off knows to take the revive branch (see [`amend.md`](amend.md) Step 5 case 3). The revive branch is the only path that flips `status` back to `active`; the normal amend hand-off preserves the prior `status` per the ownership matrix (the same rule `set-goal` and `/goal:close` follow). Without this explicit revive flag the reopen request would land an `amend` row and a `current_phase: scope` transition but leave `status: done | cancelled`, dead-ending the documented `/goal:run` follow-up (which requires `status: active`). +3. **Compose check.** Scan `session-goals/*.md` for an active session goal. If present, surface via `AskUserQuestion`: + - `Continue with Goal Loop start — the session goal stays active` (Recommended) + - `Clear the session goal first via /set-goal --clear, then resume here` + Do not auto-clear the session goal. +4. (New goals only.) Create the directory `goals/$1/` (Bash, `mkdir -p`), plus the standard sub-directories: `goals/$1/observations/`, `goals/$1/actions/`, `goals/$1/reviews/`, `goals/$1/archive/`, `goals/$1/amendments/`. The `amendments/` subdirectory is required from creation — `/goal:amend` writes per-goal amendment records there (`goals//amendments/-amend-.md`) on every amendment, and the directory must exist or the first amend fails (or worse, leaves a dangling `## History` artifact link if implementers skip the write failure). +5. Invoke the [`set-goal`](../../skills/set-goal/SKILL.md) skill. Pass `slug: $1`, `intent: $2` (when provided), and `mode: create | amend` per step 2. + - **Create mode** — walks the user through intent, constraints, acceptance criteria, mode (one-shot vs recurring), cadence (for recurring), observe sources, and act-gate policy. Writes `goals/$1/goal-state.md` with `current_phase: scope` and `iteration: 0` (per the [`_shared/goal-state.md`](../../skills/_shared/goal-state.md) schema; the first Observe transitions it to `observe`). + - **Amend mode** — reads the existing `goals/$1/goal-state.md`, presents each scope section in turn, and lets the user accept, edit, or replace it. Bumps `updated_at` and applies the scope-section changes; **does not append an `## History` row** — `set-goal`'s own contract preserves `## History` verbatim in amend mode (see [`../../skills/set-goal/SKILL.md`](../../skills/set-goal/SKILL.md) §"Outputs"). Never silently overwrites — every changed section is shown back for re-confirmation. + - Both modes surface the resulting goal for human sign-off (the **Goal gate**). The first (or next) loop iteration must not run until the user approves the contract. +6. **Amend path only — write the amendment record, then orchestrator hand-off.** When step 5 ran in amend mode, mirror [`/goal:amend`](amend.md) Step 5: **first** write the amendment record file at `goals/$1/amendments/-amend-.md` (using [`../../templates/constitution-amendment-template.md`](../../templates/constitution-amendment-template.md) scoped to the goal's contract — section(s) changed, before / after diff, rationale, approver; `` is a per-day sequence number to disambiguate multiple amendments on the same date). This file is the resolvable artifact the upcoming `## History` `outcome: amend` row points at; without writing it the History link would dangle, breaking `trace-loop` and `export-trace` artifact resolution. Required on every back-compat amend through `/goal:start`, just as `/goal:amend` requires it. **Then** dispatch [`goal-orchestrator`](../../agents/goal-orchestrator.md) to (a) append an `amend` row to `## History` citing the section(s) changed, `outcome: amend`, and the `artifact` column pointing at the amendment record file written above as the **goal-relative path** `amendments/-amend-.md` (per the canonical row format at [`../../skills/_shared/goal-state.md`](../../skills/_shared/goal-state.md) §"`## History`" — a prefixed citation would resolve as `goals//goals//...` in `trace-loop` / `export-trace`), (b) set `current_phase: scope` to re-bracket the goal gate, and (c) **on the revive branch** (`revive: true` set in step 2 for a previously-closed goal) **also flip `status` from `done | cancelled` back to `active`**, matching the revive-via-amend path in [`amend.md`](amend.md) Step 5 case 3. On the normal amend branch (existing `active | paused | blocked` goal), preserve the prior `status` verbatim — the orchestrator owns every subsequent status transition per the ownership matrix and a maintenance amend must not silently resume a paused/blocked goal. Without this step the amendment lands in the body but leaves no audit trail. Skip this step on the create path; `current_phase: scope` is already set by `set-goal` for new goals. +7. Print a summary: goal slug, create-or-amend, mode, cadence, number of observe sources, act-gate policy, and the next recommended command: + - New / amended one-shot goal → `/goal:run $1`. + - New / amended recurring goal → `/goal:run $1` to drive the first iteration, or `/goal:observe $1` to start the loop manually. + - Reopened goal → `/goal:run $1` after the Goal gate signs. + +## Don't + +- Don't run any loop phase from this command. `/goal:start` is bootstrap only — Observe/Orient/Decide/Act all require the Goal gate to have been signed first. +- Don't invent acceptance criteria. If the user cannot state observable conditions, the `set-goal` skill must surface that as a clarification, not paper over it. +- Don't write into `goals//` artifacts other than `goal-state.md` and the empty directory shells. Phase artifacts are written by their own commands. diff --git a/plugin-v2/commands/goal/status.md b/plugin-v2/commands/goal/status.md new file mode 100644 index 000000000..59046115a --- /dev/null +++ b/plugin-v2/commands/goal/status.md @@ -0,0 +1,46 @@ +--- +description: Print the current state of a goal — phase, iteration, last actions, last review verdict, open acceptance criteria. Read-only. +argument-hint: [goal-slug] +allowed-tools: [Read, Grep, AskUserQuestion] +model: haiku +--- + +# /goal:status + +Report the current state of a goal. **Read-only** — no artifact is written or modified. + +## Inputs + +- `$1` — goal slug (optional). When omitted: + - If exactly one goal under `goals/` has `status: active`, use it. + - If zero or more than one is active, list all goals (slug, status, current phase, iteration) and ask the user to pick — or report all of them in a compact table when the user asks for a portfolio view. + +## Procedure + +1. Resolve the goal slug from `$1` or by inspecting `goals/`. +2. Read `goals//goal-state.md`. Extract: + - `status`, `mode`, `cadence` (if recurring), `goal_signed_off`. + - `current_phase`, `iteration`, `updated_at`. + - The most recent `## History` row (phase, outcome, artifact link). +3. Locate the most recent artifacts: + - Last observation index under `goals//observations/` — newest by filename timestamp (filenames are `--.md` or `--_index.md` / `--_merged.md`). + - Current `goals//orientation.md` (if any). + - Last decision block in `goals//decisions.md` (and its `status` — proposed / approved / done / failed / rejected / deferred). + - Last action file under `goals//actions/iter-/` — **newest by frontmatter `ended_at` (preferred) or file mtime**; action logs are named by action id (`a-1.md`, `a-2.md`), not timestamp, so filename ordering is unreliable for "most recent action". `ended_at` is the schema field defined in `templates/action-log-template.md`. + - Last review under `goals//reviews/` and its recommended outcome — newest by filename timestamp (`.md`). +4. Compute the **open acceptance criteria**: from `goal-state.md`'s declared criteria, filter to those not marked `met` in the most recent review (criteria the loop is still working on). +5. **Read `health.md` if present.** Read `goals//health.md`. Extract its `## Snapshot` line (status, last phase, last updated, stalled-since, iteration) and its `## Trend` paragraph. Surface these at the **top** of the status report — before the structured per-phase details — so an SRE or operator gets the rolling observability summary first. If `health.md` is absent (goal was created before this template shipped, or no phase transition has run yet), note that explicitly with a one-line "no `health.md` present yet (will be written on the next phase transition)" and skip the snapshot block. +6. Print a compact, human-readable report: + - Print a 1-line headline first, then the structured report. Headline format: *"`` @ iter ``, phase ``, ``/`` criteria green, gate pending: `>`, last activity `` ago."* The 1-line headline answers "where am I?" before the structured report fills in the rest. + - Health — `health.md` `## Snapshot` block (status, last phase, last updated, stalled-since, iteration) followed by the `## Trend` paragraph. Skip with a one-line note if `health.md` is absent. + - Phase — `current_phase`, `iteration`, count of approved action IDs in the latest decision set's `## Human Approval` section (if any). + - Last activity — timestamps and paths for the most recent observation, orientation, decision block, action, and review. + - Last verdict — the `loop-reviewer`'s recommended outcome and per-criterion verdicts (one line each). + - Open acceptance criteria — bullet list of criteria not yet `met`. + - Suggested next command — derived from `current_phase` (e.g. `observe` → `/goal:observe`, `act` → `/goal:act`, `review` → `/goal:review`, terminal status → no action needed). + +## Don't + +- Don't write or modify any file. `/goal:status` is read-only — that is its contract. +- Don't dispatch any phase agent or skill. Status reads artifacts directly. +- Don't infer beyond what the artifacts say. If a field is missing, report it as missing rather than guessing. diff --git a/plugin-v2/commands/goal/trace.md b/plugin-v2/commands/goal/trace.md new file mode 100644 index 000000000..f14a156dd --- /dev/null +++ b/plugin-v2/commands/goal/trace.md @@ -0,0 +1,33 @@ +--- +description: Reconstruct the full reasoning trail for one Goal Loop iteration — read-only walk from acceptance criteria back through observations. +argument-hint: [slug] [iteration] +allowed-tools: [Read, Grep, Write, AskUserQuestion] +model: haiku +--- + +# /goal:trace + +Audit one iteration of a Goal Loop end-to-end. **Read-only** — every artifact is read, none is modified. Wraps the [`trace-loop`](../../skills/trace-loop/SKILL.md) skill. + +Use this when the user wants to walk how a decision was reached, prepare a postmortem on a closed loop, or surface the evidence chain behind a single acceptance criterion. + +## Inputs + +- `$1` — goal slug (optional). When omitted: + - If exactly one goal under `goals/` has `status` in `{active, paused, blocked, done, cancelled}`, use it. + - Otherwise list candidates (slug, status, last iteration) and ask the user to pick. +- `$2` — iteration number (optional). When omitted, default to the most recent **closed** iteration (latest `## History` row whose `outcome` is `continue` / `close-met` / `close-abandon` / `amend`). The skill will ask if the choice is ambiguous (e.g., loop is mid-iteration). + +## Procedure + +1. Resolve `$1` to a goal slug. If unset and the goal is not unique, ask via `AskUserQuestion`. +2. Resolve `$2` to an iteration number. If unset, pick the most recent closed iteration from `goals//goal-state.md`'s `## History`; if the latest iteration is mid-flight, let the skill ask which to trace. +3. Invoke the [`trace-loop`](../../skills/trace-loop/SKILL.md) skill with the resolved slug and iteration. The skill walks each acceptance criterion backwards from the review verdict to the cited observations, renders the chain criterion-by-criterion, and surfaces every missing link as `[gap]`. +4. Print the rendered trace to console. If the user opts in via the skill's follow-up prompt, the skill persists a copy to `goals//traces/iter--.md` — otherwise the output is console-only. + +## Don't + +- Don't write to any phase artifact. The only allowed write is the optional persisted trace under `goals//traces/`, and only on explicit user opt-in inside the skill. +- Don't fill chain gaps. Every missing link is reported as `[gap]` with the observed deficit named. +- Don't speculate about *why* a chain is incomplete. Report only what the artifacts say. +- Don't run from outside the plugin's directory — relative paths in the skill assume the plugin layout. diff --git a/plugin-v2/commands/goal/welcome.md b/plugin-v2/commands/goal/welcome.md new file mode 100644 index 000000000..043a3fd16 --- /dev/null +++ b/plugin-v2/commands/goal/welcome.md @@ -0,0 +1,31 @@ +--- +description: First-time guided welcome for the goal-loop plugin. Walks the user through the concept, optionally runs a "hello world" loop, or hands off to the getting-started doc. +argument-hint: [tour | hello | docs] +allowed-tools: [Read, Edit, Write, Bash, AskUserQuestion] +model: haiku +--- + +# /goal:welcome + +First-time guided welcome for the `goal-loop` plugin. Orients a new user in under ten minutes and hands them off to a working first loop. + +## Inputs + +- `$1` — optional path selector. One of `tour`, `hello`, `docs`. When omitted, the [`welcome`](../../skills/welcome/SKILL.md) skill gates with `AskUserQuestion` to let the user pick. + - `tour` — four-gate plain-language walkthrough of the Goal Loop concept (goal-bounded OODA, the four phases, the two gates, the loop outcomes). + - `hello` — scaffolds `goals/hello-loop/` from the worked example at [`../../examples/hello-loop/goal-state.md`](../../examples/hello-loop/goal-state.md) and drives a single end-to-end iteration with the user watching. + - `docs` — prints a short summary and link to [`../../docs/getting-started.md`](../../docs/getting-started.md), exits cleanly. + +## Procedure + +1. Invoke the [`welcome`](../../skills/welcome/SKILL.md) skill. Pass `$1` straight through as the path selector when present. +2. The skill detects prior use by running `ls goals/ 2>/dev/null`. If `goals/` already contains one or more goal folders, it switches to **Welcome back** mode and offers to resume an existing goal, walk the most recent trace, or run hello-world as a refresher. +3. The skill is the conductor for the welcome flow itself. It dispatches the existing per-phase skills ([`set-goal`](../../skills/set-goal/SKILL.md), [`observe`](../../skills/observe/SKILL.md), [`orient`](../../skills/orient/SKILL.md), [`decide`](../../skills/decide/SKILL.md), [`act`](../../skills/act/SKILL.md), [`review-loop`](../../skills/review-loop/SKILL.md)) for the hello-world iteration. No new subagent is introduced. +4. On exit, the skill prints a three-line summary — what the user just did, where state lives (under `goals/hello-loop/` for the hello path), and three concrete next commands to try. + +## Don't + +- Don't edit, resume, or close any pre-existing goal under `goals/`. The welcome flow is opt-in and additive — it scaffolds `goals/hello-loop/` only when the user picks the `hello` path and confirms. +- Don't auto-run any irreversible action. The hello-world goal is bounded to `goals/hello-loop/` by its constraints; the act gate still applies before the actor executes anything. +- Don't bypass the goal gate. Even on the hello path, the user must sign off on the seeded `goal-state.md` before the first Observe runs. +- Don't substitute synonyms for `phase`, `gate`, `iteration`, `observation`, `orientation`, `decision`, `action`, or `review`. The vocabulary is locked in [`../../docs/method.md`](../../docs/method.md). diff --git a/plugin-v2/commands/set-goal.md b/plugin-v2/commands/set-goal.md new file mode 100644 index 000000000..e1809c613 --- /dev/null +++ b/plugin-v2/commands/set-goal.md @@ -0,0 +1,42 @@ +--- +description: Activate a session goal. In Claude Code, invokes the native /goal command with the goal's stop-hook condition. In Codex/Cursor, writes the goal as a session directive the tool honours for the duration of the session. +argument-hint: [slug] +allowed-tools: [Read, Edit, Write, Bash, AskUserQuestion] +--- + +# /set-goal + +Activate an existing **session goal** in the current session. The user-visible name is `/set-goal`; the backing skill is [`activate-goal`](../skills/activate-goal/SKILL.md) (the name `set-goal` is reserved for the Goal Loop intake skill — see [`../skills/set-goal/SKILL.md`](../skills/set-goal/SKILL.md)). + +A session goal is a session-scoped intent — distinct from a [Goal Loop iteration goal](../skills/_shared/goal-state.md). For the structured, gated, phase-driven loop, use `/goal:start` instead. + +## Inputs + +- `$1` — optional. The slug of an existing session goal. Resolves to `session-goals/.md`. When omitted, the skill lists `session-goals/*.md` and asks the user to pick. +- `--clear` — special form. Tears down the active session goal: clears the native `/goal` stop-hook in Claude Code, deletes `SESSION-GOAL.md` in Codex, deletes `.cursor/rules/session-goal.mdc` in Cursor. + +## Procedure + +1. **Resolve the slug.** If `$1` is `--clear`, jump to the tear-down branch in step 5. Otherwise resolve from `$1`; if missing, `Bash` `ls session-goals/*.md 2>/dev/null` and gate with `AskUserQuestion` on the discovered list. If `session-goals/` is empty, surface that and recommend [`/create-goal`](create-goal.md). +2. **Compose check.** Before activating, scan `goals/*/goal-state.md` for any goal with `status: active | paused | blocked`. If one or more exist, surface via `AskUserQuestion`: + - `Activate session goal alongside the active Goal Loop` (Recommended — they are orthogonal: one is conversation-scoped, the other is iteration-scoped) + - `Pause the Goal Loop while the session runs` (advanced — only useful for short sessions where loop work would distract) + - `Cancel — review the Goal Loop first via /goal:status` + Do not silently activate over an active Goal Loop. +3. **Read the session-goal file.** Verify frontmatter is complete (`slug`, `intent`, `success_criterion`, `stop_condition`, `reversibility`, `status`). Verify the body has `## Intent`, `## Success criterion`, `## Stop condition`. If anything is missing or `status: cancelled | done`, surface the gap and stop — recommend `/create-goal ` to fix. +4. **Local rubric check.** Apply the same falsifiability rubric the [`set-goal`](../skills/set-goal/SKILL.md) skill uses on `acceptance_criteria` to the session goal's `success_criterion` and `stop_condition`. If either fails, gate with `AskUserQuestion`: `Edit the goal first (recommended)` / `Activate as-is` / `Cancel`. On `Edit`, hand off to `/create-goal `. +5. **Dispatch the [`activate-goal`](../skills/activate-goal/SKILL.md) skill.** The skill owns **both** the tool-adapter branch (Claude Code native `/goal ""` / Codex `SESSION-GOAL.md` / Cursor `.cursor/rules/session-goal.mdc`) **and** the stamp on `session-goals/.md` (`status: active`, `activated_at`, and the `## Activation notes` row). The command does not edit the session-goal file itself — `activate-goal` is the sole writer for activation state, matching the single-writer ownership pattern the plugin uses elsewhere (`decide` skill owns `## Human Approval`; `goal-orchestrator` owns `## History`). +6. **Confirmation.** Print one line: `Session goal active: . Stop condition: . Until stop (or /set-goal --clear).` + +### Tear-down branch (`/set-goal --clear`) + +1. Dispatch the [`activate-goal`](../skills/activate-goal/SKILL.md) skill in **tear-down mode**. The skill finds the active session-goal file by frontmatter `status: active`, clears per adapter (Claude Code: `/goal clear` — explicit `clear` argument; Codex: `rm SESSION-GOAL.md`; Cursor: `rm .cursor/rules/session-goal.mdc`), and stamps the `Cleared at:` timestamp on the latest `## Activation notes` row. As with activation, the command does not edit the session-goal file itself. +2. Print one line: `Session goal cleared: .` + +## Don't + +- Don't run any Goal Loop phase from this command. `/set-goal` is session-goal activation only; the Goal Loop runs through `/goal:*`. +- Don't auto-activate a goal without explicit user invocation of this command. A goal file existing under `session-goals/` is not consent to activate it. +- Don't write into another tool's adapter. The activation path is one per tool — Claude Code uses native `/goal`, Codex uses `SESSION-GOAL.md`, Cursor uses `.cursor/rules/session-goal.mdc`. Don't mirror across adapters. +- Don't silently overwrite an already-active session goal. Gate with `AskUserQuestion` on `Replace ` / `Keep ` / `Cancel`. +- Don't synthesise a `stop_condition` if the file is missing one. Refuse activation and recommend `/create-goal `. diff --git a/plugin-v2/docs/README.md b/plugin-v2/docs/README.md new file mode 100644 index 000000000..5f3890891 --- /dev/null +++ b/plugin-v2/docs/README.md @@ -0,0 +1,92 @@ +--- +title: Goal Loop — Docs +folder: plugin-v2/docs +description: Index of the goal-loop plugin documentation set. +entry_point: true +--- + +# Goal Loop — Docs + +> **Start here:** [`method.md`](method.md) is the canonical definition of the Goal Loop. Every other file in this folder either backgrounds it (foundations), shapes it (patterns and customisation), or shows it in action (examples). + +## Files + +| File | One-line description | +|---|---| +| [`getting-started.md`](getting-started.md) | Guided first-loop walkthrough. Pairs with [`/goal:welcome`](../commands/goal/welcome.md). Reads in 5–10 minutes; runs in 15. **Start here on day one.** | +| [`method.md`](method.md) | Canonical definition of the Goal Loop — phases, agents, gates, state model. The contract. | +| [`domain-model.md`](domain-model.md) | The single-read mental model. Every domain type — Goal, Iteration, Phase, Observation, Orientation, DecisionSet, ActionLog, Review, History, Health — documented with shape, ownership, lifecycle, transformations. Read this once before deep work. | +| [`ooda-foundations.md`](ooda-foundations.md) | Background primer on Boyd's OODA loop and how Goal Loop instantiates it. | +| [`goal-orientation.md`](goal-orientation.md) | Why explicit goals beat implicit ones, what makes an acceptance criterion falsifiable, plus the Goal Quality Checklist. | +| [`session-goal-best-practices.md`](session-goal-best-practices.md) | How to formulate a high-quality session goal — falsifiable, bounded, single-outcome, with a clear stop condition. Pairs with `/create-goal` and `/set-goal`; complements but does not replace Goal Loop iteration goals. | +| [`usage-patterns.md`](usage-patterns.md) | The five canonical goal patterns (issue resolution, daily brief, incident triage, release readiness, continuous awareness) with a pattern picker. | +| [`customizing.md`](customizing.md) | How to extend the plugin in your own project — sources, decision criteria, gate policies, subagents, templates. | +| [`contributing.md`](contributing.md) | **Deep-dive** contributor guide — fork-vs-overlay decision, per-surface contribution rubric (agent / skill / template / command / amendment), and the verification checklist before opening a PR. The **entry point** is [`../CONTRIBUTING.md`](../CONTRIBUTING.md) at the plugin root; this file is the long-form reference it links to. | +| [`maintenance.md`](maintenance.md) | How the plugin maintainer keeps the baseline healthy — versioning, deprecation, schema evolution, multi-tool drift, security cadence, contribution model, EOL. | +| [`improvement-strategy.md`](improvement-strategy.md) | Maintainer-facing forward-looking strategy — extension points, multi-tool expansion, domain specialisation, anti-patterns, contribution rubric, roadmap shape. | +| [`anti-patterns.md`](anti-patterns.md) | Tactical anti-patterns catalogue — concrete drifts seen during plugin-v2 development (enum drift, ghost frontmatter, phase-isolation leaks, etc.), the contract or check that resists each, and the grep query that catches a regression. Pairs with the strategic anti-patterns in `improvement-strategy.md`. | +| [`release-checklist.md`](release-checklist.md) | Concrete pre-release gate list — local gates, vocabulary, schema, docs, adapters, examples, compatibility, security, version bump, sign-off. Run before bumping `version` in `plugin.json` and tagging. Pairs with `maintenance.md` (cadence) and `improvement-strategy.md` (direction). | +| [`constitution-v1-criteria.md`](constitution-v1-criteria.md) | Graduation criteria for the constitution moving from v0.1 (Foundation) to v1.0 — the three criteria (no Article I–III amendments for two cycles, five adopters with closures, all five canonical patterns shipped), current status, and what v1.0 does and does not unlock. | +| [`automation-spec.md`](automation-spec.md) | **Spec** (implementation deferred) for the lint / verify / validate / format / spell-check / security / self-application / Obsidian-compliance pipeline that gates every PR touching `plugin-v2/**`. | +| [`tool-adapters.md`](tool-adapters.md) | How the same plugin serves Claude Code, Codex, and Cursor through thin adapters. | + +### Integration & compatibility + +| File | One-line description | +|---|---| +| [`obsidian-compatibility.md`](obsidian-compatibility.md) | How the plugin's `goals//` output integrates with Obsidian vaults — frontmatter property types, tag namespace, link form, file naming, recommended vault setup, and optional Dataview / Bases rollups. The **contract**; pairs with `obsidian-enforcement.md`. | +| [`obsidian-enforcement.md`](obsidian-enforcement.md) | How the Obsidian-compatibility contract is **enforced** — automated O1–O12 checks, recommended tooling stack (`markdownlint-obsidian-cli` + `lychee`), three-layer rollout (plugin CI, adopter pre-commit, adopter on-demand), and integration with `automation-spec.md` Section H. Pairs with `obsidian-compatibility.md`. | +| [`obsidian-setup-guide.md`](obsidian-setup-guide.md) | Step-by-step adopter setup for using the plugin's output as an Obsidian vault — vault-shape choice, recommended Settings panels, recommended community plugins, what works out of the box, common gotchas. Pairs with the compatibility and enforcement contracts. | +| [`dataview-snippets.md`](dataview-snippets.md) | Paste-ready Dataview queries (portfolio dashboard, stalled goals, outcome rollups, per-goal artifact tree, recent reviews) for adopters who open their goal-loop project as an Obsidian vault. Requires the Dataview community plugin. | +| [`examples/issue-resolution.md`](examples/issue-resolution.md) | Narrative walkthrough — one-shot issue resolution end-to-end. | +| [`examples/daily-brief.md`](examples/daily-brief.md) | Narrative walkthrough — recurring daily brief end-to-end. | +| [`examples/incident-triage.md`](examples/incident-triage.md) | Narrative walkthrough — compressed-tempo incident triage. | +| [`examples/release-readiness.md`](examples/release-readiness.md) | Narrative walkthrough — checklist-gated release readiness end-to-end. | +| [`examples/continuous-awareness.md`](examples/continuous-awareness.md) | Narrative walkthrough — perpetual non-software awareness loop (regulatory monitoring). | +| [`glossary.md`](glossary.md) | Quick definitions of the terms the plugin uses, lifted from the canonical sources so domain-neutral newcomers do not have to chase cross-references. | +| [`ux-agentic-cowork.md`](ux-agentic-cowork.md) | Deep UX research on agentic-cowork patterns and how they apply to the goal-loop plugin. For the maintainer and for adopters extending the plugin for their own users. | +| [`research-goal-oriented-ai.md`](research-goal-oriented-ai.md) | Deep research synthesis on goal-oriented work with AI and the OODA loop, read from six product perspectives (user, agent, maintainer, compliance, operations, strategy). Surfaces concrete recommendations for the next RALPH wave. | +| [`troubleshooting.md`](troubleshooting.md) | Problem → cause → fix table for the common loop blockers. | +| [`hooks-recipes.md`](hooks-recipes.md) | Opt-in Claude Code hook recipes that surface Goal Loop state. The plugin ships no hooks; these are adopter-owned. | +| [`progress-affordance-recipe.md`](progress-affordance-recipe.md) | Opt-in adopter recipes for surfacing fan-out / async progress during Observe and Act phases — file-system `_progress.md` primitive plus an optional Claude Code heartbeat hook. | +| [`cadence-recipes.md`](cadence-recipes.md) | Scheduler recipes (cron, GitHub Actions, systemd) for recurring `/goal:run`. The plugin schedules nothing. | +| [`death-spirals.md`](death-spirals.md) | Diagnostic catalogue for the three canonical death-spiral shapes the hard-stop caps prevent — Time spiral, Decision spiral, Act spiral. Pairs with `method.md` §"Hard-stop gates". | +| [`specorator-interop.md`](specorator-interop.md) | How the Goal Loop plugin coexists with the parent Specorator workflow — when to use each, sharing rules, lifecycle independence. | +| [`announcement.md`](announcement.md) | v2.1.0 adopter-facing announcement. TL;DR + persona-by-persona adoption story + 60-second try-it-out. | +| [`adoption-tracking.md`](adoption-tracking.md) | Voluntary adopter self-report channel feeding constitution v1.0 criterion 2 (5 adopters with one closure each). Opt-in only; no telemetry. | + +### Security & compliance + +| File | One-line description | +|---|---| +| [`non-negotiable-guarantees.md`](non-negotiable-guarantees.md) | Distilled hard promises with article and file citations. | +| [`threat-model.md`](threat-model.md) | OWASP-aligned threat-and-mitigation breakdown. | +| [`tool-matrix.md`](tool-matrix.md) | Agent-by-agent tool list for compliance audits. | + +## Reading paths + +- **Need the whole mental model in one read.** Open `domain-model.md` — every type, every relationship, every transformation in a single page. The map; `method.md` and the per-template files are the territory. +- **Brand new — first 10 minutes.** Run [`/goal:welcome`](../commands/goal/welcome.md) — it walks you through the concept and runs a hello-world iteration with you. Reading-first equivalent: [`getting-started.md`](getting-started.md). Either path gets you to a working loop without reading the rest of the docs. +- **Brand new to the plugin.** Read `method.md`, then `glossary.md` (5 minutes), then pick a pattern in `usage-patterns.md`, then read the example that matches. +- **Need OODA context.** Read `ooda-foundations.md` first, then `method.md`. +- **Want to extend the plugin.** Read `method.md` to lock in the contract, then `customizing.md`. For recurring runs see `cadence-recipes.md`. For hooks that surface state see `hooks-recipes.md`. For surfacing fan-out / async progress during long observe or act phases see `progress-affordance-recipe.md`. +- **Contributing to the plugin baseline.** Read `contributing.md` — fork-vs-overlay decision, per-surface contribution rubric, and the verification checklist. Pair with `improvement-strategy.md` for the maintainer's roadmap rubric and `../templates/agent-template.md` / `../templates/skill-template.md` for the scaffolds. +- **Maintaining the plugin itself.** Read `maintenance.md` — versioning, deprecation windows, schema migrations, adapter parity, security cadence, contribution model, and EOL signalling. Pair with `anti-patterns.md` for the tactical drifts each review pass should resist. +- **Improving the plugin (forward-looking).** Read `improvement-strategy.md` — extension points, multi-tool expansion, domain specialisation, anti-patterns, contribution rubric, roadmap shape. Companion to `maintenance.md`. +- **Operating the plugin (release / amendment cycle).** Read `release-checklist.md` before bumping `version` in `plugin.json` and tagging — top-to-bottom pre-release gate. Read `constitution-v1-criteria.md` when planning the v0.1 → v1.0 graduation — the three criteria and what each one is currently sitting on. +- **Shaping plugin UX.** Read `ux-agentic-cowork.md` — twelve agentic-cowork patterns with verdicts against the current plugin, cross-pattern principles, anti-patterns to avoid, and concrete next-step recommendations. Use when designing a new agent, skill, or command surface. +- **Updating the plugin's intellectual foundations.** Read `research-goal-oriented-ai.md` — literature synthesis from six perspectives with concrete file-targeted recommendations. Use when planning a wave that touches the method's foundations, gate metadata, trace exports, runaway protection, acceptance-criteria templates, or regulator-facing artefacts. +- **Wiring the quality pipeline.** Read `automation-spec.md` — the contract every PR-blocking lint / verify / validate / format / spell-check / security / Obsidian-compliance script must satisfy. Implementation lands in a follow-up PR; the spec is the acceptance contract. +- **Keeping output Obsidian-clean.** Read `obsidian-compatibility.md` for the contract, then `obsidian-enforcement.md` for the automated checks that uphold it. +- **Setting up Obsidian.** Read `obsidian-setup-guide.md`, then `dataview-snippets.md` for queries. Reference `obsidian-compatibility.md` (contract) and `obsidian-enforcement.md` (CI). +- **Adopting the plugin in Codex or Cursor.** Read `tool-adapters.md` and the adapter folders ([`.codex/`](../.codex/), [`.cursor/rules/`](../.cursor/rules/)). +- **Auditing the plugin for adoption in a regulated environment.** Read `non-negotiable-guarantees.md` for the contract level, then `threat-model.md` for the OWASP-aligned threat surface, then `tool-matrix.md` for the per-agent tool audit, then [`../memory/constitution.md`](../memory/constitution.md) for the governing principles every guarantee is read against. +- **Loop stuck or behaving weirdly.** Open `troubleshooting.md`. + +## Cross-references + +- Worked example artifacts live under [`../examples/`](../examples/). +- Plugin manifest with the locked agent and skill list: [`../.claude-plugin/plugin.json`](../.claude-plugin/plugin.json). +- Templates referenced by every phase agent: [`../templates/`](../templates/). +- Plugin-wide operating rules: [`../AGENTS.md`](../AGENTS.md). +- Governing principles: [`../memory/constitution.md`](../memory/constitution.md). diff --git a/plugin-v2/docs/adoption-tracking.md b/plugin-v2/docs/adoption-tracking.md new file mode 100644 index 000000000..9a560033c --- /dev/null +++ b/plugin-v2/docs/adoption-tracking.md @@ -0,0 +1,49 @@ +--- +title: Goal Loop — Adoption tracking +folder: plugin-v2/docs +description: Self-report channel for adopters to declare their use of the plugin. Counts toward constitution v1.0 graduation criterion 2 (5 adopters with one completed goal closure each). Voluntary. +entry_point: false +--- + +# Goal Loop — Adoption tracking + +> Companion to [`constitution-v1-criteria.md`](constitution-v1-criteria.md) (the v1.0 graduation criteria) and [`announcement.md`](announcement.md) (the adopter-facing onboarding). This doc names the one self-report channel the plugin operates and explains why participation is voluntary, what gets aggregated, and how to opt out. + +## Why this exists + +[`constitution-v1-criteria.md`](constitution-v1-criteria.md) criterion 2 requires *five adopters running the loop in production, each with at least one completed goal closure* (`outcome: close-met` or `outcome: close-abandon` recorded in `## History` and rolled to a `lessons.md`). The plugin has no telemetry — it cannot count adopters by observing them, and it will not start. Adopters self-report by opening a tracking issue, and the counter is updated by hand from the issue list. This is slow and imprecise, and that is the point: the v1.0 signal should come from adopters who care enough to file an issue, not from a passive metric. + +## How to declare + +Open a GitHub issue against the parent repo with the following shape: + +- **Title:** `[adoption-tracking] ` (the prefix is what the aggregator greps for). +- **Body:** + - **Tool used.** One of Claude Code, Codex, Cursor, Aider, Copilot, Gemini, or "other — specify". + - **What you used Goal Loop for.** One paragraph. Domain, goal shape (one-shot or recurring), rough size (how many iterations to close). + - **Closing review link (optional).** A public link to a `lessons.md` or a closing `## History` row if the project is open. "Private — confirmed verbally" is also acceptable; the counter does not require the artifact, only the report. + - **Anything you want the maintainer to know.** Optional. Friction, surprises, missing features, regretted choices. +- **Label:** `adoption-tracking`. + +That is the full protocol. No survey, no follow-up email, no usage stats to fill in. + +## What gets aggregated + +A quarterly counter (no personally identifying information) lives in [`constitution-v1-criteria.md`](constitution-v1-criteria.md) §"Current status" and shows the number of distinct projects that have self-reported. When the counter hits 5, criterion 2 is met and the plugin is one step closer to constitution v1.0 graduation. Aggregation is the *count* and an optional one-line genre breakdown ("3 software, 1 research, 1 ops" — derived from the issue body, not from extra reporting). Nothing else is rolled up. + +## Privacy + +The plugin requests no information beyond what the adopter chooses to share in the issue body. Tooling consent, contact details, billing data, machine identifiers — none are collected because none are needed. The counter is the only published figure. + +The plugin's no-telemetry stance is structural: there is no runtime, no daemon, no phone-home. The adoption-tracking issue is the *only* signal the maintainer has, by design. + +## Opting out + +Adopters who do not want to be counted simply do not open the issue. The plugin works identically whether or not you self-report; there is no degraded mode, no nag prompt, no telemetry-disable flag (because there is no telemetry to disable). If you have already filed an issue and want to withdraw, close the issue with the comment "withdraw from adoption count" — the maintainer will remove it from the next quarterly aggregate. + +## See also + +- [`constitution-v1-criteria.md`](constitution-v1-criteria.md) — criterion 2 and the v1.0 graduation story. +- [`announcement.md`](announcement.md) — adopter-facing onboarding. +- [`maintenance.md`](maintenance.md) — the release cadence the counter feeds into. +- [`improvement-strategy.md`](improvement-strategy.md) §"State of the Loop" — the quarterly writeup the counter feeds into. diff --git a/plugin-v2/docs/announcement.md b/plugin-v2/docs/announcement.md new file mode 100644 index 000000000..bba8a071e --- /dev/null +++ b/plugin-v2/docs/announcement.md @@ -0,0 +1,62 @@ +--- +title: Goal Loop plugin — Announcement +folder: plugin-v2/docs +description: Adopter-facing onboarding announcement for the goal-loop plugin v2.1.0. Explains what it is, what it gives you, who should adopt it, and the migration story for existing Specorator users. +entry_point: false +--- + +# Goal Loop plugin — Announcement + +> **Announcement-voice doc, more direct than the rest of the doc set.** This page is built for the unprepared first reader — pitch and value rather than method. For the methodical introduction, start with [`getting-started.md`](getting-started.md). For the canonical method, see [`method.md`](method.md). For the type map in one read, [`domain-model.md`](domain-model.md). Read those first if you want the contract before the marketing. + +## TL;DR + +- The `goal-loop` plugin is a domain-agnostic, goal-bounded OODA loop for any decision or delivery cycle — code, content, research, operations, strategy. The method is defined in [`method.md`](method.md). +- One command — `/goal:demo` — scaffolds a sample goal and drives a full Observe → Orient → Decide → Act → Review iteration end-to-end. You can see it work in under two minutes. +- Install by `git subtree` into the plugin root of any project, or as a Claude Code plugin via the standard plugin install path. The plugin manifest is `.claude-plugin/plugin.json`; see [`getting-started.md`](getting-started.md). + +## What's new in v2.1 + +The v2.1 line ships the plugin's first set of hardened guarantees: + +- **Hard-stop gates.** Three pre-declared caps (`max_iterations`, `max_consecutive_rejects`, `max_failed_acts`) bound the loop against the three canonical death-spiral shapes (Time / Decision / Act). See [`death-spirals.md`](death-spirals.md) and [`method.md` §"Hard-stop gates"](method.md#hard-stop-gates). +- **Canonical enum lock.** The `status`, `current_phase`, action-log `status`, review `verdict`, History-row `outcome`, and decision `reversible` values are now constitution-bound; [`scripts/check-vocabulary.sh`](../scripts/check-vocabulary.sh) enforces them. +- **OpenTelemetry GenAI trace export.** `/goal:export-trace` emits OTLP-shaped JSON for ingestion into Langfuse / Datadog / Helicone / Arize / Phoenix. Machine-facing sibling of `/goal:trace`. +- **Per-goal health surface.** `goals//health.md` rolls a snapshot of counters and trend on each phase transition. +- **Session goals (cross-tool).** `/create-goal` + `/set-goal` produce session-scoped intents that keep the assistant aligned for one sitting — distinct from full Goal Loop iterations. +- **Adapter parity.** Claude Code, Codex (via `.codex/`), and Cursor (via `.cursor/rules/`) all read the same templates and the same contract; the plugin owns no runtime. +- **Worked examples for every canonical pattern.** Five `examples/` artifact sets plus one non-software example cover the canonical usage patterns from [`usage-patterns.md`](usage-patterns.md). + +## Who should adopt it + +Three personas the v2.1 line is shaped for: + +- **The solo operator who wants session-scoped guardrails.** You drive long sessions with Claude Code, Codex, or Cursor; you want the assistant to stay aligned without re-prompting every 20 minutes. Start with `/create-goal` + `/set-goal`. Cost: five minutes. +- **The team running a recurring awareness loop.** You want a daily brief, a weekly stand-up, an incident-triage runbook, or a release-readiness checklist driven with the same discipline every time. Start with `/goal:start ` then `/goal:run ` on cadence. Cost: one iteration to feel the rhythm. +- **The regulated-environment adopter.** You need a method whose audit trail reconstructs every decision (observation → orientation → decision → approval → execution → verification) and whose constitution your compliance reviewer can cite. Read [`constitution-v1-criteria.md`](constitution-v1-criteria.md) for the v1.0 graduation story; the spine (Articles I–X) is already stable enough to pilot against. + +## How to try it in 60 seconds + +``` +/goal:demo +``` + +That command scaffolds `goals/hello-loop/`, signs the goal gate against a canonical seed (no questions asked), runs one full Observe → Orient → Decide → Act → Review iteration, prints the closing summary, and stops. You will see one goal contract, one observation set, one orientation, one decision set, one action log, one review, and one closing `## History` row. The method's shape is visible from this single artifact tree. + +## Migration story for Specorator users + +Nothing breaks. Specorator's spec-driven lifecycle, its 11 stages, its `specs//` artifact tree, and its quality framework are unchanged by this release. The plugin sits alongside under `goals//` and `plugin-v2/`; the two workflows do not share state and do not compete for slugs (see [`specorator-interop.md`](specorator-interop.md) for the coexistence rules). You can adopt the plugin feature-by-feature, goal-by-goal, or not at all — your existing Specorator work stays valid either way. + +## Where to file feedback / bugs + +[https://github.com/Luis85/agentic-workflow/issues](https://github.com/Luis85/agentic-workflow/issues) — use the `plugin-v2` label so the maintainer can route it. Adoption tracking is voluntary and lives in [`adoption-tracking.md`](adoption-tracking.md). + +## What's next + +The v2.2 roadmap is shaped around three goals: + +- **Constitution v1.0 graduation.** Hit the three criteria in [`constitution-v1-criteria.md`](constitution-v1-criteria.md) — two release cycles without an Article I–III amendment, five adopters with one completed goal closure each, all five canonical patterns shipped (one already done in v2.1). +- **`/goal:diff` and the forensic surface.** A read-only diff between two iterations' artifacts (orientation, decisions, reviews), and a forensic mode for after-action analysis. +- **More pattern examples.** Non-software patterns (research, regulatory monitoring, content production) get worked artifact sets to match the software-centric ones. + +See [`improvement-strategy.md`](improvement-strategy.md) for the longer roadmap and the open EP-1 … EP-11 extension points. diff --git a/plugin-v2/docs/anti-patterns.md b/plugin-v2/docs/anti-patterns.md new file mode 100644 index 000000000..33262cd03 --- /dev/null +++ b/plugin-v2/docs/anti-patterns.md @@ -0,0 +1,129 @@ +--- +title: Goal Loop — Anti-patterns catalogue +folder: plugin-v2/docs +description: Patterns the plugin maintainer has seen go wrong, what causes them, and how the plugin's contract resists them. Distilled from review feedback during plugin-v2 development. +entry_point: false +--- + +# Goal Loop — Anti-patterns catalogue + +> Companion to [`improvement-strategy.md`](improvement-strategy.md) (the strategic *don't go theres*) and [`maintenance.md`](maintenance.md) (the defensive contract). This file is the **tactical** catalogue — concrete patterns that already drifted at least once during plugin-v2 development, the file or check that resists each one, and the grep query that catches a regression. Read it before adding a new agent, skill, command, template, or doc. Read it again before reviewing one. + +Things in this catalogue **look right**. They read fluently. They pass a casual review. They cause drift over a release cycle because each one feels like a small, locally reasonable choice that quietly undermines a contract elsewhere. The pattern is always the same: the local edit makes the local thing easier; the system-wide cost is invisible until two or three of these have accumulated and the schema, the vocabulary, or the gate model has decayed. The fix is never "be more careful". The fix is a check, a contract, or a convention that flags the regression at the next commit. + +Each entry below names a real drift caught during plugin-v2 development, names the file or check that exists to resist it, and gives a grep query a maintainer or reviewer can run to spot a regression. Where possible the citation is to a script under [`../scripts/`](../scripts/) so the resistance is machine-checkable; where the resistance is convention-only, the convention's home doc is cited. + +## Catalogue + +### 1. Enum drift on closure outcome + +- **Where it shows up.** Skill prose under `skills/review-loop/`, agent prose under `agents/loop-reviewer.md`, the History row in `goal-state.md` template, decider-side comments invented by an author who half-remembered the schema. +- **Why it's wrong.** The canonical enums are *two distinct rosters*: the goal `status` enum is `draft | active | paused | blocked | done | cancelled`; the History-row `outcome` enum at loop closure is `continue | close-met | close-abandon | amend`. Inventing a third roster like `outcome: done | skipped | failed` produces artifacts that cannot be read by `loop-reviewer`, `trace-loop`, or any downstream Dataview query, and contradicts every other artifact in the same goal folder. +- **What we did about it.** Locked the vocabulary in [`method.md` §"Naming reference"](method.md#naming-reference-locked-vocabulary). Pinned the ownership of `status` and `outcome` in the schema contract at [`skills/_shared/goal-state.md`](../skills/_shared/goal-state.md). Added a forbidden-token sweep in [`scripts/check-vocabulary.sh`](../scripts/check-vocabulary.sh) covering `outcome: done`, `outcome: failed`, `outcome: skipped`. +- **How to spot regression.** Run `bash scripts/check-vocabulary.sh` from `plugin-v2/`. Or grep `grep -rn "outcome:" agents/ skills/ templates/ examples/` and confirm every match is one of the four canonical closure values or free text for in-iteration phase transitions. + +### 2. Ghost frontmatter fields + +- **Where it shows up.** Skill procedures and agent procedures that claim to read or write a frontmatter field that never appears in the schema — `pending_actions`, `act_approval`, `closed_at` on a `goal-state.md` (legal on `lessons.md`, illegal here), `current_phase: goal` (the canonical pre-iteration value is `scope`, not `goal`). +- **Why it's wrong.** Ghost fields propagate by copy-paste. One skill claims to write `pending_actions`; another skill claims to read it; the `goal-orchestrator` never produces it, so every downstream consumer is reading nothing. Worse: the prose looks coherent, so reviewers don't catch it. +- **What we did about it.** The ownership matrix at [`skills/_shared/goal-state.md` §"Ownership matrix"](../skills/_shared/goal-state.md) is the authoritative roster — anything not in the matrix does not exist. The forbidden-token sweep in [`scripts/check-vocabulary.sh`](../scripts/check-vocabulary.sh) names each ghost field explicitly. `lessons-template.md` is excepted for `closed_at:` because its closure timestamp is owned by the lessons artifact. +- **How to spot regression.** `grep -rn "pending_actions\|act_approval\|current_phase: goal" agents/ skills/ commands/ templates/`. Also run the vocabulary check; it flags these by name. + +### 3. Phase-isolation leaks + +- **Where it shows up.** A phase agent's procedure claims to write into another phase's artifact. Common temptations: the `decider` "appending a note to `orientation.md`", the `actor` "fixing the latest decision row", a skill "patching the History row mid-iteration". +- **Why it's wrong.** [Constitution Article II](../memory/constitution.md) is the spine of the method — one phase, one writer. Cross-writes break `trace-loop`'s reconstruction, break adopter audit assumptions, and break the agent tool-list discipline that ensures phase agents only have the file-handles they need. +- **What we did about it.** The ownership matrix at [`skills/_shared/goal-state.md`](../skills/_shared/goal-state.md). The agent tool-list pin at [`scripts/check-tool-lists.sh`](../scripts/check-tool-lists.sh) so phase agents cannot be silently broadened to write outside their phase. The `goal-orchestrator` is the only writer of `goal-state.md` (its `tools:` list is `Read, Grep, Edit, Write`; everyone else has narrower writes against their own artifacts). +- **How to spot regression.** `bash scripts/check-tool-lists.sh` flags any agent whose `tools:` list drifts from the canonical roster. Manual: grep agent and skill files for the strings `orientation.md`, `decisions.md`, `goal-state.md` and confirm the only agent writing each is the one named in the ownership matrix. + +### 4. History row written by the wrong actor + +- **Where it shows up.** The `set-goal` skill being told to "append a row to `## History`" during an amend, even though `set-goal` owns body sections and the orchestrator owns `## History`. The `/goal:amend` and `/goal:start` amend paths both have to dispatch `goal-orchestrator` explicitly so the History row is written by the correct actor. +- **Why it's wrong.** `## History` is append-only by [`skills/_shared/goal-state.md` §"Ownership matrix"](../skills/_shared/goal-state.md) — owned exclusively by `goal-orchestrator`. If `set-goal` rewrites a row, auditability breaks: the same actor that mutates body sections also rewrites the change log, and the chain of custody is no longer trustworthy. +- **What we did about it.** Ownership matrix is unambiguous: `set-goal` owns body sections and creation-time frontmatter; `goal-orchestrator` owns `## History` and post-sign-off frontmatter. The amend commands (`/goal:amend`, `/goal:start `) dispatch `goal-orchestrator` to record the amend row after `set-goal` finishes editing bodies. +- **How to spot regression.** `grep -rn "History\|## History" skills/set-goal/ commands/goal/amend.md commands/goal/start.md`. The only legitimate `## History` mentions in `set-goal` should be "preserves verbatim" or equivalent read-only language. Run `bash scripts/check-tool-lists.sh` to confirm `set-goal` has not silently been granted `Write` on the History section. + +### 5. Trigger phrase collision + +- **Where it shows up.** Two skills or commands claiming the same natural-language trigger. The hardest collision so far: `"set goal"` was simultaneously a Goal Loop intake trigger (for `set-goal`, the iteration-goal skill) and a session-goal activation trigger (for `activate-goal`, exposed as `/set-goal`). +- **Why it's wrong.** Triggers are how natural-language requests reach the right conductor. Collisions produce non-deterministic dispatch: the same phrase invokes different skills in different contexts. The user cannot debug it because the trigger phrase looks fine in the SKILL.md frontmatter. +- **What we did about it.** Broad triggers were trimmed in favour of specific ones — `set-goal` (the Goal Loop skill) triggers on `"set up a goal loop"`, `"start a goal loop"`, `"/goal:start"`; `activate-goal` (the session-goal skill) triggers on `"/set-goal"`, `"activate session goal"`. The user-visible `/set-goal` slash command maps unambiguously to the session-goal skill, with the rename rationale documented in [`AGENTS.md`](../AGENTS.md) §"Slash-command roster". +- **How to spot regression.** Diff the `description:` and trigger phrases across every `SKILL.md`: `grep -rn "description:" skills/*/SKILL.md`. Any phrase that appears in two descriptions is a candidate for collision; tighten both. + +### 6. Path-rooted citations to overwritten files + +- **Where it shows up.** Skill procedures that cite `orientation.md` as a History-row artifact path, agent prose that links to `orientation.md` from review files. The trap: `orientation.md` is overwritten each iteration; the previous content is rolled to `archive/orientation-.md`. A citation that only names `orientation.md` cannot reconstruct earlier iterations. +- **Why it's wrong.** The audit trail's value is reconstructability. `trace-loop` walks History to reconstruct iteration N's reasoning. If iteration 3's History row points at `orientation.md` and the loop is now on iteration 7, the cited file is iteration 7's orientation, not iteration 3's. The trace is silently wrong. +- **What we did about it.** [`skills/orient/SKILL.md`](../skills/orient/SKILL.md) §"Update History" mandates that the History row cite **both** the current pointer (`orientation.md`) *and* the iteration-specific archive path (`archive/orientation-.md`). The archive path is what `trace-loop` resolves when reconstructing past iterations. The `orient` skill enforces the archive-before-overwrite rule. +- **How to spot regression.** `grep -rn "orientation.md" goals/*/goal-state.md` (in adopter projects, conceptually) — every History row referencing orientation should cite an archive path alongside. In plugin docs: `grep -rn "archive/orientation" skills/ docs/` should show the convention reinforced wherever orientation is discussed. + +### 7. Auto-loop in conductors + +- **Where it shows up.** The `goal-loop` conductor skill or `/goal:run` slash command being tempted to dispatch the next iteration automatically when the current iteration's review records `outcome: continue`. The pull is strong because "continue" is the *most common* outcome, and avoiding a round-trip feels like a UX improvement. +- **Why it's wrong.** Auto-loop strips the human's tempo control. The user invokes `/goal:run`; they get one iteration with one set of human gates (goal-gate already signed, act-gate per iteration). If the conductor auto-loops, the human is now committed to N iterations without re-entry. That breaks [Article III](../memory/constitution.md) (Human Gates) in spirit — the gates fire, but the user has no breath between them to abandon. +- **What we did about it.** [`commands/goal/run.md`](../commands/goal/run.md) and [`skills/goal-loop/SKILL.md`](../skills/goal-loop/SKILL.md) are explicit: one iteration per invocation. The conductor reports the review outcome and **stops**. The user re-invokes for the next iteration. Documented as the "stop and hand back" rule in the conductor skill. +- **How to spot regression.** `grep -rn "dispatch.*observe\|next iteration\|auto.*loop" skills/goal-loop/ commands/goal/run.md`. Any wording suggesting the conductor self-dispatches after a `continue` outcome is the regression. + +### 8. Boolean reversibility + +- **Where it shows up.** Decision-template fields, decider prose, risk-scout commentary. A draft slipped in `reversible: true` / `reversible: false` despite the canonical encoding being `Y|N` (per the decision-template enum). +- **Why it's wrong.** `true|false` is a YAML boolean; `Y|N` is a single-character string. Downstream readers built against `Y|N` (the decision-template, the act-gate routing, the trace) silently fail or treat `true` as a truthy string rather than the boolean the author meant. Worse: the two encodings co-exist in two artifacts in the same goal folder and no human notices until a trace pass fails. +- **What we did about it.** Decision-template enum is `Y|N`. Forbidden-token sweep in [`scripts/check-vocabulary.sh`](../scripts/check-vocabulary.sh) flags `reversible: true` and `reversible: false` across `agents/`, `skills/`, `commands/`, `templates/`, `examples/`, `memory/`. +- **How to spot regression.** Run `bash scripts/check-vocabulary.sh`. Or grep `grep -rn "reversible:" agents/ skills/ templates/ examples/`; every match should be `Y` or `N`. + +### 9. Plain-text artifact citations + +- **Where it shows up.** Orientation files citing an observation as `observations/2026-05-16T10-00-00.md` in body prose rather than `[2026-05-16T10:00:00 observation](observations/2026-05-16T10-00-00.md)`. Review files citing decisions in plain text instead of Markdown links. +- **Why it's wrong.** Obsidian's graph view depends on backlinks; backlinks depend on `[link](path)` or `[[wikilink]]` form. Plain-text mentions are invisible to the graph, breaking the per-goal sub-graph that adopters rely on for navigation. +- **What we did about it.** [`docs/obsidian-compatibility.md`](obsidian-compatibility.md) pins the link-form contract. The check `scripts/check-obsidian.sh` covers the structural rules around link form, frontmatter, and tags. Artifact templates (`orientation-template.md`, `review-template.md`, `decision-template.md`) demonstrate Markdown links in their example bodies. +- **How to spot regression.** `bash scripts/check-obsidian.sh` from `plugin-v2/`. For a manual sweep: grep `grep -rn "observations/20" templates/ examples/` and confirm every match sits inside `[...](...)` brackets. + +### 10. Pipe-in-cell tables + +- **Where it shows up.** Agent or skill prose using a table cell like `| Verdict | |` — a literal pipe inside a cell, used to express an enum. +- **Why it's wrong.** Markdown tables treat `|` as a column separator. Obsidian's Reading View (and GitHub's renderer) break the row at the unescaped pipe — the table renders with one extra column per inner pipe, mangling alignment and silently truncating the row's visible content. The author sees the source rendering fine and the reader sees a wreck. +- **What we did about it.** Convention: enum values inside table cells use either an escape (`\|`) or a definition-list pattern instead of an inline pipe. Templates that show enums avoid pipe-in-cell. The pattern is reinforced in [`docs/obsidian-compatibility.md`](obsidian-compatibility.md) §"Authoring rules". +- **How to spot regression.** `grep -rn " | " templates/ skills/ agents/ docs/` is too noisy; instead, render the doc set in Obsidian Reading View as part of the release checklist (see [`release-checklist.md` §"Compatibility"](release-checklist.md)) and visually scan for broken tables. The structural Obsidian check `scripts/check-obsidian.sh` covers some cases but not all. + +### 11. Dash-form datetimes in frontmatter + +- **Where it shows up.** Frontmatter timestamps written as `created_at: 2026-05-16T10-00-00` (dashes between time components) instead of `created_at: 2026-05-16T10:00:00` (colons). +- **Why it's wrong.** Obsidian's Date & Time property type binds to ISO-8601 datetimes with `:` separators. Dash-form values are rendered as plain text, not parsed as datetimes, so Dataview queries like `WHERE updated_at < date(today)` silently exclude them. Filenames *do* use dashes (because `:` is illegal in many file systems); the divergence between filename and frontmatter is the source of confusion. +- **What we did about it.** [`docs/obsidian-compatibility.md`](obsidian-compatibility.md) §"Property type mapping" pins the rule: filenames use dashes, frontmatter uses colons. The schema at [`skills/_shared/goal-state.md`](../skills/_shared/goal-state.md) labels every timestamp `ISO-8601 timestamp` so the contract is explicit. `scripts/check-obsidian.sh` covers the frontmatter form. +- **How to spot regression.** Run `bash scripts/check-obsidian.sh`. Manual: `grep -rEn "created_at: [0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}-" templates/ examples/` should return zero hits. + +### 12. Skill-name collisions + +- **Where it shows up.** Adding a new skill called `set-goal` when one already exists with that name. The plugin-v2 history caught this when the session-goal feature wanted a `set-goal` activation skill while the iteration-goal intake skill `set-goal` already existed. +- **Why it's wrong.** Skill folders under `skills/` are looked up by name. Two folders with the same name is a filesystem impossibility; near-collisions (one called `set-goal`, another called `setgoal`) are worse because they parse but route ambiguously. +- **What we did about it.** Renamed the session-goal skill to `activate-goal` (folder + frontmatter). The user-visible slash command stays `/set-goal`; only the backing skill folder is disambiguated. The rationale is recorded in [`AGENTS.md`](../AGENTS.md) §"Slash-command roster" and in the changelog entry that introduced the rename. +- **How to spot regression.** `ls skills/` and confirm every folder name is unique and distinct from any phase-skill name. When introducing a new skill, search `grep -rn "" skills/ commands/ agents/ docs/` for prior uses of the name. Renames are a MAJOR-bump concern (per [`maintenance.md` §"What counts as a breaking change"](maintenance.md)) — collide-then-rename is much costlier after release than before. + +### 13. Forbidden command paths + +- **Where it shows up.** Adapter docs or skill prose referencing slash commands that don't exist — `/goal:set` (correct: `/goal:start`), `/goal:show` (no such command). Sometimes copied from an earlier draft or from a sibling plugin's namespace. +- **Why it's wrong.** Users follow the doc, hit the broken command, lose trust in the doc set. Adapters (Codex, Cursor) cannot expose commands that don't exist in the source — the parity check fails silently because adapter readers cannot grep the plugin manifest from inside the adapter. +- **What we did about it.** [`scripts/check-vocabulary.sh`](../scripts/check-vocabulary.sh) flags `/goal:set` explicitly. The slash-command roster in [`AGENTS.md`](../AGENTS.md) §"Slash-command roster" is the single source of truth; adapter docs cite it rather than re-list. The plugin manifest at [`.claude-plugin/plugin.json`](../.claude-plugin/plugin.json) is the machine-readable register. +- **How to spot regression.** Run `bash scripts/check-vocabulary.sh`. Manual: `grep -rn "/goal:" docs/ .codex/ .cursor/` and reconcile every match against the manifest's `commands` list. + +### 14. Constitutional restatement in prose + +- **Where it shows up.** A new skill or agent that re-states an Article ("the act gate is non-negotiable; the human must approve every irreversible action; …") in its own words rather than citing the article by reference. +- **Why it's wrong.** Restatement drifts. Six months later, the constitution is amended; the restatement is not. Adopters reading the agent file see the stale paraphrase and follow it instead of the amended source. By [`maintenance.md` §"What counts as a breaking change"](maintenance.md), wording changes inside Articles I–III, VIII, and X are MAJOR-bumping precisely because adopters audit their fork against the constitution — but only the constitution; nobody audits paraphrases. +- **What we did about it.** Convention: skill and agent files **cite** the constitution by article number and link to [`memory/constitution.md`](../memory/constitution.md). They do not re-state. The improvement-strategy doc reinforces this in [`improvement-strategy.md` §"Accepting a new skill"](improvement-strategy.md#accepting-a-new-skill) — "Does the skill avoid re-implementing the constitution or the method in prose? (Reference, don't restate.)" +- **How to spot regression.** `grep -rn "non-negotiable\|Article" agents/ skills/` — every match should be a citation to the constitution, not a fresh paraphrase. If a paraphrase is necessary for context, the citation must be in the same paragraph. + +--- + +## How this catalogue is maintained + +Add a new entry every time a review catches drift that wasn't covered above. The entry must name: the file or surface where it showed up, the contract or check that resists it, and the grep query or script that catches a regression. Entries are append-only — never delete or renumber. A retired anti-pattern (one whose resistance is now structural enough that regression is impossible) gets a `> **Retired in v...**` note at the top of its entry; the entry stays for adopters on older versions who still see the failure mode. + +## See also + +- [`improvement-strategy.md`](improvement-strategy.md) — the strategic anti-patterns (auto-merge, scheduler daemon, SaaS, etc.). This file covers the tactical ones. +- [`maintenance.md`](maintenance.md) — the defensive contract that some of these checks gate. +- [`skills/_shared/goal-state.md`](../skills/_shared/goal-state.md) — the schema and ownership matrix many entries cite. +- [`method.md`](method.md) §"Naming reference" — the locked vocabulary. +- [`memory/constitution.md`](../memory/constitution.md) — the articles every regression eventually traces back to. +- [`scripts/check-vocabulary.sh`](../scripts/check-vocabulary.sh), [`scripts/check-tool-lists.sh`](../scripts/check-tool-lists.sh), [`scripts/check-obsidian.sh`](../scripts/check-obsidian.sh), [`scripts/check-frontmatter.sh`](../scripts/check-frontmatter.sh) — the machine-checkable resistance layer. diff --git a/plugin-v2/docs/automation-spec.md b/plugin-v2/docs/automation-spec.md new file mode 100644 index 000000000..20fe37b6b --- /dev/null +++ b/plugin-v2/docs/automation-spec.md @@ -0,0 +1,510 @@ +--- +title: Goal Loop — Automation Pipeline Spec +folder: plugin-v2/docs +description: Specification for the quality / lint / verification / validation / formatting / spell-check / security scripts that gate every PR touching the plugin. Implementation deferred to a follow-up PR. +entry_point: false +--- + +# Goal Loop — Automation Pipeline Spec + +> This is a **specification**. Implementation is deferred to a follow-up PR. When that PR lands, this document is the acceptance contract — every check below MUST exist and behave as described. + +## Scope and goals + +This spec defines the automated quality pipeline that gates every PR touching `plugin-v2/**`. Eight check categories — lint (A), verification (B), validation (C), formatting (D), spell-check (E), security (F), self-application (G), Obsidian compliance (H) — run as thin scripts under `plugin-v2/scripts/`. Checks emit JSON findings on stdout and exit non-zero on `error`-severity findings. Contracts the checks enforce live in [`method.md`](method.md), [`maintenance.md`](maintenance.md), [`improvement-strategy.md`](improvement-strategy.md), [`skills/_shared/goal-state.md`](../skills/_shared/goal-state.md), [`obsidian-enforcement.md`](obsidian-enforcement.md), and [`.claude-plugin/plugin.json`](../.claude-plugin/plugin.json). + +Out of scope: + +- Runtime guards on live loops (e.g., asserting `actor` honours the act gate at runtime). +- Adopter-owned `goals//` trees — the pipeline scans only `plugin-v2/**`. +- The implementation itself — scripts, manifests, CI YAML, and hooks land in a follow-up PR whose acceptance is this document. + +## Check categories + +Every check declares a stable id (`.`), a severity (`error` / `warning` / `info`), and a false-positive policy. JSON shape on stdout: + +```json +{ "check": "lint.frontmatter-shape", "severity": "error", "file": "plugin-v2/agents/observer.md", "line": 1, "message": "missing required field: color", "fix_hint": "add `color: cyan` to frontmatter" } +``` + +### A. Lint + +Style, structure, presence. Cheap; runs first. + +#### A1 — `lint.frontmatter-shape` (severity: error, blocking) + +Verify YAML frontmatter is present and matches the required field set for each file category: + +| Category | Required | Optional | +|---|---|---| +| Agent (`agents/*.md`) | `name`, `description`, `tools` (list), `color` | — | +| Skill (`skills//SKILL.md`) | `name`, `description`, `argument-hint` | — | +| Command (`commands/goal/*.md`) | `description`, `argument-hint`, `allowed-tools` (list) | `model` (enum `haiku` \| `sonnet` \| `opus`) | +| Template (`templates/*-template.md`) | per-template — see C3 | — | +| Folder README | `title`, `folder`, `description`, `entry_point: true` | — | +| Doc (`docs/*.md`) | `title`, `description` | `folder`, `entry_point` | + +Tool: Node script using [`gray-matter@4.x`](https://github.com/jonschlinkert/gray-matter); or `yamllint@1.35.x` for the YAML alone. **No false-positive policy** — frontmatter is the contract. + +#### A2 — `lint.folder-path` (error) + +Every folder README's `folder:` MUST match its path from the repo root (`plugin-v2/agents`, `plugin-v2/skills`, `plugin-v2/commands/goal`, `plugin-v2/docs`, `plugin-v2/templates`, `plugin-v2/examples`). Same Node script as A1. + +#### A3 — `lint.entry-point` (error) + +Every folder README MUST declare `entry_point: true`. Other docs MAY declare `entry_point: false`. + +#### A4 — `lint.skill-trigger-phrases` (error / warning) + +Each skill's `description` MUST contain at least one quoted trigger phrase (substring inside `"..."`). Conductor and per-phase skills MUST have at least two distinct phrases. Tool: regex `/"([^"]+)"/g`. No false-positive policy — triggers are the natural-language surface. + +#### A5 — `lint.heading-order` (error; info on extras) + +Body section order MUST match the contract per category: + +- **Agent:** `## Scope` → `## Read first` → `## Procedure` → `## Boundaries` → `## Outputs`. +- **Skill:** `## Read first` → `## What you do, step by step` → `## Outputs` → `## Boundaries` → `## References`. +- **Command:** `## Inputs` → `## Procedure` → `## Don't`. + +Extra `## …` sections allowed after the required ones; flagged `info` so drift surfaces. Tool: Markdown AST walker via [`remark-parse@11.x`](https://github.com/remarkjs/remark) or `markdown-it@14.x`. Silence extras by listing in `plugin-v2/scripts/.lint-heading-extras.json`. + +#### A6 — `lint.relative-link-convention` (error / warning) + +Flag absolute paths (`](/…)`) as `error`; flag relative paths escaping more than two parents (`](../../../…)`) as `warning`. External `http(s)://` exempt. Silence via `plugin-v2/scripts/.lint-link-exceptions.json` (with justification field). + +#### A7 — `lint.no-emoji` (info, advisory) + +Flag emoji introduced in any file that did not previously contain one (baseline computed against PR merge base). Tool: [`emoji-regex@10.x`](https://github.com/mathiasbynens/emoji-regex). Silence via `plugin-v2/scripts/.lint-emoji-allow.json`. + +#### A8 — `lint.line-length` (info, advisory) + +Flag lines > 200 chars in Markdown. Tool: `markdownlint-cli2@0.13.x` rule `MD013` with `line_length: 200, code_blocks: false, tables: false`. Silence inline with ``. + +#### A9 — `lint.indent-discipline` (warning) + +Markdown nested lists: 2-space indent (no tabs, no four-space). YAML frontmatter: 2-space indent. Tools: `markdownlint-cli2` (`MD007`) and `yamllint@1.35.x`. + +### B. Verification + +Semantic, cross-file. Runs second. + +#### B1 — `verify.manifest-roster` (error) + +For [`.claude-plugin/plugin.json`](../.claude-plugin/plugin.json): + +1. Every path under `capabilities.agents`, `capabilities.skills`, `capabilities.commands` exists. +2. Every `agents/*.md` (excluding `README.md`) is listed in `capabilities.agents`. +3. Every `skills//` folder (excluding `_shared/`) is listed in `capabilities.skills`. +4. Every command folder referenced from `capabilities.commands` contains the expected `*.md` files. +5. `entrypoints.method_doc` and `entrypoints.readme` resolve. + +Tool: Node script using `fast-glob@3.x`. No false-positive policy. + +#### B2 — `verify.roster-index-consistency` (error) + +> **Status:** implemented — all surfaces covered. See [`../scripts/check-roster.sh`](../scripts/check-roster.sh). The script cross-checks eight surfaces: `.claude-plugin/plugin.json` (manifest agents and skills, each direction), `agents/README.md`, `skills/README.md`, `commands/goal/README.md` (goal commands + cross-tool See-also entries), `AGENTS.md` (`## Subagent roster` + `## Skill roster` blocks vs. disk), `README.md`'s `## Status` inventory counts (subagents / skills / slash-commands / templates) vs. disk reality, and per-command frontmatter consistency between each `commands/goal/*.md` file's own `description:` field and the matching "One-liner" cell in `commands/goal/README.md`'s `## Commands` table (substantive-keyword overlap, stop-word filtered). + +The agent / skill / command rosters in five surfaces MUST be set-equal: + +- [`AGENTS.md`](../AGENTS.md) — Subagent / Skill / Slash-command roster tables. +- [`README.md`](../README.md) — "What you get" table. +- [`agents/README.md`](../agents/README.md) — Agent index. +- [`skills/README.md`](../skills/README.md) — Skill tables. +- [`commands/goal/README.md`](../commands/goal/README.md) — Commands table. + +Tool: custom — parse each table by header signature, normalise paths, compare sets. + +#### B3 — `verify.cross-references` (error file / warning anchor) + +Every relative Markdown link inside `plugin-v2/**` MUST resolve to an existing file. Anchor fragments validated against the target's heading set. Tool: [`lychee@0.15.x`](https://github.com/lycheeverse/lychee) with `--offline --base plugin-v2`. External URLs handled by an opt-in nightly run, not this gate. Silence via `plugin-v2/.lycheeignore`. + +#### B4 — `verify.locked-vocabulary` (error) + +Flag any occurrence of these deprecated / never-introduced tokens anywhere under `plugin-v2/**`: + +- `/goal:set` — never existed; the slash command is `/goal:start`. +- `pending_actions` — not a `goal-state.md` field. +- `act_approval` — not a field; canonical approval lives in `decisions.md` `## Human Approval`. +- `act_gate_policy` — frontmatter key is `act_gate`, body section is `## Act Gate Policy`. +- `closed_at` — not a field; closure is recorded in `## History`. +- `current_phase: goal` — invalid; pre-iteration phase is `scope`. +- `goal_orchestrator` with underscore where `goal-orchestrator` (kebab) is expected — `warning`. + +The list above is the single source of truth and MUST be re-read whenever [`method.md`](method.md) §"Naming reference" changes. Tool: `ripgrep@14.x` against `plugin-v2/scripts/.verify-locked-vocab.txt`. Inline escape: `` on the preceding line. + +#### B5 — `verify.phase-isolation` (error) + +Each agent's `## Procedure` and `## Outputs` MUST only reference write paths the ownership matrix in [`skills/_shared/goal-state.md`](../skills/_shared/goal-state.md) permits: + +| Agent | Allowed write paths | +|---|---| +| `goal-orchestrator` | `goals//goal-state.md` only | +| `observer` | `goals//observations/*.md` | +| `orienter` | `goals//orientation.md` (+ archive of prior) | +| `decider` | `goals//decisions.md` | +| `actor` | `goals//actions/iter-/.md` | +| `loop-reviewer` | `goals//reviews/*.md` | +| `goal-critic`, `signal-deduper`, `risk-scout` | — (consult-only) | + +Pseudo-code: parse `## Outputs` + `## Procedure`, collect `goals//…` path strings, fail any not in the agent's allowed set. Inline escape: ``. (See Open Q 3 — a `writes:` frontmatter list would make this trivial.) + +#### B6 — `verify.canonical-enums` (error) + +These enums MUST appear consistently and exclusively wherever they are mentioned in `plugin-v2/**`: + +| Enum | Allowed values | Source of truth | +|---|---|---| +| `status` (goal) | `draft` \| `active` \| `paused` \| `blocked` \| `done` \| `cancelled` | [`_shared/goal-state.md`](../skills/_shared/goal-state.md) | +| `current_phase` | `scope` \| `observe` \| `orient` \| `decide` \| `act` \| `review` \| `closed` | [`_shared/goal-state.md`](../skills/_shared/goal-state.md) | +| `mode` | `one-shot` \| `recurring` | [`_shared/goal-state.md`](../skills/_shared/goal-state.md) | +| `act_gate` | `always` \| `low-risk-auto` \| `never` | [`_shared/goal-state.md`](../skills/_shared/goal-state.md) | +| Action-outcome `status:` | `done` \| `partial` \| `stopped` \| `blocked` \| `failed` | [`actor.md`](../agents/actor.md) + [`templates/action-log-template.md`](../templates/action-log-template.md) | +| Per-criterion verdict | `met` \| `partial` \| `unmet` \| `blocked` | [`method.md`](method.md) + [`templates/review-template.md`](../templates/review-template.md) | +| Loop-closure `outcome` | `continue` \| `close-met` \| `close-abandon` \| `amend` | [`method.md`](method.md) + [`templates/review-template.md`](../templates/review-template.md) | + +Tool: `ripgrep@14.x` with a pattern bundle per enum. Values inside the source-of-truth file's own enum-documentation row are exempt. + +#### B7 — `verify.tool-list-discipline` (error / warning) + +Each agent's `tools:` frontmatter MUST be consistent with the verbs in its `## Procedure`. Verb→tool dictionary at `plugin-v2/scripts/.verify-tool-verbs.json`: + +| Verb | Required tool | +|---|---| +| "write a file", "writes …" | `Write` | +| "edit", "update inline" | `Edit` | +| "read", "scan signals" | `Read` | +| "search", "grep" | `Grep` | +| "fetch URL" | `WebFetch` | +| "run search query" | `WebSearch` | +| "run command", "execute bash" | `Bash` | + +Procedure verb without backing tool → `error`. Declared but unused → `warning`. Inline escape: ``. + +#### B8 — `verify.slash-command-coverage` (error) + +Each `commands/goal/*.md` MUST be referenced from: + +1. The commands table in [`commands/goal/README.md`](../commands/goal/README.md). +2. The Slash-command roster in [`AGENTS.md`](../AGENTS.md). +3. The skill it wraps (when one exists) — the skill's body MUST cite the matching `/goal:*` invocation. + +### C. Validation + +Schema enforcement. Runs third. + +#### C1 — `validate.plugin-json` (error) + +Validate `.claude-plugin/plugin.json` against `plugin-v2/scripts/schemas/plugin.schema.json`. Required: `name` (string), `version` (semver), `description` (string), `author.name` (string), `license` (string), `homepage` (URL), `keywords` (array), `capabilities.{agents,skills,commands}` (arrays of relative paths), `entrypoints.{primary_skill,primary_command,method_doc,readme}`, `compatibility.claude_code` (semver range), `compatibility.adapters` (array, subset of `codex` / `cursor`). Tool: [`ajv@8.x`](https://ajv.js.org). + +#### C2 — `validate.goal-state-examples` (error) + +Validate every `examples//goal-state.md` against [`skills/_shared/goal-state.md`](../skills/_shared/goal-state.md): + +1. All required frontmatter fields present with correct types. +2. Frontmatter `constraints` ↔ body `## Constraints` bullets (set-equal, whitespace-normalised). +3. Frontmatter `acceptance_criteria` ↔ body `## Acceptance Criteria` numbered list. +4. Frontmatter `observe_sources` ↔ body `## Observe Sources` table on `id`, `type`, `target`. +5. Body section order per `_shared/goal-state.md` §"Body sections". +6. Enum values fall in allowed sets (B6). + +Tool: Node script with `gray-matter@4.x` + `ajv@8.x`; body parsing via `remark-parse@11.x`. + +#### C3 — `validate.template-frontmatter` (error) + +Each template under `templates/*-template.md` MUST declare its consumers' expected fields. Minimum required keys (hard-coded in `plugin-v2/scripts/schemas/templates.schema.json`): + +| Template | Required keys | +|---|---| +| `goal-state-template.md` | full `_shared/goal-state.md` schema | +| `observation-template.md` | `goal_slug`, `iteration`, `source_id`, `captured_at` | +| `orientation-template.md` | `goal_slug`, `iteration`, `refreshed_at` | +| `decision-template.md` | `goal_slug`, `iteration`, `proposed_at` | +| `action-spec-template.md` | `goal_slug`, `iteration`, `action_id`, `reversible` | +| `action-log-template.md` | `goal_slug`, `iteration`, `action_id`, `started_at`, `ended_at`, `status` | +| `review-template.md` | `goal_slug`, `iteration`, `reviewed_at`, `outcome` | +| `brief-template.md` | `goal_slug`, `rendered_at`, `cadence` | +| `goal-archive-template.md` | `goal_slug`, `archived_at`, `final_status` | +| `lessons-template.md` | `goal_slug`, `captured_at` | +| `constitution-amendment-template.md` | `article`, `version_before`, `version_after`, `proposed_at` | + +#### C4 — `validate.enum-values-in-frontmatter` (error) + +Scan every YAML frontmatter under `plugin-v2/**/*.md` for `status`, `current_phase`, `mode`, `act_gate`, `outcome`; values MUST fall in B6's sets. Template placeholders matching `` are exempt (detected by leading `<`). + +#### C5 — `validate.iso-8601-timestamps` (error) + +> **Status:** implemented — see [`../scripts/check-iso8601.sh`](../scripts/check-iso8601.sh). Widens the timestamp-shape rule already partially covered by `check-obsidian.sh` (O2) to every artifact frontmatter under `agents/`, `skills/`, `commands/`, `templates/`, `examples/`, and `docs/`. + +Every timestamp value in frontmatter (`created_at`, `updated_at`, `captured_at`, `started_at`, `ended_at`, `refreshed_at`, `proposed_at`, `reviewed_at`, `rendered_at`, `archived_at`) MUST match `^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$` (colon-bearing form) or be a template placeholder (``). Filename timestamps use the colon-free form (`2026-05-16T10-00-00`) — covered by C2 path patterns. + +### D. Formatting + +Deterministic rewriters. Two modes: `check` (CI, fails on diff) and `fix` (local, applies). Picked at implementation; the spec accepts either tool per row. + +| Check | Scope | Tools (pick one) | Severity | Auto-fix in `fix.sh` | +|---|---|---|---|---| +| **D1** `format.markdown` | `**/*.md` | `markdownlint-cli2@0.13.x` (config at `plugin-v2/scripts/.markdownlint-cli2.jsonc`) **or** `prettier@3.x --parser markdown` | error (blocking rules) / info (`MD013`) | yes (subset) | +| **D2** `format.yaml` | YAML frontmatter blocks | `prettier@3.x --parser yaml` **or** `yamllint@1.35.x` (`plugin-v2/scripts/.yamllint`) | error (parse) / warning (style) | yes | +| **D3** `format.json` | `.claude-plugin/plugin.json`, `plugin-v2/scripts/schemas/*.json` | `prettier@3.x --parser json` **or** `jq --indent 2` | error | yes | +| **D4** `format.trailing-whitespace` | all text files | line scan | error | yes | +| **D5** `format.final-newline` | all text files | byte check | error | yes | + +D1 blocking rules (when `markdownlint-cli2` is chosen): `MD001` (heading levels), `MD003` (ATX), `MD004` (list dash), `MD009` (no trailing spaces), `MD010` (no hard tabs), `MD012` (no multiple blanks), `MD022` (heading blank lines), `MD025` (single H1), `MD040` (fenced code language). `MD013` runs at `info` (covered by A8). + +### E. Spell-check + +#### E1 — `spell.typos` (error) + +Run [`crate-ci/typos@v1.46.0`](https://github.com/crate-ci/typos) with a plugin-local config at `plugin-v2/_typos.toml`. Intentionally separate from the repo-root [`_typos.toml`](../../_typos.toml) so adopters who copy `plugin-v2/` get a self-contained allow-list. + +Minimum allow-list (under `[default.extend-words]` unless noted): + +- **Method / framework names:** `OODA`, `Boyd`, `Goldratt`, `Goldratt's`, `Schön`, `Schon`, `Cynefin`, `MAPE-K`, `PDCA`, `Specorator`, `goal-loop`. +- **Trigger-phrase vocabulary (deliberately unusual):** `falsifiable`, `falsifiability`, `orienter`. +- **Under `[default]`:** `extend-ignore-re = ["[A-Z]+(-[A-Z]+)+(-\\d+)?"]` to skip trace-style IDs. +- **Under `[files]`:** `extend-exclude = ["examples/**"]` so adopter-shaped examples may drift. + +Auto-fix: `typos --write-changes` in `fix.sh` for safe single-suggestion typos only. False-positive policy: extend the word list in the same PR that introduces the term, with a comment citing where it's used. + +### F. Security / safety + +#### F1 — `security.no-secrets` (error) + +Run [`gitleaks@8.18.x`](https://github.com/gitleaks/gitleaks) with config at `plugin-v2/scripts/.gitleaks.toml`. Allow-listed false positives: ``, ``, `` placeholders in templates; `Bearer ` example strings; `ghp_xxx` examples in [`docs/cadence-recipes.md`](cadence-recipes.md). New allow-list entries go in `.gitleaks.toml` `allowlist.regexes` with a justification comment. + +#### F2 — `security.no-urls-in-agent-procedures` (error) + +Flag any `http(s)://` URL embedded in an agent file's `## Procedure` section. Agents MAY receive URLs as runtime inputs; agents MUST NOT hard-code live URLs. Templates, docs, and skills are exempt. Tool: section-bounded scan on `agents/*.md` only. + +#### F3 — `security.no-destructive-bash` (error) + +Flag any of these patterns in any agent's `## Procedure`: + +- `rm -rf` +- `git push --force` / `git push -f` +- `git reset --hard` +- `git clean -fd` +- `> /dev/sd[a-z]` and similar disk-write sinks +- `curl … | sh` / `wget … | sh` +- `chmod -R 777` +- `kill -9 1` + +Tool: `ripgrep@14.x` against `plugin-v2/scripts/.security-destructive-bash.txt`. Inline escape: ``; every exception surfaces in the PR description. + +### G. Self-application meta-check + +#### G2 — `self.goal-length-cap` (error) + +> **Status:** implemented — see [`../scripts/check-goal-length.sh`](../scripts/check-goal-length.sh). + +The body of every goal artifact (everything after the closing `---` of the frontmatter) MUST be ≤ 3500 characters. The cap applies equally to: + +- `templates/goal-state-template.md`, `templates/session-goal-template.md` +- `examples/**/goal-state.md`, `examples/session-goal-example.md` +- adopter-side `goals//goal-state.md` and `session-goals/.md` + +`set-goal` and `create-goal` surface the count to the user at write time. The check runs in `check-all.sh` and on PRs touching `plugin-v2/**`. A goal whose body needs more than 3500 characters is usually doing too much — split it. + +#### G1 — `self.release-loop` (error, release-blocking) + +> **Status:** implemented (static subset) — see [`../scripts/check-self-application.sh`](../scripts/check-self-application.sh). The script enforces the static preconditions the live `/goal:run` would assume: a clean `goals/` shape, template→example coverage, locked-vocabulary references, constitution-article coverage in `non-negotiable-guarantees.md`, and a semver `plugin.json` `version`. The dynamic loop run itself stays `[spec]` — it requires a Claude Code runtime and lands when the maintainer cuts the release. + +The plugin MUST be able to run a Goal Loop on its own release. Per [`maintenance.md`](maintenance.md) §Versioning, the maintainer runs `/goal:run plugin-v2-release-` against a goal whose acceptance criteria are this spec. The goal's `goal-state.md` MUST include: + +```yaml +acceptance_criteria: + - "All eight check categories (A–H) defined in docs/automation-spec.md are implemented as scripts under plugin-v2/scripts/, callable individually, and exit non-zero on error-severity findings." + - "plugin-v2/scripts/check-all.sh returns 0 against the current tip of the release branch." + - "plugin-v2/scripts/fix.sh applies the deterministic formatters (D1–D5, E1) and leaves a clean tree on a second run." + - ".github/workflows/plugin-v2-quality.yml runs check-all.sh on a PR touching plugin-v2/** and surfaces findings as PR annotations." + - "Every check emits JSON findings on stdout matching the shape in docs/automation-spec.md §Check categories." + - "Version bump in .claude-plugin/plugin.json matches the release tag (see docs/maintenance.md §Versioning)." +``` + +If the loop will not close `close-met`, the release is not ready. + +### H. Obsidian compliance + +Vault-shape checks on plugin-emitted artifacts. Full treatment in [`obsidian-enforcement.md`](obsidian-enforcement.md). The category-H subset below is the PR-blocking floor for `plugin-v2/examples/**` and `plugin-v2/templates/**`; the full O1–O12 set runs at adopter-side L2 / L3 layers per `obsidian-enforcement.md` §"Enforcement layers". + +#### H1 — `obsidian.frontmatter-types` (error) + +Every YAML key in every plugin-emitted artifact maps to one of Obsidian's seven property types (`text`, `list`, `number`, `checkbox`, `date`, `datetime`, `tags`). Type per key is fixed by [`skills/_shared/goal-state.md`](../skills/_shared/goal-state.md) and the per-template tables in C3. Tool: Node script using `gray-matter@4.x` + hand-written classifier. False-positive policy: template placeholders matching `^<[^>]+>$` are exempt; overrides at `plugin-v2/scripts/obsidian/.o1-type-overrides.json`. See `obsidian-enforcement.md` §O1. + +#### H2 — `obsidian.date-literal-form` (error) + +`date` properties match `^\d{4}-\d{2}-\d{2}$`; `datetime` properties match `^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$`. Quoted strings fail — Obsidian renders them as `text`, surfacing the "type mismatch, expected date" defect. No false-positive policy. See `obsidian-enforcement.md` §O2. + +#### H3 — `obsidian.forbidden-filename-chars` (error) + +No file under `plugin-v2/examples/**` or `plugin-v2/templates/**` uses characters Obsidian forbids on **any** platform — superset across desktop, iOS, iPadOS, Android, Windows. Forbidden: `[ ] # ^ | \ : * " < > ?` plus filenames beginning with `.`. Tool: shell scan plus Node helper for JSON-finding emission. No false-positive policy on user-visible files; internal tool config is scope-excluded by glob. See `obsidian-enforcement.md` §O3. + +#### H4 — `obsidian.internal-link-resolution` (error / warning) + +Every Markdown link `[text](path)` with a relative target resolves to an existing file; every wikilink `[[Note]]` likewise resolves under the vault root. Tool: [`lychee@0.24.x`](https://github.com/lycheeverse/lychee) with `--offline --include-wikilinks --base plugin-v2`, plus [`markdownlint-obsidian-cli@1.1.x`](https://github.com/alisonaquinas/markdownlint-obsidian) (OFM00x rule family) for the Obsidian-aware wikilink resolver. `error` on broken targets; `warning` on ambiguous wikilinks. False-positive allow-list at `plugin-v2/scripts/obsidian/.o5-allow.toml`. Coexists with B3 (B3 covers `plugin-v2/**` arbitrary cross-references; H4 covers vault-rooted resolution). See `obsidian-enforcement.md` §O5. + +#### H5 — `obsidian.heading-and-block-refs` (error / warning) + +Every `[[Note#Heading]]` reference points to a heading that exists in the target file (case-insensitive, whitespace-shrunk per Obsidian's anchor rule). Every `[[Note^block-id]]` reference points to a `^block-id` declared in the target with the canonical syntax (Latin letters, numbers, dashes). Tool: custom AST walker on `remark-parse@11.x` + `@portaljs/remark-wiki-link@1.x`; `markdownlint-obsidian-cli@1.1.x` block-references rule family for the standard cases. `error` on missing targets; `warning` on duplicate `^id` declarations within one file. False-positive policy: code-block contents are stripped before resolution. See `obsidian-enforcement.md` §O6, §O7. + +#### H6 — `obsidian.callout-syntax` (error / warning) + +Every callout (`> [!type]`) declares a `type` from Obsidian's twelve-default set or documented aliases (`note` / `abstract` / `summary` / `tldr`, `info` / `todo`, `tip` / `hint` / `important`, `success` / `check` / `done`, `question` / `help` / `faq`, `warning` / `caution` / `attention`, `failure` / `fail` / `missing`, `danger` / `error`, `bug`, `example`, `quote` / `cite`). Folding modifiers `+` / `-` allowed. Tool: `markdownlint-obsidian-cli@1.1.x` callout rule family; regex fallback for `--quick`. `error` on unknown type; `warning` on case-variant style drift. Adopter custom-callout escape at `plugin-v2/scripts/obsidian/.o9-extra-types.json`. See `obsidian-enforcement.md` §O9. + +#### H7 — `obsidian.tag-namespace` (error / warning / info) + +Plugin-emitted artifacts carry the canonical tag namespace where required: `goal-loop/goal/`, `goal-loop/phase/`, `goal-loop/iteration/`. Tag characters: letters, numbers, underscores, hyphens, forward slashes — no emoji or spaces. Tool: Node script reading frontmatter `tags:` + scanning body for `/(?:^|\s)#([\w/-]+)/g`. Required-tag matrix at `plugin-v2/scripts/obsidian/.o8-required-tags.json`. `error` on missing required tag; `warning` on malformed character; `info` on inline+frontmatter duplication. See `obsidian-enforcement.md` §O8. + +#### H8 — `obsidian.folder-shape` (error / warning) + +For every `goals//` (within `plugin-v2/examples/**`), the file inventory matches [`method.md`](method.md) §"State model": `goal-state.md` (exactly one), optional `orientation.md`, `decisions.md`, `brief.md`, plus `observations/`, `actions/`, `reviews/`, `archive/` subfolders. Stray top-level files are flagged. Tool: Node script using `fast-glob@3.x`. `error` on unknown top-level file or missing `goal-state.md`; `warning` on per-phase count anomalies. Adopter escape: files prefixed `_adopter/` are skipped. See `obsidian-enforcement.md` §O10. + +## Pipeline structure + +### `plugin-v2/scripts/` layout + +``` +plugin-v2/scripts/ +├── check-all.sh # orchestrator +├── fix.sh # local — D1–D5 + E1 auto-fix +├── lint.sh # category A +├── verify.sh # category B +├── validate.sh # category C +├── format.sh # category D (check mode) +├── spell.sh # category E +├── security.sh # category F +├── obsidian.sh # category H — see obsidian-enforcement.md +├── lib/ # shared helpers +│ ├── frontmatter.js +│ ├── markdown-ast.js +│ ├── roster.js +│ └── findings.js # JSON-finding emitter +├── schemas/ # JSON schemas for C1, C3 +│ ├── plugin.schema.json +│ └── templates.schema.json +├── obsidian/ # category H configs — see obsidian-enforcement.md +│ ├── lint-config.jsonc +│ ├── lychee.toml +│ ├── .o1-type-overrides.json +│ ├── .o5-allow.toml +│ ├── .o8-required-tags.json +│ ├── .o9-extra-types.json +│ ├── .o11-roots.json +│ └── config.json +├── .markdownlint-cli2.jsonc +├── .yamllint +├── .gitleaks.toml +├── .lint-heading-extras.json +├── .lint-link-exceptions.json +├── .lint-emoji-allow.json +├── .verify-locked-vocab.txt +├── .verify-tool-verbs.json +└── .security-destructive-bash.txt +``` + +Each script MUST: + +1. Accept `--json` (JSON findings on stdout; default is human-readable summary on stderr + JSON on stdout when `--json`). +2. Accept `--files ` to limit scan scope (used by the pre-commit hook). +3. Exit `0` on no `error`-severity findings, `1` on any `error`, `2` on a tool-invocation failure. + +### `check-all.sh` + +1. Run each category script in declared order: A → B → C → D → E → F → H. +2. Aggregate findings into a single JSON document at `plugin-v2/scripts/.findings.json` (gitignored). +3. Print a final verdict: `GREEN` (zero findings), `YELLOW` (warnings / info only), `RED` (any `error`). +4. Honour `--quick`: skip B and C; run A + D + E on staged files only. Used by the pre-commit hook. + +### `fix.sh` + +1. Run D1 (`markdownlint --fix` or `prettier --write`), D2, D3, D4 (strip trailing whitespace), D5 (append final newline). +2. Run E1 (`typos --write-changes`) for the safe-fix subset only. +3. Print touched files. +4. NEVER run categories that mutate semantic content (B, C, F). + +### CI workflow shape + +> **Status:** implemented — see [`.github/workflows/plugin-v2-quality.yml`](../../.github/workflows/plugin-v2-quality.yml) at the repo root. The landed workflow is the minimum gate: it checks out the tree (SHA-pinned `actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd` — v6.0.2) and runs `bash plugin-v2/scripts/check-all.sh`. Deferred from the spec block below: `actions/setup-node` + `npm ci --prefix plugin-v2/scripts` (no Node deps yet — the seven landed checks are POSIX shell + optional `jq`), `--json` invocation + `findings.json` artifact upload via `actions/upload-artifact`, and the `lib/annotate-pr.js` PR-annotation step. The `permissions: contents: read` floor is in place; `pull-requests: write` will be added when the annotator lands. The reference shape below stays as the acceptance contract for those follow-up slices. + +At `.github/workflows/plugin-v2-quality.yml`: + +```yaml +name: plugin-v2-quality +on: + pull_request: + paths: ['plugin-v2/**'] + push: + branches: [main] + paths: ['plugin-v2/**'] + +permissions: + contents: read + pull-requests: write # for finding annotations + +concurrency: + group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }} + cancel-in-progress: true + +jobs: + quality: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@ # v6.x + - uses: actions/setup-node@ # v6.x, node 24, cache: npm + - run: npm ci --prefix plugin-v2/scripts + - run: plugin-v2/scripts/check-all.sh --json > findings.json + - uses: actions/upload-artifact@ # v5.x + if: always() + - name: Annotate PR + if: failure() && github.event_name == 'pull_request' + run: plugin-v2/scripts/lib/annotate-pr.js findings.json +``` + +Action versions MUST be SHA-pinned matching the parent repo's convention in [`.github/workflows/verify.yml`](../../.github/workflows/verify.yml) and [`.github/workflows/typos.yml`](../../.github/workflows/typos.yml). No matrix; node 24 on `ubuntu-latest`. Cache: `actions/setup-node` `cache: npm` keyed on `plugin-v2/scripts/package-lock.json`. + +### Pre-commit hook + +Opt-in for the maintainer's own clone — not shipped to adopters: + +```bash +#!/usr/bin/env bash +# .git/hooks/pre-commit (or .husky/pre-commit) +set -e +plugin-v2/scripts/check-all.sh --quick --files "$(git diff --cached --name-only --diff-filter=ACM | grep '^plugin-v2/')" +``` + +Runs A + D + E only; exits non-zero on any `error`; never auto-fixes (use `fix.sh`). + +## Acceptance criteria for the implementation PR + +Falsifiable, numbered. This section is the acceptance contract. + +1. `plugin-v2/scripts/check-all.sh` exists, is executable, and on a clean tree exits `0` (or documents every pre-existing finding as a known issue in the PR description). +2. One script per category exists at `plugin-v2/scripts/{lint,verify,validate,format,spell,security,obsidian}.sh`, each callable standalone with `--json` and `--files `. +3. Every check id from §"Check categories" (A1–A9, B1–B8, C1–C5, D1–D5, E1, F1–F3, G1, H1–H8) is reachable via at least one category script and emits findings in the JSON shape from §"Check categories". +4. `plugin-v2/scripts/fix.sh` exists, runs only D1–D5 + E1 auto-fix, and is idempotent (second run produces no diff). +5. `plugin-v2/_typos.toml` exists with the minimum allow-list from E1. +6. `.github/workflows/plugin-v2-quality.yml` exists, runs on every PR touching `plugin-v2/**`, SHA-pins every `uses:` line, and uploads `findings.json` as an artifact. +7. All tool versions are pinned per these targets: `crate-ci/typos@v1.46.0`, `prettier@3.x`, `markdownlint-cli2@0.13.x`, `markdownlint-obsidian-cli@1.1.x`, `yamllint@1.35.x`, `ajv@8.x`, `gitleaks@8.18.x`, `lychee@0.24.x`, `ripgrep@14.x`, `gray-matter@4.x`, `remark-parse@11.x`, `@portaljs/remark-wiki-link@1.x`, `fast-glob@3.x`, `emoji-regex@10.x`. SHA pins in the workflow YAML; minor-range pins in `package.json`. (Note: B3 stays on `lychee@0.15.x` until H4 bumps the floor; the implementation PR aligns them.) +8. The G1 self-application meta-check is referenced from [`maintenance.md`](maintenance.md) §Versioning or §Release with a link back to this spec. +9. Every finding emitted in CI surfaces as a PR annotation with file path and line number. +10. The implementation PR cites this spec by section number for every check it adds. + +## Out of scope + +- Runtime guards on a live goal's `goals//` tree. Adopter trees are not scanned. +- Domain-specific linters (e.g., regulatory keyword scanners). Adopters add their own in their project, not in `plugin-v2/scripts/`. +- External URL availability checks (B3 is offline). An opt-in nightly workflow MAY add this later; not part of the PR-blocking gate. +- Performance benchmarking of the loop itself. +- Adapter-internal checks for `.codex/` and `.cursor/` beyond what their adapter shim documents (see [`tool-adapters.md`](tool-adapters.md)). +- Documentation-coverage metrics. Tracked separately in [`improvement-strategy.md`](improvement-strategy.md). + +## Open questions + +1. **Markdown formatter pick.** D1 lists `markdownlint-cli2` and `prettier` as alternatives. The implementation PR MUST pick one and document the choice. Author leans `markdownlint-cli2` for rule granularity; `prettier` is simpler to wire. +2. **Roster-table parsing.** B2 parses Markdown tables across five surfaces. Header-signature match vs. positional column index vs. AST visitor — left to implementation. Recommend committing a unit-test fixture set. +3. **B5 phase-isolation algorithm.** Parsing prose for write paths is brittle. Proposal: add a structured `writes:` frontmatter list to every agent in a follow-up MINOR bump; B5 then checks the list, not the prose. +4. **Pre-commit framework.** Bash hook vs. [pre-commit.com](https://pre-commit.com) framework — leave to the implementation PR. +5. **Adopter copy fidelity.** When an adopter copies `plugin-v2/`, do the scripts copy too? Default: yes (scripts live under `plugin-v2/scripts/`). Confirm; some adopters may want a thinner subset. +6. **Severity thresholds.** Block on `error` only for PRs; should the G1 self-application loop block on `error | warning`? Author leans yes. +7. **JSON-finding schema versioning.** Should the JSON shape carry a `schema_version`? Proposal: yes, start at `1`. Defer to implementation. diff --git a/plugin-v2/docs/cadence-recipes.md b/plugin-v2/docs/cadence-recipes.md new file mode 100644 index 000000000..9369bb6c2 --- /dev/null +++ b/plugin-v2/docs/cadence-recipes.md @@ -0,0 +1,145 @@ +--- +title: Goal Loop — Cadence Recipes +description: Opt-in recipes for wiring /goal:run to an external scheduler — cron, GitHub Actions, systemd timers. The plugin schedules nothing. +folder: plugin-v2/docs +--- + +# Goal Loop — Cadence Recipes + +> Recurring goals declare a `cadence` in `goal-state.md`, but the plugin schedules nothing — cadence is **informational** (see [`memory/constitution.md`](../memory/constitution.md) and [`customizing.md`](customizing.md)). This doc gives you three baseline ways to wire `/goal:run ` to a scheduler when you actually want time-based execution. + +Pick the recipe whose surface you already own. Schedulers are an operational decision, not a method decision; the Goal Loop runs identically under any of them. + +--- + +## Recipe 1 — cron + +**When to use.** You have a host running 24/7 with `cron` available and you want a low-ceremony daily or weekly trigger. + +**Crontab entry.** Daily at 09:00 local time. Replace `claude-code` with your CLI binary path; replace `my-daily-brief` with your goal slug. + +```cron +# m h dom mon dow command + 0 9 * * * cd /path/to/project && claude-code /goal:run my-daily-brief >> goals/my-daily-brief/cron.log 2>&1 +``` + +**Timezone caveats.** `cron` uses the system timezone. If your host is UTC and you wanted local time, either change the entry's hour or set `CRON_TZ=Europe/Berlin` (or equivalent) at the top of your crontab. Daylight-saving transitions cause one missed or doubled run per year — note it; do not auto-recover. The orchestrator's history will show the gap. + +--- + +## Recipe 2 — GitHub Actions + +**When to use.** The goal lives in a GitHub-hosted repository and you want the run history and logs in the same place as the goal artifacts. + +**Sample workflow.** `.github/workflows/goal-daily.yml`: + +```yaml +name: Goal Loop — daily brief + +on: + schedule: + - cron: "0 9 * * *" # 09:00 UTC; adjust to your fleet timezone + workflow_dispatch: + +permissions: + contents: write # required to commit updated goals// artifacts + +jobs: + run: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Install Claude Code CLI + run: | + # adopter-owned step — install the CLI you actually use + curl -fsSL https://example.invalid/install.sh | sh + + - name: Run the loop + env: + ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} + run: claude-code /goal:run my-daily-brief + + - name: Commit artifacts + run: | + git config user.name "goal-loop-bot" + git config user.email "goal-loop-bot@users.noreply.github.com" + git add goals/ + git diff --cached --quiet || git commit -m "goal-loop: my-daily-brief $(date -u +%Y-%m-%dT%H:%MZ)" + git push +``` + +**Auth caveats.** Schedule triggers run as `github-actions[bot]`; if branch protection requires reviewed commits, the bot will fail to push. Either exempt the workflow with a deploy key / fine-grained PAT, or have the job open a PR instead of pushing directly. Never bypass the act gate to make a workflow run unattended — the act gate is a human check by construction. + +--- + +## Recipe 3 — systemd timer + +**When to use.** The goal runs on a Linux host you already manage with systemd, and you want the timer logs in `journalctl`. + +**Service unit.** `/etc/systemd/system/goal-loop-daily.service`: + +```ini +[Unit] +Description=Goal Loop — daily brief + +[Service] +Type=oneshot +WorkingDirectory=/srv/project +ExecStart=/usr/local/bin/claude-code /goal:run my-daily-brief +StandardOutput=append:/var/log/goal-loop/daily.log +StandardError=append:/var/log/goal-loop/daily.err +User=goal-loop +``` + +**Timer unit.** `/etc/systemd/system/goal-loop-daily.timer`: + +```ini +[Unit] +Description=Goal Loop — daily brief (timer) + +[Timer] +OnCalendar=*-*-* 09:00:00 +Persistent=true +AccuracySec=1min + +[Install] +WantedBy=timers.target +``` + +Enable with `systemctl enable --now goal-loop-daily.timer`. `Persistent=true` runs a missed trigger on boot if the host was off at scheduled time. + +--- + +## What NOT to do + +These rules apply to every recipe above. Violating any one of them collapses the human-in-the-loop contract. + +- **Do not auto-approve the act gate.** Reversible, low-risk actions may be auto-approved only when the goal explicitly declares `act_gate: low-risk-auto`. A scheduler does not get to weaken the policy. See [Article III](../memory/constitution.md). +- **Do not run irreversible actions without a human.** Irreversible actions always require a human Act gate regardless of policy. A scheduled trigger is not a human. See [Article V](../memory/constitution.md). +- **Do not chain iterations without intermediate review.** One iteration at a time per [Article VI](../memory/constitution.md). If a scheduled run produces `outcome: continue`, the next iteration runs on the next cadence tick — not immediately, unless your goal explicitly says so and your gate policy is sound. +- **Do not silently swallow errors.** If the scheduler-driven run fails (CLI crash, network blip, missing source), the failure goes to the human, not into the void. Cron jobs that mail nothing on error are a footgun; configure stderr capture or a notification step. + +## See also + +- [`hooks-recipes.md`](hooks-recipes.md) — opt-in hooks for surfacing goal state in interactive sessions. +- [`customizing.md`](customizing.md) — broader extension points. +- [`usage-patterns.md`](usage-patterns.md) — which goal shapes typically need a cadence. +- [`memory/constitution.md`](../memory/constitution.md) — the gates a scheduler must not weaken. + +## Periodic Notes integration (Obsidian) + +For recurring goals on a daily cadence, adopters can wire daily briefs to Obsidian's **Periodic Notes** plugin (`liamcain/obsidian-periodic-notes`) so each day's brief shows up in the Daily Notes calendar. + +**Setup:** + +1. Install Periodic Notes. +2. In its Settings, set **Daily Notes folder** to `goals//archive/brief/`. +3. Set **Daily Notes format** to `YYYY-MM-DD`. +4. Configure your scheduler (cron / GitHub Actions / systemd from the recipes above) to also write a date-only-named copy of `brief.md` to `goals//archive/brief/.md` after each `/goal:run`. + +Now your daily briefs surface in Obsidian's calendar view; clicking a date opens the brief from that day. + +**Why date-only filenames here** + +The brief archive convention in the plugin is `.md` (e.g. `2026-01-15T07-30-00.md`). Periodic Notes only matches date-only filenames. Adopters who want both keep the iso-timestamp archive **and** symlink (or duplicate, if symlinks aren't an option on their platform) to a date-only filename in the same folder. The plugin itself doesn't ship this — it's a per-adopter scheduler concern. diff --git a/plugin-v2/docs/constitution-v1-criteria.md b/plugin-v2/docs/constitution-v1-criteria.md new file mode 100644 index 000000000..d03e43a9c --- /dev/null +++ b/plugin-v2/docs/constitution-v1-criteria.md @@ -0,0 +1,100 @@ +--- +title: Constitution v1.0 — Graduation criteria +folder: plugin-v2/docs +description: When and how the Goal Loop constitution graduates from v0.1 (Foundation) to v1.0. Lays out the three criteria, the current status, and what's holding each one back. +entry_point: false +--- + +# Constitution v1.0 — Graduation criteria + +The Goal Loop constitution is at v0.1 (`Foundation`) — see [`../memory/constitution.md`](../memory/constitution.md). **v1.0 is the bar at which the method is considered stable enough for regulated adoption** without the "v0.1" caveat dragging compliance reviewers into a moratorium argument. v0.1 is not "unfinished"; it is "still mutable" — amendments are expected, especially to Articles I–III, where lived experience may still adjust load-bearing wording. This doc tracks when v1.0 becomes justified, why each criterion matters, and what gap each one is currently sitting on. + +The three criteria below are stated as cumulative — all three must be true at the same release for the bump to fire. Hitting one and waiting on the others is the expected operating mode, not a failure state. + +## The three criteria + +### 1. No Article I–III amendments for two release cycles + +Articles I (Goal Primacy), II (Phase Isolation), and III (Human Gates) are the load-bearing spine of the method. The whole point of v0.1 is to leave them mutable while real loops shake out edge cases. Once they survive two consecutive minor (or major) releases without amendment, that is empirical evidence that the spine is stable enough to bind. Wording-only edits inside an article do **not** count as amendments for this criterion; structural change to an article's principles does. + +The release cycle is defined in [`maintenance.md`](maintenance.md) — quarterly MINOR / annual MAJOR is the suggested cadence; in practice a "release cycle" is one MINOR or one MAJOR, whichever comes next. Two cycles ≈ six months of real adopter exposure. + +**Why this matters.** A constitution amended every release is not stable enough to cite in compliance documentation. An auditor reading "the act gate is non-negotiable" wants the same wording to be true in six months. Two release cycles without an Article I–III amendment is the cheapest credible signal we can offer. + +**Current status (this release: v2.1.0).** v2.0.0 introduced Articles I–X in their current form. v2.1.0 is additive — no Article I–III amendment. **Counter: 1 of 2 cycles.** The next release without an Article I–III amendment graduates this criterion. + +### 2. Five adopters running the loop in production + +Five distinct projects, each with at least one completed goal closure (`outcome: close-met` or `outcome: close-abandon` recorded in `goal-state.md`'s `## History` and rolled to a `lessons.md`). "Production" is defined as: not the plugin maintainer's own project (the plugin's `examples/` and the maintainer's tutorial runs do not count); not a tutorial run executed once and discarded; not a demo recorded for a video. A real adopter project has its own goals, its own act-gate approvals, and its own evidence trail. + +**Why this matters.** The method has to survive adopter pressure, not maintainer pressure. Five is the smallest number that distinguishes "one adopter's specific need" from "a pattern that recurs". Below five, the maintainer cannot tell whether the method generalises; at five, the per-adopter variance is visible enough to inform amendment decisions in v1.x and beyond. + +**Current status.** Unknown — the plugin emits no telemetry by design (see [`improvement-strategy.md` §"Anti-patterns"](improvement-strategy.md#anti-patterns) — "an observability platform" is on the never-list). Adopter counts are self-reported via the [`bugs.url`](../.claude-plugin/plugin.json) channel or voluntary write-ups. **Counter: unknown of 5.** The maintainer should solicit reports in the changelog and in any "State of the Loop" writeup that pre-dates v1.0. + +### 3. All five canonical use-case patterns have shipped worked examples + +The five canonical patterns are defined in [`usage-patterns.md`](usage-patterns.md): + +- **Issue resolution** — one-shot, bounded. +- **Daily brief** — recurring, awareness. +- **Incident triage** — rapid, time-critical. +- **Release readiness** — checklist, gated. +- **Continuous awareness** — perpetual. + +A canonical pattern has a worked example when an artifact set lives under [`../examples//`](../examples/) (or the doc-side narrative at [`examples/.md`](examples/)) containing at least one full iteration's `goal-state.md`, observations, orientation, decisions, actions, and reviews — runnable, traceable, and current with the schema. A narrative-only example does **not** count. + +**Why this matters.** v1.0 implies the method works across the published pattern space. Shipping only the patterns the maintainer's home turf produces is exactly the domain-neutrality failure Article VII forbids. Five worked examples force the maintainer to test the method against scenarios that *aren't* the maintainer's daily work. + +**Current status.** + +| Pattern | Narrative | Artifact set | Counts toward v1.0? | +|---|---|---|---| +| Issue resolution | shipped | shipped | yes | +| Daily brief | shipped | shipped | yes | +| Incident triage | shipped | shipped (`examples/incident-triage/`) | yes | +| Release readiness | shipped | shipped (`examples/release-readiness/`) | yes | +| Continuous awareness | shipped | shipped (`examples/continuous-awareness/`) | yes | +| Policy consultation *(bonus, non-software)* | shipped | shipped | bonus — does not substitute for any canonical pattern | + +**Counter: 5 of 5 canonical artifact sets** (plus 1 bonus non-software set). Wave-6 closed this criterion fully — all five canonical patterns now ship with both a narrative under `docs/examples/` and a worked artifact set under `examples/`. + +## Current status + +| Criterion | Current | Target | Gap | +|---|---|---|---| +| No Article I–III amendments for two release cycles | 1 of 2 | 2 of 2 | 1 more release without an Article I–III amendment | +| Five adopters with one completed goal closure each | unknown | 5 | self-report channel needs activation; counter must be observable | +| All five canonical worked examples shipped | **5 of 5 (+1 bonus)** | 5 of 5 | **met** | + +## What v1.0 unlocks + +v1.0 is not a feature release. It is a **maturity signal**. Three concrete unlocks: + +- **Regulated-environment adoption.** Compliance reviewers reading a v0.1 constitution have to flag it; the same constitution at v1.0 reads as a stable contract the adopter can cite in their controls register. The wording does not change between v0.x and v1.0; the *trust profile* does. +- **Stable plugin manifest for any future MCP server.** If the plugin ever exposes an MCP surface (currently on the never-list per [`improvement-strategy.md` §"Anti-patterns"](improvement-strategy.md#anti-patterns), but the door is not bolted), an MCP manifest that pins to a v1.0 constitution has a longer shelf life than one pinned to v0.1. +- **Citation in compliance audits without a caveat.** Adopters in regulated environments — ISO 9001, SOC 2, GDPR DPIA, healthcare, financial services — cite the constitution articles in their control documentation. A v1.0 cite holds; a v0.1 cite invites a "what changes when this matures?" follow-up that the adopter would rather not field. + +## What v1.0 does NOT do + +Graduating to v1.0 does **not** freeze the constitution. Amendments still flow through the [Amendment Process](../memory/constitution.md#amendment-process). The bar for Articles I–III stays the same as it always was — highest scrutiny, structured amendment record, named approver. The difference is the **default disposition**: at v0.1, an amendment to Article II is a normal occurrence; at v1.0, it is an exceptional one with a heavier burden of evidence. v1.0 is a *posture*, not a moratorium. + +v1.0 also does not lock the plugin's surface (agents, skills, commands, templates). Those evolve under SemVer regardless of the constitution's version. The plugin's `2.x` or `3.x` line and the constitution's `v1.0` are independent versioning streams — see [`maintenance.md` §"Versioning"](maintenance.md) for the plugin's SemVer rules. + +## Open questions + +The maintainer should resolve these before declaring v1.0. None are blockers individually; together they shape what the v1.0 announcement says and what it does not promise. + +- **Should there be a v0.2 / v0.3 intermediate, or jump straight to v1.0 once the criteria are met?** Intermediate versions absorb wording-level cleanup without spending the v1.0 signal; the cost is more version-fatigue for adopters tracking the constitution. Default lean: jump straight, but reserve v0.2/v0.3 for amendments that need to ship before all three criteria are met. +- **Does the five-adopter criterion need a stricter "from outside the plugin maintainer's network" rule?** Five adopters who all heard about the plugin from the maintainer at the same conference is not the same evidence as five independent discoveries. The rule could read "at least three of the five outside the maintainer's immediate network", but verifying that is hard without surveillance the plugin will not do. Default lean: trust the self-reports; document the caveat. +- **Should `outcome: close-abandon` count toward the "completed goal closure" criterion, or only `outcome: close-met`?** Closure honesty (Article X) treats both as equally valid closures. Counting only `close-met` biases toward the loops that succeed and hides the equally-informative loops that closed because the goal was reframed. Default lean: both count; the criterion measures *completion*, not *success*. +- **Does v1.0 require a security audit that v0.1 did not?** The quarterly agentic-security review described in [`maintenance.md` §"Security review"](maintenance.md) is the current floor. v1.0 could add a pre-graduation external audit. Default lean: no, but a maintainer-led OWASP pass against the v1.0 candidate is recommended and should be cited in the v1.0 announcement. +- **How does graduation interact with the plugin's own SemVer?** A constitution v1.0 announcement that lands inside a plugin MINOR is mechanically possible (the constitution version is a frontmatter value, not a plugin-level field). But it might warrant a plugin MAJOR for visibility. Default lean: announce inside the next plugin MINOR; cross-link it in the MAJOR's release notes when one fires. + +## See also + +- [`../memory/constitution.md`](../memory/constitution.md) — the v0.1 document this graduation targets. +- [`../templates/constitution-amendment-template.md`](../templates/constitution-amendment-template.md) — the structured form every amendment must use; counts against criterion 1 when an Article I–III amendment fires. +- [`maintenance.md`](maintenance.md) — the release-cycle definition criterion 1 references. +- [`usage-patterns.md`](usage-patterns.md) — the five canonical patterns criterion 3 lists. +- [`improvement-strategy.md`](improvement-strategy.md) — the strategic context the v1.0 declaration sits inside. +- [`release-checklist.md`](release-checklist.md) — the gate every release passes; the release that graduates the constitution clears it like any other. diff --git a/plugin-v2/docs/contributing.md b/plugin-v2/docs/contributing.md new file mode 100644 index 000000000..f82cbfe3f --- /dev/null +++ b/plugin-v2/docs/contributing.md @@ -0,0 +1,161 @@ +--- +title: Goal Loop — Contributing +folder: plugin-v2/docs +description: How to contribute to the plugin baseline. Covers the fork-vs-overlay decision, the contribution rubric per surface type, and the safety checklist before opening a PR. +entry_point: false +--- + +# Goal Loop — Contributing + +> Maintainer-level contribution guide for the `goal-loop` plugin baseline. Adopters extending the plugin **in their own project** start with [`customizing.md`](customizing.md) — most extensions belong there, not here. Contributions that propose to change the baseline itself land through this guide. + +## Before you start + +Read these first, in order. They are the contracts every contribution is measured against: + +1. [`method.md`](method.md) — the locked Goal Loop definition. Phase order, vocabulary, state model, gates. +2. [`customizing.md`](customizing.md) — the adopter-facing extension guide. **Most "I want to add X" needs land here, not in the baseline.** +3. [`improvement-strategy.md`](improvement-strategy.md) — the maintainer's rubric for what enters the baseline and what stays an overlay or domain pack. +4. [`../memory/constitution.md`](../memory/constitution.md) — the ten governing articles. Every change is read against them. + +A contribution that has not been measured against these four documents will be sent back for that step. + +## Fork vs. overlay vs. baseline + +The plugin is a **baseline**, not a framework — see [`improvement-strategy.md` §"The plugin's posture"](improvement-strategy.md). Three places a change can land, in preference order: + +| Mechanism | Use when | Cost | Where it lives | +|---|---|---|---| +| **Overlay** (preferred) | The plugin's surfaces are sufficient; you are only adding new content for your project. | Lowest — upgrades the plugin in place. | Your project's `.claude/agents/`, `.claude/skills/`, `templates/` — never inside `plugin-v2/`. | +| **Domain pack** | A coherent bundle exists that ≥ 3 adopters in the same domain would reuse verbatim. | Medium — pack becomes its own maintenance concern. | Sibling repo or `packs//` folder. | +| **Baseline contribution** | ≥ 5 adopters re-implement the same primitive in the same way **and** it is structurally impossible to ship as an external pack (cuts across phases, gates, or the state model). | Highest — every adopter pays the upgrade tax. | This repository, via the rubric below. | + +The default answer to "should this be in the baseline?" is **no, write it as an overlay first**. See [`improvement-strategy.md` §"Domain specialisation"](improvement-strategy.md) for the full matrix and the 5-checkbox test a domain pack must pass before earning a place next to the baseline. + +If you are contributing because an extension point is missing — propose the extension point (EP-N entry), not the feature. + +## Adding a new agent + +Use [`../templates/agent-template.md`](../templates/agent-template.md) as the scaffold. Pick **Shape A** (consult-only) unless you are amending the method — new phase agents require a constitution amendment first (see [Article II](../memory/constitution.md) and [`improvement-strategy.md` §"Extension points the maintainer should refuse to add"](improvement-strategy.md)). + +Checklist (lifted from [`improvement-strategy.md` §"Accepting a new agent"](improvement-strategy.md), expanded with the file-touch list): + +- [ ] **Is it consult-only?** New phase agents need a filled [`../templates/constitution-amendment-template.md`](../templates/constitution-amendment-template.md) before any agent code lands. +- [ ] **Single, narrow scope** expressible in one sentence in the `description` frontmatter. +- [ ] **Tool list is the narrowest** that supports the procedure. Read-only consultants take `[Read, Grep]`. Broadening the list beyond the parent phase agent's scope is forbidden by [`customizing.md` §"The subagent tool-list rule"](customizing.md) without an amendment log entry. +- [ ] **Domain-neutral vocabulary** — Article VII. Software metaphors (commits, branches, tests) belong in examples, not core agent prose. +- [ ] **Names the consulting skill(s)** in the `description` so the dispatch path is unambiguous. +- [ ] **Documents the artifact(s) it writes** — or "Console output only — consult-only agent." Consult-only agents must end the Outputs section with: *"Never writes a phase artifact under `goals//`."* +- [ ] **Writes only to its own outputs** ([Article II](../memory/constitution.md)) and never to another agent's artifact. +- [ ] **Added to the agent roster** in [`../agents/README.md`](../agents/README.md) and [`../AGENTS.md`](../AGENTS.md). +- [ ] **Registered in [`../.claude-plugin/plugin.json`](../.claude-plugin/plugin.json)** `capabilities.agents`. +- [ ] **Added to `docs/tool-matrix.md`** if that file exists at contribution time. +- [ ] **Worked example** — at least one sample dispatch in [`examples/`](examples/) showing where the agent gets consulted, what input it reads, and what it returns. + +## Adding a new skill + +Use [`../templates/skill-template.md`](../templates/skill-template.md) as the scaffold. The skill / command boundary: skills are **reusable how-tos** any agent or human invokes; slash commands are **dispatched workflows** that resolve a goal slug and invoke one skill. Get the category right before discussing the content. + +Checklist: + +- [ ] **Frontmatter is complete:** `name`, `description`, optional `argument-hint`. The `description` carries **3+ trigger phrases as quoted strings** for natural-language auto-load (see [`../docs/automation-spec.md`](automation-spec.md) §A4 `lint.skill-trigger-phrases`). +- [ ] **Body section order** matches the canonical: Title, intro, `## Read first`, `## What you do, step by step`, `## Outputs`, `## Boundaries`, `## References`. +- [ ] **`## What you do, step by step`** block uses numbered or `### Step N — name` sub-headings. The final step is "Report and hand back". +- [ ] **`## Boundaries`** block names what the skill **never** does — phase isolation, gate respect, scope discipline. References [`../skills/_shared/loop-pattern.md`](../skills/_shared/loop-pattern.md) §"Constraints common to all Goal Loop conductors". +- [ ] **Touches only the phase or artifact its name implies.** Cross-phase skills are forbidden by [Article II](../memory/constitution.md). +- [ ] **Never edits `goal-state.md` directly** — state changes route through the `goal-orchestrator` dispatch. +- [ ] **References the shared rules** in [`../skills/_shared/`](../skills/_shared/) rather than restating them in prose. +- [ ] **Registered in [`../skills/README.md`](../skills/README.md)** and [`../AGENTS.md`](../AGENTS.md) skill roster. +- [ ] **Registered in [`../.claude-plugin/plugin.json`](../.claude-plugin/plugin.json)** `capabilities.skills`. +- [ ] **If wrapped by a slash command**, that command file under [`../commands/goal/`](../commands/goal/) references this skill explicitly. +- [ ] **Worked example** — at least one usage trace in [`examples/`](examples/) or a worked block in the skill body. + +## Adding a new template + +Templates are framework-agnostic Markdown; placeholders use `` angle brackets. + +Checklist: + +- [ ] **Frontmatter** carries `title`, `folder`, `description`, and `entry_point: false` (only `templates/README.md` is the entry point). +- [ ] **Preserves canonical frontmatter fields** the agents read. You may **add** fields; you may not silently **remove** ones the existing agents depend on. +- [ ] **Framework-agnostic** — no language- or tool-specific assumptions baked into the structure. +- [ ] **Added to the [`../templates/README.md`](../templates/README.md) Index table** with three columns filled: `Produced by`, `Lives at`, `Filename pattern`. +- [ ] **Referenced from the agent or skill that produces it.** A template no one writes is dead weight. +- [ ] **Used at least once in an example** — either a worked example under [`examples/`](examples/) or an instantiated copy in a sample goal. + +## Adding a new command + +Commands live under [`../commands/goal/`](../commands/goal/) and resolve a goal slug, then invoke exactly one skill. See [`../commands/goal/README.md`](../commands/goal/README.md) for the existing roster. + +Checklist: + +- [ ] **Frontmatter** carries `description`, `argument-hint`, `allowed-tools`, and optionally `model`. +- [ ] **Standard body sections in order:** `## Inputs`, `## Procedure`, `## Don't`. +- [ ] **Resolves the goal slug** (or surfaces a clear error if it cannot) before dispatching. +- [ ] **Invokes exactly one skill** — commands are thin wrappers, not workflows in themselves. +- [ ] **Respects the act gate and goal gate.** A command never bypasses a human gate even if the underlying skill says it could. +- [ ] **Added as a row in [`../commands/goal/README.md`](../commands/goal/README.md)**. +- [ ] **Surfaced in [`../AGENTS.md`](../AGENTS.md)** slash-command roster. +- [ ] **One worked example** in the command body or under [`examples/`](examples/). + +## Amending the constitution + +If your contribution requires changing one of the ten governing articles — for example, introducing a new phase agent or a new phase — the amendment is the **first deliverable, not the code**. + +1. Fill [`../templates/constitution-amendment-template.md`](../templates/constitution-amendment-template.md) completely. Quote current text verbatim. Name every affected template, agent, skill, and doc. +2. Cite a real loop, review, or incident that surfaced the gap — not a hypothetical. +3. Follow the process in [`../memory/constitution.md`](../memory/constitution.md) §"Amendment process". +4. Amendments to Articles I–III (Goal Primacy, Phase Isolation, Human Gates) warrant a 14-day open comment window before acceptance. Other amendments may move on 7 days. +5. The default answer on a constitution amendment is **no**; the burden is on the proposer. See [`improvement-strategy.md` §"Accepting a constitution amendment"](improvement-strategy.md) for the full acceptance rubric. + +## Verification before PR + +Run these locally before opening the PR. They are fast and they catch the things human reviewers should not have to. + +```bash +npm run check:links # cross-doc links resolve +npm run check:frontmatter # YAML frontmatter is well-formed and complete +``` + +Both must be green. A red gate is not a request for the reviewer to help fix it — it is a request to fix it before re-asking for review. + +Once implemented, every PR touching `plugin-v2/**` is gated by the **eight check categories** specified in [`automation-spec.md`](automation-spec.md): + +| Category | Check ids | Purpose | +|---|---|---| +| **A — lint** | A1–A9 | Frontmatter completeness, section order, trigger phrases, capability registration. | +| **B — verify** | B1–B8 | Cross-doc link resolution, contract surfaces, schema conformance. | +| **C — validate** | C1–C5 | State-file shape, template instantiation, agent / skill / template registration. | +| **D — format** | D1–D5 | Whitespace, heading levels, list shape, code-block fencing. | +| **E — spell-check** | E1 | Glossary-aware spell-check across docs and prompts. | +| **F — security** | F1–F3 | Secret scanning, dependency surface check, tool-list audit. | +| **G — self-application** | G1, G2 | The plugin runs the Goal Loop against each release goal at release time (G1); goal artifact bodies stay under the 3500-character cap (G2). | +| **H — Obsidian compliance** | H1–H8 | Vault-shape checks on plugin-emitted artifacts. | + +Until the scripts under `plugin-v2/scripts/` land, run the equivalent checks by hand, or invoke the parent repository's `npm run verify`. See [`automation-spec.md`](automation-spec.md) for the full check-id list and the JSON shape each check emits. + +## PR hygiene + +- **Conventional Commits 1.0.0.** `feat:`, `fix:`, `docs:`, `chore:`, `refactor:`, `test:`. See [`maintenance.md`](maintenance.md) §"Versioning" for the SemVer mapping. +- **One concern per PR.** Two new agents in one PR get sent back to be split. +- **Reference the rubric checklist** in the PR body. Tick the boxes you actually ran; do not pre-tick. +- **Cite the article(s)** your change touches if any constitution-adjacent code is in scope — even when no amendment is needed, the cite proves the change was read against the constitution. +- **Doc update rides with the change.** No "I'll write the doc later." See [`improvement-strategy.md` §"General contribution hygiene"](improvement-strategy.md). +- **Worked example or test fixture** exercising the change ships in the same PR. +- **Backward compatibility** is preserved within a major version. Breaking changes wait for the next major and ship with a deprecation period — see [`maintenance.md`](maintenance.md) for the defensive side of this rule. + +## Code of conduct + +This plugin lives inside the [parent `agentic-workflow` repository](../../README.md). Code of conduct follows the parent project's norms — reasonable open-source behaviour, plain language, no harassment, no demands for free maintainer time. A dedicated `CODE_OF_CONDUCT.md` may be added when the contributor base grows; until then, default to the parent repo's conventions and the constitution's escalation pattern: when in doubt, ask the human. + +## See also + +- [`method.md`](method.md) — the locked Goal Loop definition. +- [`customizing.md`](customizing.md) — adopter-facing extension guide. **Most "I want to add X" needs land there.** +- [`improvement-strategy.md`](improvement-strategy.md) — maintainer rubric and roadmap shape. +- [`maintenance.md`](maintenance.md) — versioning, deprecation, security, EOL. +- [`automation-spec.md`](automation-spec.md) — the eight check categories that will gate every PR once implemented. +- [`../templates/agent-template.md`](../templates/agent-template.md) — scaffold for new agents. +- [`../templates/skill-template.md`](../templates/skill-template.md) — scaffold for new skills. +- [`../templates/constitution-amendment-template.md`](../templates/constitution-amendment-template.md) — required form for any constitution change. +- [`../memory/constitution.md`](../memory/constitution.md) — the ten governing articles. diff --git a/plugin-v2/docs/customizing.md b/plugin-v2/docs/customizing.md new file mode 100644 index 000000000..d2aa7a4fd --- /dev/null +++ b/plugin-v2/docs/customizing.md @@ -0,0 +1,89 @@ +--- +title: Customizing the Goal Loop +description: How to extend the goal-loop plugin in your own project — new observe sources, decision criteria, act-gate policies, domain subagents, and template swaps. +--- + +# Customizing the Goal Loop + +> Extend the plugin in your own project without forking it. The plugin's locked vocabulary, phase order, and human gates are non-negotiable; everything else is a place to plug in. See [`method.md`](method.md) for the contract and [`.claude-plugin/plugin.json`](../.claude-plugin/plugin.json) for the surface the host project loads. + +Extensions live in the consuming project, not in the plugin folder. Keep customisations close to the goal they serve so the plugin can be upgraded without losing your work. + +## Adding a new observe source type + +The `observer` already handles file, directory, URL, search query, command output, and document sources. Add a new type when none of these fits — for example, a metrics API, a chat archive, or a sensor stream. + +Steps: + +1. Add the new `type` to the source table in your goal's `goal-state.md` (`observe_sources` block). Use a short kebab-case slug — `metrics-api`, `chat-archive`, `sensor-feed`. +2. Document how to read it. Two options: + - **Inline** — describe the read command or query in the source row's `target` column. The observer follows it verbatim. + - **Helper skill** — if the source is reused across goals, add a small skill in your project under `.claude/skills/observe-/` whose only job is to fetch and shape signals for that type. The observer invokes it during step 2 of its procedure. +3. Keep the observer contract intact: signals only, no interpretation. New source types do not get a licence to summarise. + +## Custom decision-ranking criteria + +The default `decider` ranks by `impact × confidence ÷ cost`. Domains often need extra dimensions — regulatory exposure, customer impact, blast radius, strategic fit. + +Steps: + +1. In `goal-state.md`, add a `decision_dimensions:` block under the act-gate section listing the extra dimensions and their 1–5 (or H/M/L) rubrics. +2. Reference the block from the goal's intent or constraints so the decider knows to read it. +3. The decider's procedure already enumerates candidates and ranks them; the extra dimensions feed into its score. Keep the formula explicit in `decisions.md` so the audit trail shows the math. +4. If a dimension is binary and disqualifying (e.g. "violates a regulation"), encode it as a constraint in `goal-state.md` rather than a ranking dimension. Constraint violations drop the action entirely; ranking dimensions only reorder. + +## Custom act-gate policies + +The shipped policies are `always`, `low-risk-auto`, and `never`. A project may need a policy that depends on the action's target or value. + +Steps: + +1. In `goal-state.md`, replace the single `act_gate` field with a small policy table — per action class, declare a gate. Example classes: `read-only`, `local-edit`, `external-write`, `customer-visible`, `money-movement`. Each row maps a class to `auto` or `human`. +2. The decider's procedure already tags each proposal with `reversible: Y | N`; extend its rubric to also tag the action class so the gate maps cleanly. +3. The orchestrator's act-gate handling step (procedure step 6) reads the policy table and routes each proposal to the right gate. +4. Irreversible actions always require a human gate regardless of class. That rule is in the constitution; no policy can override it. + +## Adding domain-specific subagents + +The five phase agents are domain-neutral. Domain expertise belongs in additional subagents the phase agents *consult*, not in new phase agents. + +Steps: + +1. Create the new subagent under your project's `.claude/agents/` (not in the plugin folder). Give it a narrow scope and an explicit tool list. Example: `compliance-reviewer`, `release-notes-drafter`, `metrics-summariser`. +2. Document when the existing phase agents consult it. For instance, the `decider` may consult `compliance-reviewer` to mark whether an action class clears regulatory constraints; the consult result lands in the rationale. +3. Keep the consult one-way: the consulted agent returns a fact or verdict; the phase agent decides what to do with it. The consulted agent does not own the phase artifact. +4. Tool lists may be **narrowed** for stricter scopes — give a read-only consultant only `Read` and `Grep`. Tool lists may not be silently **broadened** beyond the parent phase agent's surface. If a new tool is genuinely needed, record the change in your project's amendment log and explain why. + +## Swapping templates + +Every artifact has a template under [`templates/`](../templates/). You may swap a template for a project-specific one when the goal demands extra structure. + +Steps: + +1. Copy the template into your project (e.g. `templates/goal-state-template..md`). Do not edit the plugin's copy. +2. Keep the existing frontmatter fields. The orchestrator and phase agents read them. You may **add** fields; you may not **remove** the canonical ones. +3. Reference your variant from the goal's `goal-state.md` so the agents read your version. The agents follow the path the goal points at. +4. Sections in the body may be reshaped freely, as long as the contract each agent depends on (e.g. "every claim cites an observation") still holds. + +## The subagent tool-list rule + +This rule applies to every customisation above and is worth stating once, clearly: + +- Subagent tool lists may be **narrowed** to enforce stricter scopes. +- Subagent tool lists may **not** be silently **broadened**. +- A widened tool list is a method change. Record it in your amendment log alongside the rationale and the constraint it relaxes. The constitution's Article II (Phase Isolation) and Article IX (Escalate, Don't Invent) apply unchanged. + +## Where to look next + +- [`method.md`](method.md) — the locked contract for phases, artifacts, and gates. +- [`usage-patterns.md`](usage-patterns.md) — pick the right shape before customising the parts. +- [`tool-adapters.md`](tool-adapters.md) — how the same plugin serves Claude Code, Codex, and Cursor. + +## See also + +When your customisation outgrows your own project and you want to land it upstream in the plugin baseline: + +- [`contributing.md`](contributing.md) — the maintainer-level contribution guide. Fork-vs-overlay decision, per-surface rubric (agent / skill / template / command / amendment), verification checklist before PR. +- [`../templates/agent-template.md`](../templates/agent-template.md) — scaffold for a new consult-only or phase-extension agent. +- [`../templates/skill-template.md`](../templates/skill-template.md) — scaffold for a new helper, phase, or read-only skill. +- [`improvement-strategy.md`](improvement-strategy.md) — the rubric the maintainer applies when deciding what enters the baseline vs. what stays an overlay or domain pack. diff --git a/plugin-v2/docs/dataview-snippets.md b/plugin-v2/docs/dataview-snippets.md new file mode 100644 index 000000000..e944c7ce3 --- /dev/null +++ b/plugin-v2/docs/dataview-snippets.md @@ -0,0 +1,128 @@ +--- +title: Goal Loop — Dataview snippets +folder: plugin-v2/docs +description: Paste-ready Dataview queries for adopters who open their goal-loop project as an Obsidian vault. Requires the Dataview community plugin. +entry_point: false +--- + +# Goal Loop — Dataview snippets + +Drop any of these into a personal note in your vault. Each query is one self-contained code block. Requires the [Dataview](https://github.com/blacksmithgu/obsidian-dataview) community plugin. + +The plugin itself does **not** ship Dataview — these snippets are pure adopter-side sugar. They read the frontmatter the plugin already writes (see [`obsidian-compatibility.md`](obsidian-compatibility.md) for the schema and the canonical tag namespace). Tweak field lists, filters, and limits to taste. + +## Portfolio dashboard + +The Obsidian-rendered equivalent of `/goal:list`. One row per goal, recency-sorted. + +````markdown +```dataview +TABLE status, current_phase, iteration, updated_at +FROM "goals" +WHERE !example +SORT updated_at DESC +``` +```` + +**What this shows.** Every `goal-state.md` under `goals/` (worked-example folders are skipped via the `example: true` frontmatter convention), with its lifecycle status, the loop phase it currently sits in, the iteration counter, and the last time the orchestrator touched it. + +**Tweak it.** Filter by `status` to narrow the view: `WHERE !example AND status = "active"` gives the live portfolio; `WHERE !example AND status = "blocked"` surfaces what needs human attention. + +## Stalled goals + +Active, paused, or blocked goals untouched in seven days. The slowest signal that something needs follow-up. + +````markdown +```dataview +TABLE status, current_phase, iteration, updated_at +FROM "goals" +WHERE !example + AND (status = "active" OR status = "paused" OR status = "blocked") + AND updated_at < date(today) - dur(7 days) +SORT updated_at ASC +``` +```` + +The oldest row is the one most likely to be drifting silently. Pair with `/goal:status ` to read the loop's last History row. + +## Outcome rollup + +Closed goals grouped by `outcome` — useful for monthly or quarterly retros. + +````markdown +```dataview +TABLE WITHOUT ID + outcome AS "Outcome", + length(rows) AS "Count" +FROM "goals" +WHERE !example AND (status = "done" OR status = "cancelled") +GROUP BY outcome +``` +```` + +`outcome` here is the closure verdict the orchestrator copies onto `goal-state.md` from the final review (`close-met` / `close-abandon`). For a per-review version, see the recent-reviews query below. + +## Pending act gates + +Decisions awaiting human approval. The frontmatter-friendly view — flagging decision-set artifacts whose `status` is still `pending`: + +````markdown +```dataview +TABLE goal_slug, iteration, proposed_at +FROM "goals" AND #goal-loop/artifact/decision +WHERE !example AND status = "pending" +SORT proposed_at ASC +``` +```` + +**Caveat — body-section gates.** A more thorough view would scan each `decisions.md` for an unfilled `## Human Approval` section. Dataview cannot reliably parse per-block content without a per-block inline-field convention the plugin does not emit. Stick to frontmatter `status` for now, or write an inline `gate_status:: pending` field on the line above the section if you want Dataview to see it. + +## Per-goal artifact tree + +Given a specific slug, list every artifact under it. Replace `wiki-redirect-fix` with the slug you want. + +````markdown +```dataview +LIST file.link +FROM "goals/wiki-redirect-fix" +SORT file.path ASC +``` +```` + +Handy when you want to scan one goal's full audit trail without leaving the dashboard note. For an iteration-by-iteration walk, use `/goal:trace ` instead. + +## Recent reviews + +Last ten reviews across the whole portfolio — a lightweight weekly digest. + +````markdown +```dataview +TABLE goal_slug, iteration, outcome, reviewed_at +FROM "goals" AND #goal-loop/artifact/review +WHERE !example +SORT reviewed_at DESC +LIMIT 10 +``` +```` + +Bump the `LIMIT` for a fuller view, or add `WHERE outcome = "close-met"` to filter to successful closures only. + +## Tag conventions + +These queries lean on the canonical `goal-loop/...` tag namespace the plugin's templates emit. Refresher: + +- `goal-loop/artifact/` — one of `goal-state`, `observation`, `orientation`, `decision`, `action`, `review`, `brief`, `lessons`. +- `goal-loop/status/` — mirrors the `status` frontmatter on `goal-state.md`. +- `goal-loop/phase/` — `observe` / `orient` / `decide` / `act` / `review` on per-iteration artifacts. +- `goal-loop/mode/` — `one-shot` / `recurring`. +- `goal-loop/outcome/` — `continue` / `close-met` / `close-abandon` / `amend` on reviews. +- `goal-loop/gate/` — `always` / `low-risk-auto` / `never` on `goal-state.md`. + +Canonical list: [`obsidian-compatibility.md`](obsidian-compatibility.md) §Tags. Adopters may add their own; the plugin will not strip them. + +## Caveats + +- **Dataview is a community plugin, not core.** Adopters who do not install it will see the queries render as plain code blocks. The audit trail still works; only the rollups disappear. +- **Queries assume the canonical frontmatter shape.** If you have hand-edited an artifact and broken a property type, expect an empty row rather than an error — Dataview silently coerces. +- **`## Human Approval` blocks in `decisions.md` are not Dataview-native.** Per-block parsing requires inline fields. The frontmatter `status: pending` convention is the supported lever. +- **Example folders are excluded by `!example`.** This keeps the shipped worked examples out of an adopter's portfolio. Remove the predicate if you want to see them. diff --git a/plugin-v2/docs/death-spirals.md b/plugin-v2/docs/death-spirals.md new file mode 100644 index 000000000..3daaa87ba --- /dev/null +++ b/plugin-v2/docs/death-spirals.md @@ -0,0 +1,100 @@ +--- +title: Goal Loop — Death-spiral diagnostic catalogue +folder: plugin-v2/docs +description: The three canonical death-spiral shapes the hard-stop caps prevent, with diagnostic patterns and intervention recipes. Pairs with the hard-stop caps in method.md and the orchestrator's gate evaluation. +entry_point: false +--- + +# Goal Loop — Death-spiral diagnostic catalogue + +> Companion to [`method.md`](method.md) §"Hard-stop gates" (the caps), [`agents/goal-orchestrator.md`](../agents/goal-orchestrator.md) §"Hard-stop gate evaluation" (the runtime), and [`research-goal-oriented-ai.md`](research-goal-oriented-ai.md) §H-3 (the literature). This doc names the three failure modes a Goal Loop can fall into without bounded caps, gives diagnostic signatures the human can spot in `goal-state.md`, and lists concrete intervention recipes to run **before** a cap fires at 100%. The point is not to celebrate the cap when it triggers — it is to read the loop's body language early enough that the cap never has to fire. + +Death spirals are the three failure modes a Goal Loop can fall into without bounded caps. Each has a distinct signature visible in `goal-state.md` `## History`, `## Health`, and the artifact tree; each maps 1:1 to one of the three caps; each has a recipe for early intervention. Recognising the shape is the operator's main job once a loop has been running for more than a few iterations. + +## The three shapes + +### Time spiral — the loop runs without converging + +- **What it looks like.** + - `## History` shows ≥ 5 iterations with no acceptance-criterion verdict moving from `unmet` → `met`. + - The same Open Question recurs across three or more orientation files. + - `loop-reviewer` keeps returning `outcome: continue` with a fresh "next observation focus" that mirrors a focus from two iterations back. + - The user starts re-reading earlier iterations to re-orient before each session — Czerwinski-style re-entry cost (see [`research-goal-oriented-ai.md`](research-goal-oriented-ai.md) §1). + - `## Health` shows `Iteration count` climbing while `Failed acts` and `Consecutive rejects` stay at zero — the loop is *busy*, not *broken*. + +- **What it usually means.** The acceptance criteria are not falsifiable enough to ever read `met`. The goal may be aspirational ("understand our customers better") rather than verifiable ("complete five customer interviews and extract three recurring themes"). Alternatively the observe-source set is too broad — every iteration scans too much and synthesises too thinly. + +- **The cap that prevents it.** [`max_iterations`](method.md#hard-stop-gates) — default `25`. The orchestrator raises `approaching-cap` at 80% (iteration 20) and `at-cap` at 100% (iteration 25); the loop stops dispatching the next phase at 100%. Recurring goals can raise this; one-shot goals rarely need more than 5. + +- **Intervention recipes (run before 80%).** + - Run `/goal:amend ` to tighten the acceptance criteria — replace fuzzy verbs ("understand", "improve") with falsifiable surfaces ("recorded in", "produced", "verified by"). The [`acceptance-criteria-helper`](../skills/acceptance-criteria-helper/SKILL.md) skill walks this. + - Narrow the observe-sources to the two or three with the highest signal-to-noise. A spiralling Time loop with eight sources almost always over-scans; drop the long-tail sources for one iteration and see if orientation sharpens. + - Split the goal into smaller, sequentially closable goals — if the intent is genuinely multi-outcome, the goal is the wrong shape (per [`anti-patterns.md`](anti-patterns.md) discipline on single-intent goals). + - If the criteria are correct and the loop is still spiralling, the honest move is `/goal:close close-abandon` with a rationale that captures what was learned. Article X (Closure Honesty) treats abandonment as a valid closure. + +### Decision spiral — the decider keeps proposing acts the human keeps rejecting + +- **What it looks like.** + - Three or more consecutive `decisions/.md` files where the decider's top-ranked option was rejected at the act gate. + - The rejection rationale is the same across rejections ("scope creep", "not what I asked for", "wrong target system") — the decider is not learning from the previous rejection. + - `orientation.md` Open Questions count rises across iterations but no Open Question gets resolved into a constraint. + - `Recommendation` blocks in `decisions.md` start arriving empty or marked "no confident option available" — the decider has stopped sharpening. + +- **What it usually means.** Almost always a goal that has been scoped wrong, not a tactical decider failure. The decider is honestly proposing options the goal contract justifies; the human is honestly rejecting them because the *real* constraint lives outside the contract. The spiral is the signal that the goal needs amendment, not that the decider needs prompting differently. + +- **The cap that prevents it.** [`max_consecutive_rejects`](method.md#hard-stop-gates) — default `3`. Resets when any decision is approved. The orchestrator surfaces `approaching-cap` after 2 rejects (66%; below the 80% threshold for this cap because the absolute number is so small) and `at-cap` after 3. + +- **Intervention recipes (run before the third reject).** + - Invoke [`risk-scout`](../agents/risk-scout.md) before the next Decide phase. Risk-scout's job is to surface unstated risks the orientation missed; a spiralling Decision loop usually has one such risk sitting unstated in the user's head. + - Revisit the goal definition. Run `/goal:amend ` and walk the human through "what is the real constraint here?" — Klein's pre-mortem prompt (see [`research-goal-oriented-ai.md`](research-goal-oriented-ai.md) §1) is the operative move: "name one piece of evidence that, if absent, would force you to mark this criterion unmet". + - Only after the goal is amended should the cap itself be raised. Raising the cap on an un-amended goal turns a Decision spiral into a Time spiral. + - If amendment surfaces a constraint the loop genuinely cannot satisfy (out-of-scope tool, missing authority, unavailable signal), `/goal:close close-abandon` with rationale is the correct close. + +### Act spiral — actors keep returning `status: failed` + +- **What it looks like.** + - Lifetime `Failed acts` counter climbs past 3 with no `Done` between failures. + - The same action shape (same tool, same target) appears across the failures — the actor is retrying a structurally broken action, not encountering bad luck. + - The action-log `## What changed` blocks are empty or list rollback-only entries — every act has been undone. + - The orienter's claims that motivated the failing acts may not cite observations (Article IV — Evidence-Based Orientation, violated upstream). + +- **What it usually means.** The problem is rarely in the actor. The actor is faithfully executing a decision built on a faulty orientation, or built on a sound orientation but the wrong shape of action. An Act spiral is almost always a defect that lives one or two phases upstream. + +- **The cap that prevents it.** [`max_failed_acts`](method.md#hard-stop-gates) — default `5`, counted across the goal's lifetime (not reset per iteration). Surfaces `approaching-cap` at 4 failed acts (80%) and `at-cap` at 5. + +- **Intervention recipes (run before the fourth failure).** + - Review the action spec quality against the next iteration's criteria. Run [`acceptance-criteria-helper`](../skills/acceptance-criteria-helper/SKILL.md) over the most recent failed action's criteria and see whether the criteria themselves are observably checkable. If they are not, the action is shaped wrong. + - Audit the orienter's claims that fed the failing decision. Every claim in `orientation.md` is supposed to cite an observation by file and signal index (Article IV); a spiralling Act loop often has uncited claims that the decider treated as ground truth. + - Consider that the action shape is wrong, not the action target. If three "edit file X" actions failed, the answer may not be a fourth edit but a different tool entirely (write, append, regenerate) or a different target (an upstream config, not the artifact). + - If the orientation and decision look correct and the action keeps failing, the system being acted on may be the wrong system. `/goal:amend ` to narrow scope, or `/goal:close close-abandon` if the target is genuinely unreachable. + +## Spotting a spiral early + +Before the 80% gate fires, the loop usually telegraphs the shape. Treat any of these signals as a "look at the spiral catalogue now" prompt rather than a "we'll address it next iteration" deferral: + +- Two consecutive `partial` action verdicts on the same criterion — Time spiral starting. +- The same orientation contradiction surviving across iterations without being resolved or escalated — Time spiral with Decision-spiral risk. +- Decision-set `Recommendation` block consistently empty across two consecutive Decide phases — Decision spiral; decider has run out of options inside the current goal frame. +- User pasting the same act-gate exclusion ("don't touch X again") three times in a row — Decision spiral; the human is enforcing a constraint that should be in the goal contract. +- The orienter producing one-line entries instead of synthesised paragraphs — observer signal has dried up; Time spiral on the way unless observe sources are revisited. + +## What hitting 100% means + +The orchestrator stops the loop. At `at-cap` it does **not** dispatch the next phase, regardless of the human's preference. This is a constitutional gate, not a stylistic preference — [Article VI Loop Discipline](../memory/constitution.md) forbids the orchestrator from iterating past a declared cap without a recorded amendment. + +The only two legal escapes are: + +- **`/goal:amend `** — raises the cap (with a `## History` row recording why the amendment was necessary). The amendment is the audit trail that closes the loop on the spiral honestly: the human has named the spiral, accepted that the next N iterations have a real budget, and signed for it. +- **`/goal:close close-abandon`** — closes the goal with rationale (positional outcome syntax per [`commands/goal/close.md`](../commands/goal/close.md) — no `--abandon` flag). The rationale becomes part of the audit trail; the goal-state file rolls to `status: cancelled`; a `lessons.md` captures what the spiral taught. + +Bypassing the gate without amendment or close is impossible by construction — the orchestrator does not have a "force-continue" code path. This is the design ([ADR-0008](https://github.com/Luis85/agentic-workflow/issues) — see plugin maintenance log) and it is the point: an unforced loop is an audited loop. + +## See also + +- [`method.md`](method.md) §"Hard-stop gates" — the canonical cap definitions and threshold behaviour. +- [`agents/goal-orchestrator.md`](../agents/goal-orchestrator.md) §"Hard-stop gate evaluation" — the orchestrator's gate-evaluation procedure. +- [`templates/goal-state-template.md`](../templates/goal-state-template.md) §Health — the `## Health` block that surfaces the counters. +- [`templates/health-template.md`](../templates/health-template.md) — the separate per-goal `health.md` rolling snapshot. +- [`research-goal-oriented-ai.md`](research-goal-oriented-ai.md) §H-3 — the literature grounding for runaway-loop gates. +- [`anti-patterns.md`](anti-patterns.md) — drift catalogue; spirals are run-time failures, anti-patterns are author-time failures. +- [`troubleshooting.md`](troubleshooting.md) — problem → cause → fix for blockers that have not yet shaped into a spiral. diff --git a/plugin-v2/docs/domain-model.md b/plugin-v2/docs/domain-model.md new file mode 100644 index 000000000..cb39b8a1b --- /dev/null +++ b/plugin-v2/docs/domain-model.md @@ -0,0 +1,435 @@ +--- +title: Goal Loop — Domain model (CONTEXT) +folder: plugin-v2/docs +description: The single-read mental model of the Goal Loop plugin. Every domain type documented in one place — fields, relationships, lifecycle, file location, ownership, transformations. Read this once before deep work on the plugin; then use the targeted docs. +entry_point: false +--- + +# Goal Loop — Domain model (CONTEXT) + +> **How to read this doc.** Read sections 1–8 (the core iteration types you touch on day one: Goal, GoalState, Iteration, Phase, Observation, MergedObservations, Orientation, DecisionSet). Sections 9–24 are reference — return when you need them (Decision, HumanApproval, ActionSpec, ActionLog, Review, Verdict, Outcome, History, Health, Brief, Lessons, Trace, GoalCard + ObserveSourceDatasheet, SessionGoal, AmendmentRecord, Index). The section numbers are stable — adopters who jump here from a search expect them not to move. + +The `goal-loop` plugin is a goal-bounded OODA loop expressed as a file-system state machine. There is no runtime, no database, no daemon — every concept is a Markdown file with a frontmatter header and a small set of body sections, written by exactly one agent and read by many. This document enumerates every domain type, its file location, its sole writer, its shape, its lifecycle, and the relationships that hold between types. Read it once to assemble the mental model in one pass; then drop into the canonical sources ([`method.md`](method.md), [`skills/_shared/goal-state.md`](../skills/_shared/goal-state.md), [`glossary.md`](glossary.md), the per-template files) for detail. + +## Mental model in one diagram + +```mermaid +flowchart TD + classDef root fill:#fef3c7,stroke:#92400e,stroke-width:2px + classDef artifact fill:#e0f2fe,stroke:#075985 + classDef rolling fill:#dcfce7,stroke:#166534 + classDef terminal fill:#fee2e2,stroke:#991b1b + classDef audit fill:#f3e8ff,stroke:#6b21a8 + + G[Goal / GoalState
goals slash slug slash goal-state.md]:::root + + G -->|references| Card[GoalCard
card.md]:::audit + G -->|references| Sheet[ObserveSourceDatasheet
sources slash src-id.md]:::audit + + G -->|written by observer x N| Obs[Observation
observations slash iso--src.md]:::artifact + Obs -->|merged when N greater-equal 2| Merged[MergedObservations
observations slash iso--_merged.md]:::artifact + Merged --> Or[Orientation
orientation.md]:::artifact + Obs --> Or + Or --> DS[DecisionSet
block in decisions.md]:::artifact + DS -->|contains| D[Decision rows]:::artifact + DS -->|contains| HA[HumanApproval
act-gate record]:::artifact + HA --> AS[ActionSpec optional
actions slash a-id.spec.md]:::artifact + HA --> AL[ActionLog
actions slash a-id.md]:::artifact + AL --> Rev[Review
reviews slash iso.md]:::artifact + + Rev -->|outcome continue| G + Rev -->|outcome close-met or close-abandon| Closed[GoalState closed
status done or cancelled]:::terminal + Rev -->|outcome amend| Amend[set-goal amend mode] + Amend --> G + + G -.->|orchestrator refreshes each transition| Hsec[Health section in goal-state.md]:::rolling + G -.->|orchestrator refreshes each transition| Hfile[health.md rolling record]:::rolling + G -.->|recurring goals only| Brief[Brief
brief.md and archive slash brief slash YYYY-MM-DD.md]:::artifact + Closed -.->|filled at closure| Lessons[Lessons
lessons.md]:::artifact + G -.->|appended on closure| Index[Index
goals slash INDEX.md]:::audit + + subgraph Conductor + Orch[goal-orchestrator
sole writer of goal-state.md and health.md] + end + Orch --> G + + subgraph PhaseAgents + OBA[observer] --> Obs + DDA[signal-deduper consult] --> Merged + ORA[orienter] --> Or + DEA[decider] --> DS + DEA --> D + DSK[decide skill] --> HA + ACA[actor] --> AL + LRA[loop-reviewer] --> Rev + end +``` + +ASCII fallback (same flow, smaller surface): + +``` + set-goal ──► Goal (goal-state.md) ◄── goal-orchestrator (sole writer) + │ + ├─► observer × N ─► Observation(s) ─► [MergedObservations] + │ │ + │ ▼ + │ orienter ─► Orientation + │ │ + │ ▼ + │ decider ─► DecisionSet (+ Decisions) + │ │ + │ decide skill + │ │ + │ ▼ + │ HumanApproval (act gate) + │ │ + │ ▼ + │ actor × M ─► ActionLog(s) + │ │ + │ ▼ + │ loop-reviewer ─► Review + │ │ + │ ┌──────────────────────────────────────────┤ + │ ▼ ▼ + │ continue / amend close-met / close-abandon + │ │ │ + └────────────┘ ▼ + GoalState (closed) + ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ + Rolling, orchestrator-owned: Health section + health.md + Recurring goals: Brief; Closure: Lessons; Portfolio: Index +``` + +## The core types + +Documented in dependency order. Each entry follows the same shape: purpose, lives at, owned by, shape, transitions, relationships. + +### 1. Goal + +- **Purpose** — The contract for one loop. Declares intent, constraints, falsifiable acceptance criteria, mode, cadence, observe sources, and act-gate policy. Source of truth for every downstream artifact. +- **Lives at** — `goals//goal-state.md` (one file per goal; the same `` keys every artifact in the folder). +- **Owned by** — Body sections by [`set-goal`](../skills/set-goal/SKILL.md); frontmatter transitions, `## History`, and `## Health` by [`goal-orchestrator`](../agents/goal-orchestrator.md). Phase agents are read-only. +- **Shape** — See [the schema](../skills/_shared/goal-state.md) for the full contract; the template lives at [`templates/goal-state-template.md`](../templates/goal-state-template.md). Frontmatter holds the typed contract; body sections hold the human-facing narrative. +- **Transitions** — `draft` (created by `set-goal`) → `active` (goal gate cleared) → optionally `paused` / `blocked` ↔ `active` → terminal `done` (via `close-met`) or `cancelled` (via `close-abandon`). +- **Relationships** — Pointed at by every other type via `goal_slug`. Points at no other type by reference; it sits at the centre of the graph. + +### 2. GoalState + +- **Purpose** — The live state slice of a Goal: which phase the loop is in, which iteration, what has happened so far. Conceptually distinct from the Goal contract above (intent / constraints / acceptance) but co-located in the same file for atomicity. +- **Lives at** — Same file as Goal: `goals//goal-state.md`. The frontmatter fields `status`, `current_phase`, `iteration`, `updated_at`, `goal_signed_off`, `last_review`, plus the body `## History` and `## Health`, are the state slice. +- **Owned by** — [`goal-orchestrator`](../agents/goal-orchestrator.md) exclusively (the orchestrator writes; `set-goal` writes the *contract* slice and the creation-time `status: draft → active` transitions only). +- **Shape** — Tracked by `current_phase`, `iteration`, `status`, the append-only `## History` table, and the cap-counter snapshot in `## Health`. See [the schema §Ownership matrix](../skills/_shared/goal-state.md#ownership-matrix). +- **Transitions** — Driven by `goal-orchestrator` at every phase boundary. Phase transitions advance `current_phase` and refresh `## Health`. On a `continue` review verdict, the orchestrator sets `current_phase: observe` (and the **next Observe dispatch** owns the `iteration` bump per the canonical single-owner rule in [the schema](../skills/_shared/goal-state.md), not the closure step). Closure transitions set `status: done | cancelled` and `current_phase: closed`. +- **Relationships** — Points at the latest artifact per phase through `## History` rows. Points at the latest `reviews/*.md` through `last_review`. Pointed at by every other type as the anchor. + +### 3. Iteration + +- **Purpose** — One full pass through Observe → Orient → Decide → Act → Review for one Goal. The unit of work; the basis for every iteration-scoped artifact's namespacing. +- **Lives at** — Not a file. A value type: the integer in `iteration:` frontmatter on `goal-state.md`. Every iteration-scoped artifact's `iteration:` frontmatter mirrors it. +- **Owned by** — `goal-orchestrator` increments at every new Observe; `set-goal` writes the initial `iteration: 0`. +- **Shape** — Integer ≥ 0. `iteration: 0` is the scope-only state (post-goal-gate, pre-first-Observe). `iteration: 1` is the first executing iteration. +- **Transitions** — Increments on the `goal-orchestrator`'s transition from `review` (outcome `continue` or `amend`) back to `observe`. Bounded by `max_iterations` (default 25) — the time-spiral cap. +- **Relationships** — Every iteration-scoped artifact (Observation, Orientation, DecisionSet, ActionLog, Review) carries the iteration counter in its frontmatter. Iterations are not retained as a file — the audit trail is reconstructed by walking artifacts whose `iteration:` matches. + +### 4. Phase + +- **Purpose** — Which step of the loop is currently executing. Seven values total: four execution phases plus three boundary states. +- **Lives at** — Frontmatter field `current_phase:` on `goal-state.md`. The same value drives the orchestrator's `## History` row when a phase ends. +- **Owned by** — `goal-orchestrator` for all transitions except `scope`, which `set-goal` owns at creation time. +- **Shape** — Enum: `scope` | `observe` | `orient` | `decide` | `act` | `review` | `closed`. +- **Transitions** — `scope` (post-goal-gate) → `observe` (iteration 1 begins) → `orient` → `decide` → `act` → `review` → [back to `observe` on `continue` / `amend`; or to `closed` on `close-met` / `close-abandon`]. Skipping a phase requires explicit authorisation in the goal's policy (Article VI). +- **Relationships** — Drives subagent dispatch. Each execution-phase value maps 1:1 to a phase agent: `observe → observer`, `orient → orienter`, `decide → decider`, `act → actor`, `review → loop-reviewer`. The pseudo-phases (`scope`, `closed`) have no specialist subagent — `set-goal` owns `scope`, `goal-orchestrator` owns the transition to `closed`. + +### 5. Observation + +- **Purpose** — Raw signals captured from one declared observe source in one iteration. No interpretation, no recommendations — pure capture. +- **Lives at** — `goals//observations/--.md` (or `goals//observations/.md` when only one source ran). +- **Owned by** — [`observer`](../agents/observer.md). Parallel-capable: one observer instance per declared source when fan-out is on. +- **Shape** — Frontmatter (`goal_slug`, `iteration`, `observer_id`, `source_id`, `started_at`, `ended_at`) + body sections `## Source`, `## Signals` (one per line, quoted not paraphrased), `## Noise Excluded`, `## Anomalies`, `## Open Questions`. Template: [`templates/observation-template.md`](../templates/observation-template.md). +- **Transitions** — Written once per iteration per source. Never edited. Subsequent iterations produce new files; prior files remain as audit history. +- **Relationships** — Cites no other type. Cited by the iteration's Orientation (`## Signal Map`, `## What's New`), by Decisions (rationale chain), and by the Review (per-criterion evidence). One per row of `## Observe Sources` per iteration, when fan-out is on. + +### 6. MergedObservations + +- **Purpose** — A single deduped, source-attributed view across N parallel observers' outputs, so the orienter focuses on synthesis instead of bookkeeping. +- **Lives at** — `goals//observations/--_merged.md` (double-dash prefix; `_merged` literally). +- **Owned by** — [`signal-deduper`](../agents/signal-deduper.md) (consult-only agent, dispatched by the [`observe`](../skills/observe/SKILL.md) skill at fan-in when N ≥ 2 observers ran). +- **Shape** — Frontmatter (`goal_slug`, `iteration`, `sources_merged`, `dedup_at`) + body sections `## Merged Signals`, `## Unique Signals`, `## Cross-source conflicts`. The deduper preserves source attribution on every merged entry and never resolves conflicts. +- **Transitions** — Written once at fan-in. Per-source Observations remain unchanged as the audit record. +- **Relationships** — Reads every iteration-scoped Observation. Read by the Orientation in place of (or alongside) the per-source files. Not produced when only one source ran. + +### 7. Orientation + +- **Purpose** — Synthesis of all observations in one iteration against goal, history, and prior orientation. Every claim must cite an observation; speculation belongs in `## Open Questions` / `## Contradictions`. +- **Lives at** — `goals//orientation.md` (current); prior versions archived to `goals//archive/orientation-.md` before overwrite. +- **Owned by** — [`orienter`](../agents/orienter.md). Single writer. +- **Shape** — Frontmatter (`goal_slug`, `iteration`, `synthesised_at`) + body sections `## Summary`, `## What's New`, `## What's Blocked`, `## What's At Risk`, `## Signal Map` (per-criterion status table), `## Contradictions`, `## Recommended Areas For Decision`. Template: [`templates/orientation-template.md`](../templates/orientation-template.md). +- **Transitions** — Overwritten each iteration; history preserved in `archive/`. +- **Relationships** — Reads Observations (and MergedObservations when present) plus prior Orientation and latest Review. Cited by the DecisionSet (every decision's rationale anchors here). The `## Signal Map` mirrors the acceptance criteria of the parent Goal. + +### 8. DecisionSet + +- **Purpose** — One iteration's proposed actions, ranked with rationale, confidence, and reversibility. Appended to the running `decisions.md` log (append-only across iterations). +- **Lives at** — One block per iteration inside `goals//decisions.md`. +- **Owned by** — [`decider`](../agents/decider.md) writes everything except the `## Human Approval` sub-block; that section is owned by the [`decide`](../skills/decide/SKILL.md) skill (sole writer). +- **Shape** — Frontmatter (`goal_slug`, `iteration`, `proposed_at`) + body sections `## Decision Set` (summary table + per-action definition lists — the definition list is canonical), `## Recommendation`, `## Alternatives Considered`, `## Risks`, optional `## Risks surfaced (risk-scout)`, `## Verification`, `## Human Approval`. Template: [`templates/decision-template.md`](../templates/decision-template.md). +- **Transitions** — Appended once per iteration. Never rewritten. `## Human Approval` is filled by the `decide` skill when the act gate clears. +- **Relationships** — Reads Orientation (every decision's rationale cites it) plus prior DecisionSets, latest ActionLogs, latest Review. May incorporate a `risk-scout` consult. Contains one or more Decisions and exactly one HumanApproval. + +### 9. Decision + +- **Purpose** — One proposed action inside a DecisionSet. The unit of approval at the act gate. +- **Lives at** — A definition-list block inside the parent DecisionSet's `## Decision Set` section. Identified by its `` (e.g., `a-1`, `a-2`). +- **Owned by** — [`decider`](../agents/decider.md) (writes the definition-list block). +- **Shape** — Fields: `Action` (one line), `Rationale` (required), `Impact` (H/M/L), `Confidence` (H/M/L, required), `Cost` (H/M/L), `Reversible` (Y/N, required), `Dependencies`, `Gate` (auto/human). The summary table is for scanning; if it disagrees with the definition list, the definition list wins. +- **Transitions** — Written once. Approved, excluded, edited, or deferred at the act gate — the outcome is recorded in HumanApproval. Never mutated in place. +- **Relationships** — May have an ActionSpec and an ActionLog. Its `Reversible: N` value carries through to the ActionSpec's mandatory `## Rollback Plan` (Article V). + +### 10. HumanApproval + +- **Purpose** — The act-gate record: which Decisions in a DecisionSet the human approved, excluded, edited, or deferred. The actor reads this section to decide what to execute; the orchestrator reads it to record an act-gate `## History` row. +- **Lives at** — `## Human Approval` sub-block inside each DecisionSet in `goals//decisions.md`. +- **Owned by** — [`decide`](../skills/decide/SKILL.md) skill exclusively. Not the `decider` agent; not the `actor`; not the `goal-orchestrator`. (See [the schema §Related ownership](../skills/_shared/goal-state.md#related-ownership--decisionsmd--human-approval).) +- **Shape** — One of: "Approved as recommended" | "Approved with exclusions" | "Approved with edits" | "Rejected — rationale: …" | "Defer to next iteration". Plus `Approved action ids:` (canonical machine-readable list), `Excluded action ids:`, per-id edits, `Approver:`, `Approved at:` (ISO-8601). +- **Transitions** — Written once when the act gate clears. The actor parses the approved-id list; without it, Act refuses to dispatch. +- **Relationships** — Sub-block of one DecisionSet. Cited by every ActionLog (`Approval reference:`). Cited by the orchestrator's `## History` row recording the act-gate outcome. + +### 11. ActionSpec + +- **Purpose** — Pre-execution specification for one approved action. The actor follows it verbatim and records deviations in the corresponding ActionLog. Optional but recommended for any non-trivial or irreversible action. +- **Lives at** — `goals//actions/iter-/.spec.md` (or co-located with the ActionLog at adopter discretion). Namespaced under `iter-/` so recurring goals with repeating action ids do not overwrite prior-iteration specs. +- **Owned by** — Written verbatim from the approved Decision by the actor at dispatch (or by the `decide` skill when it scaffolds specs ahead of Act). +- **Shape** — Frontmatter (`goal_slug`, `iteration`, `action_id`, `reversible`) + body sections `## Goal Of Action`, `## Steps` (ordered, verb + object), `## Expected Outcome`, `## Rollback Plan` (required when `reversible: N`), `## Verification`. Template: [`templates/action-spec-template.md`](../templates/action-spec-template.md). +- **Transitions** — Written once per action. Never edited after Act starts — deviations land in the ActionLog instead. +- **Relationships** — One per approved Decision. Inputs to one ActionLog. Carries the `Rollback Plan` that Article V mandates for irreversible actions. + +### 12. ActionLog + +- **Purpose** — Execution record for one action: what was approved, what was done, what was skipped, what was verified, what evidence exists. One file per executed action. +- **Lives at** — `goals//actions/iter-/.md`. Namespaced under `iter-/` so recurring goals reusing `a-1`, `a-2`, … each cycle do not overwrite prior-iteration evidence (which would break `## History` row links and the trace/export immutability contract). +- **Owned by** — [`actor`](../agents/actor.md). Single writer per action. Parallel-capable: one actor per Decision when `parallel_act` is on. +- **Shape** — Frontmatter (`goal_slug`, `iteration`, `action_id`, `started_at`, `ended_at`, `status`) + body sections `## What Was Approved`, `## What Was Done`, `## What Was Skipped`, `## Verification Results`, `## Diff / Evidence`, `## Follow-ups`. Template: [`templates/action-log-template.md`](../templates/action-log-template.md). +- **Transitions** — Written once per action. `status:` is terminal at write time — one of `done` | `partial` | `stopped` | `blocked` | `failed`. +- **Relationships** — Cites the HumanApproval block as `Approval reference:`. Cites the ActionSpec when present. Cited by the iteration's Review as evidence per acceptance criterion. Counted into the lifetime `failed_acts` cap when `status: failed`. + +### 13. Review + +- **Purpose** — Closes one iteration. Compares outcomes to acceptance criteria criterion-by-criterion, picks exactly one of the four loop outcomes, and surfaces next-iteration handles (for `continue` / `amend`). +- **Lives at** — `goals//reviews/.md` (UTC, colon-free). +- **Owned by** — [`loop-reviewer`](../agents/loop-reviewer.md). Single writer. +- **Shape** — Frontmatter (`goal_slug`, `iteration`, `reviewed_at`, `outcome`) + body sections `## Acceptance Check` (per-criterion table: criterion / evidence / verdict), `## Outcome`, `## Rationale`, `## Next Steps`, `## Loop Hygiene` (one-line honest assessment of Observe coverage, Orient quality, Decide soundness, Act fidelity). Template: [`templates/review-template.md`](../templates/review-template.md). +- **Transitions** — Written once per iteration. Never revised; subsequent iterations produce new files. +- **Relationships** — Reads Goal (acceptance criteria), Orientation, latest DecisionSet (with HumanApproval), every ActionLog this iteration, prior Reviews (for follow-up tracking). Drives the orchestrator's next move via `outcome:`. The closing Review (`close-met` / `close-abandon`) is the basis for Lessons. + +### 14. Verdict + +- **Purpose** — The per-criterion judgement inside a Review. +- **Lives at** — Not a file. A cell value in the Review's `## Acceptance Check` table. +- **Owned by** — `loop-reviewer`. +- **Shape** — Enum: `met` | `partial` | `unmet` | `blocked`. A criterion without evidence is `unmet`, not `met` (Article X). +- **Transitions** — Per-iteration. A criterion can move `unmet` → `partial` → `met` across iterations; `blocked` indicates a dependency outside the loop's control. +- **Relationships** — One Verdict per acceptance criterion per Review. `close-met` requires every Verdict to be `met` (Article X §2). + +### 15. Outcome + +- **Purpose** — The loop-closure verdict, picked by `loop-reviewer` once per iteration. Drives the orchestrator's next move. +- **Lives at** — Frontmatter `outcome:` on the Review, plus the `## History` row for the closing-iteration transition. +- **Owned by** — `loop-reviewer` writes; `goal-orchestrator` consumes. +- **Shape** — Enum: `continue` | `close-met` | `close-abandon` | `amend`. Exhaustive and mutually exclusive — see [`skills/_shared/loop-pattern.md` §The four loop outcomes](../skills/_shared/loop-pattern.md). +- **Transitions** — Final once written. Drives one of four orchestrator actions: set `current_phase: observe` and re-enter Observe (`continue` — the next Observe dispatch owns the `iteration` bump per the schema, not this closure step); set `status: done` + `current_phase: closed` (`close-met`); set `status: cancelled` + `current_phase: closed` (`close-abandon`); route through `set-goal` in amend mode, then resume Observe with `current_phase: scope` (`amend` — iteration again bumped by Observe, not at amend time). +- **Relationships** — One per Review. Drives all GoalState terminal transitions. + +### 16. History + +- **Purpose** — Append-only audit log of every phase transition and loop-closure outcome for one Goal. The trace-loop reconstruction is anchored on it. +- **Lives at** — `## History` section in `goals//goal-state.md`. +- **Owned by** — [`goal-orchestrator`](../agents/goal-orchestrator.md) exclusively. Append-only — never rewritten. +- **Shape** — Markdown table with columns `iteration | phase | started_at | ended_at | outcome | artifact`. `outcome` is free text for in-iteration phases (e.g., `observations captured`); a fixed enum at closure (`continue` | `close-met` | `close-abandon` | `amend`); or a typed hard-stop value (`hard-stop-iterations` | `hard-stop-rejects` | `hard-stop-failed-acts`). +- **Transitions** — One row appended per phase transition. Never mutated — auditability depends on this. +- **Relationships** — Each row points at one artifact (Observation, Orientation, DecisionSet, ActionLog, Review). Walked by [`trace-loop`](../skills/trace-loop/SKILL.md) and [`export-trace`](../skills/export-trace/SKILL.md) to reconstruct an iteration's reasoning chain. + +### 17. Health + +- **Purpose** — Rolling observability for one Goal. Surfaces the three hard-stop counters and lifecycle trend so the orchestrator, the human, and external observability tooling all see the same picture. +- **Lives at** — Two surfaces, one type. `## Health` section in `goals//goal-state.md` is the **snapshot** (four lines: iteration count, consecutive rejects, lifetime failed acts, `Hard-stop status`). `goals//health.md` is the **rolling record** (snapshot + running counters + cap progress + last five phase durations + plain-English trend paragraph). Prior `health.md` rolls into `archive/health-.md` on overwrite. +- **Owned by** — `goal-orchestrator` exclusively, for both surfaces. Refreshed on every phase transition. +- **Shape** — Snapshot template: see `goal-state.md` §`## Health`. Rolling record template: [`templates/health-template.md`](../templates/health-template.md). +- **Transitions** — Overwritten on every phase transition. `Hard-stop status` enum: `healthy` (< 80%) | `approaching-cap` (≥ 80%) | `at-cap` (= 100%) | `over-cap-amend-pending` (after a `/goal:amend` raises a cap but before the next transition recomputes). +- **Relationships** — Computed from frontmatter caps + `## History` rows + walking the artifact tree. Read by `/goal:status` and external SRE / observability tooling (tail-able, scrape-able). Phase agents never read or write `health.md`. + +### 18. Brief + +- **Purpose** — Scannable summary of one iteration for recurring goals (e.g., daily brief). Designed to be read in under 60 seconds. +- **Lives at** — `goals//brief.md` (current); date-only archive form at `goals//archive/brief/.md` (Periodic Notes plugin convention). +- **Owned by** — `/goal:brief` command (rendered from the iteration's Orientation, DecisionSet, and ActionLogs). +- **Shape** — Frontmatter (`goal_slug`, `brief_date`, `iteration`) + body sections `## TL;DR` (three bullets max), `## What's New`, `## Recommended Today` (approved DecisionSet), `## Watching`, `## Optional Actions`. Template: [`templates/brief-template.md`](../templates/brief-template.md). +- **Transitions** — Overwritten each iteration; dated copy archived. Recurring goals only. +- **Relationships** — Reads Orientation, DecisionSet (approved-id list), ActionLogs. Consumed by humans, not the loop. + +### 19. Lessons + +- **Purpose** — Cross-iteration learning, captured at goal closure (or at a checkpoint on long-running goals). Read by future goal authors so the next loop of this kind starts smarter. +- **Lives at** — `goals//lessons.md`. +- **Owned by** — User (or `loop-reviewer` in extended mode; the human owns the final wording). +- **Shape** — Frontmatter (`title`, `goal_slug`, `iteration_count`, `closed_at`, `outcome`) + body sections `## What worked`, `## What did not work`, `## What we would change about the goal definition`, `## What we would change about the loop hygiene`, `## Carry-overs for next goal`. Template: [`templates/lessons-template.md`](../templates/lessons-template.md). +- **Transitions** — Filled at closure. May be revised post-closure by the human; not the loop. +- **Relationships** — Cites Reviews, Orientations, Decisions, ActionLogs. Pure feedforward — the loop does not consume it. + +### 20. Trace + +- **Purpose** — End-to-end reconstruction of the reasoning chain for one iteration: acceptance criterion → Review verdict → ActionLog evidence → approved Decision → Orientation claim → Observation signals. Transient by default. +- **Lives at** — Console output of [`trace-loop`](../skills/trace-loop/SKILL.md) (always). Optional file at `goals//traces/iter--.md` when the user opts in. JSON export at adopter-chosen path via [`export-trace`](../skills/export-trace/SKILL.md) (OpenTelemetry GenAI / Langfuse / raw formats). +- **Owned by** — `trace-loop` and `export-trace` skills. Read-only on every other artifact; never mutates state. +- **Shape** — Markdown chain per acceptance criterion, with `[gap]` markers where a chain link is missing. JSON export carries the OTel GenAI span structure for ingestion by Langfuse / Datadog / Helicone / Arize / Phoenix. +- **Transitions** — Generated on demand. Not part of the loop's state. +- **Relationships** — Reads `## History`, Goal acceptance criteria, every iteration-scoped artifact. Writes nothing unless explicitly persisted. + +### 21. GoalCard + ObserveSourceDatasheet + +- **Purpose** — One-page audit surfaces. The GoalCard is the elevator pitch: name, owner, approver, purpose, in-scope, out-of-scope, acceptance summary, known limitations, risks and mitigations, dependencies, reversibility profile, audit trail. The ObserveSourceDatasheet is the per-source provenance and reliability sheet read by the observer on every dispatch. +- **Lives at** — `goals//card.md` (one per goal); `goals//sources/.md` (one per declared `observe_source`). +- **Owned by** — `set-goal` in extended mode (creation); `/goal:amend` (refresh on amendment). +- **Shape** — GoalCard: [`templates/goal-card-template.md`](../templates/goal-card-template.md), inspired by Mitchell et al. (Model Cards, 2019). ObserveSourceDatasheet: [`templates/observe-source-datasheet-template.md`](../templates/observe-source-datasheet-template.md), inspired by Gebru et al. (Datasheets for Datasets, 2021). +- **Transitions** — Refreshed on amendment. Not mutated by the loop. +- **Relationships** — GoalCard summarises Goal; never duplicates it (contract wins on disagreement). Datasheet read by `observer` before every scan; declared row in Goal's `## Observe Sources` is the join key. + +### 22. SessionGoal + +- **Purpose** — Session-scoped intent keeping an agentic tool aligned on one sitting's outcome. Distinct from a Goal Loop iteration goal — no phases, no act gate, no `goals//` state folder. +- **Lives at** — `session-goals/.md` (one file per session goal). +- **Owned by** — [`create-goal`](../skills/create-goal/SKILL.md) skill (creation); [`activate-goal`](../skills/activate-goal/SKILL.md) skill (activation timestamps and `## Activation notes`). +- **Shape** — Frontmatter (`slug`, `intent`, `success_criterion`, `stop_condition`, `anti_goals`, `time_budget`, `reversibility`, `status`, `tool`) + body sections `## Intent`, `## Success criterion`, `## Stop condition`, `## Anti-goals`, `## Time budget`, `## Reversibility note`, `## Activation notes`. Template: [`templates/session-goal-template.md`](../templates/session-goal-template.md). +- **Transitions** — `draft` → `active` (on `/set-goal`) → `done` | `cancelled` (on `/set-goal --clear` or stop-condition met). Per-tool activation: native `/goal` stop-hook in Claude Code, `SESSION-GOAL.md` in Codex, `.cursor/rules/session-goal.mdc` in Cursor. +- **Relationships** — None to Goal. Lives in a separate root (`session-goals/` vs. `goals/`). See [`docs/session-goal-best-practices.md`](session-goal-best-practices.md). + +### 23. AmendmentRecord + +- **Purpose** — One proposal, one file, for any change to the constitution. Required by [`memory/constitution.md`](../memory/constitution.md) §Amendment process — the constitution may not be edited silently. +- **Lives at** — `goals//amendments/-amend-.md`. +- **Owned by** — Human proposer. +- **Shape** — Frontmatter (`title`, `article_touched`, `proposed_at`, `proposed_by`, `status`) + body sections `## Current text`, `## Proposed text`, `## Rationale`, `## Affected templates / agents / skills`, `## Version bump`, `## Human approval`. Template: [`templates/constitution-amendment-template.md`](../templates/constitution-amendment-template.md). +- **Transitions** — `proposed` → `accepted` | `rejected`. Acceptance requires the `## Human approval` block filled in. +- **Relationships** — Targets one constitution article. Lists affected templates / agents / skills so downstream drift can be checked. + +### 24. Index + +- **Purpose** — Project-level roster of every goal under `goals/`. Active and paused goals refresh in place; closed goals append immutable rows. +- **Lives at** — `goals/INDEX.md`. +- **Owned by** — `goal-orchestrator`. Refreshed on every state transition for non-terminal goals; appended on closure. +- **Shape** — Markdown table: `slug | status | intent (one-line) | mode | iteration | last_updated_at | outcome | folder`. Sorted by `last_updated_at` descending. Template: [`templates/goal-archive-template.md`](../templates/goal-archive-template.md). +- **Transitions** — Closed rows are immutable; active rows overwrite in place. Removing a goal folder requires removing its row in the same commit. +- **Relationships** — Surfaces every Goal in the project. Read by `/goal:list` and the conductor's resume-detection step ([`skills/_shared/loop-pattern.md` §Detect resume vs. fresh start](../skills/_shared/loop-pattern.md)). + +## The agents that operate on types + +Lifted from [`tool-matrix.md`](tool-matrix.md) and [the ownership matrix](../skills/_shared/goal-state.md#ownership-matrix). Nine agents total: one orchestrator, five phase, three consult. + +| Agent | Class | Writes | Reads | Tools | +|---|---|---|---|---| +| [`goal-orchestrator`](../agents/goal-orchestrator.md) | orchestrator | GoalState (`goal-state.md`), Health (`health.md`), History | Goal, latest artifact per phase, every iteration's artifacts at closure | Read, Grep, Edit, Write, AskUserQuestion | +| [`observer`](../agents/observer.md) | phase | Observation | Goal, prior Observations for same source, ObserveSourceDatasheet | Read, Grep, Write, Bash, WebFetch, WebSearch | +| [`orienter`](../agents/orienter.md) | phase | Orientation (archives prior) | Goal, all iteration Observations (or MergedObservations), prior Orientation, latest Review | Read, Edit, Write | +| [`decider`](../agents/decider.md) | phase | DecisionSet (append), Decisions within it | Goal, Orientation, prior DecisionSets, latest ActionLogs, latest Review | Read, Edit, Write | +| [`actor`](../agents/actor.md) | phase | ActionLog | Goal, DecisionSet (incl. HumanApproval), prior ActionLogs, Orientation | Read, Edit, Write, Bash | +| [`loop-reviewer`](../agents/loop-reviewer.md) | phase | Review | Goal, Orientation, latest DecisionSet, all iteration ActionLogs, prior Reviews | Read, Edit, Write, Grep | +| [`goal-critic`](../agents/goal-critic.md) | consult | — (console only) | drafted Goal, constitution, goal-orientation doc, method | Read, Grep | +| [`signal-deduper`](../agents/signal-deduper.md) | consult | MergedObservations | all per-source Observations this iteration, Goal | Read, Edit, Write, Grep | +| [`risk-scout`](../agents/risk-scout.md) | consult | — (console / transient) | Goal, Orientation, DecisionSet, Reviews, constitution, method | Read, Grep | + +## The skills that compose operations + +Thirteen skills. The conductors gate, dispatch, and persist; the phase skills wrap a single phase agent dispatch; the audit skills are read-only. + +| Skill | Inputs | Outputs | Side effects | +|---|---|---|---| +| [`goal-loop`](../skills/goal-loop/SKILL.md) | Goal slug (or fresh) | Iteration progression | Dispatches every phase skill in sequence; gates with user | +| [`set-goal`](../skills/set-goal/SKILL.md) | User intake (or amend mode) | Goal body sections + GoalCard + ObserveSourceDatasheets | Holds goal gate; clarity gate on each acceptance criterion | +| [`observe`](../skills/observe/SKILL.md) | Goal | Observation(s) + optional MergedObservations | Dispatches N observers in parallel; consults signal-deduper at fan-in | +| [`orient`](../skills/orient/SKILL.md) | Observations | Orientation | Archives prior Orientation | +| [`decide`](../skills/decide/SKILL.md) | Orientation | DecisionSet + HumanApproval | Sole writer of HumanApproval; optionally consults risk-scout | +| [`act`](../skills/act/SKILL.md) | DecisionSet + HumanApproval | ActionLog(s) | Dispatches M actors when `parallel_act` on; refuses without approval | +| [`review-loop`](../skills/review-loop/SKILL.md) | Goal, Orientation, DecisionSet, ActionLogs | Review (with Outcome) | Routes amend through set-goal; routes close to orchestrator | +| [`acceptance-criteria-helper`](../skills/acceptance-criteria-helper/SKILL.md) | One vague criterion | One EARS-shaped falsifiable criterion | Used by set-goal on clarity-gate failure | +| [`trace-loop`](../skills/trace-loop/SKILL.md) | Goal slug + iteration | Trace (console; optional file) | Read-only | +| [`export-trace`](../skills/export-trace/SKILL.md) | Goal slug + iteration (or `--all`) + format | JSON trace (OTel GenAI / Langfuse / raw) | Read-only | +| [`list-goals`](../skills/list-goals/SKILL.md) | (optional filter) | Index view | Read-only; portfolio scan | +| [`welcome`](../skills/welcome/SKILL.md) | Mode (tour / hello / docs) | Console walkthrough | First-time guided welcome | +| [`create-goal`](../skills/create-goal/SKILL.md) | User intent | SessionGoal | Writes `session-goals/.md` | +| [`activate-goal`](../skills/activate-goal/SKILL.md) | SessionGoal slug | Activation directive per tool | Native `/goal` (Claude Code), `SESSION-GOAL.md` (Codex), `.cursor/rules/session-goal.mdc` (Cursor) | + +## State transitions (the iteration as a function) + +One iteration is a deterministic transform on the Goal's file-system state: + +``` +iterate(Goal, OldGoalState, ObserveSources) -> NewGoalState x Observation* x [MergedObservations] x Orientation x DecisionSet x HumanApproval x ActionLog* x Review + +where: + Observation* = { Observation_i for i in 1..N(ObserveSources) when parallel_observe } + | { Observation_1 } when single-source + MergedObservations = signal_deduper(Observation*) when N >= 2; absent otherwise + Orientation = orienter(Goal, Observation* or MergedObservations, prior_Orientation, latest_Review) + DecisionSet = decider(Goal, Orientation, prior_DecisionSets, latest_ActionLogs, latest_Review) + HumanApproval = decide_skill_gate(DecisionSet) -- main-thread AskUserQuestion + ActionLog* = { actor(d, ActionSpec_d) for d in HumanApproval.approved_ids } + Review = loop_reviewer(Goal, Orientation, DecisionSet, HumanApproval, ActionLog*) + Outcome = Review.outcome in { continue, close-met, close-abandon, amend } + + NewGoalState = orchestrator_apply(OldGoalState, Outcome): + continue -> current_phase <- observe ; (iteration is bumped by the *next* Observe dispatch, not here — single-owner rule per schema) + close-met -> status <- done, current_phase <- closed + close-abandon -> status <- cancelled, current_phase <- closed + amend -> route through set-goal amend mode; then current_phase <- scope ; (iteration again bumped by Observe on resume, not at amend time) + +invariants refreshed each transition: + History.append(row) + Health.snapshot() -- inside goal-state.md + health.md.overwrite(prior -> archive/) +``` + +The conductor never does phase work itself. Each line of the transform is one specialist subagent dispatch, gated by the orchestrator and (where required) by the human. + +## Constraints + +The type-system invariants below are derived from the constitution. Every one of them is enforced at the file-system level by a single writer plus a verify check. + +- An **Observation cannot exist without a declared ObserveSource** — `source_id` must match a row in Goal's `## Observe Sources`. (Article I.) +- An **Orientation claim cannot exist without an Observation citation** — every bullet in `## Summary`, `## What's New`, `## What's Blocked`, `## What's At Risk` cites an `observations/.md` signal index. Unsourced claims belong in `## Open Questions` or `## Contradictions`. (Article IV.) +- A **Decision's `Reversible: N` requires an ActionSpec with a `## Rollback Plan`** — and the ActionLog cannot record `status: done` without referencing that rollback plan. (Article V.) +- **HumanApproval is the sole gate for irreversible actions** — `act_gate: low-risk-auto` covers reversible actions only; irreversible actions always require explicit approval regardless of policy. (Article III §2.) +- A **Review's `outcome: close-met` requires every per-criterion Verdict to be `met`** (or `not_applicable` where the criterion is conditional). Partial / unknown verdicts block closure. (Article X §2.) +- **GoalState transitions to `current_phase: closed` only via `close-met` or `close-abandon`** — recorded in `## History` and reflected in `status: done | cancelled`. No silent shutdowns. (Article X §1.) +- **History is append-only** — never rewrite a row. Auditability depends on it. (Article VIII.) +- **No agent edits another agent's artifacts** — phase isolation is enforced by the ownership matrix in [the schema](../skills/_shared/goal-state.md). Disagreements surface through the next phase, not by rewriting upstream output. (Article II.) +- **Goals change only through structured amendment** — ad-hoc redefinition mid-iteration is forbidden. The amend path re-runs the goal gate via `set-goal`. (Article I §4.) +- **GoalState cannot iterate past a 100% hard-stop cap** — `max_iterations` / `max_consecutive_rejects` / `max_failed_acts`. The orchestrator stops dispatching regardless of human preference; the only escape is `/goal:amend` (raise the cap, recorded) or `/goal:close close-abandon` (recorded rationale). (Article VI.) + +## Hard-stop caps (the three failure modes as types) + +Three pre-declared counters on the GoalState bound the loop's lifetime against the three canonical death-spiral shapes. Each cap is optional frontmatter on `goal-state.md`; defaults apply when omitted. The orchestrator recomputes counters at every phase transition and refreshes `## Health`. At 80% of any cap the orchestrator surfaces `AskUserQuestion` (continue with risk / amend / pause / close-abandon); at 100% the loop **must stop** until `/goal:amend` raises the cap or `/goal:close` records abandonment. + +| Cap | Default | Death-spiral shape | Counter source | +|---|---|---|---| +| `max_iterations` | 25 | **Time spiral** — the loop runs without converging | `iteration:` frontmatter | +| `max_consecutive_rejects` | 3 | **Decision spiral** — the decider keeps proposing acts the human keeps rejecting | Consecutive History rows with rejection outcome | +| `max_failed_acts` | 5 | **Act spiral** — actors keep `status: failed` | Lifetime count of ActionLogs with `status: failed` | + +The 100% gate is constitutional ([Article VI](../memory/constitution.md)). See [`docs/death-spirals.md`](death-spirals.md) for diagnostic shapes and [`method.md` §Hard-stop gates](method.md#hard-stop-gates) for the contract. + +## What this document is NOT + +- **Not a tutorial.** Use [`getting-started.md`](getting-started.md) or run `/goal:welcome`. +- **Not a reference.** Use [`method.md`](method.md) for the canonical method definition and [`skills/_shared/goal-state.md`](../skills/_shared/goal-state.md) for the schema. +- **Not a glossary.** Use [`glossary.md`](glossary.md) for term-by-term definitions. +- **Not an API spec.** There is no API — the loop runs against file-system state. + +## See also + +- [`method.md`](method.md) — canonical method definition (phases, agents, gates, state model). +- [`skills/_shared/goal-state.md`](../skills/_shared/goal-state.md) — schema and ownership matrix. +- [`skills/_shared/loop-pattern.md`](../skills/_shared/loop-pattern.md) — conductor rules and the four loop outcomes. +- [`glossary.md`](glossary.md) — quick definitions per term. +- [`tool-matrix.md`](tool-matrix.md) — per-agent tool list audit. +- [`non-negotiable-guarantees.md`](non-negotiable-guarantees.md) — the thirteen hard promises with article and file citations. +- [`death-spirals.md`](death-spirals.md) — diagnostic catalogue for the three hard-stop shapes. +- [`../memory/constitution.md`](../memory/constitution.md) — the ten articles every invariant derives from. diff --git a/plugin-v2/docs/examples/continuous-awareness.md b/plugin-v2/docs/examples/continuous-awareness.md new file mode 100644 index 000000000..ff7965838 --- /dev/null +++ b/plugin-v2/docs/examples/continuous-awareness.md @@ -0,0 +1,115 @@ +--- +title: "Example: Continuous Awareness Walkthrough" +description: End-to-end narrative of using the goal-loop plugin for the continuous-awareness pattern, applied to regulatory monitoring. +--- + +# Example — Continuous Awareness Walkthrough + +> A narrative walkthrough of the continuous-awareness pattern (see [`../usage-patterns.md`](../usage-patterns.md#5-continuous-awareness-perpetual)). The example is deliberately non-software: tracking regulatory changes in a single jurisdiction over an open-ended horizon. The same shape works for a competitive landscape, a market-signal beat, dependency health for a downstream consumer, or any "keep me oriented; do not act on my behalf" goal. + +A worked artifact set for this example lives under [`../../examples/continuous-awareness/`](../../examples/continuous-awareness/). + +The defining traits: recurring on a slow cadence (weekly), persistent orientation memory, and `act_gate: never` — the loop surfaces decisions but never executes them automatically. This is the **pure awareness** pattern. + +## Setup + +A compliance officer at a mid-sized firm starts the conversation with: + +> "I want to stay oriented on regulatory changes in jurisdiction Y. Each Monday morning, tell me what changed in the last week, what's on the calendar for the next four weeks, and what — if anything — I should escalate." + +The orchestrator calls the `set-goal` skill. The interview produces: + +- **Slug.** `jurisdiction-y-regulatory-monitor` +- **Intent.** "Keep me oriented on regulatory changes in jurisdiction Y so I know when a meaningful shift happens and what response — if any — to escalate internally." +- **Constraints.** No automated outbound communications. No filings, no subscriptions, no public commentary by the loop itself. The loop reads and reports; humans decide and act. Source scope is jurisdiction Y only — adjacent jurisdictions are not in scope. +- **Acceptance criteria.** This is a recurring goal with no terminal closure expected. Per-iteration criteria are recorded instead of a single goal-level acceptance set: + 1. Each working Monday, `brief.md` is fresh (timestamp within the last 7 days of generation) and at least one named "what's on the calendar" item is present. + 2. Every claim in the brief cites at least one underlying observation by file and signal index — no unsourced assertions. + 3. Items not yet decided on by the human roll forward into the next iteration's `watching` section so they are not silently dropped. +- **Mode.** `recurring`. +- **Cadence.** `weekly Monday` at 07:00 local, plus on-demand. +- **Stop condition.** The user marks the goal paused, cancelled, or amended; or the firm's regulated activity in jurisdiction Y ceases. +- **Observe sources.** Regulator's official rulemaking feed, the regulator's enforcement-actions feed, the jurisdiction's parliamentary committee calendar, two curated trade-press feeds tracking the sector, the prior week's brief. +- **Act gate.** `never` — the loop never executes a decision. Every proposed escalation is a human decision recorded in the brief; the loop only surfaces. +- **Escalation.** Head of compliance (the user's manager). + +The user signs `goal-state.md`. The orchestrator records the goal gate and schedules the first iteration for the upcoming Monday. + +## Iteration 1 (Week 1, Monday) + +### Observe + +The orchestrator dispatches three observers in parallel — one per active source family (the prior-brief observer is empty on iteration 1; one trade-press feed observer is folded into a single trade-press file for compactness): + +- `observations/2026-05-04T07-00-00--regulator-feed.md` — official rulemaking and enforcement actions published by the regulator in the last 7 days. Quotes 4 distinct items: 2 new draft rules opened for consultation, 1 enforcement-action notice against an industry peer, 1 procedural circular. +- `observations/2026-05-04T07-00-00--committee-calendar.md` — parliamentary committee agenda items in the next 4 weeks that touch sector-relevant statute. 3 items quoted with dates and committee names. +- `observations/2026-05-04T07-00-00--trade-press.md` — relevant articles from the two curated trade-press feeds in the last 7 days. 5 items quoted with publication date, outlet, and one-sentence summary. + +Each observation file lists signals only. No interpretation. The orchestrator notes the artifacts in `goal-state.md` and moves on. + +### Orient + +The `orienter` synthesises across the three observation files and writes `orientation.md`. The synthesis cites each signal by file and signal index. It highlights: + +- **What's new.** Two new draft rules opened for consultation, both with named close-dates inside the next 6 weeks; one of them (the "operational-resilience" draft) touches the firm's regulated activity directly. The enforcement-action notice against an industry peer is descriptive — no firm-side implication, but useful situational awareness. +- **What's on the calendar.** Three committee sessions, one on 2026-05-19 directly relevant to the firm's sector. +- **Watching.** The procedural circular and the trade-press items are noise-floor — recorded but not material this week. + +### Decide + +The `decider` proposes three items, each gated `human` since the act gate is `never`: + +| id | proposed escalation | rationale | impact | confidence | cost | reversible | gate | +|---|---|---|---|---|---|---|---| +| a-1 | Flag the "operational-resilience" draft rule to head of compliance with a one-paragraph summary; recommend a Yes/No decision on whether the firm submits a consultation response. | because the rule directly touches the firm's regulated activity (orientation §What's-new) and the consultation window is 6 weeks | H | H | L | Y | human-decide; never auto | +| a-2 | Add the 2026-05-19 committee session to the head of compliance's calendar as an "observe-and-report" item. | because the session covers sector-relevant statute (orientation §What's-on-the-calendar) | M | H | L | Y | human-decide; never auto | +| a-3 | Note the peer enforcement action in the firm's internal awareness log for the quarterly compliance review. | because the action is descriptive only but useful for the quarterly trend read (orientation §What's-new) | L | H | L | Y | human-decide; never auto | + +The decider recommends surfacing all three to the human; **the loop never decides on behalf of the human in this pattern**. The decision block is the act gate — the orchestrator stops and asks the user. + +### Render the brief + +For recurring goals, the orchestrator runs a brief-rendering step. `/goal:brief` reads `orientation.md`, the latest proposed decision set, and the most recent review, then renders `brief.md` directly using [`../../templates/brief-template.md`](../../templates/brief-template.md) — no phase agent is dispatched. The brief is the human's interface; the dated copy is archived to `archive/brief/2026-05-04.md`. + +### Act gate + +The user reads the brief at the start of the working week. They accept a-2 and a-3 (calendar add, awareness-log note); they defer a-1 to a conversation with the head of compliance during the week's standing 1:1. Because `act_gate: never`, the loop performs none of these — the human's "accept" is a decision to act personally, not authorisation for the loop. The user records their dispositions back in the brief's `## Decisions taken` block. + +### Review + +The `loop-reviewer` writes `reviews/2026-05-04T08-00-00.md`: + +- **Acceptance check.** + 1. Brief fresh within 7 days — **met**. + 2. Every claim cites an observation — **met** — orienter's signal-map column references signal indices. + 3. Unactioned items roll forward — **met** — a-1 is deferred; recorded in next week's `watching:` section. +- **Outcome.** `continue` — recurring goal, no close condition triggered. + +## Iteration 2 (Week 2, Monday) + +The orchestrator re-enters Observe the following Monday. The `prior-brief` observer now reads the previous week's `brief.md`; it reports which items were acted on (a-2 added to calendar, a-3 noted in log) and which rolled forward (a-1 still deferred). The orienter rolls a-1 into the current `watching:` section automatically. + +The cycle repeats every Monday. Each week's brief is short. Each is archived. The audit trail — orientation, decisions, reviews — survives in the working folders. The orientation is persistent across iterations; the orienter does not start from scratch each week but updates the running synthesis. + +## Why the loop fits awareness + +- **The act gate is `never`, and the constitution honours it.** The loop never sends a filing, never auto-subscribes, never posts external commentary. Article III's act-gate principle reads `never` literally; the orchestrator refuses to dispatch an actor for any decision. +- **The brief is the artefact.** Unlike incident triage (artefact = restored service) or release readiness (artefact = release record), continuous-awareness's deliverable is the brief itself. Closure is per-iteration freshness, not goal-level done-ness. +- **Memory is structural.** The `prior-brief` observer is the mechanism by which the loop avoids re-discovering the same items every week. Orientation is a *running synthesis*, not a per-iteration rebuild. +- **Domain neutrality is real.** The narrative is regulatory; the same shape works for a competitive landscape (swap regulator-feed for press releases), a dependency health monitor (swap for security advisory feeds), or a research-trend beat (swap for arXiv categories and conference programmes). Article VII ("Domain Neutrality") is load-bearing here. + +## What the user typed, in total, per week + +One or two prompts: + +1. The initial goal definition (week 1 only). +2. The weekly disposition recorded back into the brief — accept, defer, or escalate each surfaced item. Or zero if the loop runs on cron and the human just reads the brief. + +That is the point of the continuous-awareness pattern: the loop runs unattended; the human's job is to read the brief and decide what (if anything) to do. + +## Files referenced + +- [`../method.md`](../method.md) — the canonical loop definition. +- [`../usage-patterns.md`](../usage-patterns.md#5-continuous-awareness-perpetual) — pattern details. +- [`../../templates/brief-template.md`](../../templates/brief-template.md) — the brief template. +- [`../../examples/continuous-awareness/`](../../examples/continuous-awareness/) — the worked artifact set for this example. diff --git a/plugin-v2/docs/examples/daily-brief.md b/plugin-v2/docs/examples/daily-brief.md new file mode 100644 index 000000000..3a18d8e79 --- /dev/null +++ b/plugin-v2/docs/examples/daily-brief.md @@ -0,0 +1,137 @@ +--- +title: "Example: Daily Brief Walkthrough" +description: End-to-end narrative of using the goal-loop plugin for the recurring daily-brief pattern. +--- + +# Example — Daily Brief Walkthrough + +> A narrative walkthrough of the daily-brief pattern (see [`../usage-patterns.md`](../usage-patterns.md#2-daily-brief-recurring-awareness)). The example is generic: keeping a single person oriented across one mid-sized project. The same shape works across portfolios, beats, or markets. + +A worked artifact set for this example lives under [`../../examples/daily-brief/`](../../examples/daily-brief/). + +## Setup + +The user starts the conversation with: + +> "I want a daily brief on project Atlas. Each morning, tell me what changed since yesterday and what the top three things to look at today are." + +The orchestrator calls the `set-goal` skill. The interview produces: + +- **Slug.** `atlas-daily-brief` +- **Intent.** "Keep me oriented across project Atlas every morning so I know the day's top three actions." +- **Constraints.** No actions taken without the human approving; brief must be readable in under 60 seconds; no surveillance of private messages. +- **Acceptance criteria.** + 1. Each working morning, `brief.md` is fresh (timestamp within the last 24 hours). + 2. The brief lists at most three "recommended today" items, each tied to an observed change. + 3. Items not yet acted on roll forward in a "watching" section so they are not silently dropped. +- **Mode.** `recurring`. +- **Cadence.** `daily` at 07:30 local, plus on-demand. +- **Stop condition.** The user marks the goal paused or cancelled, or the project Atlas closes. +- **Observe sources.** + - `src-repo` — the Atlas repository activity (commits, PR list, open issues). + - `src-tracker` — the issue tracker filtered to project Atlas. + - `src-changelog` — the project's `CHANGELOG.md`. + - `src-prior-brief` — yesterday's brief, to track what rolled forward. +- **Act gate.** `always` — the brief proposes; the human acts. + +The user signs `goal-state.md`. The orchestrator records the goal gate and schedules the first iteration. + +## Iteration 1 (Day 1) + +### Observe + +The orchestrator dispatches four `observer`s in parallel, one per source: + +- `observations/2026-01-15T07-30-00--repo.md` — 14 new commits on `develop` since the prior scan; 3 PRs opened, 2 merged; the PR for the data-export feature has new review comments. +- `observations/2026-01-15T07-30-00--tracker.md` — 2 new bugs filed overnight (one tagged "critical"), 4 issues moved to "in review", no stale items beyond the watch threshold. +- `observations/2026-01-15T07-30-00--changelog.md` — one new entry added under "unreleased" for the data-export fix. +- `observations/2026-01-15T07-30-00--prior-brief.md` — "no prior brief" since this is the first iteration; full baseline mode. + +### Orient + +The `orienter` synthesises across the four files and writes `goals/atlas-daily-brief/orientation.md`. The synthesis cites each signal by file and signal index. It highlights: + +- **What's new.** The critical bug filed overnight; the merged data-export PR; the changelog growth. +- **What's at risk.** The data-export PR's new review comments are unresolved and the release is on Friday — criterion-style concern even though acceptance criteria here are about the brief itself. +- **Watching.** Three issues moved to "in review" but no reviewer assigned yet. + +### Decide + +The `decider` proposes a three-item set, sized to the brief's "max three" constraint: + +| id | action | rationale | impact | confidence | cost | reversible | gate | +|---|---|---|---|---|---|---|---| +| a-1 | Triage the critical bug filed overnight (`#1241`). | newest critical signal; orientation §What's-new | H | H | L | Y | human | +| a-2 | Resolve the data-export PR review comments. | release at risk; orientation §What's-at-risk | H | M | M | Y | human | +| a-3 | Assign reviewers to the three issues moved to "in review". | unblocks downstream work; orientation §Watching | M | H | L | Y | human | + +The brief is the human's decision tool, so every action is gated `human`. The decision block is appended to `decisions.md`. + +### Render the brief + +For recurring goals, the orchestrator runs a brief-rendering step. `/goal:brief` reads `orientation.md`, the latest approved decision set, and the most recent review, then renders `goals/atlas-daily-brief/brief.md` directly using [`../../templates/brief-template.md`](../../templates/brief-template.md) — no phase agent is dispatched: + +``` +# Brief — atlas-daily-brief / 2026-01-15 + +## TL;DR +- Critical bug overnight: `#1241`. Triage first. +- Data-export PR has unresolved review comments; release is Friday. +- Three in-review issues need reviewers; assign before the day fills up. + +## What's New +- 14 new commits on develop — see observations §repo signals 1–14 +- 2 new bugs filed overnight (1 critical) — see observations §tracker signal 2 +- Changelog: data-export entry added — see observations §changelog signal 1 + +## Recommended Today +| id | action | gate | status | +|---|---|---|---| +| a-1 | Triage critical bug #1241 | human | approved | +| a-2 | Resolve data-export PR review comments | human | approved | +| a-3 | Assign reviewers to 3 in-review issues | human | approved | + +## Watching +- Data-export release Friday — risk: review comments unresolved +- No assigned reviewer on three in-review issues +``` + +The brief is the human's interface. The dated copy is archived to `brief-2026-01-15.md` so history is preserved without overwriting the current `brief.md`. + +### Act gate + +The user reads the brief at the start of the working day. They mentally accept items a-1 and a-3, defer a-2 to the afternoon (they want time with the data-export author), and write nothing back in this case — the brief is advisory. + +If the goal had `act_gate: low-risk-auto`, the orchestrator could perform a-3 (assigning reviewers) automatically. Here it does not. + +### Review + +The `loop-reviewer` writes `reviews/2026-01-15T07-30-00.md`: + +- **Acceptance check.** + 1. Brief fresh within 24 hours — **met**. + 2. ≤ 3 "recommended today" items, each tied to an observed change — **met** — 3 items, each cites a signal. + 3. Unactioned items roll forward — **met** — the "watching" section captures the deferred and in-flight risks. +- **Outcome.** `continue` — recurring goal, no close condition triggered. + +## Iteration 2 (Day 2) + +The orchestrator re-enters Observe the next morning. The `src-prior-brief` observer now has yesterday's `brief.md` to read; it reports which items were acted on (a-1 closed, a-3 partially done, a-2 still open). The orienter rolls a-2 forward into today's `watching:` block automatically because the prior brief's recommendations did not all close. + +Each day's brief is short, citing only what changed and what to do. Each is archived; the current `brief.md` is the only mutable one. The audit trail — orientation, decisions, reviews — survives in the working folders. + +## What the user typed, in total, per day + +One or two prompts: + +1. The initial goal definition (day 1 only). +2. "Run today's brief" each morning — or zero if the orchestrator is on cron and renders the brief automatically. + +That is the point of the daily-brief pattern: the loop runs unattended; the human's job is to read the brief and act. + +## Files referenced + +- [`../method.md`](../method.md) — the canonical loop definition. +- [`../usage-patterns.md`](../usage-patterns.md#2-daily-brief-recurring-awareness) — pattern details. +- [`../../templates/brief-template.md`](../../templates/brief-template.md) — the brief template. +- [`../../examples/daily-brief/`](../../examples/daily-brief/) — the worked artifact set for this example. diff --git a/plugin-v2/docs/examples/incident-triage.md b/plugin-v2/docs/examples/incident-triage.md new file mode 100644 index 000000000..85ef44d7e --- /dev/null +++ b/plugin-v2/docs/examples/incident-triage.md @@ -0,0 +1,127 @@ +--- +title: "Example: Incident Triage Walkthrough" +description: Narrative of running the goal-loop plugin at compressed tempo to restore a degraded service. +--- + +# Example — Incident Triage Walkthrough + +> A narrative walkthrough of the incident-triage pattern (see [`../usage-patterns.md`](../usage-patterns.md#3-incident-triage-rapid-time-critical)). The example uses a generic checkout-error-rate degradation; the same flow works for an editorial pipeline outage, a billing-job stall, or any time-critical restoration. + +The defining traits: compressed tempo, multiple short iterations, and pre-authorised runbook actions. Pre-authorisation is set in the goal definition itself — it is not invented mid-incident. + +## Setup (T+0:00) + +An alert fires. The on-call engineer types: + +> "Checkout error rate is at 4% and rising. Open an incident-triage loop." + +The orchestrator runs `set-goal` with the user. The interview is fast — the user has done this before and uses the team's standing template: + +- **Slug.** `inc-2026-01-15-checkout` +- **Intent.** "Restore checkout error rate below 0.5 percent and confirm baseline for thirty consecutive minutes." +- **Constraints.** No schema changes, no destructive deletes, escalate to a human commander if error rate exceeds 10% or duration passes 45 minutes. +- **Acceptance criteria.** + 1. Checkout error rate < 0.5% for 30 consecutive minutes. + 2. Root cause identified and recorded (at least a working hypothesis). + 3. Follow-up issue filed with the actions to make the failure mode less likely. +- **Mode.** `recurring` until acceptance is met; cadence continuous (one iteration immediately follows the last). +- **Observe sources.** Metrics dashboard, alert stream, last 24h deploy history, checkout-service error logs, dependency status pages, war-room chat. +- **Act gate.** `low-risk-auto` for the team's pre-authorised runbook items (cache flush, restart pool member, increase rate-limit budget by ≤ 20%, force-refresh dependency token); `always` for anything else. +- **Escalation.** Human commander if criteria fire. + +The user signs `goal-state.md`. Goal gate cleared. + +## Iteration 1 (T+0:02 → T+0:08) + +### Observe (parallel, 4 observers) + +- `observations/2026-01-15T08-02-00--metrics.md` — error rate 4.1%, climbing 0.3%/min over the last 6 minutes; latency p95 unchanged. +- `observations/2026-01-15T08-02-00--deploys.md` — checkout service deployed 22 minutes before the alert; payment-gateway client deployed 5 hours earlier. +- `observations/2026-01-15T08-02-00--logs.md` — concentrated cluster of "401 from payment gateway" errors; token expiration timestamp in the dependency client matches the start of the climb. +- `observations/2026-01-15T08-02-00--deps.md` — payment gateway status page reports normal; their incident feed is quiet. + +### Orient (1 minute) + +The `orienter` synthesises: + +- **Summary.** Error pattern is concentrated on payment-gateway token expiry. The checkout deploy is recent but its diff did not touch auth code. The payment-gateway service itself reports healthy. +- **Signal map.** Criterion #2 — root cause hypothesis: stale token refresh after the checkout deploy invalidated the cached client. Confidence: medium. +- **Contradictions.** None. +- **Recommended areas for decision.** Force a token refresh (runbook item), and observe whether error rate falls. + +### Decide + +The `decider` proposes: + +| id | action | rationale | impact | confidence | cost | reversible | gate | +|---|---|---|---|---|---|---|---| +| a-1 | Force-refresh the payment gateway token across the checkout pool (runbook item R-014). | logs §signal 3 cluster matches token-expiry pattern | H | M | L | Y | auto (runbook) | +| a-2 | Open a watch on the metrics dashboard for the next 5 minutes; iterate. | confirms or refutes the hypothesis | H | H | L | Y | auto | + +a-1 is in the goal's pre-authorised runbook set, so its gate is `auto`. a-2 is observation, not action; trivially `auto`. No human approval needed for this iteration. + +### Act (T+0:06) + +The `actor` runs the runbook command. Action log captures the command, the exit code, the affected pool members, and the timestamp. + +### Review (T+0:08) + +The `loop-reviewer` reads observations + action log: + +- **Acceptance check.** + 1. < 0.5% for 30 min — **unmet** — too soon to tell. + 2. Root cause — **partial** — strong hypothesis, not confirmed. + 3. Follow-up issue — **unmet** — premature. +- **Outcome.** `continue` — re-enter Observe immediately. + +## Iteration 2 (T+0:08 → T+0:13) + +### Observe (lighter scan) + +Only metrics + logs this time — the orienter's prior synthesis already covered deploys and dependency status, and they have not changed. Two observers, narrower scope. + +- Metrics: error rate dropped to 0.3% within 90 seconds of the token refresh; holding steady for 5 minutes. +- Logs: no new "401 from payment gateway" entries since the refresh. + +### Orient + Decide + +Orientation upgrades the root-cause hypothesis to confirmed (criterion #2 → met). Decision set: "no action this iteration; continue observing for the 30-minute baseline." + +### Review + +Outcome `continue` — criterion #1 is on a clock. + +## Iteration 3 (T+0:37) + +Thirty minutes after the refresh. Observe scans metrics one more time; error rate has held below 0.5% for the full window. + +The decider proposes a final action set: + +| id | action | rationale | impact | confidence | cost | reversible | gate | +|---|---|---|---|---|---|---|---| +| a-1 | File follow-up issue describing the token-refresh failure mode and recommending a pre-deploy token check in checkout's deploy pipeline. | criterion #3 requires it; cause is now clear | H | H | L | Y | human | + +The user approves the follow-up filing. Actor writes the action log with the new issue URL. + +### Review + +- **Acceptance check.** + 1. < 0.5% for 30 min — **met**. + 2. Root cause — **met** — recorded in orientation and follow-up issue. + 3. Follow-up issue — **met** — see action log. +- **Outcome.** `close-met`. + +The orchestrator sets `goal-state.md` to `status: done` and archives the working files. Total elapsed time: 37 minutes. + +## Why the loop fits incident work + +- **Tempo is configurable.** Cadence "continuous until close" means iteration 2 starts the moment iteration 1's review writes `continue`. There is no idle gap. +- **Pre-authorisation is explicit, not invented.** The team's runbook items are codified in the goal's `act_gate` policy before the incident. No one is making "is this OK to do?" judgments mid-incident. +- **Audit survives.** Every observation, every decision, every executed runbook command, and every review is in the working folder. The post-incident report writes itself from the artifacts. +- **Escalation is a constraint, not a wish.** The 10% error-rate ceiling and the 45-minute clock are constraints in `goal-state.md`. If the loop crosses either, the orchestrator blocks and pages the human commander. + +## Files referenced + +- [`../method.md`](../method.md) — the canonical loop definition. +- [`../usage-patterns.md`](../usage-patterns.md#3-incident-triage-rapid-time-critical) — pattern details. +- [`../customizing.md`](../customizing.md#custom-act-gate-policies) — encoding runbook items in the act-gate policy. diff --git a/plugin-v2/docs/examples/issue-resolution.md b/plugin-v2/docs/examples/issue-resolution.md new file mode 100644 index 000000000..455fc4bff --- /dev/null +++ b/plugin-v2/docs/examples/issue-resolution.md @@ -0,0 +1,119 @@ +--- +title: "Example: Issue Resolution Walkthrough" +description: End-to-end narrative of using the goal-loop plugin to resolve a scoped issue in a single iteration. +--- + +# Example — Issue Resolution Walkthrough + +> A narrative walkthrough of the issue-resolution pattern (see [`../usage-patterns.md`](../usage-patterns.md#1-issue-resolution-one-shot-bounded)). The example is intentionally generic: a wiki redirects breakage. Software framing is illustrative, not required — the same flow works for a contract-clause review or a marketing-copy error. + +The narrative follows the user's prompts, the orchestrator's gating, and the artifacts each phase agent writes. A worked artifact set for this example lives under [`../../examples/issue-resolution/`](../../examples/issue-resolution/). + +## Setup + +The user opens the plugin in a project and types: + +> "Let's run a goal loop. The wiki redirects for legacy URLs are broken — all `/old/...` paths return 404 instead of pointing at the new slugs. I want to fix it." + +The orchestrator calls the `set-goal` skill, which interviews the user for intent, constraints, acceptance criteria, mode, and observe sources. The interview produces: + +- **Slug.** `wiki-redirect-fix` +- **Intent.** "Resolve the wiki-redirect breakage so legacy URLs land on the new article slugs without 404s." +- **Constraints.** No changes to article content; redirect mapping changes only; complete within one working day. +- **Acceptance criteria.** + 1. Every legacy URL listed in `legacy-urls.txt` returns a 301 to a working article slug. + 2. No `/old/...` URL returns a 404 in a fresh crawl. + 3. The redirect map change is reviewed and merged. +- **Mode.** `one-shot`, no cadence. +- **Observe sources.** The wiki repo's `redirects.yaml`, the `legacy-urls.txt` inventory, the production crawl log from the last week, the issue thread. +- **Act gate.** `always` — every change ships through a PR for review. + +The user signs off on `goal-state.md`. The orchestrator records the **goal gate** as cleared and recommends `/goal:observe`. + +## Iteration 1 + +### Observe + +The orchestrator dispatches one `observer` per source (four in parallel, since the goal allows fan-out — `parallel_observe` defaults to `true` when more than one source is declared, per [the schema](../../skills/_shared/goal-state.md#optional-frontmatter); set it to `false` if you want strictly sequential observers). Each observer writes a file under `goals/wiki-redirect-fix/observations/`: + +- `2026-01-15T09-00-00--redirects-yaml.md` — raw current redirect entries, sorted; flags entries with missing targets. +- `2026-01-15T09-00-00--legacy-urls.md` — full inventory list, 312 entries; marks which appear in the current redirect map. +- `2026-01-15T09-00-00--crawl-log.md` — quotes 41 distinct `/old/...` paths that returned 404 in the past week, with timestamps. +- `2026-01-15T09-00-00--issue-thread.md` — quotes the original reporter's two URLs, the maintainer's hypothesis ("we shipped the slug rename without regenerating the map"), and the follow-up confirmation request. + +Each observation file lists signals only — quotes, paths, counts. No interpretation. The orchestrator notes the artifacts in `goal-state.md` iteration log and moves on. + +### Orient + +The orchestrator dispatches one `orienter`. It reads the four observation files and writes `goals/wiki-redirect-fix/orientation.md`. The synthesis includes: + +- **Summary.** Of the 312 legacy URLs, 271 are mapped correctly, 38 are mapped to slugs that no longer exist (mapping rot from a prior rename), and 3 are unmapped entirely. The 41 unique 404s observed in the crawl all fall in the 38 + 3 set. +- **Signal map.** + 1. Every legacy URL → 301 to working slug — **partial** — 271 / 312 verified. + 2. No `/old/...` 404 in fresh crawl — **unmet** — 41 distinct 404s observed. + 3. Redirect map change reviewed and merged — **unknown** — no PR yet. +- **Contradictions.** None. +- **Recommended areas for decision.** Closing the 38 broken-target mappings and the 3 unmapped URLs. + +The orchestrator updates `goal-state.md` and moves on. + +### Decide + +The `decider` reads orientation, prior decisions (none), and the goal. It writes a decision block appended to `goals/wiki-redirect-fix/decisions.md`: + +| id | action | rationale | impact | confidence | cost | reversible | gate | +|---|---|---|---|---|---|---|---| +| a-1 | Regenerate redirect targets for the 38 mapped-but-broken entries by running `tools/refresh-redirects` against `legacy-urls.txt` and writing the new targets into `redirects.yaml`. | because orientation §Signal-Map #2 shows 38 targets stale; refresh-tool already exists | H | H | L | Y (local edit) | human | +| a-2 | Add the 3 unmapped URLs to `redirects.yaml` with targets chosen from `legacy-urls.txt` notes. | because orientation flags 3 unmapped entries; the notes name the canonical replacement slug | H | M | L | Y | human | +| a-3 | Open a PR with the updated `redirects.yaml`, link the issue, request a maintainer review. | because criterion #3 requires merge; the PR is the gate | H | H | L | Y (until merge) | human | + +The decider recommends approving all three as a set; they are independent enough that the user could approve a subset. The block is the **act gate** — the orchestrator stops and asks the user. + +### Act gate + +The user reviews `decisions.md`. They approve a-1, a-2, and a-3 unchanged. The orchestrator records the approval against the decision-set id in `goal-state.md` and dispatches the `actor`. + +### Act + +Three actors run, one per action, in parallel: + +- `goals/wiki-redirect-fix/actions/iter-1/a-1.md` — runs `tools/refresh-redirects`, captures the diff (38 entries updated), records the command output. +- `goals/wiki-redirect-fix/actions/iter-1/a-2.md` — edits `redirects.yaml` to add the 3 entries, captures the diff and the source notes that justified each chosen target. +- `goals/wiki-redirect-fix/actions/iter-1/a-3.md` — opens the PR via the host's PR tool, captures the URL and the request-for-review acknowledgement. + +Each action file copies the approved action verbatim, lists the executed steps with timestamps, links the produced artifacts, and sets `status: done`. No actor expands scope; each stays inside its assigned action. + +### Review + +The `loop-reviewer` reads all artifacts and writes `goals/wiki-redirect-fix/reviews/2026-01-15T11-30-00.md`: + +- **Acceptance check.** + 1. 312 / 312 legacy URLs → 301 to working slug — **met** — see a-1 diff, a-2 diff. + 2. No `/old/...` 404 in fresh crawl — **met** — re-crawl on staging shows 0 of 41 prior 404 URLs still failing. + 3. Redirect map change reviewed and merged — **partial** — PR open, awaiting maintainer. +- **Outcome.** `continue` — criterion #3 not yet met; one short follow-up iteration expected. +- **Next steps.** Re-observe the PR's state after the maintainer review; no other source needs re-scan. + +## Iteration 2 + +The orchestrator re-enters Observe with a single source (the PR). The observer captures the merged status; the orienter records criterion #3 as met; the decider proposes "no action this iteration"; the reviewer writes `outcome: close-met`. + +The orchestrator sets `goal-state.md` to `status: done` and archives the working artifacts. The loop is closed. + +## What the user typed, in total + +Five prompts: + +1. The initial goal statement. +2. Sign-off on `goal-state.md` (the goal gate). +3. "Run the next phase" after each agent completes (or a single "drive the full iteration" at the start; the orchestrator gates at the act step regardless). +4. Approval of the decision set (the act gate). +5. Confirmation that the merged PR closes the loop (the close-met gate is implicit in the review's `outcome` once the maintainer's merge is observed). + +Everything else — the four observations, the orientation, the ranked decisions, the three action logs, the two reviews — was produced by the subagents. The user reviewed; the loop did the work. + +## Files referenced + +- [`../method.md`](../method.md) — the canonical loop definition. +- [`../usage-patterns.md`](../usage-patterns.md) — picking the right pattern. +- [`../../examples/issue-resolution/`](../../examples/issue-resolution/) — the worked artifact set for this example. diff --git a/plugin-v2/docs/examples/policy-consultation.md b/plugin-v2/docs/examples/policy-consultation.md new file mode 100644 index 000000000..21c5d5937 --- /dev/null +++ b/plugin-v2/docs/examples/policy-consultation.md @@ -0,0 +1,135 @@ +--- +title: "Example — Policy consultation (non-software)" +description: Worked walkthrough of one Goal Loop iteration on a public-policy consultation. Shows how the same loop drives non-software work. +folder: plugin-v2/docs/examples +entry_point: false +--- + +# Example — Policy Consultation Walkthrough + +> A narrative walkthrough of the Goal Loop driving a **non-software** outcome: a public-policy team synthesising stakeholder feedback into a defensible draft revision. The loop, the gates, the artifacts, and the subagent roles are identical to the [issue-resolution walkthrough](issue-resolution.md). Only the domain changes. + +The example is deliberately free of software vocabulary — no repositories, no tests, no deploys. The participants are policy officers, a regulator, members of the public, and a head of policy. Their artifacts are submissions, draft sections, rebuttals, and a record of decision. A worked artifact set lives under [`../../examples/policy-review/`](../../examples/policy-review/). + +## Setup + +A senior policy officer opens the plugin in the team's working folder and types: + +> "We have to turn the v3 consultation feedback into a v4 draft in four weeks. Run a goal loop for it." + +The orchestrator invokes the `set-goal` skill, which interviews the officer for intent, constraints, acceptance criteria, mode, and observe sources. The interview produces: + +- **Slug.** `policy-review` +- **Intent.** "Synthesise stakeholder feedback on the v3 draft into a defensible v4 revision within 4 weeks." +- **Constraints.** Statutory consultation window already closed — no new submissions accepted; the head of policy must personally sign off the v4 draft; the regulator's named objections must be addressed in writing; the final 1-week comment circulation is non-negotiable. +- **Acceptance criteria.** + 1. Every public submission that arrived before the deadline is logged, categorised, and linked to a body-section change in the v4 draft (or to a rejected-with-rationale record). + 2. Every objection from the named regulator is either accepted into v4 or rebutted in writing, with the rebuttal logged in `record-of-decision.md`. + 3. v4 draft is signed off by the head of policy and circulated for a final 1-week comment window by the deadline. +- **Mode.** `one-shot`, no cadence. +- **Observe sources.** + - `src-inbox` — the consultation inbox (`type: inbox`). + - `src-v3-draft` — the v3 draft document under review (`type: document`). + - `src-qa-log` — the stakeholder Q&A log from public sessions (`type: archive`). + - `src-regulator-letter` — the regulator's response letter (`type: record`). +- **Act gate.** `always` — every change to v4 is human-approved. No auto-approval, even for editorial fixes. + +The head of policy reviews `goal-state.md` and signs off. The orchestrator records the **goal gate** as cleared and recommends `/goal:observe`. + +## Iteration 1 + +### Observe + +The orchestrator dispatches one `observer` per source — four observers in parallel, since the goal allows fan-out. Each writes a file under `goals/policy-review/observations/`: + +- `2026-04-22T08-30-00--inbox.md` — quotes every submission received before the deadline. Each entry: sender, ISO timestamp, one-sentence position summary, and a verbatim pull-quote of the key claim. Tally: 47 submissions, of which 12 represent industry, 19 community groups, 14 individual citizens, and 2 academic responses. +- `2026-04-22T08-30-00--v3-draft.md` — section-by-section index of the v3 draft. Records section IDs (e.g. `§4.2`), one-line summary per section, and a flag where the section explicitly invited public comment. +- `2026-04-22T08-30-00--qa-log.md` — quotes the questions raised at the three public Q&A sessions, with the policy team's on-the-day responses. Marks where commitments were made to "consider in v4". +- `2026-04-22T08-30-00--regulator-letter.md` — quotes the regulator's letter section by section. The letter raises 6 named objections, numbered R-1 through R-6, each with a paragraph of rationale. + +Each observation file lists raw signals only — quotes, counts, identifiers. No interpretation. The orchestrator records each artifact in `goal-state.md`'s iteration log and moves to Orient. + +The user sees: four files written, a one-line summary per source, and a prompt to proceed. + +### Orient + +The orchestrator dispatches one `orienter`. It reads the four observation files and writes `goals/policy-review/orientation.md`. The synthesis includes: + +- **Summary.** Of the 47 public submissions, 41 cluster into 5 thematic concerns (cost burden, definitional scope of "small operator", transition timeline, enforcement mechanism, appeals process). 6 are off-topic or duplicates. The regulator's 6 objections map onto the same themes — R-1 and R-2 to scope, R-3 to transition, R-4 and R-5 to enforcement, R-6 to appeals. The Q&A log shows the team has already verbally committed to "revisit scope and transition timeline in v4", which carries reputational risk if v4 contradicts those commitments. +- **Signal map against acceptance criteria.** + 1. Every submission logged and linked to a v4 change — **partial** — 47 submissions logged in observations; none yet linked to v4 changes because v4 does not exist yet. + 2. Every regulator objection accepted or rebutted — **unmet** — 0 of 6 addressed. + 3. Head-of-policy sign-off and 1-week circulation by deadline — **unknown** — depends on v4 production. +- **Contradictions.** One: a submission from Industry Group B (inbox §17) argues against the same scope expansion that Community Coalition C (inbox §29) argues for. The contradiction must be resolved in v4 with an explicit rationale. +- **Open questions.** None of the public submissions explicitly addressed the appeals process, yet R-6 (regulator) flags it as a gap. Is the gap a v3 oversight or a v4 deferral? +- **Recommended areas for decision.** Produce a categorised submissions register, produce point-by-point rebuttals/acceptances for the 6 regulator objections, draft the v4 sections most affected (§4 scope, §6 transition, §8 enforcement, §9 appeals), then circulate. + +The orchestrator updates `goal-state.md` to `current_phase: decide` and dispatches the `decider`. + +### Decide + +The `decider` reads orientation, prior decisions (none), and the goal. It writes a decision-set block appended to `goals/policy-review/decisions.md` containing four ranked proposals: + +1. **d-1** — Build the submissions register: one row per submission, linking each to one of the 5 themes and to a target v4 section. +2. **d-2** — Draft rebuttals/acceptances for the 6 regulator objections in `record-of-decision.md`, one paragraph each. +3. **d-3** — Draft v4 §4, §6, §8, and §9 with the changes implied by the register and the regulator response. +4. **d-4** — Circulate v4 draft + supporting register + record of decision to the head of policy for sign-off, then open the 1-week comment window. + +Each row carries `impact`, `confidence`, `cost`, `reversible`, `dependencies`, and `gate`. All four are gated as `human` because the act-gate policy is `always`. The decider recommends approving d-1 and d-2 immediately (foundational work) and deferring d-3 and d-4 to a follow-up iteration once the foundations exist. + +The block is the **act gate** — the orchestrator stops and asks the head of policy. + +### Act gate + +The head of policy reads `decisions.md`. They approve d-1 and d-2 unchanged, defer d-3 and d-4 to iteration 2, and add one explicit edit: the rebuttal to R-6 (appeals) must reference the Q&A log's silence as evidence that the appeals process was insufficiently consulted on, and propose a supplementary mini-consultation. + +The orchestrator records the approval against the decision-set id in `goal-state.md`, captures the head-of-policy edit on R-6, and dispatches the `actor`. + +### Act + +Two actors run, one per approved action: + +- `goals/policy-review/actions/iter-1/d-1.md` — produces `submissions-register.md` with 47 rows, each carrying source observation index, theme tag, target v4 section, and a one-line disposition. Records the methodology used to cluster (manual review against the 5 themes named in orientation). Lists the 6 off-topic submissions separately with a one-line "out of scope" rationale. +- `goals/policy-review/actions/iter-1/d-2.md` — produces `record-of-decision.md` with 6 sections, one per regulator objection. Each section quotes the objection verbatim, states the disposition (`accept` / `partially-accept` / `rebut`), and gives the rationale. R-6 includes the head-of-policy's mini-consultation proposal. + +Each action file copies the approved action verbatim, lists executed steps with timestamps, links the produced artifacts, and sets `status: done`. The actor on d-2 explicitly notes the head-of-policy edit on R-6 in the action log's "Approved edits applied" section. + +The user sees: two completed action files, two new artifact files (`submissions-register.md`, `record-of-decision.md`), and a prompt to review. + +### Review + +The `loop-reviewer` reads all iteration-1 artifacts and writes `goals/policy-review/reviews/2026-04-22T10-00-00.md`: + +- **Acceptance check.** + 1. Every submission logged and linked to a v4 change — **partial** — all 47 logged and categorised; not yet linked to v4 changes (v4 does not yet exist). + 2. Every regulator objection accepted or rebutted in writing — **partial** — 6 of 6 dispositions drafted in `record-of-decision.md`; head-of-policy edit applied; final sign-off pending. + 3. Head-of-policy sign-off + 1-week circulation — **unmet** — v4 not drafted yet. +- **Outcome.** `continue` — foundations laid; iteration 2 produces the v4 draft and the final circulation. +- **Next steps.** Re-observe only the freshly-produced register and record of decision (the public inbox is closed; the v3 draft is stable). Decide d-3 and d-4 in iteration 2. + +The orchestrator updates `goal-state.md` to `current_phase: observe`, increments `iteration` to 2, and pauses for the user. + +## What the user typed, in total + +Across the four-week loop, the head of policy and the senior officer between them typed roughly seven prompts: + +1. The initial goal statement. +2. Sign-off on `goal-state.md` (the goal gate). +3. "Run the next phase" or "drive the full iteration" — the orchestrator gates at Act regardless. +4. Approval of the iteration-1 decision set, with one explicit edit on R-6 (the act gate). +5. Approval of the iteration-2 decision set covering d-3 and d-4. +6. Confirmation that the v4 draft circulation completed by the deadline (the close-met gate is implicit in iteration 2's review). +7. Sign-off on closure. + +Everything else — the submissions register, the record of decision, the v4 section drafts, the reviews — was produced by subagents. The humans reviewed, edited at gates, and signed off. + +## Why this example matters + +The Goal Loop is **domain-agnostic**. The same five phase agents (`observer`, `orienter`, `decider`, `actor`, `loop-reviewer`), the same two human gates (goal, act), the same `goals//` state layout, and the same review verdicts drive a public-policy consultation as drive a wiki redirect fix. No software vocabulary is needed. If your work has signals to gather, an outcome to drive toward, and irreversible steps that need human approval, the loop fits. + +## Files referenced + +- [`../method.md`](../method.md) — the canonical loop definition. +- [`../usage-patterns.md`](../usage-patterns.md) — picking the right pattern. +- [`issue-resolution.md`](issue-resolution.md) — the software-domain twin of this walkthrough. +- [`../../examples/policy-review/`](../../examples/policy-review/) — the worked artifact set for this example. diff --git a/plugin-v2/docs/examples/release-readiness.md b/plugin-v2/docs/examples/release-readiness.md new file mode 100644 index 000000000..6ae457238 --- /dev/null +++ b/plugin-v2/docs/examples/release-readiness.md @@ -0,0 +1,126 @@ +--- +title: "Example: Release Readiness Walkthrough" +description: End-to-end narrative of using the goal-loop plugin for the release-readiness checklist pattern. +--- + +# Example — Release Readiness Walkthrough + +> A narrative walkthrough of the release-readiness pattern (see [`../usage-patterns.md`](../usage-patterns.md#4-release-readiness-checklist-gated)). The example is intentionally generic: confirming v1.4.0 of an unspecified product is ready to publish. Software framing is illustrative — the same flow works for a policy publication, a journal-issue lock, or any "we are about to publish; is every precondition green?" decision. + +A worked artifact set for this example lives under [`../../examples/release-readiness/`](../../examples/release-readiness/). + +## Setup + +The user starts the conversation with: + +> "We are scheduled to ship v1.4.0 on Friday. I want a goal loop that confirms every precondition is green before we cut the release." + +The orchestrator calls the `set-goal` skill. The interview produces: + +- **Slug.** `release-v1-4-readiness` +- **Intent.** "Confirm v1.4.0 is ready to publish — tests green, changelog complete, sign-offs collected, rollback documented." +- **Constraints.** Release date is fixed at Friday 2026-03-13. Tests must be green on the release branch. Every changelog entry must trace to a merged PR. Two named sign-offs are required: engineering lead and product lead. A rollback runbook entry must exist for this version. +- **Acceptance criteria.** + 1. CI is green on the release branch `release/v1.4.0`, with all required jobs passing, captured as a frozen status link. + 2. `CHANGELOG.md` has a complete `## v1.4.0` section, every entry tied to a merged PR id, and the unreleased section is empty for items now in scope of v1.4.0. + 3. Sign-offs are recorded for engineering lead and product lead in the release record, with timestamps and attribution. + 4. Rollback runbook entry `R-v1.4.0` exists and names the operator, the rollback target, and the verification command. +- **Mode.** `one-shot`. The loop runs once when invoked and closes when every checklist item is green (or when the release is explicitly abandoned). +- **Cadence.** `null` — triggered on demand. +- **Observe sources.** CI status feed, repo status (open PRs, branch protections, version tags), `CHANGELOG.md`, sign-off ledger, draft release notes. +- **Act gate.** `always` — the release itself is irreversible; every intermediate change ships through human approval. +- **Escalation.** Release captain (the engineering lead in their secondary role). + +The user signs `goal-state.md`. The orchestrator records the goal gate and recommends `/goal:observe`. + +## Iteration 1 + +### Observe + +The orchestrator dispatches three observers in parallel (release-readiness loops are I/O-light; three observers cover the scope): + +- `observations/2026-03-12T09-00-00--ci-status.md` — CI pipeline state on `release/v1.4.0`: 17 required jobs, 16 green, 1 amber (the `cross-platform-integration` job is flaky and has retried twice). +- `observations/2026-03-12T09-00-00--changelog.md` — `CHANGELOG.md` state: `## v1.4.0` section exists with 11 entries; 2 entries lack a trailing PR id; the `## Unreleased` section still lists 3 items that are merged into the release branch. +- `observations/2026-03-12T09-00-00--open-issues.md` — repo status: 4 PRs open against `release/v1.4.0`, of which 2 are labelled `release-blocker`, 2 are `nice-to-have`; release captain has not posted a sign-off and product-lead has not been pinged yet; rollback runbook `R-v1.4.0` is missing — the closest entry is `R-v1.3.x` from last quarter. + +Each observation file lists signals only. No interpretation. The orchestrator notes the artifacts in `goal-state.md` and moves on. + +### Orient + +The `orienter` synthesises across the three observation files and writes `orientation.md`. The synthesis includes: + +- **Summary.** The release branch is mostly ready: 16-of-17 CI jobs are green, 11 changelog entries land in v1.4.0 with 2 needing PR id back-fill, 2 release-blocker PRs remain open, 0 sign-offs collected, rollback runbook missing. +- **Signal map.** + 1. CI green — **partial** — 16/17 jobs green; the amber job is the known flaky `cross-platform-integration` test. + 2. Changelog complete — **partial** — 2 entries missing PR ids; 3 items still in `## Unreleased` that belong in v1.4.0. + 3. Sign-offs collected — **unmet** — 0/2 sign-offs recorded. + 4. Rollback runbook — **unmet** — `R-v1.4.0` does not exist. +- **What's at risk.** The 2 release-blocker PRs (`#1287` and `#1291`) sit on the critical path; if they are not merged or explicitly deferred today, the Friday date slips. +- **Contradictions.** None. +- **Recommended areas for decision.** Resolve the flaky CI job; back-fill the 2 changelog PR ids and prune `## Unreleased`; ping the named approvers for sign-off; draft and file the rollback runbook entry. + +The orchestrator updates `goal-state.md` and moves on. + +### Decide + +The `decider` reads orientation, prior decisions (none), and the goal. It writes a decision block in `decisions.md`: + +| id | action | rationale | impact | confidence | cost | reversible | gate | +|---|---|---|---|---|---|---|---| +| a-1 | Re-run the flaky `cross-platform-integration` CI job and, if green on retry, mark the job stable for this release with a follow-up issue to investigate the flake. | because orientation §Signal-Map #1 names this as the single remaining red signal on CI | H | M | L | Y | human | +| a-2 | Back-fill PR ids on the 2 changelog entries from orientation §Signal-Map #2, move the 3 `## Unreleased` items into the `## v1.4.0` section, run the changelog linter. | because criterion #2 requires every entry trace to a PR id and the unreleased section to be empty for in-scope items | H | H | L | Y | human | +| a-3 | Ping engineering lead and product lead in the release channel, link the release record, request explicit sign-off comments with timestamps. | because criterion #3 cannot close without their approval; pinging is reversible and cheap | M | H | L | Y | human | +| a-4 | Draft rollback runbook entry `R-v1.4.0` referencing the v1.4.0 release tag, the previous tag (v1.3.6), the named on-call rollback operator, and the verification command; file as a PR against `ops/runbooks.md`. | because criterion #4 cannot close without the runbook entry; drafting from the v1.3.x template keeps cost low | H | H | L | Y | human | + +The decider recommends approving all four as a set; they are independent and parallelisable. The decision block is the act gate — the orchestrator stops and asks the user. + +### Act gate + +The release captain reviews `decisions.md`. They approve a-1, a-2, and a-4 unchanged; they edit a-3 to add a second product-side approver (the product manager owning the feature) — recorded as an "Approved with edits" entry in the decision block. The orchestrator records the approval against the decision-set id and dispatches the actor. + +### Act + +Four actors run, one per action. a-1 reruns CI and gets a green result on the second retry; a-2 back-fills the changelog and runs the linter clean; a-3 pings the approvers with the edited list and captures their immediate "will review by 14:00" acknowledgements; a-4 files the runbook PR and tags the on-call operator. + +Each action file copies the approved action verbatim, lists the executed steps with timestamps, links the produced artifacts, and sets `status: done`. No actor expands scope. + +### Review + +The `loop-reviewer` reads all artifacts and writes `reviews/2026-03-12T11-00-00.md`: + +- **Acceptance check.** + 1. CI green — **met** — the flake retried green and the follow-up issue is filed. + 2. Changelog complete — **met** — 11 entries with PR ids; `## Unreleased` empty for in-scope items. + 3. Sign-offs collected — **partial** — approvers pinged with edited list; no sign-off comments yet. + 4. Rollback runbook — **partial** — PR filed; not yet merged. +- **Outcome.** `continue` — criteria #3 and #4 are pending external confirmation; one short follow-up iteration expected once approvers respond and the runbook PR merges. + +## Iteration 2 + +The orchestrator re-enters Observe with a narrower scope: the sign-off ledger and the runbook PR's merge state. The two named approvers post sign-off comments at 13:42 and 13:58; the runbook PR merges at 14:11. The orienter records criteria #3 and #4 as met. The decider proposes "no action — confirm closure". The reviewer writes `outcome: close-met`. + +The orchestrator sets `goal-state.md` to `status: done` and archives the working artifacts. The release record is now the single auditable artefact of every precondition that gated the publish. + +## Why the loop fits release readiness + +- **Acceptance is the checklist.** The release is irreversible; the checklist is what makes the release reviewable. The loop captures every checklist item as a falsifiable acceptance criterion, which is exactly what an auditor wants. +- **Act gate stays human.** Every intermediate action (rerun CI, back-fill changelog, ping approver, file runbook PR) passes through human approval. The release captain is not waving items through — they are actively shaping the iteration's action set. +- **Audit is automatic.** Every observation, decision, action log, and review is on disk under `goals/release-v1-4-readiness/`. The post-release report writes itself from the artifacts. +- **Closure is deterministic.** The loop closes only when every criterion is met. "Mostly ready" is `outcome: continue`, not `outcome: close-met` — there is no fudging. + +## What the user typed, in total + +Four prompts: + +1. The initial goal statement. +2. Sign-off on `goal-state.md` (the goal gate). +3. Approval of the iteration-1 decision set, with one edit to a-3 (the act gate). +4. Confirmation that the merged runbook PR and the two sign-off comments close the loop (the close-met read is implicit in iteration-2's review). + +Everything else — the three observations, the orientation, the four ranked decisions, the four action logs, and the two reviews — was produced by the subagents. The user reviewed; the loop did the work. + +## Files referenced + +- [`../method.md`](../method.md) — the canonical loop definition. +- [`../usage-patterns.md`](../usage-patterns.md#4-release-readiness-checklist-gated) — pattern details. +- [`../../examples/release-readiness/`](../../examples/release-readiness/) — the worked artifact set for this example. diff --git a/plugin-v2/docs/first-five-minutes.md b/plugin-v2/docs/first-five-minutes.md new file mode 100644 index 000000000..3ea143499 --- /dev/null +++ b/plugin-v2/docs/first-five-minutes.md @@ -0,0 +1,59 @@ +--- +title: First five minutes +folder: plugin-v2/docs +description: 90-second on-ramp for adopters. Install verification → /goal:demo → what landed → where to go next. Strictly time-budgeted; the longer walkthrough is getting-started.md. +entry_point: false +--- + +# First five minutes + +> Strict 90-second budget. If you have more time, read [`getting-started.md`](getting-started.md) instead — this page is the absolute minimum. + +## Step 1 — Confirm the plugin loaded (15 seconds) + +``` +ls plugin-v2/.claude-plugin/plugin.json +``` + +If the file exists, the plugin is installed. If not, see [`getting-started.md` §Install verification](getting-started.md#install-verification). + +## Step 2 — Run the canonical first-touch (30 seconds, zero input) + +``` +/goal:demo +``` + +This scaffolds `goals/hello-loop/` from a pre-signed seed and drives **one full iteration end-to-end**: Observe → Orient → Decide → (act-gate prompt) → Act → Review. You approve once at the act gate; the rest runs without input. + +## Step 3 — Look at the five artifacts that landed (30 seconds) + +``` +goals/hello-loop/ +├── goal-state.md ← contract + frontmatter + ## History +├── observations/2026-…--.md ← raw signals from one source +├── orientation.md ← synthesised view, every claim cites an observation +├── decisions.md ← ranked proposals + ## Human Approval block +├── actions/iter-1/.md ← execution log: what was done, what was skipped, what was verified +└── reviews/2026-….md ← per-criterion verdict + loop outcome +``` + +The audit chain reconstructs from the bottom up: review verdict cites action evidence → action cites approved decision → decision cites orientation claim → orientation claim cites observation signal. `/goal:trace hello-loop` walks it for you. + +## Step 4 — Pick one of these six next (15 seconds) + +1. **Resume a goal you already started** — `/goal:list` shows every goal under `goals/`, recency-sorted. Filter with `--active` / `--stalled` / `--done` to narrow. The shortest path back into work after a context switch. +2. **Run a real goal** — `/goal:start ` opens the intake interview. See [`goal-orientation.md`](goal-orientation.md) for what makes a goal worth running. +3. **Understand the full method** — [`method.md`](method.md). 5–10 minute read. +4. **Compare patterns** — [`usage-patterns.md`](usage-patterns.md) shows when to use one-shot vs. recurring vs. compressed-tempo loops. +5. **Session-scoped intent (different surface, different tool)** — [`session-vs-iteration-goals.md`](session-vs-iteration-goals.md) explains when `/create-goal` (session-scoped) is the right call instead of `/goal:start` (iteration-scoped). +6. **Skim the type map** — [`domain-model.md`](domain-model.md) sections 1–8 cover the day-one types in one read. + +## What this page deliberately leaves out + +This is the *first* five minutes. It does not teach the constitution, the two-writer ownership matrix, the hard-stop caps, the OTel exporter, the canonical enums, the OODA-fidelity tradeoffs, the threat model, or the Boyd reading list. Those all live in dedicated docs and are reached by following the links above when you need them. The goal here is: **see one full loop work, and know which door to walk through next**. + +## See also + +- [`getting-started.md`](getting-started.md) — the methodical introduction with explanations between each step. ~10-minute read. +- [`announcement.md`](announcement.md) — the pitch / "why try it" framing. +- [`README.md`](../README.md) — repo entry point. diff --git a/plugin-v2/docs/getting-started.md b/plugin-v2/docs/getting-started.md new file mode 100644 index 000000000..d27b22144 --- /dev/null +++ b/plugin-v2/docs/getting-started.md @@ -0,0 +1,199 @@ +--- +title: Goal Loop — Getting started +folder: plugin-v2/docs +description: Guided first-loop walkthrough. Pairs with the /goal:welcome command. Reads in 5–10 minutes; gets you to a working loop in 15. +entry_point: false +--- + +# Getting started + +> A guided first loop. Reads in 5–10 minutes; runs in 15. Pairs with the [`/goal:welcome`](../commands/goal/welcome.md) command — the doc walks you through the same loop the welcome skill would conduct for you. + +You have just installed the `goal-loop` plugin. The next ten minutes will: + +1. Verify the install is in place. +2. Define a trivial "hello world" goal so you have a contract for the loop to run against. +3. Run one full iteration (one Observe → Orient → Decide → Act → Review pass) — with you watching every artifact land. +4. Close the loop and point you at where to go next. + +If you would rather have the plugin drive this for you with conductor gating, stop reading and run `/goal:welcome hello`. The reading-along version below covers the same ground at the same depth. + +The plugin is **domain-agnostic**. Examples here use a tiny self-referential goal (confirm the plugin runs in this project). Once the loop has fired once, the same shape covers code work, research, operations, content review, or any knowledge work — see [`usage-patterns.md`](usage-patterns.md). + +## Install verification + +Before you define a goal, confirm the plugin is in place. Three checks; thirty seconds. + +- **Agents present.** `ls plugin-v2/agents/ | wc -l` — expect at least 9 (orchestrator + five phase agents + three consult-only specialists). If the count is short, the plugin folder did not copy fully — re-do the install step in [`../README.md`](../README.md). +- **Slash commands registered.** In Claude Code: `/help | grep goal:` — expect at least `/goal:start`, and ideally the full namespace (`observe`, `orient`, `decide`, `act`, `review`, `run`, `status`, `close`, `brief`, `amend`, `trace`, `welcome`). If nothing shows, your Claude Code session has not picked up the plugin folder yet — restart the session. +- **Manifest reachable.** `cat plugin-v2/.claude-plugin/plugin.json | grep '"version"'` — expect the version string to print. If the file is missing, see [`troubleshooting.md`](troubleshooting.md). + +If any check fails, [`troubleshooting.md`](troubleshooting.md) lists the common causes (folder not adopted, adapter not configured, session not restarted). Do not proceed until all three pass — every later step depends on the plugin actually being loaded. + +## Your first goal in 60 seconds + +A goal is the contract the loop runs against. It declares what outcome you want, what limits apply, and how an outside observer would verify it is met. Without one, the loop has no anchor. + +For the walkthrough, the goal is deliberately self-referential — *confirm the plugin runs in this project*. The shape is real; the data is small. + +The canonical seed lives at [`../examples/hello-loop/goal-state.md`](../examples/hello-loop/goal-state.md). Copy it to `goals/hello-loop/goal-state.md`: + +``` +mkdir -p goals/hello-loop/observations goals/hello-loop/actions goals/hello-loop/reviews goals/hello-loop/archive +cp plugin-v2/examples/hello-loop/goal-state.md goals/hello-loop/goal-state.md +``` + +Then open `goals/hello-loop/goal-state.md` and surgically remove two lines: + +- The `example: true` frontmatter line. +- The body notice that begins `> **EXAMPLE — this is the seed for /goal:welcome's hello-world path.**` (the whole blockquote). + +Everything else is correct as-is. The file declares: + +- **Intent.** Confirm the plugin runs end-to-end in this project. +- **Constraints.** Do not edit anything outside `goals/hello-loop/`. Complete in one iteration. +- **Acceptance criteria.** Three falsifiable items — sign-off flag set, one observation file produced, one review file with outcome `close-met`. +- **Mode.** `one-shot`. Cadence `null`. (Recurring goals carry a cadence; this one closes after a single iteration.) +- **Observe source.** One — `goals/hello-loop/` as a document target. Trivial because the goal is self-referential. +- **Act gate.** `always`. Every action is human-gated, even the trivial ones — the point is to exercise the gate. +- **Status.** `draft`. **`goal_signed_off`.** `false`. The loop refuses to advance until you sign off. + +### Sign the goal gate + +The **goal gate** is one of two non-negotiable human gates in the method. You read the goal, agree it is the contract you want, and sign off. In a normal run this is `AskUserQuestion` driven by [`set-goal`](../skills/set-goal/SKILL.md); reading along, you flip two fields by hand. + +Edit the frontmatter of `goals/hello-loop/goal-state.md`: + +``` +status: active +goal_signed_off: true +``` + +That is the gate signed. The loop may now advance. + +## What just happened + +After the seed copy and the gate sign-off, `goals/hello-loop/` contains: + +``` +goals/hello-loop/ +├── goal-state.md # the contract you just signed +├── observations/ # empty — observer will write here +├── actions/ # empty — actor will write here +├── reviews/ # empty — loop-reviewer will write here +└── archive/ # empty — for rolled history on long-running goals +``` + +Each file or folder is owned by exactly one writer per the [`goal-state.md` ownership matrix](../skills/_shared/goal-state.md#ownership-matrix). You will not edit any of them directly from here on; the phase skills do. + +## Drive the loop manually + +The full iteration is five phases. You can run them one at a time and inspect each artifact as it lands, or drive the whole thing with `/goal:run hello-loop` and watch the orchestrator dispatch each phase in order. The reading version below does it one phase at a time so you can see what changes after each step. + +### Observe + +``` +/goal:observe hello-loop +``` + +The [`observe`](../skills/observe/SKILL.md) skill dispatches the [`observer`](../agents/observer.md) subagent against the single declared source (`goals/hello-loop/`). The observer scans, records raw signals, and writes one observation file: + +``` +goals/hello-loop/observations/2026-05-16T10-00-00--workspace-walk.md +``` + +The filename is an ISO-8601 UTC timestamp. The file lists what the observer found — for the hello-world goal, that is a small set of signals describing what is in the folder right now (the seeded `goal-state.md`, four empty sub-directories, no prior artifacts). Open it. Every claim is sourced; nothing is invented. + +The orchestrator appends a row to `goal-state.md`'s `## History` table recording the observe phase: `started_at`, `ended_at`, free-text outcome, and the relative path to the artifact. + +### Orient + +``` +/goal:orient hello-loop +``` + +The [`orient`](../skills/orient/SKILL.md) skill dispatches the [`orienter`](../agents/orienter.md) subagent. It reads every observation in the current iteration, plus the goal, plus any prior `orientation.md`, and writes a refreshed synthesis to: + +``` +goals/hello-loop/orientation.md +``` + +Every claim cites an observation by file and signal index. Nothing is speculative — orientation is evidence-based per [Article IV of the constitution](../memory/constitution.md). For hello-world the synthesis is short: the goal is in place, the loop folder is intact, no contradiction is visible against the acceptance criteria. + +### Decide + +``` +/goal:decide hello-loop +``` + +The [`decide`](../skills/decide/SKILL.md) skill dispatches the [`decider`](../agents/decider.md) subagent. It reads the orientation and proposes a ranked set of next actions with rationale and confidence, written to: + +``` +goals/hello-loop/decisions.md +``` + +For a well-formed hello-world iteration the decision set will be small — typically a single action that records "the seeded state is sufficient; no further action required" or a small confirmatory write into `goals/hello-loop/`. + +Now the **act gate** fires. The `decide` skill surfaces the decision set and asks you to approve, approve a subset, or reject. This is the second non-negotiable human gate. You see exactly what would be done before it runs. For hello-world, you approve. + +### Act + +``` +/goal:act hello-loop +``` + +The [`act`](../skills/act/SKILL.md) skill dispatches the [`actor`](../agents/actor.md) subagent against only the approved actions. Each action produces one log under: + +``` +goals/hello-loop/actions/iter-/.md +``` + +The log records exactly what was done, what changed, and what was skipped. Evidence (diffs, output, hashes) is linked, not summarised — per [Article VIII (Transparency)](../memory/constitution.md). For hello-world the act is trivial and reversible; for a real goal it would carry a rollback plan. + +### Review + +``` +/goal:review hello-loop +``` + +The [`review-loop`](../skills/review-loop/SKILL.md) skill dispatches the [`loop-reviewer`](../agents/loop-reviewer.md) subagent. It compares the outcome of the iteration to each acceptance criterion individually, writes: + +``` +goals/hello-loop/reviews/2026-05-16T11-30-00.md +``` + +…and returns one of four loop outcomes. For hello-world all three acceptance criteria are met (sign-off flag set, one observation, one review with outcome `close-met`), so the verdict is **`close-met`**. The orchestrator updates `goal-state.md` to `status: done`, `current_phase: closed`, and appends the closure row to `## History`. + +That is one full iteration end-to-end. + +## Closing the loop + +Every review returns one of four outcomes. You will see all four eventually; here is the short version. + +- **`close-met`** — every acceptance criterion is met with cited evidence. The goal becomes `status: done`. Hello-world should end here on the first pass. +- **`close-abandon`** — the goal is no longer worth pursuing. The reviewer records rationale; the goal becomes `status: cancelled`. Use this when reality changes and the goal is moot — not when the loop feels long. Closure is honest per [Article X](../memory/constitution.md). +- **`amend`** — the goal needs revising before the next iteration. The reviewer flags the section that needs to change; [`/goal:amend`](../commands/goal/amend.md) drives the structured change and re-runs the goal gate. +- **`continue`** — acceptance is not yet met but the goal is sound. The orchestrator starts iteration N+1 by re-entering Observe. + +The closure outcome is recorded in the review file *and* in `goal-state.md`'s `## History` row. There is no silent closure. + +## Where to go next + +Three reading paths from here, depending on what you want to do next. + +- **Extend the plugin** — add a new observe-source type, a new decision-ranking criterion, a domain-specific template, or a narrower agent tool list. Read [`customizing.md`](customizing.md). Every extension lives in your project; the plugin folder stays clean for upgrades. +- **Pick a real pattern** — the five canonical use-case shapes (issue resolution, daily brief, incident triage, release readiness, continuous awareness) plus the policy-consultation pattern live in [`usage-patterns.md`](usage-patterns.md). Pick the one that matches your work; copy a goal from [`../examples/`](../examples/) and edit. +- **Wire a recurring loop** — if your goal is recurring (e.g. a daily brief), [`cadence-recipes.md`](cadence-recipes.md) shows cron, GitHub Actions, and systemd recipes for scheduling `/goal:run`. The plugin itself schedules nothing. + +For the canonical method definition — phases, agents, gates, state model, vocabulary — read [`method.md`](method.md). For the ten governing principles, read [`../memory/constitution.md`](../memory/constitution.md). For the vocabulary in one place, read [`glossary.md`](glossary.md). + +## If you got lost + +The loop is small enough to inspect at every step. Recovery affordances: + +- **`/goal:status hello-loop`** — read-only snapshot. Tells you what phase the goal is in, what iteration, what was the last action, and which acceptance criteria are open. +- **`/goal:trace hello-loop`** — read-only walk of the full reasoning trail for the current iteration, criterion → review verdict → action → decision → orientation → observation. Surfaces gaps in the trail. +- **`goals/hello-loop/goal-state.md` `## History` table** — every phase transition is logged. Read top to bottom to see where the loop is. +- **[`troubleshooting.md`](troubleshooting.md)** — problem → cause → fix for the common loop blockers (goal gate not signed, observer ran but wrote nothing, decision set rejected, act gate timed out). + +If a check or gate is making you fight the tool, fix the goal definition. Most loop pain traces to an under-specified acceptance criterion or a missing observe source. The Goal Loop is process-light; the contract is where the work lives. diff --git a/plugin-v2/docs/glossary.md b/plugin-v2/docs/glossary.md new file mode 100644 index 000000000..9b59ec882 --- /dev/null +++ b/plugin-v2/docs/glossary.md @@ -0,0 +1,190 @@ +--- +title: Goal Loop — Glossary +description: Quick definitions of the terms the goal-loop plugin uses, lifted from the canonical method and state contracts so newcomers do not have to chase cross-references. +folder: plugin-v2/docs +--- + +# Goal Loop — Glossary + +> Quick definitions of the terms the plugin uses, lifted from the canonical [`method.md`](method.md) and [`skills/_shared/goal-state.md`](../skills/_shared/goal-state.md) so a domain-neutral newcomer does not have to chase cross-references. Each entry points back at its authoritative source; this file is a lookup, not a redefinition. + +> **Authoritative sources** (where the contracts behind each term live): +> - Method definition: [`method.md`](method.md) +> - State schema and ownership: [`../skills/_shared/goal-state.md`](../skills/_shared/goal-state.md) +> - Constitution: [`../memory/constitution.md`](../memory/constitution.md) +> - Plugin manifest: [`../.claude-plugin/plugin.json`](../.claude-plugin/plugin.json) + +## Goal + +The contract for a loop. Declares **intent**, **constraints**, **acceptance criteria**, **mode**, **cadence** (if recurring), **observe sources**, and an **act-gate policy**. Lives at `goals//goal-state.md`. A goal is mutable only through structured amendment — ad-hoc redefinition mid-iteration is forbidden by [Article I](../memory/constitution.md). See [`method.md` §Core concepts](method.md#goal). + +## Goal slug + +The kebab-case identifier for one goal. Matches the parent folder name under `goals/`. Same slug appears in every artifact for that goal — observations, decisions, actions, reviews, lessons. Owned by `set-goal` and immutable after creation. See [the schema](../skills/_shared/goal-state.md#yaml-frontmatter). + +## Iteration + +One pass of the four phases (Observe → Orient → Decide → Act), closed by a Review. Counted by `iteration:` in frontmatter, starts at `0`, incremented by `goal-orchestrator` at each new Observe. One iteration at a time — the next begins only when the current `review.md` records `continue` or `amend`. See [Article VI](../memory/constitution.md). + +## Phase + +One of the four execution phases (Observe, Orient, Decide, Act) or one of the two pseudo-phases (`scope`, `closed`) that bracket a goal's life. See [`method.md` §The four phases](method.md#the-four-phases). + +## Phase agent + +A specialist subagent that owns exactly one phase artifact: `observer`, `orienter`, `decider`, `actor`, or `loop-reviewer`. Each phase agent writes only its own artifacts; no agent edits another's output. See [Article II](../memory/constitution.md) and [`AGENTS.md` §Subagent roster](../AGENTS.md). + +## Goal gate + +The human sign-off that clears `goal_signed_off: true` before iteration 1 begins. One of two non-negotiable gates per [Article III](../memory/constitution.md). Without it, no phase agent runs. + +## Act gate + +The human approval of the decision set before any irreversible action executes. Reversible, low-risk actions may be auto-approved only when the goal explicitly declares `act_gate: low-risk-auto`. The second non-negotiable gate per [Article III](../memory/constitution.md). The `## Human Approval` block in `decisions.md` is owned solely by the `decide` skill — see [the schema](../skills/_shared/goal-state.md#related-ownership--decisionsmd--human-approval). + +## Observe source + +A concrete place the `observer` reads to gather raw signals: a feed, repo, inbox, API, document, sensor, person, or command. Declared as a row in `## Observe Sources` with `id`, `type`, and `target`. At least one source per goal. Vague categories are not sources; "the team chat" is not, "the `#release` channel in tool X" is. See [the schema](../skills/_shared/goal-state.md#observe-sources). + +## Reversible action + +An action whose effect on the world can be undone without coordination, time pressure, or coordination cost. Archiving an internal draft, saving a working copy you can roll back to, renaming a private folder (and, in software, committing locally on an unpushed branch) are reversible. When unsure, treat as irreversible per [Article V](../memory/constitution.md). + +## Irreversible action + +An action whose effect cannot be undone by the actor alone — sending a customer email, publishing an announcement, deleting records of record, moving money, anything that crosses a system boundary (and, in software, `git push --force`, deploys, deletes). Always carries a **rollback plan** in its action spec; no rollback plan, no execution. Always requires a human Act gate regardless of policy. + +## Rollback plan + +A short, concrete description of how to undo an irreversible action if it produces the wrong outcome. Lives inside the action spec, alongside the action itself. Required by [Article V](../memory/constitution.md) — "no rollback plan, no execution". + +## Acceptance criterion + +A falsifiable condition that decides whether the goal is met. **Falsifiable** means an outside observer, given the artifact under review, can mark it met or unmet without consulting the author. The canonical example: "Make it better" is not falsifiable; "engagement on landing page > 8% by end of month, measured by event X in tool Y" is. The clarity gate in `set-goal` loops on a criterion until it is falsifiable. See [`goal-orientation.md` §What "falsifiable" means here](goal-orientation.md#what-falsifiable-means-here). + +### EARS patterns (the five falsifiable shapes) + +EARS (Mavin et al., 2009) is the structured-sentence form the plugin uses for acceptance criteria. Five patterns cover every shape; each maps to one falsifiable sentence with named slots. Full entry below at [§EARS](#ears-easy-approach-to-requirements-syntax). + +| Pattern | Shape | One-line example | +|---|---|---| +| Ubiquitous | `The shall .` | The redirect map shall return 301 for every legacy URL. | +| Event-driven | `When , the shall .` | When a crawler hits `/old/*`, the wiki shall return a 301 to the renamed slug. | +| State-driven | `While , the shall .` | While the goal is `status: active`, the orchestrator shall block direct edits to `goal-state.md` from phase agents. | +| Optional feature | `Where , the shall .` | Where `parallel_observe: true`, the orchestrator shall dispatch one observer per declared source concurrently. | +| Unwanted behaviour | `If , then the shall .` | If any cap reaches 100%, then the orchestrator shall stop dispatching the next phase. | + +A criterion that does not fit one of these five shapes is almost always under-specified — surface it through [`acceptance-criteria-helper`](../skills/acceptance-criteria-helper/SKILL.md) before sign-off. + +## EARS (Easy Approach to Requirements Syntax) + +Five-pattern structured syntax for writing unambiguous acceptance criteria (Mavin et al., 2009): Ubiquitous, Event-driven, State-driven, Optional feature, Unwanted behaviour. Each pattern is a single sentence with named slots. Used by [`../templates/acceptance-criteria-template.md`](../templates/acceptance-criteria-template.md) and surfaced as `AskUserQuestion` options by [`../skills/acceptance-criteria-helper/SKILL.md`](../skills/acceptance-criteria-helper/SKILL.md). For the five patterns inline with examples, see [§Acceptance criterion → EARS patterns](#ears-patterns-the-five-falsifiable-shapes). + +## Frontmatter + +The YAML block at the top of every plugin artifact (`---` delimited), parsed by Obsidian, Dataview, and the plugin's verify scripts. Carries the typed contract for each artifact — `goal_slug`, `iteration`, `status`, `current_phase`, timestamps, ownership keys. The narrative body sections that follow are for humans; the frontmatter is for tooling and for the orchestrator's state-machine transitions. Drift from canonical frontmatter keys is treated as a contract defect — see [`../scripts/check-frontmatter.sh`](../scripts/check-frontmatter.sh). + +## Constraint + +A hard limit the goal must respect: time, budget, scope, policy, tempo, blackout window, escalation rule. Mirrors the `constraints` frontmatter list. Constraint violations drop an action entirely; ranking dimensions only reorder. See [`method.md` §Goal](method.md#goal) and [the schema](../skills/_shared/goal-state.md#constraints). + +## Mode + +One of two shapes a goal can take: **one-shot** (close the loop after one Act+Review) or **recurring** (iterate until stopped). Recurring goals must declare a `cadence` and a `Stop condition` in `## Mode & Cadence`. See [`method.md` §Use-case patterns](method.md#use-case-patterns). + +## Cadence + +For recurring goals: how often a loop runs — `daily 09:00 local`, `weekly Monday`, `ad-hoc`, `event-driven`, etc. **Informational only.** The plugin schedules nothing; cadence is a contract the adopter wires to their own scheduler. See [`cadence-recipes.md`](cadence-recipes.md). + +## Cap (hard-stop) + +One of three pre-declared limits (`max_iterations`, `max_consecutive_rejects`, `max_failed_acts`) that force the loop to a controlled close. Caps are advisory at 80% (the `goal-orchestrator` surfaces `AskUserQuestion` with continue / amend / pause / close-abandon choices); mandatory at 100% (the loop stops unless `/goal:amend` raises the cap). Cap values live in optional frontmatter on `goal-state.md`; counters live in `## Health`. The 100% gate is constitutional — see [Article VI](../memory/constitution.md). See [`method.md` §Hard-stop gates](method.md#hard-stop-gates) and [the schema](../skills/_shared/goal-state.md#hard-stop-caps). + +## Death spiral + +A loop that keeps iterating without progressing on its acceptance criteria. The three hard-stop caps detect the three canonical shapes: **time spiral** (iteration count grows without convergence, bounded by `max_iterations`), **decision spiral** (consecutive decision sets keep being rejected at the act gate, bounded by `max_consecutive_rejects`), **act spiral** (actors keep returning `status: failed`, bounded by `max_failed_acts`). When any cap reaches 100% the loop must stop and either amend the goal or close-abandon — continuing past the cap is forbidden by [Article VI](../memory/constitution.md). + +## Health (loop) + +The cap-counter snapshot recorded in the `## Health` section of `goal-state.md`. Owned exclusively by `goal-orchestrator` and refreshed on every phase transition. Surfaces three counters (iteration count, consecutive rejects, lifetime failed acts) against their caps plus a `Hard-stop status` of `healthy` (< 80% of every cap) | `approaching-cap` (≥ 80% of any cap) | `at-cap` (= 100% of any cap) | `over-cap-amend-pending` (after `/goal:amend` raises the cap but before the next phase transition recomputes). See [the schema](../skills/_shared/goal-state.md#health) and [`method.md` §Hard-stop gates](method.md#hard-stop-gates). + +## Goal health + +Per-goal observability surface. The orchestrator refreshes `goals//health.md` on every phase transition with counters (iterations, approval ratio, action statuses, review outcomes), cap progress, recent phase durations, and a plain-English trend line. `/goal:status` reads it; external observability tooling (Langfuse, Datadog) can tail or scrape it. Companion to the in-state `## Health` snapshot in `goal-state.md` — the section is the snapshot, the file is the rolling record. See [`templates/health-template.md`](../templates/health-template.md). + +## Loop closure outcomes + +After Review, `loop-reviewer` returns exactly one of four outcomes recorded in the review's frontmatter: + +- `continue` — acceptance criteria not yet met; re-enter Observe. +- `close-met` — all acceptance criteria met; `status: done`. +- `close-abandon` — goal explicitly abandoned with rationale; `status: cancelled`. +- `amend` — goal definition needs revision (human-approved), then continue. + +See [`skills/_shared/loop-pattern.md` §The four loop outcomes](../skills/_shared/loop-pattern.md). + +## Per-criterion verdicts + +Inside a review, each acceptance criterion gets one of: `met` | `partial` | `unmet` | `blocked`. A criterion without evidence is `unmet`, not `met`. Closure on `close-met` requires `met` on every criterion with evidence cited per [Article X](../memory/constitution.md). See [`agents/loop-reviewer.md`](../agents/loop-reviewer.md). + +## Status state machine + +The `status:` frontmatter field. States and transitions: + +``` +draft → active → (paused | blocked | active) → (done | cancelled) +``` + +- `draft` — created by `set-goal`, before the goal gate is cleared. +- `active` — goal gate cleared; loop iterates. +- `paused` — user-initiated halt; resumes back to `active` at the same `current_phase`. +- `blocked` — escalation triggered; resumes when blocker is cleared. +- `done` — `loop-reviewer` returned `close-met`. Terminal. +- `cancelled` — `loop-reviewer` returned `close-abandon`. Terminal. + +See [the schema §Status state machine](../skills/_shared/goal-state.md#status-state-machine). + +## Session goal + +Session-scoped intent that keeps an agentic tool aligned on what the user wants the *current sitting* to produce. Lives one-file-per-goal under `session-goals/.md`. Distinct from a Goal Loop iteration goal (above) — no phases, no act gate, no `goals//` state folder. Authored by [`create-goal`](../skills/create-goal/SKILL.md), activated by [`activate-goal`](../skills/activate-goal/SKILL.md). See [`../commands/create-goal.md`](../commands/create-goal.md) and `docs/session-goal-best-practices.md`. + +## Stop condition + +The concrete trigger that ends a session goal. In Claude Code, the native `/goal` command holds the assistant in the session until the stop condition is met (or `/set-goal --clear` is run). In Codex and Cursor, the stop condition is part of the activated `SESSION-GOAL.md` or `.cursor/rules/session-goal.mdc` directive — the tool honours it for the rest of the session. The condition is observer-checkable, like a Goal Loop acceptance criterion: "Until I'm done" is not a stop condition; "docs/prd.md exists, signed off, with section X populated" is. + +## Goal card + +One-page summary of what a Goal Loop goal is, who owns it, what it claims, and what it cannot do. Inspired by Mitchell et al. (Model Cards, 2019). Lives at `goals//card.md`. Filled at goal creation by [`set-goal`](../skills/set-goal/SKILL.md) (extended mode); refreshed on amendment via [`/goal:amend`](../commands/goal/amend.md). The card is the auditor's first surface and the adopter's elevator pitch; the full contract lives in `goal-state.md`. See [`../templates/goal-card-template.md`](../templates/goal-card-template.md) and [Guarantee 13](non-negotiable-guarantees.md). + +## Observe-source datasheet + +Provenance + reliability sheet for one observe source. Inspired by Gebru et al. (Datasheets for Datasets, 2021). One sheet per declared `observe_source`. Lives at `goals//sources/.md`. Declares provenance, freshness, coverage, reliability, biases, access model, privacy stance, and failure mode. Read by the [`observer`](../agents/observer.md) on every dispatch so it knows the source's profile before it scans. See [`../templates/observe-source-datasheet-template.md`](../templates/observe-source-datasheet-template.md). + +## `current_phase` enum + +The `current_phase:` frontmatter field. Records where the loop is right now. Values: + +- `scope` — pseudo-phase. Owned by `set-goal`; active after goal-gate sign-off, before the first Observe. +- `observe` — Observe phase running. +- `orient` — Orient phase running. +- `decide` — Decide phase running (or at the act gate). +- `act` — Act phase running. +- `review` — Review phase running. +- `closed` — pseudo-phase. Terminal state after `close-met` or `close-abandon`. Owned by `goal-orchestrator`. + +The two pseudo-phases (`scope`, `closed`) sit alongside the four execution phases but have no specialist subagent — `set-goal` owns `scope` transitions and `goal-orchestrator` owns the transition to `closed`. See [`method.md` §The four phases](method.md#the-four-phases). + +## Canonical enums + +The constitution's [Article II §4 (canonical enum lock)](../memory/constitution.md) treats drift from the values below as a contract defect. Every plugin artifact uses these values verbatim — no synonyms, no localisations. + +| Enum | Canonical values | Defined in | Used by | +|---|---|---|---| +| `status` | `draft` \| `active` \| `paused` \| `blocked` \| `done` \| `cancelled` | §"Status state machine" above | `goal-state.md` frontmatter | +| `current_phase` | `scope` \| `observe` \| `orient` \| `decide` \| `act` \| `review` \| `closed` | §"`current_phase` enum" above | `goal-state.md` frontmatter | +| Action-log `status` | `done` \| `partial` \| `stopped` \| `blocked` \| `failed` | [`../templates/action-log-template.md`](../templates/action-log-template.md) §"Status enum — canonical boundaries" | `actions/iter-/.md` frontmatter, `## History` rows | +| Per-criterion `verdict` | `met` \| `partial` \| `unmet` \| `blocked` | §"Per-criterion verdicts" above | Review files | +| Loop-closure `outcome` | `continue` \| `close-met` \| `close-abandon` \| `amend` | §"Loop closure outcomes" above | Review files, `## History` rows | +| `reversible` | `Y` \| `N` | [`../agents/decider.md`](../agents/decider.md) §"Procedure" | Decision proposals, `decisions.md` | + +A reader who has not assembled this table from the constitution and the schema independently will see enum names without values in Article II §4. This consolidator is the canonical lookup; every other reference cites back here. diff --git a/plugin-v2/docs/goal-orientation.md b/plugin-v2/docs/goal-orientation.md new file mode 100644 index 000000000..d1517be13 --- /dev/null +++ b/plugin-v2/docs/goal-orientation.md @@ -0,0 +1,91 @@ +--- +title: Goal Orientation +description: Why explicit goals beat implicit ones, what makes an acceptance criterion falsifiable, and how Goal Loop relates to OKRs and JTBD. +--- + +# Goal Orientation + +> Companion to [`method.md`](method.md). This note is about *why* the Goal Loop puts a goal contract at the top, and what a good one looks like. + +## Implicit goals fail quietly + +Most loops in the wild have implicit goals: "look at the dashboard", "triage the inbox", "ship the release". Implicit goals fail in three predictable ways: + +1. **No close condition.** The loop keeps spinning because nobody can say "we're done". Energy decays into busywork. +2. **Drift.** Each iteration reinterprets the intent slightly; after enough iterations, the work is solving a different problem from where it started. +3. **No conflict surface.** When two stakeholders disagree about what success means, an implicit goal hides the disagreement. The loop produces output that satisfies neither. + +An **explicit goal** — intent + constraints + acceptance criteria + mode + cadence — eliminates all three. The goal contract is the most important artifact in the loop; the orchestrator refuses to start without it. + +## What "falsifiable" means here + +A criterion is **falsifiable** if an outside observer, given the artifact under review, can mark it met or unmet without consulting the author. + +- "The site loads quickly" — not falsifiable. Loads on what device? How quickly? +- "The home page renders below 1.5 s p95 on a cold 3G simulation from the staging URL" — falsifiable. +- "Users feel confident about the new dashboard" — not falsifiable. +- "Five of seven users in moderated tests complete the primary task without help in under two minutes" — falsifiable. + +Falsifiability is harder than precision. A criterion can be precise and still unmeasurable. The test is: *can someone disprove this without re-running the loop?* + +## EARS — a structured pattern for falsifiable criteria + +When falsifiability is the goal but the user is stuck on phrasing, EARS (Easy Approach to Requirements Syntax — Mavin, Wilkinson, Harwood and Novak, 2009) gives five canonical sentence shapes that, slot-filled correctly, are falsifiable by construction. The plugin's `acceptance-criteria-helper` skill surfaces these as multi-choice options when sharpening a vague criterion. + +| Pattern | Shape | Use when | +|---|---|---| +| Ubiquitous | `The shall .` | Invariant — holds at all times. | +| Event-driven | `When , the shall .` | A discrete event must cause a defined response. | +| State-driven | `While , the shall .` | A sustained state must hold a defined response in place. | +| Optional feature | `Where is enabled, the shall .` | A configurable feature or flag must produce the response when on. | +| Unwanted behaviour | `If , then the shall .` | A safety-net response on error, failure, or ambiguity. | + +The full template lives at [`../templates/acceptance-criteria-template.md`](../templates/acceptance-criteria-template.md), including anti-patterns, worked rewrite examples, and the legitimate cases when EARS does not fit (emergent acceptance, counterfactual reasoning, multi-criterion compound goals, aesthetic-only judgement). EARS is the default, not a mandate — record a deviation reason when it is set aside so the goal gate sees it. + +## How Goal Loop relates to OKRs + +[Objectives and Key Results](https://en.wikipedia.org/wiki/Objectives_and_key_results) (Andy Grove, John Doerr) sit one level above Goal Loop: + +- An **Objective** is a multi-quarter outcome statement. Goal Loop does not produce these; it consumes them. +- A **Key Result** is the quarter-scale measurable target. A Goal Loop goal often instantiates one key result, or a slice of one. The acceptance criteria correspond to the KR's measurable definition. + +Goal Loop is not a replacement for OKR planning. It is a way to drive one unit of work *under* an OKR with explicit phases and gates. + +## How Goal Loop relates to Jobs-To-Be-Done + +[Jobs-To-Be-Done](https://strategyn.com/jobs-to-be-done/) (Christensen, Ulwick) frames work as "the job a user hires this system to do". Goal Loop is downstream: + +- JTBD names the job and the desired outcomes for the job-doer. That is product-discovery framing. +- A Goal Loop goal can be: "deliver a feature that helps user-segment X get job Y done with desired outcomes Z" — but the goal also has constraints and acceptance criteria that JTBD does not by itself supply. + +Use JTBD to discover *which* goals are worth setting. Use Goal Loop to drive *each* goal once chosen. + +## Goal Quality Checklist + +Before signing off a goal at the goal gate, the human should be able to answer yes to every line: + +1. **Intent is one sentence** that a stranger can read and understand without context. +2. **Each acceptance criterion is falsifiable** by an outside observer. +3. **Constraints are listed**, including what must not change (scope, budget, time, dependency). +4. **Mode is declared** as one-shot or recurring, and recurring goals have an explicit stop condition. +5. **Observe sources are concrete** — paths, URLs, channels, or named contacts — not vague categories. +6. **Act gate is declared** — always-human, low-risk-auto, or never — with explicit handling for irreversible actions. +7. **The goal is one goal.** If it has "and" between two outcomes, split it. +8. **Each acceptance criterion has named its EARS pattern** (Ubiquitous / Event-driven / State-driven / Optional feature / Unwanted behaviour), or carries an explicit free-form deviation reason per [`../templates/acceptance-criteria-template.md`](../templates/acceptance-criteria-template.md) §"When EARS does not fit". + +A goal that fails any line is sent back to the intake skill (`set-goal`) before the first iteration runs. + +## Related reading + +- [`ooda-foundations.md`](ooda-foundations.md) — the OODA half of the synthesis. +- [`method.md`](method.md) — the full method, including the goal state schema. +- [`usage-patterns.md`](usage-patterns.md) — five canonical shapes a goal can take. + +## Further reading + +Goal-setting practice has a long literature outside the OODA tradition. The works below are the ones that most directly shape the Goal Loop's framing of intent, falsifiability, and outcome measurement. + +- Eliyahu Goldratt — *The Goal*. +- George T. Doran — "There's a S.M.A.R.T. way to write management's goals and objectives" (1981). +- John Doerr — *Measure What Matters* (for OKRs). +- Anthony Ulwick — *What Customers Want* (for Jobs-To-Be-Done). diff --git a/plugin-v2/docs/hooks-recipes.md b/plugin-v2/docs/hooks-recipes.md new file mode 100644 index 000000000..050cb351a --- /dev/null +++ b/plugin-v2/docs/hooks-recipes.md @@ -0,0 +1,162 @@ +--- +title: Goal Loop — Hooks Recipes +description: Opt-in Claude Code hook recipes that surface Goal Loop state. The plugin ships no executable hooks; adopters wire these into their own settings.json. +folder: plugin-v2/docs +--- + +# Goal Loop — Hooks Recipes + +> The plugin ships **no executable hooks** — runtime dependencies are out of scope (see [`customizing.md`](customizing.md)). This doc gives you ready-to-paste recipes for common Claude Code hooks that surface Goal Loop state, which you can adopt into your project's own `.claude/settings.json`. + +These recipes are **opt-in, adopter-owned**, not plugin-owned. The plugin remains pure data + prompts; the hooks below are conveniences the adopter wires into their own harness. Nothing in the plugin assumes any of these run, and removing them never breaks the loop. + +All recipes are POSIX-compatible shell. No exotic dependencies — `find`, `awk`, `grep`, `git`. They are self-contained and run from the repository root. + +--- + +## Recipe 1 — SessionStart: surface active goals + +**Purpose.** When Claude Code starts a session in a project with active goals, print a one-line roster so the user (and Claude) know what is in flight before the first prompt. + +**Shell command.** Scans `goals/*/goal-state.md` for any goal whose `status:` is `active`, `paused`, or `blocked`. Prints `slug | status | current_phase | updated_at` per match. Silent when no goals are active. + +```sh +#!/bin/sh +# .claude/hooks/goal-loop/active-goals.sh +set -eu +GOALS_DIR="${GOALS_DIR:-goals}" +[ -d "$GOALS_DIR" ] || exit 0 + +found=0 +for state in "$GOALS_DIR"/*/goal-state.md; do + [ -f "$state" ] || continue + slug=$(awk -F': *' '/^slug:/ {print $2; exit}' "$state") + status=$(awk -F': *' '/^status:/ {print $2; exit}' "$state") + phase=$(awk -F': *' '/^current_phase:/ {print $2; exit}' "$state") + updated=$(awk -F': *' '/^updated_at:/ {print $2; exit}' "$state") + case "$status" in + active|paused|blocked) + if [ "$found" -eq 0 ]; then + echo "Active Goal Loop goals:" + found=1 + fi + echo " - $slug | $status | phase $phase | updated $updated" + ;; + esac +done +exit 0 +``` + +**`.claude/settings.json` snippet.** + +```json +{ + "hooks": { + "SessionStart": [ + { + "command": ".claude/hooks/goal-loop/active-goals.sh" + } + ] + } +} +``` + +--- + +## Recipe 2 — Stop: remind about untracked goal-state changes + +**Purpose.** When a session ends, warn if anything under `goals/` was modified but not committed. Goal state is auditable; uncommitted changes silently break the trail. + +**Shell command.** Uses `git status --porcelain` filtered to the `goals/` path. Warns on dirty files; silent on clean. + +```sh +#!/bin/sh +# .claude/hooks/goal-loop/goal-dirty-check.sh +set -eu +GOALS_DIR="${GOALS_DIR:-goals}" +[ -d "$GOALS_DIR" ] || exit 0 +command -v git >/dev/null 2>&1 || exit 0 +git rev-parse --is-inside-work-tree >/dev/null 2>&1 || exit 0 + +dirty=$(git status --porcelain -- "$GOALS_DIR" 2>/dev/null | head -20) +if [ -n "$dirty" ]; then + echo "Goal Loop: uncommitted changes under $GOALS_DIR/ — commit before ending the session for an auditable trail:" + echo "$dirty" +fi +exit 0 +``` + +**`.claude/settings.json` snippet.** + +```json +{ + "hooks": { + "Stop": [ + { + "command": ".claude/hooks/goal-loop/goal-dirty-check.sh" + } + ] + } +} +``` + +--- + +## Recipe 3 — UserPromptSubmit: append active-goal context + +**Purpose.** When exactly one goal is `active`, prepend a one-line context tag to the user's prompt — `Active goal: (phase , iter )`. With zero or multiple active goals, the hook does nothing (avoids ambiguity). + +**Shell command.** Same scan as Recipe 1, but counts `active`-status goals only. If the count is exactly 1, emit the tag; otherwise emit nothing. + +```sh +#!/bin/sh +# .claude/hooks/goal-loop/active-goal-context.sh +set -eu +GOALS_DIR="${GOALS_DIR:-goals}" +[ -d "$GOALS_DIR" ] || exit 0 + +count=0 +slug=""; phase=""; iter="" +for state in "$GOALS_DIR"/*/goal-state.md; do + [ -f "$state" ] || continue + status=$(awk -F': *' '/^status:/ {print $2; exit}' "$state") + [ "$status" = "active" ] || continue + count=$((count + 1)) + slug=$(awk -F': *' '/^slug:/ {print $2; exit}' "$state") + phase=$(awk -F': *' '/^current_phase:/ {print $2; exit}' "$state") + iter=$(awk -F': *' '/^iteration:/ {print $2; exit}' "$state") +done + +[ "$count" -eq 1 ] || exit 0 +echo "Active goal: $slug (phase $phase, iter $iter)" +exit 0 +``` + +**`.claude/settings.json` snippet.** + +```json +{ + "hooks": { + "UserPromptSubmit": [ + { + "command": ".claude/hooks/goal-loop/active-goal-context.sh" + } + ] + } +} +``` + +--- + +## Notes + +- These recipes are conveniences. The Goal Loop's correctness does not depend on any hook firing. +- Keep hooks read-only against `goals/`. A hook that writes goal state breaks [Article II](../memory/constitution.md) phase isolation. +- If a hook is slow, gate it behind a project-local toggle (`GOAL_LOOP_HOOKS=1` env var, etc.) — Claude Code waits on hook output. +- Adapt the scripts to your shell of choice; the contract is the printed line, not the language. + +## See also + +- [`customizing.md`](customizing.md) — broader extension points for the plugin. +- [`cadence-recipes.md`](cadence-recipes.md) — recipes for wiring `/goal:run` to a scheduler. +- [`troubleshooting.md`](troubleshooting.md) — when surfaced state surprises you. diff --git a/plugin-v2/docs/improvement-strategy.md b/plugin-v2/docs/improvement-strategy.md new file mode 100644 index 000000000..28573e09a --- /dev/null +++ b/plugin-v2/docs/improvement-strategy.md @@ -0,0 +1,283 @@ +--- +title: Goal Loop — Improvement Strategy +folder: plugin-v2/docs +description: Forward-looking strategy for evolving the goal-loop plugin — extension points, multi-tool expansion, domain specialisation, anti-patterns, contribution rubric, roadmap shape. +entry_point: false +--- + +# Goal Loop — Improvement Strategy + +> Companion to `maintenance.md` (defensive — versioning, deprecation, security) and [`customizing.md`](customizing.md) (adopter-facing — how to extend in your project). This doc is for the **maintainer**: what to add, when, under what guardrails. It is opinionated by design. Hedged guidance gets ignored; wrong guidance gets corrected. + +## The plugin's posture + +Goal Loop is a **baseline**, not a framework. The distinction is load-bearing: + +- A **baseline** ships the smallest coherent set of artefacts that make the method runnable end-to-end. Adopters compose with their own conventions on top. +- A **framework** dictates how the surrounding system is shaped. Adopters fit themselves to it. + +Today the plugin is firmly a baseline: nine agents, nine skills, twelve commands, eleven templates, and a thin adapter layer for three tools. The method definition in [`method.md`](method.md) is the contract; everything else is replaceable. That posture must be defended. Frameworks attract gravity — each new "you should put your X here" rule narrows the addressable problem set and raises the upgrade tax for adopters who didn't want that rule. + +The plugin **should remain a baseline** until two signals show up together: + +1. A clear majority of adopters re-implement the same missing piece in the same way (evidence of a missing primitive, not a missing opinion). +2. The piece is structurally impossible to ship as an external pack (it cuts across phases, gates, or the state model). + +Until both are true, ship a documented extension point, not a framework feature. See [Brian Foote and Joseph Yoder, *Big Ball of Mud* (1997)] on what happens when frameworks grow without resisting accretion, and [Richard Gabriel, *The Rise of Worse is Better* (1991)] on why a smaller core that ships beats a larger one that doesn't. + +The lodestars: + +- **Domain neutrality** ([constitution Article VII](../memory/constitution.md)) is non-negotiable. Every proposed addition gets read against it. +- **Phase isolation** ([constitution Article II](../memory/constitution.md)) is non-negotiable. New surfaces extend phases sideways (consult-only agents, source types, ranking dimensions); they do not insert new phases. +- **Human gates** ([constitution Article III](../memory/constitution.md)) are non-negotiable. No improvement weakens a gate. Improvements may add gates; they may never remove them. + +## Extension points (formal) + +Today's extension points, lifted from [`customizing.md`](customizing.md) and named here so the maintainer can refer to them as a stable list: + +| Extension point | Where it lives | Owner | Stability | +|---|---|---|---| +| **EP-1 — Observe source type** | `goal-state.md` `observe_sources` + adopter skill under `skills/observe-/` | Adopter | Stable — the observer's contract is signals-only. | +| **EP-2 — Decision ranking dimension** | `goal-state.md` `decision_dimensions` | Adopter | Stable — decider reads the block verbatim. | +| **EP-3 — Act-gate policy table** | `goal-state.md` `act_gate` (table form) | Adopter | Stable — orchestrator routes per row. | +| **EP-4 — Consult-only subagent** | Adopter's `.claude/agents/` | Adopter | Stable — consult-only is the safe extension shape. | +| **EP-5 — Template override** | Adopter's `templates/` with `goal-state.md` pointer | Adopter | Stable — frontmatter contract is locked; bodies free. | +| **EP-6 — Cadence trigger** | External scheduler (cron / Actions / systemd) | Adopter | Stable — see [`cadence-recipes.md`](cadence-recipes.md). | +| **EP-7 — Hook recipe** | Adopter's `.claude/settings.json` | Adopter | Stable — read-only against `goals/`. See [`hooks-recipes.md`](hooks-recipes.md). | + +New extension points the maintainer should plan for, in priority order: + +1. **EP-8 — Brief renderer.** Recurring goals produce `brief.md`. A pluggable renderer (markdown today, HTML / Slack-block / email later) makes the brief consumable in more channels without touching the loop. Ship as a `skills/render-brief-/` convention, not a framework hook. +2. **EP-9 — Observation prefilter.** A signal-deduper exists; a per-goal **prefilter** (regex / heuristic / whitelist) belongs in `goal-state.md` so noisy sources don't drown the orienter. Belongs in the goal, not in the observer. +3. **EP-10 — Trace exporter.** `/goal:trace` is read-only today. An export format (JSON, OpenLineage-shaped, OTLP-shaped) lets adopters pipe iterations into their existing observability. Format is owned by the export skill, not by the loop. +4. **EP-11 — Acceptance verifier.** Today the loop-reviewer asserts acceptance in prose. A typed verifier per criterion ("test green", "checklist row=true", "metric < X") lets reviews be reproducible without forcing a runtime. Ship the typed verifier *interfaces*; let adopters bring runners. + +Extension points the maintainer should refuse to add: + +- A "skip phase" extension. Phase isolation is the method's spine. Skipping requires an amendment, not a config flag. +- A "second decider" extension. Multiple deciders break Article II's single-writer rule. Use consult-only agents (`risk-scout`, `goal-critic`) instead. +- An "auto-amend" extension. Goal amendment requires a human gate by [Article I](../memory/constitution.md). + +## Adding tool adapters + +The plugin currently supports Claude Code, Codex, and Cursor via thin adapter shims (see [`tool-adapters.md`](tool-adapters.md)). New adapters are valuable when the underlying tool has a meaningfully different surface (different rule format, different agent model, different command syntax). They are *not* valuable when the new tool can read `AGENTS.md` raw. + +### The minimum adapter contract + +A new tool earns adapter status only if it provides all of: + +1. **Entry-point file.** The tool reads at least one file deterministically on session start (`CLAUDE.md`, `AGENTS.md`, `.cursor/rules/*.mdc`). No entry point, no adapter. +2. **Import or inclusion mechanism.** The entry point can reference `AGENTS.md` and `docs/method.md` without copying their content. Adapters must not duplicate rules — drift is the failure mode (see [`tool-adapters.md` §"Drift policy"](tool-adapters.md)). +3. **Slash-command or workflow equivalent.** The tool has *some* shape that maps to `/goal:*` — slash commands, workflows, named prompts, or a CLI subcommand. The adapter documents the mapping; it does not invent new command verbs. +4. **Tool-list discipline.** The tool can express scoped tool access per agent (or per session). If it cannot, agents fall back to default scope and the adapter doc warns adopters explicitly. Silent broadening of agent tool scope is forbidden by [`customizing.md` §"subagent tool-list rule"](customizing.md). +5. **Read-only access to `goals/`.** The tool can read the state directory. Without this, the adapter is degraded to "intake only" and must say so. +6. **A worked example.** Every new adapter ships with at least one end-to-end example in `docs/examples/-.md` showing one full iteration. No example, no adapter. +7. **A drift-policy note.** The adapter folder includes a `README.md` that names the source of truth (`AGENTS.md`) and the resolution rule (source-of-truth wins). + +### Candidate adapters + +**Aider.** Strong fit. Aider already reads `.aider.conf.yml` and conventions files; it has a chat interface and a coder model with explicit edit/commit primitives. The adapter is a `.aider.conf.yml` plus an `aider/instructions.md` pointing at `AGENTS.md`. Challenge: Aider's natural unit is the edit, not the iteration — the adapter must explain how Aider sessions map to the Act phase, not to whole loops. + +**GitHub Copilot (Workspace / Chat).** Medium fit. Copilot Workspace has a planning/implementation split that maps loosely to Orient→Decide→Act. The adapter shape is `.github/copilot-instructions.md` plus a `copilot/workflows/` directory of named tasks. Challenge: Copilot's surface is more opinionated than the others — the adapter must avoid Copilot's "task" abstraction overriding the loop's phase model. + +**Gemini Code Assist / Gemini CLI.** Medium fit. The Gemini CLI reads `GEMINI.md` similarly to `CLAUDE.md`. The adapter is mechanically straightforward: a thin `GEMINI.md` import shim plus a `gemini/workflows/` set. Challenge: Gemini's agent model is less mature than Claude's; expect the adapter to be more workflow-heavy than agent-heavy in the near term. + +**Sourcegraph Cody.** Weaker fit today. Cody's commands and context layer are less aligned with the agent+skill+command triad; the adapter would be mostly a `.cody/` rules folder and a single chat-driven workflow. Defer until a clearer agent-style surface lands. + +**Continue.dev.** Medium fit. Continue has a `config.json` with `rules` and `models`; the adapter is a rules entry plus a `continue/workflows/` set. Continue's strength is the multi-model setup — the adapter doc should note that the Goal Loop's gate model is model-agnostic. + +**Order of work.** Aider first (least friction, highest leverage for non-Anthropic-stack adopters). Gemini second (parallel branch to Claude Code; mechanically symmetric). Copilot third (more delicate; needs careful avoidance of Workspace's opinions). Continue and Cody as needed. + +## Domain specialisation + +Goal Loop is domain-neutral by [Article VII](../memory/constitution.md). Adopters specialising for security operations, research operations, content operations, regulatory monitoring, or anything else must specialise **without forking**. Three mechanisms exist, with a clear preference order. + +### Domain packs vs. forks vs. overlays + +| Mechanism | What it is | Use when | Cost | +|---|---|---|---| +| **Overlay** (preferred) | A folder in the adopter project that adds agents, skills, templates, and observe-source helpers without modifying the plugin folder. | The plugin's surfaces are sufficient; you're only adding new content. | Lowest. Upgrades the plugin in place. | +| **Domain pack** | An optional sibling repo or sub-folder (`packs/security-ops/`) that ships a curated set of agents + skills + templates + example goals. Installed by copy. | A coherent bundle exists that ten or more adopters in the same domain would reuse verbatim. | Medium. Pack maintenance becomes its own concern. | +| **Fork** | Copy the plugin and edit in place. | Never as a first choice. Only when an adopter needs to violate a constitution article (and accepts the cost of leaving the upgrade path). | Highest. No upgrades. | + +The preference is **always overlay first**. A domain pack only earns life when the overlay pattern produces visible duplication across three or more adopters. + +### When a domain pack earns a place in the baseline + +A domain pack should *only* live next to the baseline when **all** of the following hold: + +- [ ] The domain's vocabulary maps cleanly onto the existing phases without redefinition. (If "Observe" needs new meaning, this is not the right approach — amend the constitution instead.) +- [ ] The pack adds only consult-only agents, source types, decision dimensions, or templates — no new phase agents, no new phases. +- [ ] At least three independent adopters have run the pack against real goals and reported feedback (not just a maintainer demo). +- [ ] The pack's footprint is < 30 % of the baseline's surface count (so adopters don't drown in domain content when installing the plugin). +- [ ] A maintainer commits to upkeep with at least one named co-owner outside the core team. + +Anything failing this checklist lives in a separate repo. The baseline stays minimal. See [Eric S. Raymond, *The Cathedral and the Bazaar* (1999)] on the "small core, large periphery" principle that has kept Unix-shaped systems usable across decades. + +## Composition with other plugins + +Goal Loop is composable but **does not coordinate**. The rule: Goal Loop owns its goals; other plugins own theirs; the human owns the cross-plugin sequencing. + +### How Goal Loop composes + +- **Alongside Specorator's `core-lifecycle`.** A Specorator feature can become the *goal* of a Goal Loop; the loop drives one stage (e.g., a stalled implementation slice) inside the Specorator stage taxonomy. The loop does not replace stages and does not write outside `goals//`. +- **Alongside a Discovery sprint kit.** Discovery produces a brief; the brief becomes the goal's intent. The loop never invokes Discovery and Discovery never invokes the loop. +- **Alongside a project-management track.** A long-running project can be a recurring goal; the PM plugin owns ceremony (standups, retros, budgets); the loop owns the daily/weekly tempo of resolution work. +- **Alongside QA / security review.** A security review can be a one-shot goal whose acceptance is the findings checklist. The QA plugin's findings flow in as observations. + +### How Goal Loop refuses to coordinate + +- It will **not** dispatch other plugins' commands. +- It will **not** subscribe to or react to other plugins' state files. +- It will **not** add a "parent plugin" or "child plugin" field to `goal-state.md`. + +Cross-plugin coordination is the human's job because the alternative is an emergent dependency graph that no maintainer can keep coherent. (See [Lehman's Laws of Software Evolution, 1980] on how unchecked feature growth degrades structure.) If a coordination need recurs across many adopters, the right move is a separate "conductor" plugin that orchestrates Goal Loop and others as peers — never a coordination feature inside Goal Loop itself. + +## Improvement signals + +The plugin's `/goal:trace` and the `trace-loop` skill already produce per-iteration reasoning trails. Aggregated across many iterations, these are the maintainer's primary improvement signal source. The maintainer should expect adopters to share *aggregates*, not raw traces (which contain goal content). + +Metrics worth tracking (in adopter projects, surfaced to the maintainer via reports, not by the plugin sending anything): + +| Metric | What a bad value means | What the maintainer should do | +|---|---|---| +| **Median iterations to closure** (per pattern) | Goals overshooting expected ranges (e.g. issue-resolution > 3 iterations median) | Investigate whether acceptance criteria are under-specified; sharpen `set-goal` skill prompts. | +| **Acceptance-met rate at closure** | < 70 % `close-met` vs. `close-abandon` | Often a goal-quality problem upstream; tune the goal-critic agent. | +| **Gate-cleared rate** (act gate approvals / proposals) | < 50 % approval rate | Decider is proposing too aggressively; revisit the ranking rubric defaults. | +| **Observe-source dead-rate** (sources producing zero signals across iterations) | > 20 % dead sources | The `observe` skill should warn during goal definition; ship a "source-fitness" check. | +| **Mean signals-per-iteration** | Sustained downward trend | Sources are stale; needs intervention but not necessarily a plugin change. | +| **Amendment frequency per goal** | > 1 amendment per 5 iterations | Goal-gate is letting under-specified goals through; tighten the `set-goal` gate. | +| **Phase-isolation violations** (cross-writes detected) | Any | Hard bug. Fix immediately; consider stricter Write tool scoping. | +| **Time-in-phase distribution** | One phase consuming > 70 % of total time | The skill prompts for that phase need work, or the agent's tool list is wrong. | + +The maintainer should publish a quarterly *State of the Loop* writeup against these metrics, pulled from voluntary adopter reports. Two reasons: it forces the maintainer to read the signal regularly, and it builds an adopter community around shared evidence rather than anecdote. + +## Anti-patterns + +The plugin must NEVER become any of the following. These are operational constraints, not preferences. + +1. **An auto-merge plugin.** The act gate is human by construction. No amount of confidence, no historical track record, no "low-risk-auto policy v2" justifies a path that bypasses humans for irreversible actions. See [constitution Article III](../memory/constitution.md) and [Article V](../memory/constitution.md). +2. **A scheduler daemon.** Cadence is informational. The plugin ships scheduler *recipes*, not a scheduler. The day the plugin runs a daemon is the day it owns uptime, retries, secret storage, and timezone bugs forever. See [`cadence-recipes.md`](cadence-recipes.md). +3. **A SaaS platform.** No hosted service, no telemetry endpoint, no remote registry. Adopters install by copy. The plugin's distribution model is "files in your repo". Everything else is a different product. +4. **A software-only tool.** Code, content, research, operations, governance, regulatory monitoring — the method serves all. Software examples are illustrative only, never normative. See [Article VII](../memory/constitution.md). +5. **A test-runner.** Acceptance verifiers (EP-11) ship the *interface* for verification, not a runner. The day the plugin runs tests is the day it competes with every test framework on earth and loses. +6. **An MCP server host.** External tool integrations are out of scope. Adopters wire MCP servers via their tool's native mechanism; the plugin references only standard tool surfaces. +7. **A multi-tenant orchestrator.** One human, one project, one set of goals. No "team workspace" feature, no shared state daemon, no cross-project goal dependencies. Multi-tenant is a different product. +8. **A workflow engine.** No DAGs, no conditional branches inside iterations, no per-phase retries. The loop is the workflow. Iteration is the retry. +9. **A LLM router.** The plugin is model-agnostic. It does not select models, balance load, or fallback chains. That belongs in the tool, not the plugin. +10. **An observability platform.** `/goal:trace` is read-only structured output. Adopters pipe it where they like (EP-10). The plugin is not Honeycomb, Datadog, or OpenLineage. + +If a contribution proposes any of these, the maintainer says no in one sentence and links here. + +## Roadmap shape + +### How the maintainer picks what to work on next + +A triage rubric, run on every adopter-reported gap, every contribution, and every speculative idea: + +1. **Does it strengthen the method or weaken it?** A change that makes the loop more honest, more traceable, or more gated is welcome. A change that hides state, weakens gates, or works around the constitution is not. +2. **Is it solvable as an extension point?** If yes, write a [`customizing.md`](customizing.md) recipe or a new EP entry; do not change the baseline. +3. **Is it requested by ≥ 3 independent adopters?** Below that bar, it's anecdote, not signal. Write it down as a candidate; don't ship it. +4. **Can it be done without amending the constitution?** If no, the constitution amendment is the first deliverable, not the code. Use [`constitution-amendment-template.md`](../templates/constitution-amendment-template.md). Amendments to Articles I–III require the highest scrutiny. +5. **Does it break any contract in [`tool-adapters.md`](tool-adapters.md)?** A change that forces every adapter to re-implement something is a high cost; needs a clear payoff. +6. **What's the rollback?** Every change has a path back. If "we'd have to fork to undo this", the change is too big — slice it. + +Voting and top-down both fail at this scale. The maintainer holds the call. Adopter votes are *evidence*, not *authority*. + +### Innovation budget per release + +A rough release split — adjust as the project matures, but the *shape* is durable: + +- **50 % polish.** Bug fixes, doc tightening, template improvements, skill prompt refinement, glossary fixes, example freshening. The vast majority of value lives here. (See [Donald Knuth, *Literate Programming* (1984)] on the long compounding return on documentation work.) +- **30 % adopter-reported gaps.** Features that came from real use — usually new extension points, new patterns, sharper prompts. The bar: at least one named adopter, ideally three. +- **15 % maintainer-driven additions.** New tool adapter, new domain pack candidate, new EP. The maintainer is allowed taste here, but only after the first 80 % is paid. +- **5 % speculative.** Experiments. Unblocked. May get cut at release. Lives behind opt-in flags or in a `next/` folder until proven. + +Releases that flip this — 50 % speculative, 5 % polish — are how plugins die. The maintainer should publish the split in each release note; it forces honesty about where the energy went. + +## Contribution rubric + +Contributions are welcome. Acceptance is not automatic. Every kind of contribution has a checklist. + +### Accepting a new agent + +- [ ] Is it **consult-only**? New *phase* agents need a constitution amendment first. Consult-only agents do not. +- [ ] Does it have a single, narrow scope expressible in one sentence? +- [ ] Is its tool list **narrower** than or equal to the phase agent that consults it? Broadening requires a justification in the amendment log per [`customizing.md`](customizing.md). +- [ ] Does it use domain-neutral vocabulary? +- [ ] Is there a worked example in `docs/examples/` showing where it gets consulted and what artifact it produces? +- [ ] Does it write only to its own outputs and never to another agent's artifact ([Article II](../memory/constitution.md))? + +### Accepting a new skill + +- [ ] Is it a how-to (skill) or a workflow (slash command)? Skills are reusable; commands are dispatched. Get the category right before discussing the content. +- [ ] Does it have a clear trigger language (natural-language + explicit)? +- [ ] Does it touch only the phase or artifact its name implies? +- [ ] Does it reference the shared rules in `skills/_shared/`? +- [ ] Is the SKILL.md frontmatter complete (`title`, `description`, etc.)? +- [ ] Does the skill avoid re-implementing the constitution or the method in prose? (Reference, don't restate.) + +### Accepting a new template + +- [ ] Does it preserve the canonical frontmatter fields the agents read? +- [ ] Is it framework-agnostic markdown — no language- or tool-specific assumptions in the structure? +- [ ] Is there a one-line entry in `templates/README.md` saying when to use it? +- [ ] Has it been used at least once in an example? + +### Accepting a constitution amendment + +- [ ] Is the proposal in [`constitution-amendment-template.md`](../templates/constitution-amendment-template.md) form, filled out completely? +- [ ] Does it name the article touched and quote the current text verbatim? +- [ ] Does it list every affected template, agent, skill, and doc? +- [ ] Does it include a rationale that points at a real loop, review, or incident — not a hypothetical? +- [ ] Is the human approver named with a timestamp? +- [ ] Is the version bump the right magnitude (Articles I–III = minor at minimum; wording-only = patch)? + +Amendments to Articles I–III warrant a 14-day open comment window before acceptance. Other amendments may move on 7 days. The maintainer's default answer on a constitution amendment is **no**; the burden is on the proposer. + +### General contribution hygiene + +- Every PR cites the EP, anti-pattern, or constitution article it touches. +- Every PR includes a doc update in the same change (no "I'll write the doc later"). +- Every PR has a worked example or test fixture exercising the change. +- Backward compatibility is preserved within a major version. Breaking changes wait for the next major and ship with a deprecation period — see `maintenance.md` for the defensive side of this rule. + +## Open questions + +The maintainer should settle these next, in roughly this order: + +1. **EP-11 acceptance verifier interface.** What is the minimal typed contract for a verifier? Boolean + evidence pointer? Tristate (met / unmet / unknown) + evidence + rationale? Decide before any runtime-bearing verifiers ship. +2. **Domain-pack lifecycle.** When a pack outgrows "examples in adopter projects" and earns sibling-repo status, who maintains it? Co-owners? A `MAINTAINERS.md` per pack? Set policy before the first pack lands. +3. **Trace-export schema.** OpenLineage-shaped, OTLP-shaped, or a Goal-Loop-native shape? The decision shapes which observability ecosystems Goal Loop plugs into for the next five years. +4. **Aider adapter scope.** Does the Aider adapter cover one full iteration, or only the Act phase (where Aider's edit-loop strength lives)? The answer changes the adapter doc structure. +5. **Telemetry consent model.** Adopter-driven sharing only — but in what form? A `goal-loop report` skill that emits a sanitised aggregate? A schema for voluntary submissions? Decide before publishing a *State of the Loop*. +6. **Skill vs. command boundary.** The current split (skills are reusable how-tos, commands are dispatched workflows) works, but the boundary is fuzzy around `/goal:run`. Tighten the rule in a follow-up to `AGENTS.md`. +7. **Constitution v1.0.** When does the method move from v0.x to v1.0? Proposal: when (a) no Article I–III amendment has been needed for two release cycles, (b) at least five independent adopters have shipped, and (c) the worked-example set covers all five canonical patterns. +8. **A "stop the loop" gate.** Today, the only way a goal closes against the human's wishes is abandonment. Should there be a hard automatic stop (e.g. > 20 iterations, > 5 abandoned proposals in a row, > N failed acts) that forces human review? Lean yes — protect the human from runaway loops — but the gate's defaults need careful selection. + +--- + +## References + +The opinions above lean on the following published sources. None of these are linked; cite by author + title so the reference survives URL rot. + +- John Boyd, *Patterns of Conflict* briefing and *The Essence of Winning and Losing* (1995–96), for the OODA loop. +- Eric S. Raymond, *The Cathedral and the Bazaar* (1999), for "small core, large periphery" and the bazaar contribution model. +- Richard Gabriel, *The Rise of Worse is Better* (1991), for the small-shipping-thing wins argument. +- Brian Foote and Joseph Yoder, *Big Ball of Mud* (1997), for the failure mode of frameworks without resistance. +- Meir M. Lehman, "Programs, Life Cycles, and Laws of Software Evolution" (1980), for the laws on feature growth and structural degradation. +- Donald Knuth, *Literate Programming* (1984), for the compounding return on documentation. +- Tim Peters, *PEP 20 — The Zen of Python* (2004), for "There should be one-- and preferably only one --obvious way to do it". +- Daniele Procida, *Diátaxis* (2017–) documentation framework, for the tutorials / how-tos / reference / explanation split underlying this doc set. +- IETF RFC 2119 and RFC 8174, for the MUST / SHOULD / MAY vocabulary used in constitution articles. +- Tom Preston-Werner, *Semantic Versioning 2.0.0*, for the versioning grammar `maintenance.md` documents. +- Hyrum Wright, *Hyrum's Law*, for why every observable behaviour will eventually be depended on (informs the backward-compatibility rule). + +## See also + +- [`method.md`](method.md) — the locked method definition that every improvement is measured against. +- [`customizing.md`](customizing.md) — adopter-facing companion (extensions in your project, not in the baseline). +- [`tool-adapters.md`](tool-adapters.md) — adapter contract; new adapters must satisfy it. +- [`memory/constitution.md`](../memory/constitution.md) — the ten articles every change is read against. +- [`templates/constitution-amendment-template.md`](../templates/constitution-amendment-template.md) — the required form for any change touching the articles. +- `maintenance.md` (defensive companion) — versioning, deprecation, security; sibling to this doc. diff --git a/plugin-v2/docs/maintenance.md b/plugin-v2/docs/maintenance.md new file mode 100644 index 000000000..baa479686 --- /dev/null +++ b/plugin-v2/docs/maintenance.md @@ -0,0 +1,199 @@ +--- +title: Goal Loop — Maintenance Guide +folder: plugin-v2/docs +description: How to maintain the goal-loop plugin over time — versioning, deprecation, schema evolution, multi-tool drift, security review cadence, and contribution patterns. +entry_point: false +--- + +# Goal Loop — Maintenance Guide + +> Companion to [`method.md`](method.md) (the *what*) and [`customizing.md`](customizing.md) (how *adopters* extend). This doc is for the plugin **maintainer** — the contracts behind keeping the baseline healthy as the surface evolves. + +The plugin ships as a copy-and-paste baseline. Adopters fork it. That means every change you make is a change every downstream fork has to absorb. Maintain on that assumption. + +## Versioning + +The plugin follows Semantic Versioning 2.0.0. `version` in [`.claude-plugin/plugin.json`](../.claude-plugin/plugin.json) is the single source of truth — bump it in the same PR as the change. + +### Semantic versioning rules for the plugin + +- **MAJOR** — any backward-incompatible change to the plugin's public surface (defined below). Forces every adopter to re-read the migration notes. +- **MINOR** — additive change: new agent, new skill, new command, new template, new optional state-file field. Does not require adopter action. +- **PATCH** — wording fixes, doc rewordings, prompt tightening that preserves trigger phrases, internal refactors with identical externally observable behaviour. + +The plugin's **public surface** is the contract adopters depend on: + +1. The names, paths, and capability lists in `.claude-plugin/plugin.json`. +2. The `goal-state.md` frontmatter schema and body section names (see [`skills/_shared/goal-state.md`](../skills/_shared/goal-state.md)). +3. The `/goal:*` slash-command set, their argument hints, and their behaviour. +4. The agent roster and each agent's *intended* scope (tool list narrowings are not breaking; tool list broadenings are — see Article II of [`memory/constitution.md`](../memory/constitution.md)). +5. The skill trigger phrases — the natural-language hooks that auto-invoke a skill. +6. The constitution's articles. Wording inside an article is patch-level only when meaning is preserved. +7. The locked vocabulary block in `method.md` ("Naming reference"). + +### What counts as a breaking change + +Bump MAJOR for any of: + +- Removing or renaming a required `goal-state.md` frontmatter field, or changing its allowed values to a narrower set. +- Removing or renaming a body section in `goal-state.md`. +- Removing or renaming an agent (`observer`, `orienter`, etc.). +- Narrowing an agent's *responsibility* such that an adopter's downstream consult-agent relationship breaks. Narrowing only its tool list is **not** breaking. +- Removing or renaming a slash command, or changing its argument hint in a way that breaks the existing invocation string. +- Moving a skill's trigger phrase such that an existing chat invocation ("set up a goal loop") no longer dispatches the skill. +- Removing or renaming a template that the skills reference by path. +- Constitutional amendments that touch Articles I (Goal Primacy), II (Phase Isolation), III (Human Gates), VIII (Transparency), or X (Closure Honesty) — these are load-bearing per the amendment template's `## Version bump` rule. +- Manifest schema changes that require the host tool to re-parse `plugin.json`. + +Wording amendments to Articles IV–VII and IX warrant at minimum a MINOR bump because adopters audit their fork against the constitution. + +## Changelog + +Follow Keep a Changelog 1.1.0. The plugin's `CHANGELOG.md` lives at the plugin root, one entry per release, latest version first, with the SemVer link. + +### Format + +- One `## [X.Y.Z] - YYYY-MM-DD` header per release. +- An `## [Unreleased]` block at the top while a release is in flight. +- Each entry is grouped by the standard categories below. Empty groups are omitted. +- Reference IDs (`AMEND-NNNN` for constitution amendments, agent / skill / command paths for surface changes) sit in the bullet text. + +### Categories + +Use exactly these six categories, in this order. They are the Keep a Changelog set; do not invent variants. + +- **Added** — new agents, skills, commands, templates, optional frontmatter fields, docs. +- **Changed** — behaviour changes to existing surfaces (prompt edits that change output shape, skill procedure changes, template restructures). +- **Deprecated** — surfaces still present but on a deprecation clock. Each bullet names the replacement and the planned removal version. +- **Removed** — surfaces gone in this release. Reference the version that first marked them `Deprecated`. +- **Fixed** — bug fixes in agent procedures, broken links, schema drift between template and shared contract. +- **Security** — agentic-security findings closed, tool-list tightenings, gate hardenings. + +### What an agentic plugin's changelog needs that a library's doesn't + +- **State-file schema deltas** — every `Changed` or `Added` row touching `goal-state.md` cites the field, the migration step, and whether the change is backfillable. +- **Prompt-behaviour notes** — if an agent's wording change can produce a different *kind* of output, say so. Adopters compare against existing artifacts. +- **Trigger-phrase changes** — every skill trigger edit gets a one-line `Changed` entry naming both the old and new phrase. Adopters' bookmarked chat patterns depend on it. +- **Constitution links** — every entry tied to an amendment links the amendment file (`memory/amendments/-.md`). +- **Tool-list deltas** — narrowings are noted but not breaking; broadenings are flagged as `BREAKING:` and required to ship with a security rationale. + +## Deprecation + +Deprecation is a contract, not a label. Mark, hold, then remove. + +- **Mark.** Add `> **Deprecated since vX.Y.0.** Replaced by ``. Removed in vX+1.0.0.` at the top of the agent / skill / command / template file. Log under `Deprecated` in the changelog. Bump the next release MINOR. +- **Hold.** Keep the deprecated surface fully functional for **at least two minor releases** before removal. If an adopter on `vX.0.0` upgrades to `vX+1.0.0`, they should see the deprecation warning before the surface disappears. +- **Signal.** The conductor skill (`goal-loop`) prints the active deprecations on its first response of an iteration. The `/goal:status` command surfaces deprecated artifacts referenced by the active goal. +- **Remove.** Drop the file. Update the manifest capability list. Update the changelog `Removed` group, citing the version that first marked it. + +A surface in `Deprecated` state never loses functionality silently. If a bug surfaces during the hold window, fix it — adopters mid-migration depend on the deprecated path working. + +## Schema evolution + +`goal-state.md` is the only schema that crosses the plugin-adopter boundary at runtime. Treat it like a database migration, not a doc edit. + +- **Additive (MINOR).** Add a new *optional* frontmatter field with a documented default. Adopters with live goals continue to read and write without action. Update [`skills/_shared/goal-state.md`](../skills/_shared/goal-state.md) and `templates/goal-state-template.md` together. +- **Subtractive (MAJOR).** Remove a required field, narrow an enum, rename a body section. Ship a migration script under `scripts/migrate-state-vX-to-vY.md` describing the diff and the manual steps. The script is markdown, not code — adopters apply it by hand or wire it into their own tooling. +- **Renames.** Always two-step: introduce the new name in version N (additive, both names accepted), remove the old name in version N+2 minimum. Document the alias window in the changelog. +- **Versioning the schema itself.** Add a `schema_version` frontmatter field at the next MAJOR. Until then, `plugin.json` `version` is the implicit schema version. + +An adopter with a live goal mid-migration follows three steps: run `/goal:status` to capture the current state, apply the migration doc to their `goal-state.md` files, then run `/goal:trace` on the active iteration to confirm the trail still reconstructs. If `trace` fails to reconstruct, the migration is wrong — fix it, don't paper over. + +## Multi-tool drift + +The plugin serves Claude Code, Codex, and Cursor through thin adapters (see [`tool-adapters.md`](tool-adapters.md)). The drift risk is real because each tool has a different load order. + +- **Source of truth is `AGENTS.md` plus `docs/method.md`.** Every adapter file is a pointer; substance never lives in the adapter. +- **Manifest is the binding contract for Claude Code.** When `plugin.json` changes, every adapter README cross-checks that the capability lists match what the adapter advertises. +- **Adapter parity check is per release.** Before tagging, the maintainer reads `.codex/instructions.md`, `.codex/README.md`, and `.cursor/rules/goal-loop.mdc` and confirms they still point at the right anchors. Drift detected → fix the adapter, never the source. +- **Workflows are not substance.** A new Codex workflow under `.codex/workflows/` is acceptable adapter mechanics; a *rule* that contradicts `method.md` is not. If the adapter would need a rule the source of truth lacks, the rule belongs in the source. +- **Cursor frontmatter.** The `.mdc` file's `alwaysApply` flag is the only mechanic Cursor has — confirm it on every release. + +## Security review + +The plugin's security surface is agentic: tool lists, gate policies, and the constitution. Run two reviews on different cadences. + +- **Per-release agent-surface review.** Before tagging any release, audit every agent file for `Tools:` drift against the AGENTS.md roster. Any broadening is blocked until the changelog carries a rationale entry under `Security`. +- **Quarterly agentic security review.** Run an OWASP-aligned pass on the loop: confirm the act gate's irreversibility rule still holds, confirm no skill bypasses `AskUserQuestion` at human gates, confirm the orchestrator still owns `goal-state.md` writes exclusively. Reference: OWASP Top 10 for LLM Applications (2025); the plugin's threat model treats every phase agent as an untrusted subprocess. +- **Annual constitution audit.** Re-read the constitution end to end. Any article that has accumulated more than two amendments in the year is a candidate for a clarifying rewrite. +- **Trigger-on-incident.** Any reported case of an agent inventing state, bypassing a gate, or writing outside its scope triggers an out-of-band review and an amendment proposal if the constitution did not cover it. + +The reviewer is the maintainer or a delegated reviewer named in `CODEOWNERS` (if present). Findings land in `quality/security-.md` in the consuming repo, not in the plugin folder. + +## Maintenance cadence + +Pick activities by tempo. Resist the urge to do everything every week. + +### Weekly (10 minutes) + +- Triage open issues. Tag with `bug`, `enhancement`, `amendment`, `adapter-drift`, `docs`. +- Skim `CHANGELOG.md [Unreleased]` for stale entries. +- Confirm no PRs sit beyond the branch-per-concern rule. + +### Monthly (1 hour) + +- Run `/goal:trace` against a synthetic goal in the plugin's own examples to confirm the loop still reconstructs end-to-end. +- Audit one agent file against its constitution articles. +- Review at least one example in [`docs/examples/`](examples/) for accuracy. +- Cut a PATCH release if any wording fixes have accumulated. + +### Quarterly (half day) + +- Run the agentic security review (above). +- Rotate one worked example to a fresh domain — examples drift toward the maintainer's home turf; quarterly rotation keeps the domain-neutrality promise of Article VII honest. +- Review the docs set against `plugin.json`: every capability listed in the manifest has at least one doc that names it. +- Decide on any deprecations whose hold window has elapsed; schedule their removal in the next MAJOR. +- Cut a MINOR release if accumulated additive changes warrant. + +### Annually (one day) + +- Constitution audit (above). +- Review the maintenance guide itself; bump versions in this doc if cadences proved wrong. +- Publish a "year in review" entry in the changelog summarising the year's amendments and the upcoming MAJOR's removals. + +## Automated quality pipeline + +Once implemented, every PR touching `plugin-v2/**` is gated by the eight check categories specified in [`automation-spec.md`](automation-spec.md) — lint (A), verification (B), validation (C), formatting (D), spell-check (E), security (F), the release-time self-application meta-check (G — including the G2 body-length cap), and Obsidian compliance (H). The spec is the **acceptance contract** for the follow-up implementation PR: scripts under `plugin-v2/scripts/`, a CI workflow at `.github/workflows/plugin-v2-quality.yml`, an opt-in pre-commit hook, and the G1 self-application loop against each release goal. Until the scripts land, the maintainer runs the checks manually using the spec's check ids; once they land, this section becomes the index into them. + +## Contribution + +External contributions are welcome but the surface is opinionated. Set expectations up front in `CONTRIBUTING.md` if you ship one. + +- **New observe source types, decision dimensions, gate policies, domain consult-agents, and template variants** are all *adopter-side* extensions per [`customizing.md`](customizing.md). They live in the adopter's project, not the plugin. Reject PRs that bake domain logic into the baseline. +- **New phase agents, new state-file fields, new slash commands, new core skills** are method changes. They require a constitution amendment proposal first (see [`templates/constitution-amendment-template.md`](../templates/constitution-amendment-template.md)) and acceptance before the PR lands. +- **Doc improvements, glossary additions, example rotations, troubleshooting entries** are welcome and review-light. Use Conventional Commits (`docs:`, `fix:`, `feat:` per the 1.0.0 spec). +- **Adapter parity fixes** — when a downstream tool's adapter has gone stale, fix the adapter, never the source. +- **PR checklist:** SemVer bump declared, changelog entry under the right category, constitution amendment cited if required, adapter parity confirmed, one concern per PR. + +Reviews are author-owned: the contributor responds to feedback in the same PR; the maintainer never silently rewrites a contributor's work. + +## LTS and end-of-life + +The plugin is not abandoned silently. Three lifecycle states beyond "active": + +- **LTS.** A MAJOR may be designated long-term-support at release. LTS means: security fixes only, no new features, hold the line for the documented period (default: 12 months from the next MAJOR's release). State the LTS window in `CHANGELOG.md` under the LTS release's entry. +- **Maintenance mode.** Activity drops below quarterly cadence. Announce by updating the README's `## Status` block, opening an issue titled `MAINTENANCE MODE: `, and tagging the next release `vX.Y.Z-maintenance`. Adopters can keep using the baseline and forks; the maintainer accepts security fixes only. +- **End of life.** Sunset announced one MAJOR in advance. The final release ships a `DEPRECATED.md` at the plugin root naming any successor (fork, replacement plugin, or "use it as-is, no more updates"). Archive the GitHub repo. Do not delete it — adopter forks may still reference issues. + +Signal each transition in three places minimum: the README `## Status`, the changelog, and the latest release notes. Adopters discover lifecycle changes through whichever channel they read; redundancy is the point. + +## Open questions + +The maintainer should resolve these before the next MAJOR. + +- **Schema versioning timing.** Should `schema_version` land as an additive MINOR with a default of `1`, or wait for the next MAJOR? Earlier introduction makes future migrations cheaper but spends a field on something with no current consumer. +- **Adapter manifest.** Codex and Cursor have no native manifest. Is a `plugin-v2/adapters/manifest.md` worth introducing to make adapter parity machine-checkable? The drift policy currently relies on the maintainer's eyes. +- **Telemetry beyond `/goal:trace`.** `/goal:trace` reconstructs one iteration. A cross-iteration metrics surface (loops per goal, time-to-first-act, gate-rejection rate, amendment frequency) would inform retros — but it pulls the plugin toward stateful tooling. Decision deferred to the v2.x retrospective. +- **Hold-window length.** Two minor releases is the current floor. For adopters on annual upgrade cadences that may be too short. Consider extending to "two minors or six months, whichever is longer". +- **Constitution amendment numbering.** Amendments are currently dated and slugged; introducing `AMEND-NNNN` IDs would make traceability tighter but adds bookkeeping the constitution does not currently require. +- **External-contributor amendments.** Should non-maintainers be allowed to author constitution amendments, or only propose them via issue? The amendment template assumes a named human approver; the contribution model has not committed either way. + +## References + +- Tom Preston-Werner, *Semantic Versioning 2.0.0* (semver.org). MAJOR / MINOR / PATCH definitions. +- Olivier Lacan, *Keep a Changelog 1.1.0*. Six-category structure and human-readable principles. +- *Conventional Commits 1.0.0*. `feat` → MINOR, `fix` → PATCH, `BREAKING CHANGE` → MAJOR mapping. +- OWASP Foundation, *Top 10 for LLM Applications* (2025). Threat model anchor for the agentic security review. +- John Boyd, *Patterns of Conflict* (briefings, 1986). Origin of the OODA loop the plugin instantiates — relevant when auditing whether amendments respect tempo. +- RFC 9116, *A File Format to Aid in Security Vulnerability Disclosure* (`security.txt`). Optional but recommended for the consuming repo's security review surface. +- RFC 8594, *The Sunset HTTP Header Field*. Conceptual reference for the end-of-life signalling pattern. diff --git a/plugin-v2/docs/method.md b/plugin-v2/docs/method.md new file mode 100644 index 000000000..03898e2b7 --- /dev/null +++ b/plugin-v2/docs/method.md @@ -0,0 +1,274 @@ +--- +title: The Goal Loop — Method Definition +description: Canonical definition of the Goal Loop method that unifies goal-oriented orchestration with the OODA loop. +status: stable +version: 2.0.0 +--- + +# The Goal Loop + +> A goal-bounded OODA loop. A single, domain-agnostic pattern for driving any decision or delivery cycle under uncertainty, with structured human gates and parallel-capable execution. + +## What this is + +The Goal Loop is the unification of two complementary patterns: + +- **Goal-oriented orchestration** — set an explicit goal with constraints and acceptance criteria, then drive a structured resolution cycle toward it. +- **OODA loop** (Observe → Orient → Decide → Act, John Boyd) — a tempo-driven decision cycle proven in environments of uncertainty and incomplete information. + +The synthesis: a **goal** sets the *what* and *why*; the **OODA loop** is the *how*. The loop runs once for bounded problems (issue resolution) and continuously for ongoing situations (daily brief, incident triage, release readiness). + +The method is **domain-agnostic**. It assumes no programming language, no software-development context, and no fixed toolchain. Use it for code, content, research, operations, strategy, or any other knowledge work. + +## Core concepts + +### Goal + +A goal is the contract for a loop. It declares: + +- **Intent** — what outcome is wanted, in plain language. +- **Constraints** — what must not change, what limits apply (time, budget, scope). +- **Acceptance criteria** — observable, falsifiable conditions that decide "done". +- **Mode** — one-shot (close the loop after one Act+Review) or recurring (iterate until stopped). +- **Cadence** — for recurring goals: how often a loop runs. + +Goals live at `goals//goal-state.md`. The goal is mutable through structured amendments; ad-hoc redefinition is forbidden. + +### The four phases + +Each loop iteration runs through the seven values of the `current_phase` enum. The four execution phases (Observe, Orient, Decide, Act) each have a specialist subagent; Review closes the iteration; `scope` and `closed` bracket the loop and are owned by the `set-goal` skill and `goal-orchestrator` respectively. + +| `current_phase` | Owner | Writer of artifact | Artifact | +|---|---|---|---| +| `scope` | `set-goal` skill | `set-goal` skill | `goal-state.md` body sections (Intent, Constraints, Acceptance Criteria, Mode & Cadence, Observe Sources, Act Gate Policy) | +| `observe` | `observer` subagent (×N parallel) | `observer` | `observations/--.md` per declared source (the `--` suffix may be omitted only when exactly one source is declared) | +| `orient` | `orienter` subagent | `orienter` | `orientation.md` (refreshed) | +| `decide` | `decider` subagent | `decider` | `decisions.md` (appended) | +| `act` | `actor` subagent (×M parallel) | `actor` | `actions/iter-/.md` | +| `review` | `loop-reviewer` subagent | `loop-reviewer` | `reviews/.md` | +| `closed` | `goal-orchestrator` | `goal-orchestrator` | none — `## History` row records closure in `goal-state.md` | + +The seven values match the canonical `current_phase` enum locked in [`glossary.md`](glossary.md) §"Canonical enums" and the constitution's Article II §4. `scope` is the pre-iteration state (active after the goal gate, before the first Observe). `closed` is terminal (after `close-met` or `close-abandon`). The four execution phases run in order on every iteration; `review` runs once per iteration to decide continue / close / amend. + +The **`goal-orchestrator`** is the conductor across the whole table. It does no phase work itself — it gates, dispatches, persists `goal-state.md` transitions, and owns the move into `closed`. + +The `loop-reviewer` subagent: + +- Compares outcomes to acceptance criteria. +- Decides whether the goal is met, the loop should continue, or the goal should be amended. +- Writes `reviews/.md`. + +### The human gates + +Two gates are non-negotiable; others are configurable per goal. + +- **Goal gate** — the human signs off on the goal definition before the first loop runs. +- **Act gate** — the human approves the decision set before Act executes any irreversible action. Reversible, low-risk actions may be auto-approved when the goal declares so. + +Other gates (between Orient↔Decide, between Decide↔Act for reversible actions, etc.) are opt-in per goal. + +### Parallelism + +The Observe phase is the natural parallel point. A goal can declare **N parallel observers** by source (one per repo, one per data feed, one per channel). The orchestrator dispatches them concurrently and merges their outputs before Orient runs. + +Act can also fan out when the decided action set has independent items; the orchestrator dispatches one `actor` per action and reduces. + +### Loop closure + +After Review, one of four outcomes: + +- **Closed — met** → goal acceptance criteria satisfied; mark `status: done`. +- **Closed — abandoned** → goal no longer worth pursuing; mark `status: cancelled` with rationale. +- **Continue** → start next iteration (re-enter Observe). +- **Amend** → revise goal definition (human-approved), then continue. + +### Hard-stop gates + +Three pre-declared caps bound the loop's lifetime against the three canonical death-spiral shapes (see [`research-goal-oriented-ai.md` §H-3](research-goal-oriented-ai.md)). Each cap is optional frontmatter on `goal-state.md`; defaults apply when omitted. + +| Cap | Default | Shape it prevents | +|---|---|---| +| `max_iterations` | `25` | **Time spiral** — the loop runs without converging. Recurring goals can raise this; one-shot goals rarely need >5. | +| `max_consecutive_rejects` | `3` | **Decision spiral** — the decider keeps proposing acts the human keeps rejecting. Signals a mis-scoped goal, not a tactical fix. Resets when any decision is approved. | +| `max_failed_acts` | `5` | **Act spiral** — actors keep `status: failed`. An upstream problem (decision, observation, or goal) is more likely than another retry. Counted across the goal's lifetime. | + +The orchestrator recomputes counters at every phase transition and refreshes `## Health` in `goal-state.md`. Two thresholds apply: + +- **80% of any cap** (`approaching-cap`) — the orchestrator surfaces `AskUserQuestion` with four choices: continue with acknowledged risk, raise the cap via `/goal:amend`, pause the goal, or close-abandon with rationale. +- **100% of any cap** (`at-cap`) — the loop **must stop**. The orchestrator does not dispatch the next phase regardless of human preference. The only escape is `/goal:amend ` to raise the cap (leaves an audit trail) or `/goal:close close-abandon` (records rationale; positional outcome syntax per `commands/goal/close.md` — no `--abandon` flag). + +The 100% gate is constitutional — [Article VI Loop Discipline](../memory/constitution.md) forbids the orchestrator from iterating past a declared cap without a recorded amendment. See [`agents/goal-orchestrator.md`](../agents/goal-orchestrator.md) §"Hard-stop gate evaluation". + +## The full loop + +``` + ┌────────────────────────────┐ + │ scope (set-goal owns) │ + │ pre-iteration state │ + └──────────────┬─────────────┘ + ▼ + ┌────────────────────────────┐ + │ GOAL │ + │ intent + constraints + │ + │ acceptance + mode │ + └──────────────┬─────────────┘ + │ (human-signed) + ▼ + ┌──────────────────────┐ + │ goal-orchestrator │ + │ conductor / gating │ + └──────────┬───────────┘ + │ + ┌────────────────────────┼─────────────────────────┐ + ▼ ▼ ▼ + ┌────────────────┐ ┌────────────────┐ ┌────────────────┐ + │ OBSERVE │ ───▶ │ ORIENT │ ───▶ │ DECIDE │ + │ observer × N │ │ orienter │ │ decider │ + │ parallel scan │ │ synthesise vs │ │ rank options, │ + │ raw signals │ │ goal+history │ │ propose set │ + └────────────────┘ └────────────────┘ └────────┬───────┘ + ▲ ▲ │ + ┊ ┊ (D2: rejection ┄┄┄┄┄┄┘ + ┊ ┊ re-orients before next Decide) + ┊ ┊ + ┊ ┊ ▼ + ┊ ┊ human gate (Act) + ┊ ┊ │ + ┊ ┊ ▼ + ┊ ┊ ┌────────────────┐ + ┊ └┄┄┄┄┄┄┄┄┄┄┄┄│ ACT │ + ┊ │ actor × M │ + ┊ (D2: mid-iter │ execute │ + ┊ action │ approved set │ + ┊ results └────────┬───────┘ + ┊ re-orient) │ + ┊ ▼ + ┊ ┌────────────────┐ + ┊ │ REVIEW │ + ┊ │ loop-reviewer │ + ┊ │ vs acceptance │ + ┊ └────────┬───────┘ + ┊ │ + ┌────────┊────────────────────────┼───────────────────────────┐ + ▼ ┊ ▼ ▼ + Continue ┄┄┄┄┘ Close Amend + (re-enter Observe; (status: done|cancel, (human-approved → + loop-reviewer back-edge) current_phase: closed) scope re-entry) +``` + +**Legend.** Solid `───▶` = canonical forward chain (Observe → Orient → Decide → Act → Review). Dashed `┄┄▶` / `┄┄┄┄` = back-edges that feed orientation: **Decide → Orient** (a rejected decision is information about orientation — see [`ooda-foundations.md`](ooda-foundations.md) §"What Boyd's actual diagram looks like"), **Act → Orient** (mid-iteration action results re-shape the picture before remaining actions run), and the **Review → Observe** continue-loop. The Mermaid version below is the simplified forward-chain view. + +> **Modern renderer / mobile?** The same flow as a Mermaid diagram: + +```mermaid +flowchart TD + scope[scope
set-goal owns] --> goal["GOAL
intent + constraints +
acceptance + mode"] + goal -->|human-signed| orch[goal-orchestrator
conductor / gating] + orch --> obs[OBSERVE
observer × N
parallel scan] + obs --> ori[ORIENT
orienter
synthesise vs
goal + history] + ori --> dec[DECIDE
decider
rank options] + dec -->|human gate Act| act[ACT
actor × M
execute approved set] + act --> rev[REVIEW
loop-reviewer
vs acceptance] + rev -->|continue| obs + rev -->|close-met / close-abandon| closed[closed
status: done / cancelled] + rev -->|amend| goal +``` + +The ASCII version above remains canonical; the Mermaid version renders on GitHub, Obsidian, and mobile readers that support it. + +## Use-case patterns + +The loop is the same; the goal shape and cadence differ. + +### Issue resolution (one-shot, bounded) + +A user submits a problem. The orchestrator runs the intake skill to define the goal with acceptance criteria, then drives one iteration of Observe → Orient → Decide → Act → Review. Loop closes when acceptance criteria are met. Maps to the original "Goal-Oriented Orchestrator" pattern. + +### Daily brief (recurring, awareness) + +A user wants to know what to do today. The goal is "stay oriented across project X". The loop runs on cadence (manual or scheduled). Observe scans configured sources; Orient compares to prior brief; Decide proposes today's actions; Act is opt-in. Each run writes `brief.md` and an archived dated copy. Maps to the original "OODA Loop" pattern. + +### Incident triage (rapid, time-critical) + +Goal: "restore service X to baseline". The loop runs at compressed tempo with reduced gates (Act gate may be pre-authorised for runbook actions). Each iteration is short; the loop continues until acceptance is met or escalation triggers. + +### Release readiness (checklist, gated) + +Goal: "ship release v1.2.3". Acceptance is a checklist (tests green, CHANGELOG updated, sign-offs collected). The loop runs once when invoked, surfaces gaps, and proposes actions to close them. Closes when all checklist items are green. + +### Continuous awareness (perpetual) + +Goal: "keep me oriented on the competitive landscape" / "monitor regulatory changes". Recurring loop with persistent orientation memory. Act is usually opt-in or human-only. + +The plugin ships these as worked examples; users define their own goal shapes by combining mode, cadence, observe sources, and act gates. + +## State model + +All state for a goal lives under `goals//`: + +``` +goals// +├── goal-state.md # canonical goal + current phase + iteration counter +├── observations/ +│ └── 2026-05-16T10-00-00.md +├── orientation.md # current synthesis (overwritten each iteration; history in archive/) +├── decisions.md # appended log of decision sets +├── actions/ +│ └── iter-/ +│ └── .md # one file per executed action; namespaced by iteration to prevent overwrite of prior cycles when action ids repeat (a-1, a-2, …) +├── reviews/ +│ └── 2026-05-16T10-30-00.md +├── brief.md # current brief (recurring goals only) +├── health.md # rolling per-goal observability record (orchestrator-only) +└── archive/ # rolled history for long-running goals +``` + +**Two-writer ownership of `goal-state.md`** (clarified by the 2026-05-16 amendment — see [`memory/amendments/2026-05-16-goal-state-two-writer-ownership.md`](../memory/amendments/2026-05-16-goal-state-two-writer-ownership.md) and [Article II §2](../memory/constitution.md)): the **`set-goal`** skill writes the body sections at creation and during amend mode (Intent, Constraints, Acceptance Criteria, Mode & Cadence, Observe Sources, Act Gate Policy). The **`goal-orchestrator`** subagent writes the frontmatter transitions (`status`, `current_phase`, `iteration`, `updated_at`, `goal_signed_off`, `last_review`, `lock`, hard-stop-cap counters) and the `## History` table. Phase agents (`observer`, `orienter`, `decider`, `actor`, `loop-reviewer`) **read** `goal-state.md` but never write it. The full mapping lives in [`../skills/_shared/goal-state.md`](../skills/_shared/goal-state.md) §"Ownership matrix". Each phase agent writes only its own phase artifacts under `goals//` and never edits others. + +Per-goal observability: `goals//health.md` (rolling snapshot of counters and trend; refreshed by orchestrator on every phase transition). + +## Quality gates + +Non-negotiable: + +- **Goal completeness** — `goal-state.md` declares intent, constraints, acceptance, mode, cadence (if recurring), and observe sources before the first iteration runs. +- **Goal length cap** — the body of `goal-state.md` and of `session-goals/.md` is capped at 3500 characters (frontmatter excluded). A goal that needs more is usually doing too much. Enforced by `scripts/check-goal-length.sh`; surfaced by `set-goal` and `create-goal` at write time. +- **Phase isolation** — each phase agent writes only its own artifacts. +- **Act audit** — every executed action records what was done, what changed, and what was skipped. +- **Acceptance trace** — Review references each acceptance criterion explicitly. + +Opt-in: + +- **Parallel-observer dedup** — when N observers run, the orienter must surface and resolve duplicates. +- **Decision rationale** — each proposed action carries a one-line rationale and confidence rating. + +## Relationship to other patterns + +- **Spec-driven development** — orthogonal. A spec-driven feature can be the goal of a loop, with the loop driving its phases. +- **Discovery sprints** — Discovery (Frame → Diverge → Converge → Prototype → Validate) is a heavier upstream pattern for unbounded problem-space exploration. Goal Loop assumes the problem space is at least partially scoped. +- **Project management** — a project can be a long-running goal with iterations as its rhythm; Goal Loop does not replace PM ceremony, it complements it. + +The plugin does not bundle these patterns; users compose. + +## Naming reference (locked vocabulary) + +These names are used verbatim across all plugin artifacts. Sub-agents authoring plugin content must not invent synonyms. + +| Concept | Canonical name | +|---|---| +| The method | Goal Loop | +| The plugin | `goal-loop` | +| Conductor agent | `goal-orchestrator` | +| Phase agents | `observer`, `orienter`, `decider`, `actor`, `loop-reviewer` | +| State root | `goals//` | +| State file | `goal-state.md` | +| Brief file (recurring) | `brief.md` | +| Slash-command namespace | `/goal:` | +| Skill namespace (top-level) | `goal-loop` | +| Phase skills | `observe`, `orient`, `decide`, `act`, `review-loop`, `set-goal` | + +## Non-goals + +- The plugin **does not** prescribe a deployment model. Loops can run interactively, on cron, or via external orchestration. +- The plugin **does not** ship MCP servers or external tool integrations. Adapters reference standard tool surfaces (Read, Edit, Write, Bash, Grep, WebSearch, WebFetch) only. +- The plugin **does not** assume software-engineering context. Examples include software cases because that is the maintainer's home turf, but the method applies broadly. diff --git a/plugin-v2/docs/non-negotiable-guarantees.md b/plugin-v2/docs/non-negotiable-guarantees.md new file mode 100644 index 000000000..46ef7752b --- /dev/null +++ b/plugin-v2/docs/non-negotiable-guarantees.md @@ -0,0 +1,74 @@ +--- +title: Goal Loop — Non-negotiable guarantees +folder: plugin-v2/docs +description: The contracts the plugin promises to honour. Distilled from the constitution and the ownership matrix; each guarantee cites the article and the implementation surface that backs it. +entry_point: false +--- + +# Goal Loop — Non-negotiable guarantees + +This doc consolidates the plugin's hard promises into a single page. It does not replace [`../memory/constitution.md`](../memory/constitution.md); it makes the constitution legible at a glance for adopters, auditors, and security reviewers. Every guarantee below cites the constitution article it derives from and the implementation surface (agent, skill, command, or contract file) that refuses to violate it. If you find behaviour that contradicts one of these, treat it as a defect, not an edge case. + +## The thirteen guarantees + +1. **The plugin will never run a phase agent without a human-signed goal.** + *Backing article:* [`Article I — Goal Primacy`](../memory/constitution.md), §1–3 (every loop runs against an explicit goal recorded in `goal-state.md`; no phase agent runs until the goal gate is human-signed). + *Enforcement surface:* [`skills/set-goal/SKILL.md`](../skills/set-goal/SKILL.md) holds the goal gate at sign-off; [`agents/goal-orchestrator.md`](../agents/goal-orchestrator.md) §Procedure step 3 blocks dispatch until `goal_signed_off: true` is recorded in `goal-state.md`. + +2. **The plugin will never execute an irreversible action without explicit human approval, regardless of `act_gate` policy.** + *Backing article:* [`Article III — Human Gates`](../memory/constitution.md), §2 (the act gate is non-negotiable for irreversible actions; `low-risk-auto` covers reversible actions only). + *Enforcement surface:* [`agents/decider.md`](../agents/decider.md) §Procedure step 6 forces `reversible: N` when in doubt; [`skills/decide/SKILL.md`](../skills/decide/SKILL.md) is the sole writer of the `## Human Approval` section; [`agents/actor.md`](../agents/actor.md) §Procedure step 1 refuses to mutate state without that section recording approval. + +3. **The plugin will never write a phase artifact from outside that phase's agent.** + *Backing article:* [`Article II — Phase Isolation`](../memory/constitution.md), §1–3 (each phase has one writer; no agent edits another agent's artifacts). + *Enforcement surface:* [`skills/_shared/goal-state.md`](../skills/_shared/goal-state.md) §Ownership matrix locks the writer per artifact; every agent's `## Boundaries` section repeats the rule for its own file set; the automation pipeline's [`automation-spec.md`](automation-spec.md) §B5 (`verify.phase-isolation`) flags violations at PR time. + +4. **The plugin will never carry an orientation claim without an observation citation.** + *Backing article:* [`Article IV — Evidence-Based Orientation`](../memory/constitution.md), §1 (every claim in `orientation.md` cites an observation by file and signal index). + *Enforcement surface:* [`agents/orienter.md`](../agents/orienter.md) §Procedure (each claim traces to a signal); [`templates/orientation-template.md`](../templates/orientation-template.md) `## Signal map` (mandatory citation column); [`agents/loop-reviewer.md`](../agents/loop-reviewer.md) §Procedure rejects orientation claims lacking citations. Speculation belongs in `## Open Questions` / `## Contradictions`, not in load-bearing claims. + +5. **The plugin will never silently amend a goal.** + *Backing article:* [`Article I — Goal Primacy`](../memory/constitution.md), §4 (ad-hoc redefinition is forbidden; goals change through structured amendment only). + *Enforcement surface:* [`skills/set-goal/SKILL.md`](../skills/set-goal/SKILL.md) amend mode plus the dedicated [`commands/goal/amend.md`](../commands/goal/amend.md) entry point re-run the goal gate; [`agents/goal-orchestrator.md`](../agents/goal-orchestrator.md) §Procedure step 8 refuses to edit `## Intent` / `## Constraints` / `## Acceptance Criteria` outside an `amend` outcome. + +6. **The plugin will never close a goal without acceptance-criteria evidence.** + *Backing article:* [`Article X — Closure Honesty`](../memory/constitution.md), §1–3 (`close-met` requires evidence against each criterion; partial / unknown verdicts block closure). + *Enforcement surface:* [`agents/loop-reviewer.md`](../agents/loop-reviewer.md) §Procedure steps 2–3 require per-criterion verdicts (`met` / `partial` / `unmet` / `blocked`) with linked evidence; [`skills/review-loop/SKILL.md`](../skills/review-loop/SKILL.md) routes only `close-met` to `status: done` and refuses to confuse abandonment with completion. + +7. **The plugin will never run a destructive command speculatively.** + *Backing article:* [`Article V — Reversibility Bias`](../memory/constitution.md), §2 (every irreversible action carries a rollback plan; no rollback plan, no execution) and [`Article IX — Escalate, Don't Invent`](../memory/constitution.md). + *Enforcement surface:* [`agents/actor.md`](../agents/actor.md) §Boundaries forbids destructive commands outside the approved action spec; [`automation-spec.md`](automation-spec.md) §F3 (`security.no-destructive-bash`) blocks the pattern set (`rm -rf`, `git push --force`, `git reset --hard`, `curl … | sh`, etc.) at lint time. + +8. **The plugin will never schedule its own runs.** + *Backing article:* [`Article VII — Domain Neutrality`](../memory/constitution.md) (the plugin serves any cadence; cadence is informational). + *Enforcement surface:* [`improvement-strategy.md`](improvement-strategy.md) §Anti-patterns #2 ("a scheduler daemon") fixes the posture: the plugin ships scheduler *recipes*, not a scheduler. [`cadence-recipes.md`](cadence-recipes.md) documents adopter-owned cron / Actions / systemd entries; no plugin code starts a timer. + +9. **The plugin will never auto-merge, push, or publish on the user's behalf.** + *Backing article:* [`Article III — Human Gates`](../memory/constitution.md), §2 plus [`Article V — Reversibility Bias`](../memory/constitution.md), §1. + *Enforcement surface:* [`improvement-strategy.md`](improvement-strategy.md) §Anti-patterns #1 ("an auto-merge plugin") and #6 ("an MCP server host") lock the posture; [`agents/actor.md`](../agents/actor.md) §Boundaries refuses scope expansion; no slash command exists for unsupervised merge / push / publish. + +10. **The plugin will never fabricate observations, decisions, or approvals.** + *Backing article:* [`Article IX — Escalate, Don't Invent`](../memory/constitution.md), §1–3 and [`Article VIII — Transparency`](../memory/constitution.md), §2 (skipped / deferred / rejected items are recorded with rationale, not silently dropped). + *Enforcement surface:* every phase agent's `## Boundaries` section includes a "do not invent" clause; [`agents/observer.md`](../agents/observer.md) records empty-source results as `no signals` rather than padding; [`agents/decider.md`](../agents/decider.md) §Procedure step 10 forbids scaffolding the `## Human Approval` section without the gate clearing. + +11. **The plugin will never broaden an agent's tool list silently.** + *Backing article:* [`Article II — Phase Isolation`](../memory/constitution.md) and [`Article VI — Agent Specialisation`](../memory/constitution.md) (tool restrictions are deliberate; do not broaden without an amendment). + *Enforcement surface:* [`customizing.md`](customizing.md) §"subagent tool-list rule" — narrowing is fine, broadening requires an amendment; [`maintenance.md`](maintenance.md) §"Security review" runs a per-release agent-surface audit; [`automation-spec.md`](automation-spec.md) §B7 (`verify.tool-list-discipline`) enforces consistency between declared `tools:` and procedure verbs at PR time. + +12. **The plugin will never iterate past a declared hard-stop cap without an explicit amendment.** + *Backing article:* [`Article VI — Loop Discipline`](../memory/constitution.md), §1–4 (one iteration at a time; phases run in order; sequencing is the orchestrator's responsibility). + *Enforcement surface:* [`agents/goal-orchestrator.md`](../agents/goal-orchestrator.md) §"Hard-stop gate evaluation" forces the loop to close at 100% of any cap; [`templates/goal-state-template.md`](../templates/goal-state-template.md) §Health records the counters; [`docs/method.md`](method.md#hard-stop-gates) §"Hard-stop gates" documents the contract. The only escape is `/goal:amend ` to raise the cap (recorded amendment) or `/goal:close close-abandon` (recorded rationale). + +13. **The plugin will never run a goal without a one-page card summarising what it does, who owns it, and what it cannot do.** + *Backing article:* [`Article VIII — Transparency`](../memory/constitution.md), §1–4 (every decision and every action is logged; evidence is linked; the trail must reconstruct the reasoning end-to-end). + *Enforcement surface:* [`templates/goal-card-template.md`](../templates/goal-card-template.md) defines the card shape; the `set-goal` skill scaffolds it at creation; [`/goal:amend`](../commands/goal/amend.md) refreshes it on amendment; the card is the auditor's first surface and the adopter's elevator pitch. One [`observe-source-datasheet`](../templates/observe-source-datasheet-template.md) accompanies the card per declared source. Without a card, an outside reviewer cannot understand what the goal claims — making Article VIII unenforceable in practice. + +## Cross-references + +- [`../memory/constitution.md`](../memory/constitution.md) — the ten articles every guarantee is read against. +- [`../skills/_shared/goal-state.md`](../skills/_shared/goal-state.md) — the ownership matrix backing guarantees 3 and 5. +- [`threat-model.md`](threat-model.md) — OWASP-aligned threat surface; pairs guarantees with the attacks they defend against. +- [`tool-matrix.md`](tool-matrix.md) — per-agent tool list audit backing guarantee 11. +- [`automation-spec.md`](automation-spec.md) — the PR-time check ids that mechanise these guarantees. +- [`maintenance.md`](maintenance.md) §"Security review" — the cadence on which the maintainer re-audits these guarantees. +- [`improvement-strategy.md`](improvement-strategy.md) §"Anti-patterns" — the ten things the plugin must never become, paired one-to-many with the guarantees above. diff --git a/plugin-v2/docs/obsidian-compatibility.md b/plugin-v2/docs/obsidian-compatibility.md new file mode 100644 index 000000000..6e81f77a4 --- /dev/null +++ b/plugin-v2/docs/obsidian-compatibility.md @@ -0,0 +1,459 @@ +--- +title: Goal Loop — Obsidian compatibility +folder: plugin-v2/docs +description: How the plugin's output integrates with Obsidian vaults — frontmatter properties, links, tags, file naming, and the conventions that keep artifacts vault-friendly without adopting any Obsidian-specific plugin. +entry_point: false +--- + +# Obsidian compatibility + +> The plugin produces plain-Markdown artifacts that work in any editor, but it is **designed to be Obsidian-vault-native**. This doc lists the conventions the plugin honours and the adopter-side setup that makes the most of them. + +The Goal Loop's value depends on the audit trail. Obsidian turns that trail into a queryable graph for free — backlinks across every History row, tag-faceted portfolio views, embedded orientation summaries inside a brief, a graph of which observation feeds which decision. None of that requires writing Obsidian-plugin code. It only requires honouring a handful of conventions in the Markdown the plugin already emits. + +## Goals and non-goals + +**Goals.** Make `goals//` a first-class Obsidian sub-vault. An adopter should be able to (a) open the project root as a vault, (b) see every goal artifact render correctly in Reading view, Live Preview, and Source mode, (c) get backlinks across observation → orientation → decision → action → review without lifting a finger, (d) drop in Dataview or Bases for portfolio rollups, (e) work from mobile without filename or sync surprises. + +**Non-goals.** The plugin does not ship Obsidian-plugin code. It does not depend on Templater, Dataview, Bases, Periodic Notes, or any other community plugin. It does not require the adopter to enable wikilinks — Markdown links are the default and remain authoritative for tool portability. None of the Obsidian-specific surface (callouts, embeds, block IDs) is mandatory; everything degrades cleanly to plain CommonMark + GFM for editors that do not speak Obsidian Flavored Markdown. + +## The compatibility contract + +The plugin guarantees the following about every artifact under `goals//`: + +1. **Pure UTF-8 Markdown.** No HTML wrappers around content. Obsidian does not render Markdown inside HTML elements ([Obsidian Flavored Markdown — Obsidian Help](https://obsidian.md/help/obsidian-flavored-markdown)); the plugin therefore keeps callout titles, table cells, and list items as plain Markdown. +2. **YAML frontmatter on every artifact.** Field order is not significant; presence is. Types map 1:1 to Obsidian's Properties data types ([Properties — Obsidian Help](https://obsidian.md/help/properties)). +3. **Cross-platform safe filenames.** No character in the universal-forbidden set `[ ] # ^ |`, no `: \ / * " < > ?`, no leading dot. See [forbidden filename characters — Obsidian Forum](https://forum.obsidian.md/t/list-of-all-forbidden-filename-characters/103977). +4. **Relative Markdown links.** Every internal reference uses `[text](path)` with a path relative to the linking file. Wikilinks are optional and adopter-controlled. +5. **One artifact per file.** No multi-document YAML, no concatenated journals. Each observation, action log, review, and brief is its own file so backlinks resolve to a single node. +6. **CommonMark + GFM body.** Tables, task lists, strikethrough, fenced code blocks, autolinks. Nothing in body content relies on a community plugin. + +If an artifact violates any of these, that is a defect in the plugin, not in the vault setup. + +## Property types in the plugin's frontmatter + +Obsidian recognises six property types — Text, List, Number, Checkbox, Date (`YYYY-MM-DD`), Date & Time (`YYYY-MM-DDTHH:MM:SS`) — plus the reserved Tags type bound to `tags` ([Properties — Obsidian Help](https://obsidian.md/help/properties); [Front matter format changes in Obsidian 1.9 — actions.work Forum](https://forum.actions.work/t/front-matter-format-changes-in-obsidian-1-9-and-how-to-deal-with-them/671)). The reserved plural names are `tags`, `aliases`, `cssclasses`; the singular forms `tag`, `alias`, `cssclass` were deprecated in Obsidian 1.9. + +Below: every frontmatter field across the plugin's templates and the property type Obsidian will infer. + +### `goal-state.md` + +| Field | Obsidian type | YAML shape | Notes | +|---|---|---|---| +| `slug` | Text | bare string | Kebab-case. Must equal the folder name. | +| `intent` | Text | quoted string | Quote if it contains `:` or `#`. | +| `constraints` | List | block list `- item` | Each item is plain text. | +| `acceptance_criteria` | List | block list `- item` | Each item is falsifiable. | +| `mode` | Text | bare string | `one-shot` or `recurring`. | +| `cadence` | Text | bare string or `null` | Use `null` for one-shot. | +| `observe_sources` | List of objects | block sequence of mappings | Each item has `id`, `type`, `target`. Indexed by Dataview as an object array. | +| `act_gate` | Text | bare string | `always`, `low-risk-auto`, or `never`. | +| `status` | Text | bare string | `draft` / `active` / `paused` / `blocked` / `done` / `cancelled`. | +| `current_phase` | Text | bare string | `scope` / `observe` / `orient` / `decide` / `act` / `review` / `closed`. | +| `iteration` | Number | bare integer | Starts at `0`. | +| `goal_signed_off` | Checkbox | `true` / `false` | Boolean. | +| `created_at` | Date & Time | ISO-8601 timestamp | `YYYY-MM-DDTHH:MM:SSZ`. Obsidian parses this as Date & Time when the time component is present. | +| `updated_at` | Date & Time | ISO-8601 timestamp | Same. | +| `escalation_contact` | Text | optional string | Quote if it contains a comma — Obsidian splits unquoted commas in alias-like contexts ([YAML commas in quoted values — Obsidian Forum](https://forum.obsidian.md/t/yaml-entry-with-commas-within-quotation-marks-should-produce-a-single-entry/19046)). | +| `parallel_observe` | Checkbox | `true` / `false` | Optional. | +| `parallel_act` | Checkbox | `true` / `false` | Optional. | +| `last_review` | Text | quoted string | Path. Quote because it contains `/`. | + +### `observation-template.md`, `orientation-template.md`, `decision-template.md`, `action-log-template.md`, `review-template.md`, `brief-template.md` + +| Field | Type | Notes | +|---|---|---| +| `goal_slug` | Text | Backlink target — see "Aliases" below. | +| `iteration` | Number | Index for Dataview `GROUP BY`. | +| `observer_id`, `source_id`, `action_id` | Text | Free-form ids. | +| `started_at`, `ended_at`, `synthesised_at`, `proposed_at`, `reviewed_at` | Date & Time | ISO-8601 with time. | +| `brief_date` | Date | `YYYY-MM-DD` only — pairs cleanly with the Daily Notes plugin's default format. | +| `status` (action log) | Text | `done` / `partial` / `stopped` / `blocked` / `failed`. | +| `outcome` (review) | Text | `continue` / `close-met` / `close-abandon` / `amend`. | + +### Three YAML gotchas every template avoids + +1. **Unquoted colons.** Anything containing `:` outside an ISO timestamp must be quoted. The plugin always quotes `intent` and `target` strings. ([YAML Rules — Linter](https://platers.github.io/obsidian-linter/settings/yaml-rules/)) +2. **Bare booleans that look like words.** Obsidian YAML interprets `yes`, `no`, `on`, `off`, `true`, `false` as booleans. The plugin never uses these as list values; if you extend it, quote them. +3. **Commas inside quoted strings.** A historic Obsidian quirk splits comma-separated alias entries even inside quotes ([YAML commas in quoted values — Obsidian Forum](https://forum.obsidian.md/t/yaml-entry-with-commas-within-quotation-marks-should-produce-a-single-entry/19046)). The plugin uses block-list YAML (`- item` on separate lines) wherever items might contain commas. + +## Tags + +Obsidian tags are `#tag` inline or a frontmatter `tags:` list ([Tags — Obsidian Help](https://obsidian.md/help/tags)). They support hierarchical namespaces via `/`, e.g. `#goal-loop/phase/observe`. Valid characters: letters, numbers, `_`, `-`, `/`, Unicode, emoji. They must contain at least one alphabetic character (purely numeric tags are invalid). + +The plugin is opinionated about a small set of canonical tags. Adopters are free to add their own; the plugin will not strip them. + +### Canonical tag namespace + +| Tag | Where it appears | Purpose | +|---|---|---| +| `goal-loop/artifact/goal-state` | `goal-state.md` | Marks the canonical state file. | +| `goal-loop/artifact/observation` | observations | Indexes raw signal sets. | +| `goal-loop/artifact/orientation` | `orientation.md` | Marks the current synthesis. | +| `goal-loop/artifact/decision` | `decisions.md` | Marks the decision log. | +| `goal-loop/artifact/action` | action logs | Indexes executed actions. | +| `goal-loop/artifact/review` | reviews | Indexes per-iteration verdicts. | +| `goal-loop/artifact/brief` | `brief.md` | Marks the periodic brief. | +| `goal-loop/artifact/lessons` | `lessons.md` | Marks the closure retrospective. | +| `goal-loop/phase/` | every per-iteration artifact | `observe`, `orient`, `decide`, `act`, `review`. | +| `goal-loop/status/` | `goal-state.md` | `draft`, `active`, `paused`, `blocked`, `done`, `cancelled`. Mirrors the `status` frontmatter field for tag-faceted graph views. | +| `goal-loop/mode/` | `goal-state.md` | `one-shot`, `recurring`. | +| `goal-loop/outcome/` | reviews | `continue`, `close-met`, `close-abandon`, `amend`. | +| `goal-loop/gate/` | `goal-state.md` | `always`, `low-risk-auto`, `never`. | + +Tags ride in frontmatter as a YAML list, not inline. Reading via the Tags pane is the same; the YAML form keeps body text uncluttered. + +```yaml +tags: + - goal-loop/artifact/goal-state + - goal-loop/status/active + - goal-loop/mode/recurring +``` + +The plugin **does not** require adopters to enable any tag. Removing a tag does not break the loop. The tags exist so portfolio rollups (Dataview, Bases, native search) work out-of-the-box. + +## Aliases and titles + +Every `goal-state.md` carries an `aliases` list with the goal's `intent` as a one-line alias: + +```yaml +aliases: + - "Resolve wiki-redirect 404s within one working day" +``` + +This lets a reader type `[[Reso...` in any note and autocomplete to the goal-state file by intent rather than by slug. Aliases also surface in the search palette and in unlinked-mentions backlinks. + +The plugin does not set `aliases` on per-iteration artifacts; their identity is structural (iteration + phase) and they are reached via backlinks from the goal-state, not by name. + +## Links and embeds + +Obsidian supports two link forms: wikilinks (`[[file]]`) and Markdown links (`[text](path)`). Both produce backlinks and graph edges ([Internal links — Obsidian Help](https://obsidian.md/help/link-notes); [Wikilink vs Markdown — Obsidian Forum](https://forum.obsidian.md/t/wikilink-vs-markdown-the-latter-suffers-from-lack-of-support/86920)). The plugin emits Markdown links because they survive outside Obsidian (Codex, Cursor, GitHub, plain editors, static-site generators). Wikilinks are not forbidden — adopters who want them can rewrite via Obsidian's built-in command "Format → Convert link to wikilink". + +### When the plugin uses links + +| Where | Link target | Form | +|---|---|---| +| `goal-state.md` `## History` `artifact` column | the artifact the row produced (goal-relative path per the canonical row format) | `[observations/2026-01-15T09-00-00--issue-thread.md](observations/2026-01-15T09-00-00--issue-thread.md)` (per-source; single-source goals may omit the `--` suffix) | +| `orientation.md` evidence citations | observation files | `[obs](observations/...md)` plus signal index in the link text | +| `decisions.md` rationale citations | orientation | `[orientation.md](orientation.md)` | +| Action logs "What Was Approved" | decision-set id | `[decisions.md#ds-iter1-...](decisions.md#ds-iter1-...)` | +| Reviews evidence column | action logs | `[a-1](actions/iter-1/a-1.md)` | +| `INDEX.md` roster | per-goal folder | `[wiki-redirect-fix/](wiki-redirect-fix/)` | + +### Heading and block references + +Obsidian's `[[Note#Heading]]` and `[[Note^block-id]]` are Obsidian-only — they do not work in plain readers ([Link to blocks — Obsidian Help](https://help.obsidian.md/How+to/Link+to+blocks); [Block reference compatibility — Obsidian Forum](https://forum.obsidian.md/t/making-heading-and-block-reference-more-compatible-with-other-editors/7810)). The plugin uses Markdown fragment links instead: `[orientation summary](orientation.md#summary)`. Most Markdown renderers resolve heading anchors via slugification (`## What's New` → `#whats-new`), and Obsidian resolves heading fragments the same way. Block-id references (`^id`) are not emitted by the plugin. + +### Embeds + +Obsidian's `![[file]]` and `![[file#heading]]` syntax embeds content inline in Reading view and Live Preview ([Embed file preview — Obsidian Forum](https://forum.obsidian.md/t/embed-file-preview/73646)). This is a powerful tool for a goal brief: the `brief.md` template can embed the current orientation summary so the brief stays in sync without copy-paste. + +The plugin **does not** emit embed syntax in its default templates — embeds are Obsidian-only and would render as raw `![[...]]` text in Codex or Cursor. Adopters who want them can edit the brief template locally; the addition is non-destructive. A worked example for adopters: + +```markdown +## Current orientation summary + +![[orientation.md#summary]] +``` + +In Reading view this inlines the synthesis. In Codex it renders as a literal `![[orientation.md#summary]]` token — visible but not actionable. Choose embeds only when the vault is the primary reader. + +### Wiki-link config recommendation + +For adopters who want the strongest Obsidian experience without the plugin emitting wikilinks, the recommended vault settings are: + +- **Settings → Files & Links → Use [[Wikilinks]]** = off. Forces Obsidian to author Markdown links when the user creates new ones (matching the plugin's emit shape). ([Settings: New Link Format — Obsidian Forum](https://forum.obsidian.md/t/settings-new-link-format-what-is-shortest-path-when-possible/6748)) +- **Settings → Files & Links → New link format** = `Relative path to file`. Matches the plugin's relative-path convention so links round-trip through rename refactors without churn. +- **Settings → Files & Links → Automatically update internal links** = on. Renames inside the vault propagate into existing links. + +## File and folder naming + +Obsidian's filename rules are the cross-platform intersection ([forbidden characters — Obsidian Forum](https://forum.obsidian.md/t/list-of-all-forbidden-filename-characters/103977); [forbidden file names — Obsidian Forum](https://forum.obsidian.md/t/forbidden-file-names/112191)): + +- **Always forbidden:** `[`, `]`, `#`, `^`, `|`. Filename must not begin with a dot. +- **macOS / iOS / iPadOS / Linux:** `\`, `/`, `:`. +- **Windows:** `*`, `"`, `\`, `/`, `<`, `>`, `:`, `|`, `?`. +- **Android:** `\`, `/`, `:`, `*`, `?`, `<`, `>`, `"`. + +### How the plugin's existing patterns map + +| Pattern the plugin emits | Cross-platform safe? | Notes | +|---|---|---| +| `goals//goal-state.md` | yes | Slugs are kebab-case ASCII. | +| `observations/2026-05-16T10-00-00--.md` (or `.md` for single-source goals) | yes | ISO timestamp with `-` substituted for `:` to satisfy macOS / iOS / Windows. The plugin already replaces colons; this is the reason. The per-source `--` suffix is canonical for multi-source goals. | +| `orientation.md`, `decisions.md`, `brief.md` | yes | Plain ASCII. | +| `actions/iter-1/a-1.md`, `actions/iter-/.md` | yes | Action ids are kebab-case ASCII; `iter-/` subdirectory disambiguates ids across iterations of recurring goals. | +| `reviews/2026-05-16T10-30-00.md` | yes | Same ISO-with-dashes pattern. | +| `archive/.md` | yes | Free-form, but adopters must avoid the forbidden set. | +| `INDEX.md` (goals roster) | yes | Plain ASCII. | +| `lessons.md` | yes | Plain ASCII. | + +The ISO-`T`-with-dashes pattern (`2026-05-16T10-00-00`) is the single most important hardening — a `:` would lock the file out of macOS, iOS, Windows, and Android simultaneously. Keep it. + +### Folder shape + +``` +project-root/ +└── goals/ + ├── INDEX.md + └── / + ├── goal-state.md + ├── observations/ + │ └── 2026-05-16T10-00-00.md + ├── orientation.md + ├── decisions.md + ├── actions/ + │ └── a-1.md + ├── reviews/ + │ └── 2026-05-16T10-30-00.md + ├── brief.md + ├── lessons.md + └── archive/ +``` + +Every level is a plain folder. No `_attachments`, no `.obsidian` requirement, no hidden files outside the standard `.obsidian/` config dir Obsidian itself manages. + +## Recommended adopter vault setup + +The plugin works on any vault root, but two shapes are common. + +**Shape A — project root as vault.** Open the entire project directory in Obsidian. `goals/` sits alongside `specs/`, `docs/`, `discovery/`, etc. Everything cross-links. The graph view shows the relationship between a feature spec and the goals that drove it. Recommended for adopters running the Specorator stack. + +**Shape B — `goals/` as vault root.** Open just the `goals/` folder. Tighter graph, faster indexing, no cross-track noise. Recommended for adopters using only the Goal Loop, or for review-only sessions on a finished portfolio. + +Both shapes work without any plugin change. + +### Properties UI configuration + +In **Settings → Editor → Properties view** set: + +- **Default visibility** = Visible. Frontmatter is the audit trail; surface it. +- For each canonical property the plugin uses, Obsidian infers the type from the YAML value. No manual type-pinning required unless the first artifact in the vault uses an ambiguous value. + +If Obsidian guesses wrong (e.g., infers `created_at` as Text because the first artifact has a malformed value), click the type icon next to the property in the side panel and pin it to **Date & time**. + +### Recommended community plugins + +| Plugin | What it unlocks | Required? | +|---|---|---| +| [Dataview](https://blacksmithgu.github.io/obsidian-dataview/) | Portfolio rollups, criterion-by-criterion review aggregation, "all observations from source X this week" queries. | No. | +| [Periodic Notes](https://github.com/liamcain/obsidian-periodic-notes) | Daily/weekly/monthly notes that can link straight into recurring-mode brief files. | No. | +| [Templater](https://silentvoid13.github.io/Templater/introduction.html) | Adopter-side templating if they want to scaffold goals from inside Obsidian. The plugin's own templates do **not** use Templater syntax — they are plain Markdown. | No. | +| Bases (core, 1.9+) | Native database views over goal frontmatter. See [Bases syntax — Obsidian Help](https://obsidian.md/help/bases/syntax). | No. | + +None is required. The plugin's artifacts render and link correctly with zero community plugins. + +## Dataview rollups (optional) + +Three ready-to-paste queries for `goals/_dashboard.md`. All read frontmatter that the plugin already writes. + +### Active goals, recency-sorted + +````markdown +```dataview +TABLE + intent AS "Intent", + mode AS "Mode", + iteration AS "Iter", + current_phase AS "Phase", + updated_at AS "Updated" +FROM "goals" +WHERE status = "active" AND file.name = "goal-state" +SORT updated_at DESC +``` +```` + +### Acceptance status across the portfolio + +````markdown +```dataview +TABLE + intent, + status, + length(acceptance_criteria) AS "Criteria", + iteration +FROM "goals" +WHERE file.name = "goal-state" +SORT status ASC, updated_at DESC +``` +```` + +### Recent reviews and their outcome + +````markdown +```dataview +TABLE + goal_slug AS "Goal", + iteration AS "Iter", + outcome AS "Outcome", + reviewed_at AS "Reviewed" +FROM "goals" +WHERE outcome +SORT reviewed_at DESC +LIMIT 20 +``` +```` + +Dataview query mechanics: TABLE / LIST / TASK / CALENDAR are the four query types, with FROM, WHERE, SORT, GROUP BY, FLATTEN, LIMIT as data commands ([Structure of a Query — Dataview](https://blacksmithgu.github.io/obsidian-dataview/queries/structure/)). Inline fields (`key:: value`) are supported but the plugin does not emit them — frontmatter is sufficient. + +## Bases templates (optional) + +Bases is the native database core plugin shipped in Obsidian 1.9+ ([Bases syntax — Obsidian Help](https://obsidian.md/help/bases/syntax)). A `.base` file is a YAML config with four sections — `filters`, `formulas`, `properties`, `views`. The plugin does not ship a `.base` file by default (adopter ergonomics vary), but the shape below is the recommended seed. + +### `goals/goals.base` — portfolio view + +```yaml +filters: + and: + - file.hasTag("goal-loop/artifact/goal-state") + +formulas: + is_terminal: 'status == "done" || status == "cancelled"' + +properties: + intent: + displayName: Intent + status: + displayName: Status + current_phase: + displayName: Phase + iteration: + displayName: Iter + updated_at: + displayName: Updated + +views: + - type: table + name: "All goals" + order: + - intent + - status + - current_phase + - iteration + - updated_at + sort: + - property: updated_at + direction: desc + + - type: table + name: "Active only" + filters: + and: + - 'status == "active"' + order: + - intent + - current_phase + - iteration + - updated_at +``` + +### `goals/reviews.base` — review outcomes + +```yaml +filters: + and: + - file.hasTag("goal-loop/artifact/review") + +properties: + goal_slug: + displayName: Goal + iteration: + displayName: Iter + outcome: + displayName: Outcome + reviewed_at: + displayName: Reviewed + +views: + - type: table + name: "Recent reviews" + order: + - goal_slug + - iteration + - outcome + - reviewed_at + sort: + - property: reviewed_at + direction: desc + limit: 50 +``` + +The `goal-loop/artifact/` tag namespace is what makes this work — Bases filters on `file.hasTag(...)` without needing every goal to declare a custom property. + +## Callouts (optional sugar) + +Obsidian supports thirteen built-in callout types — `note`, `abstract`/`summary`/`tldr`, `info`, `todo`, `tip`/`hint`/`important`, `success`/`check`/`done`, `question`/`help`/`faq`, `warning`/`caution`/`attention`, `failure`/`fail`/`missing`, `danger`/`error`, `bug`, `example`, `quote`/`cite` ([Callouts — Obsidian Help](https://obsidian.md/help/callouts)). Syntax: `> [!type]` on the first line of a blockquote, `+`/`-` after the type for foldable, deeper `>` prefixes for nesting. + +The plugin's templates do not emit callouts by default — they render as plain blockquotes in non-Obsidian readers. Adopters can locally rewrite section preambles (e.g. `> [!warning] Act gate — irreversible action`); the `[!type]` token degrades to literal text in plain Markdown with no information loss. + +## What the plugin does NOT do + +- **No Obsidian-plugin code.** No `.obsidian/plugins/goal-loop/` directory, no JavaScript, no manifest. The plugin operates at the artifact layer. +- **No Templater dependency.** Templates are plain Markdown with `` tokens, filled by the plugin's skills, not by Templater's `<% %>` engine. +- **No Dataview dependency.** Dataview is an opt-in adopter choice. Frontmatter is rich enough that any indexer (Dataview, Bases, native search, custom scripts) can read it. +- **No `.base` file shipped by default.** Adopters who want one paste the snippets above into `goals/goals.base`. +- **No Canvas files.** JSON Canvas ([jsoncanvas.org](https://jsoncanvas.org/)) is a clean spec, but a loop's reasoning trail is a graph, not a board. The graph view already does this job. +- **No mandatory tags.** Remove every `goal-loop/*` tag and the loop still runs. The tags exist for portfolio facets, nothing more. +- **No wikilinks.** Markdown links are the default emit shape. Adopters can convert manually; the plugin will not. +- **No `.canvas`, no Excalidraw, no graph artifacts.** Visual layout is the vault's responsibility. + +## Mobile and sync compatibility + +Obsidian Mobile (iOS, Android) renders the same Markdown the desktop app does ([Obsidian for iOS and Android](https://obsidian.md/mobile)). The plugin's artifacts are mobile-safe because file naming, frontmatter, and link forms all satisfy the strictest platform — Android's `\/:*?<>"` set. + +Sync caveats apply to the vault, not the plugin: + +- **Git** is the cleanest sync — pair with Working Copy on iOS, mgit on Android ([How to Sync Obsidian — Stephan Miller](https://www.stephanmiller.com/sync-obsidian-vault-across-devices/)). +- **iCloud Drive** works for native Obsidian iOS; keep `.git` **outside** the vault to avoid iCloud file-count thrash ([Obsidian-git iCloud guidance — Obsidian Forum](https://forum.obsidian.md/t/obsidian-git-users-how-to-put-the-git-folder-outside-of-my-vault-to-avoid-sync-issues-with-icloud/101968)). +- **Obsidian Sync** and **Syncthing** Just Work with the plugin's output. + +## Reading-view, Live-Preview, and Source-mode parity + +Obsidian renders Markdown in three modes ([Views and editing mode — Obsidian Help](https://help.obsidian.md/edit-and-read); [Live Preview vs Reading mode — Obsidian Forum](https://forum.obsidian.md/t/live-preview-and-reading-mode-are-very-different/87552)): + +- **Reading view** — fully rendered, no syntax markers. +- **Live Preview** — rendered except for the line with the cursor. +- **Source mode** — raw Markdown. + +The plugin's artifacts render identically in all three because they avoid the known parity-breakers: + +- No HTML wrappers (Markdown inside HTML does not render in any mode). +- No `
` inside table cells — the plugin keeps cells single-line and uses adjacent rows when a cell would otherwise wrap (Reading view wraps automatically; Live Preview is fine; Source is fine). +- No callouts in default output — Reading view and Live Preview render them identically, Source shows the raw `> [!type]`. The plugin keeps the body callout-free so all three look the same. +- No inline math (`$...$`) inside table cells — math-in-tables is fragile; the plugin's artifacts contain no math. + +## Open questions + +- **Should the plugin emit `aliases:` on every artifact?** Currently only `goal-state.md` carries an alias. Per-iteration artifacts identify themselves structurally (iteration + phase). Adding aliases would inflate the global alias palette but improve search recall. Defer until a concrete user request lands. +- **Should `INDEX.md` ship a Dataview block by default?** Convenience vs adopter-friction trade-off — adopters without Dataview would see a literal code block. Likely answer: ship a commented-out Dataview block adopters can uncomment. +- **Is a `.base` file worth shipping?** Bases is core in Obsidian 1.9+ but adopters on older versions would see a `goals.base` file they cannot open. Likely answer: ship as a doc snippet (this file), not as a vault artifact. +- **Should the plugin generate a `.canvas` per goal?** Tempting — Observe→Orient→Decide→Act is naturally a four-node graph — but the JSON Canvas 1.0 format ([JSON Canvas spec](https://github.com/obsidianmd/jsoncanvas/blob/main/spec/1.0.md)) is Obsidian-coupled and not text-diff-friendly. Probable answer: no, keep the graph view as the dynamic projection. +- **How should Templater users scaffold goals?** The plugin's own scaffolding runs through skills, not Templater. A community-contributed Templater snippet that wraps `/goal:start` could exist, but it lives in adopter space. + +## References + +- Obsidian Flavored Markdown (Obsidian) — [help.obsidian.md/obsidian-flavored-markdown](https://obsidian.md/help/obsidian-flavored-markdown) +- Properties (Obsidian) — [help.obsidian.md/properties](https://obsidian.md/help/properties) +- Callouts (Obsidian) — [help.obsidian.md/callouts](https://obsidian.md/help/callouts) +- Tags (Obsidian) — [help.obsidian.md/tags](https://obsidian.md/help/tags) +- Link notes (Obsidian) — [help.obsidian.md/link-notes](https://obsidian.md/help/link-notes) +- Link to blocks (Obsidian) — [help.obsidian.md/How+to/Link+to+blocks](https://help.obsidian.md/How+to/Link+to+blocks) +- Views and editing mode (Obsidian) — [help.obsidian.md/edit-and-read](https://help.obsidian.md/edit-and-read) +- Bases syntax (Obsidian) — [help.obsidian.md/bases/syntax](https://obsidian.md/help/bases/syntax) +- Obsidian for iOS and Android (Obsidian) — [obsidian.md/mobile](https://obsidian.md/mobile) +- "List of all forbidden filename characters" — [Obsidian Forum](https://forum.obsidian.md/t/list-of-all-forbidden-filename-characters/103977) +- "Wikilink vs Markdown: The Latter Suffers From Lack Of Support" — [Obsidian Forum](https://forum.obsidian.md/t/wikilink-vs-markdown-the-latter-suffers-from-lack-of-support/86920) +- "Settings: New Link Format: What is 'Shortest path when possible'?" — [Obsidian Forum](https://forum.obsidian.md/t/settings-new-link-format-what-is-shortest-path-when-possible/6748) +- "YAML entry with commas within quotation marks should produce a single entry" — [Obsidian Forum](https://forum.obsidian.md/t/yaml-entry-with-commas-within-quotation-marks-should-produce-a-single-entry/19046) +- "Making heading and block reference more compatible with other editors" — [Obsidian Forum](https://forum.obsidian.md/t/making-heading-and-block-reference-more-compatible-with-other-editors/7810) +- "Live Preview and Reading Mode are very different" — [Obsidian Forum](https://forum.obsidian.md/t/live-preview-and-reading-mode-are-very-different/87552) +- "Obsidian-git users: How to put the .git folder outside of my vault" — [Obsidian Forum](https://forum.obsidian.md/t/obsidian-git-users-how-to-put-the-git-folder-outside-of-my-vault-to-avoid-sync-issues-with-icloud/101968) +- "Front matter format changes in Obsidian 1.9" — Maurits van Mastrigt, [actions.work Forum](https://forum.actions.work/t/front-matter-format-changes-in-obsidian-1-9-and-how-to-deal-with-them/671) +- "Fixing YAML Metadata in Obsidian 1.9" — Practical PKM, [practicalpkm.com](https://practicalpkm.com/fixing-yaml-metadata-in-obsidian-1-9/) +- "Adding Metadata" — Dataview docs, [blacksmithgu.github.io/obsidian-dataview/annotation/add-metadata/](https://blacksmithgu.github.io/obsidian-dataview/annotation/add-metadata/) +- "Structure of a Query" — Dataview docs, [blacksmithgu.github.io/obsidian-dataview/queries/structure/](https://blacksmithgu.github.io/obsidian-dataview/queries/structure/) +- "obsidian-periodic-notes" — Liam Cain, [github.com/liamcain/obsidian-periodic-notes](https://github.com/liamcain/obsidian-periodic-notes) +- "Templater — Introduction" — SilentVoid13, [silentvoid13.github.io/Templater/introduction.html](https://silentvoid13.github.io/Templater/introduction.html) +- "JSON Canvas spec 1.0" — Obsidian, [github.com/obsidianmd/jsoncanvas/blob/main/spec/1.0.md](https://github.com/obsidianmd/jsoncanvas/blob/main/spec/1.0.md) +- "How to Sync Obsidian Across All Your Devices" — Stephan Miller, [stephanmiller.com](https://www.stephanmiller.com/sync-obsidian-vault-across-devices/) +- "YAML Rules" — Obsidian Linter, [platers.github.io/obsidian-linter/settings/yaml-rules/](https://platers.github.io/obsidian-linter/settings/yaml-rules/) diff --git a/plugin-v2/docs/obsidian-enforcement.md b/plugin-v2/docs/obsidian-enforcement.md new file mode 100644 index 000000000..1db56b013 --- /dev/null +++ b/plugin-v2/docs/obsidian-enforcement.md @@ -0,0 +1,206 @@ +--- +title: Goal Loop — Obsidian enforcement +folder: plugin-v2/docs +description: Enforcement strategy for keeping the plugin's output Obsidian-vault-compliant — automated checks, recommended tooling, integration with the broader quality pipeline. +entry_point: false +--- + +# Obsidian enforcement + +> Companion to [`obsidian-compatibility.md`](obsidian-compatibility.md) (the contract). This doc is **how the contract is enforced** — at PR time for plugin contributors, and at runtime for adopters who want to be sure their loop's output stays vault-clean. + +The plugin's output under `goals//` is meant to drop into an Obsidian vault and behave like every other note: wikilinks resolve, properties render with the right type icon, callouts pick up the right colour, tags fold into the panel, filenames sync across desktop and mobile. Compliance is cheap to maintain when checked; expensive to retrofit when not. This document pins the tools, the checks, and where they run. + +## Enforcement layers + +Three layers, each with a different audience, scope, and tempo. + +| Layer | Audience | When it runs | Scope | Severity floor | +|---|---|---|---|---| +| **L1 — Plugin CI** | Plugin contributors | Every PR touching `plugin-v2/**` | `plugin-v2/examples/**`, `plugin-v2/templates/**`, plugin-emitted output samples | `error` blocks merge | +| **L2 — Adopter pre-commit** | Adopters running a loop | Adopter's `git commit` on `goals//**` | The staged files only | `error` blocks commit; opt-in | +| **L3 — Adopter on-demand** | Adopters at any cadence | `/goal:validate ` or `/goal:validate --all` | One goal folder or every `goals/**` folder | Report-only; severity surfaces in the response | + +L1 is the source of truth. L2 and L3 reuse the same rule set; only the file scope and the failure mode differ. Pin the rule set in one place — `plugin-v2/scripts/obsidian/` — and let all three layers consume it. + +## Checks (per category) + +Every check has a stable id (`O`), a severity (`error` / `warning` / `info`), a tool, and a false-positive policy. JSON-finding shape matches the automation-spec convention (`{ check, severity, file, line, message, fix_hint }`). + +### O1 — Frontmatter property types + +- **What it checks.** Every YAML key in every plugin-emitted artifact maps to one of Obsidian's seven property types (`text`, `list`, `number`, `checkbox`, `date`, `datetime`, `tags`). The check parses the YAML, classifies each value, and asserts the inferred type matches the canonical type declared in [`skills/_shared/goal-state.md`](../skills/_shared/goal-state.md) plus the per-template tables in `automation-spec.md` §C3. +- **Tool.** Node script using `gray-matter@4.x` for parsing + a hand-written classifier (no off-the-shelf tool covers Obsidian's exact type set; the [`obsidian-linter`](https://github.com/platers/obsidian-linter) plugin is closest but is Obsidian-runtime-only and uses regex-based YAML parsing per its own docs). +- **Severity.** `error`. +- **False-positive policy.** Template files (`templates/*-template.md`) contain placeholders like `` that are not valid YAML values; exempt anything matching `^<[^>]+>$`. Allow-list resides at `plugin-v2/scripts/obsidian/.o1-type-overrides.json` with `path`, `key`, `declared_type`, `reason` per entry. + +### O2 — Date and datetime literal form + +- **What it checks.** `date` properties match `^\d{4}-\d{2}-\d{2}$`; `datetime` properties match `^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$`. **String-quoted timestamps fail** — Obsidian renders a quoted `"2026-05-16"` as text, not date, surfacing as the "type mismatch, expected date" error the Obsidian forum documents. +- **Tool.** Same Node script as O1 (regex over the raw YAML node, not the JS-parsed string). +- **Severity.** `error`. +- **False-positive policy.** None. Quoted timestamps are always a defect; if a value must be a literal string, the field is a `text` property and should be declared as such in the schema. + +### O3 — Forbidden filename characters + +- **What it checks.** No file under `plugin-v2/examples/**` or `goals/**` uses characters Obsidian forbids on **any** platform — superset of every OS's restrictions so vaults sync across desktop, iOS, iPadOS, Android, and Windows without dropping files. Forbidden set: `[`, `]`, `#`, `^`, `|`, `\`, `/` (in the filename component, not the path separator), `:`, `*`, `"`, `<`, `>`, `?`. Also flag filenames beginning with a leading `.`. +- **Tool.** Shell one-liner suitable for L2/L3, plus a Node helper for L1's JSON-finding emission. Pseudo-code: `find "$root" -type f -print0 | grep -zE '/\.[^/]*$|[][#^|*"<>?:]'`. +- **Severity.** `error`. +- **False-positive policy.** None on user-emitted files. Internal tool config files (`.gitignore`, `.lycheeignore`) are scope-excluded by glob, not by allow-list — they're not vault content. + +### O4 — Filename timestamp form + +- **What it checks.** Phase-artifact filenames carrying a timestamp use the colon-free form `2026-05-16T10-00-00` (per [`AGENTS.md`](../AGENTS.md) §"Repo conventions" and [`method.md`](method.md) §"State model"). The colon-bearing ISO form is forbidden in filenames because O3 forbids `:` on macOS-flavour vaults. +- **Tool.** Regex over `observations/`, `actions/`, `reviews/`, `archive/` subtrees. Pattern: `^\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}(\.[^/]+)?$`. +- **Severity.** `error`. +- **False-positive policy.** Action-id filenames (e.g., `actions/iter-1/a-1.md`) are exempt by glob — they're not timestamped. + +### O5 — Internal-link resolution + +- **What it checks.** Every Markdown link `[text](path)` whose target is a relative path resolves to an existing file. Every wikilink `[[Note]]` or `[[Note|alias]]` likewise resolves under the vault root (the plugin tree itself for L1; the adopter's vault for L2/L3). +- **Tool.** [`lychee@0.24.x`](https://github.com/lycheeverse/lychee) with `--offline --include-wikilinks --base `. For wikilink resolution behaviour matching Obsidian's "shortest unique" rule, run [`markdownlint-obsidian-cli@1.1.x`](https://github.com/alisonaquinas/markdownlint-obsidian) (the OFM00x rule family) as the secondary check — its wikilink resolver is vault-aware where lychee is path-aware. +- **Severity.** `error` on broken targets; `warning` on ambiguous wikilinks (matches more than one file). +- **False-positive policy.** Allow-listed placeholders in templates (`[]()`) detected by the `<…>` envelope. Adopter `[example-link](example.md)` placeholders in docs go in `plugin-v2/scripts/obsidian/.o5-allow.toml` with a `reason` field; same file format as `lychee.example.toml`. + +### O6 — Heading-anchor validity + +- **What it checks.** Every `[[Note#Heading]]` or `[Heading](Note.md#heading)` reference points to a heading that exists in the target file. Obsidian's anchor rule (per `obsidian.md/help/links`): preserve case, shrink runs of whitespace, drop a small set of special characters — no full kebab-case slugification like GFM. The check builds a heading set per file (AST visitor) and lookup-matches references. +- **Tool.** Custom AST walker on top of [`remark-parse@11.x`](https://github.com/remarkjs/remark) + [`remark-frontmatter@5.x`](https://github.com/remarkjs/remark-frontmatter) + [`@portaljs/remark-wiki-link@1.x`](https://www.npmjs.com/package/@portaljs/remark-wiki-link) (Obsidian-flavour resolver). `markdownlint-obsidian-cli`'s OFM00x rules cover this for the standard cases. +- **Severity.** `error`. +- **False-positive policy.** Subheading chains (`[[Note#Parent#Child]]`) resolve against any heading path in the file, not just leaf-to-leaf. Quoted-text references (`[[Note#"raw text"]]`) are deferred to a follow-up; flagged `info` until then. + +### O7 — Block-reference validity + +- **What it checks.** Every `[[Note^block-id]]` resolves to a `^block-id` anchor that actually exists in the target file. Block-id syntax: trailing-space `^id` for paragraphs, separate-line `^id` between blank lines for structured blocks. Allowed id characters: Latin letters, numbers, dashes. +- **Tool.** Custom AST walker; `markdownlint-obsidian-cli` (block-references rule family) is the canonical implementation. +- **Severity.** `error` on missing targets; `warning` on duplicate `^id` declarations within one file. +- **False-positive policy.** Block-id references inside fenced code blocks are stripped before resolution (code blocks are content, not links). + +### O8 — Tag-namespace enforcement + +- **What it checks.** Every artifact carries the expected canonical tag namespace. The plugin's canonical tag set: `goal-loop/goal/`, `goal-loop/phase/`, `goal-loop/iteration/`. The check walks `tags:` frontmatter arrays and inline `#tag` occurrences; both sides count. Tag-character rule (per `help.obsidian.md/tags`): letters, numbers, underscores, hyphens, forward slashes — no emoji, no spaces. +- **Tool.** Node script reading frontmatter + scanning body for `/(?:^|\s)#([\w/-]+)/g`. Per-template required-tag matrix lives at `plugin-v2/scripts/obsidian/.o8-required-tags.json`. +- **Severity.** `error` on missing required tag; `warning` on malformed tag character; `info` on inline tags when frontmatter is also present (potential duplicate of intent). +- **False-positive policy.** Inline tags inside fenced code blocks are stripped (same as O7). Adopter goals MAY add extra tags; the check enforces the **required subset**, not equality. + +### O9 — Callout-syntax validity + +- **What it checks.** Every callout (`> [!type]` ... ) declares a `type` from Obsidian's twelve-callout default set or the documented aliases: `note` (`abstract` / `summary` / `tldr`), `info` (`todo`), `tip` (`hint` / `important`), `success` (`check` / `done`), `question` (`help` / `faq`), `warning` (`caution` / `attention`), `failure` (`fail` / `missing`), `danger` (`error`), `bug`, `example`, `quote` (`cite`). Type identifier is case-insensitive. Folding modifiers `+` / `-` after the closing bracket are valid. +- **Tool.** `markdownlint-obsidian-cli@1.1.x` (callout rule family). Regex fallback for L2 quick-check: `/^>\s*\[!([a-z]+)\][+-]?/i`. +- **Severity.** `error` on unknown type; `warning` on case-variant style drift (e.g., mixed `[!Note]` / `[!note]` in the same file). +- **False-positive policy.** Custom callout types declared via vault CSS are adopter-side concerns; an adopter override list at `plugin-v2/scripts/obsidian/.o9-extra-types.json` (with `reason`) widens the allowed set per adopter. + +### O10 — File-count and folder-shape + +- **What it checks.** A `goals//` folder declares only the files and subfolders allowed by [`method.md`](method.md) §"State model": `goal-state.md`, `orientation.md`, `decisions.md`, `brief.md` (recurring only), `observations/`, `actions/`, `reviews/`, `archive/`. Stray top-level files (e.g., `notes.md`, `scratch.md`) are flagged as drift. Exactly one `goal-state.md`. Per-phase artifact counts: at least one observation per scanned source per iteration; at least one action log per approved action. +- **Tool.** Node script using `fast-glob@3.x` to enumerate, with the canonical shape table as the contract. +- **Severity.** `error` on missing required file or unknown top-level file; `warning` on per-phase count anomalies (observations < approved-sources). +- **False-positive policy.** Adopter-emitted notes that aren't part of the loop go under an `_adopter/` subfolder which the check skips by glob. Surfacing the convention here so adopters don't fight it: the loop owns the documented files; adopter notes opt out via the prefix. + +### O11 — Vault-orphan detection (L3 only) + +- **What it checks.** Every file in `goals/**` is reachable from at least one entry — a `goal-state.md`, a link from `decisions.md`, a `## History` row, or a `last_review` frontmatter pointer. Unreachable files are likely artifacts of an interrupted iteration. +- **Tool.** AST walker over the full vault, building a reachability graph from declared entry points. +- **Severity.** `warning`. +- **False-positive policy.** Files under `archive/**` are entry points in their own right (closed iterations); they don't need to be reachable from the live tree. List of allowed entry-point globs at `plugin-v2/scripts/obsidian/.o11-roots.json`. +- **Scope note.** Skipped at L1 because plugin examples are intentionally minimal; expensive on large adopter vaults so it's report-only. + +### O12 — Dataview-query syntax (adopter-emitted dashboards only) + +- **What it checks.** When an adopter renders a dashboard view that embeds Dataview queries (e.g., `/goal:list` output rendered as a Dataview table), the query body parses against the documented [Dataview Query Language](https://blacksmithgu.github.io/obsidian-dataview/queries/structure/) grammar: ` FROM `. +- **Tool.** A thin grammar check using a hand-rolled PEG parser (no shipped Dataview validator exists per current research). Scoped to fenced blocks declared `dataview` only. +- **Severity.** `warning`. Dataview is itself a community plugin — strictness here would punish adopters who don't use it. +- **False-positive policy.** Adopters who don't use Dataview can disable the check entirely by setting `o12_enabled: false` in `plugin-v2/scripts/obsidian/config.json`. + +## Recommended tooling stack + +Pin these versions in `plugin-v2/scripts/package.json` (Node deps) and the workflow YAML (CLI deps). Bump them in one PR with a regression run against the example artifacts. + +| Tool | Version | Used for | Why this one | +|---|---|---|---| +| `markdownlint-obsidian-cli` | `1.1.x` | O5, O6, O7, O9 — Obsidian-flavour Markdown rules | Purpose-built for OFM in CI; namespaced rule codes (OFM00x wikilinks, OFM06x tags, OFM08x frontmatter); SARIF / JUnit / JSON output | +| `lychee` | `0.24.x` | O5 — link resolution at scale | Rust, async, stream-based; benchmarked at ~576 links/min on the analysis-tools-dev corpus; offline-safe via `--offline`; native wikilink mode via `--include-wikilinks` | +| `remark-parse` | `11.x` | O6, O7, O11 — AST walks | Already a stack staple for [`automation-spec.md`](automation-spec.md) §A5; reuse the parser | +| `@portaljs/remark-wiki-link` | `1.x` | O6 — Obsidian-flavour resolver | "obsidian-short" path-resolution mode matches Obsidian's "shortest unique" rule | +| `gray-matter` | `4.x` | O1, O2, O8 — YAML frontmatter | Already pinned in `automation-spec.md` A1/C2; do not introduce a second parser | +| `fast-glob` | `3.x` | O10, O11 — folder enumeration | Already pinned for B1; reuse | +| **Standardise on:** | `markdownlint-obsidian-cli` + `lychee` | The whole stack | The two tools jointly cover OFM-aware lint and link-resolution at scale; everything else is supporting glue the plugin already owns | + +`obsidian-linter` is **not** in the stack. It is excellent inside the Obsidian app but ships only as a community plugin — no headless CLI mode — and its YAML parsing is regex-based per its own documentation. It is documented here as the gold-standard for what a fixed-up file looks like, not as an enforcement tool. + +## Plugin-side enforcement (L1) + +Wire into [`automation-spec.md`](automation-spec.md)'s existing pipeline. A new `plugin-v2/scripts/obsidian.sh` runs the O-check suite and emits the standard JSON-finding shape. `check-all.sh` invokes it between category G (self-application) and the verdict pass. + +``` +plugin-v2/scripts/ +├── obsidian.sh # new — category H runner +├── obsidian/ +│ ├── lint-config.jsonc # markdownlint-obsidian-cli config +│ ├── lychee.toml # lychee config (offline + include-wikilinks) +│ ├── .o1-type-overrides.json +│ ├── .o5-allow.toml +│ ├── .o8-required-tags.json +│ ├── .o9-extra-types.json +│ ├── .o11-roots.json +│ └── config.json # toggles per check (e.g., o12_enabled) +``` + +The runner accepts the standard `--json`, `--files `, `--quick` flags `automation-spec.md` already defines. + +## Adopter-side enforcement (L2, L3) + +The plugin **does not** ship a pre-commit hook to adopters — hooks are opinionated and adopter-owned. Instead, ship: + +1. **A copy-target script** at `plugin-v2/scripts/obsidian.sh` that an adopter copies (or invokes from a submodule) into their own project. Same JSON-finding shape, same flags. +2. **A `/goal:validate` slash command** (deferred — see Open Q 1) that wraps the script and runs at the adopter's request. Default scope: one slug at a time. `--all` widens to every `goals//`. +3. **A `cadence-recipes.md` recipe** documenting the cron / Actions / pre-commit shapes an adopter can choose. Echo the L1 stack; do not invent new ones. + +Adopters who **don't** want runtime enforcement skip both. The plugin remains compatible with vanilla Obsidian without the script ever running — compliance is the contract; enforcement is the safety net. + +## Integration with `automation-spec.md` + +**Decision: add Section H rather than extend A/B/C.** Justification: + +1. **Scope.** A–G scan `plugin-v2/**` (the template itself). H scans **plugin-emitted output shape** — artifacts the plugin will produce in adopter vaults, plus the example artifacts that prove the shape. Different scope, different contract. +2. **Tool footprint.** H adds two new CLIs (`markdownlint-obsidian-cli`, `lychee`-with-wikilink-mode). Folding them into A (lint) or B (verification) muddies the dependency story of those sections, both of which currently advertise their own tool list. +3. **Severity floor.** A/B/C block PR merge. H blocks PR merge **for plugin examples and templates**, and is **report-only for L3 adopter scans**. That severity duality fits its own section better than a footnote inside an existing one. +4. **Adopter reuse.** Section H's tools are the only ones in the pipeline an adopter is likely to re-invoke against their own `goals//` tree. Keeping them in one section makes the copy-target obvious. + +Cross-references the new Section H back to this doc for the full treatment, and back to [`obsidian-compatibility.md`](obsidian-compatibility.md) for the contract H enforces. + +## Performance notes + +Indicative timings measured against published benchmarks; rerun on the plugin's own corpus before pinning SLAs. + +| Scope | File count | `lychee --offline` | `markdownlint-obsidian-cli` | `remark` AST walk | Combined wall-clock | +|---|---|---|---|---|---| +| L1 (plugin tree, examples + templates) | ~80 files | < 2 s | < 3 s | < 1 s | < 6 s | +| L2 (staged-only, typical commit) | 1–10 files | < 0.5 s | < 0.5 s | < 0.5 s | < 2 s | +| L3 quick (one goal, mid-loop) | ~30 files | < 1 s | < 2 s | < 1 s | < 4 s | +| L3 full (500 goal folders ≈ 15 k files) | ~15 000 files | ~30 s with `--cache` | ~60 s | ~25 s | ~2 min | + +Lychee's `.lycheecache` cuts repeat scans by an order of magnitude. Enable it on L1 (CI cache key on `plugin-v2/scripts/obsidian/.lycheecache.lock`) and L3 only. + +## Open questions + +1. **`/goal:validate` shape.** Should the validate command be a new slash command (`/goal:validate `) or a flag on `/goal:status` (`/goal:status --validate`)? Author leans new command — validation is a distinct verb and survives a slug-less full-vault scan (`/goal:validate --all`). +2. **Wikilinks vs Markdown links.** The plugin currently emits Markdown links exclusively. Should it also support emitting wikilinks for adopters whose vault default is `[[wiki]]`? If yes, O5 must run both resolvers; if no, add an O-check that forbids `[[...]]` syntax in plugin-emitted output. Defer to a follow-up — `obsidian-compatibility.md` is the right place to decide. +3. **Custom callout types.** O9 hard-codes the twelve defaults. Adopters with custom CSS may declare their own; the `.o9-extra-types.json` escape is acceptable, but if more than a handful of adopters carry the same list, promote it to a shared file. +4. **Property-type registry.** O1 needs a per-key declared-type map. The cleanest home is a `properties:` block in [`skills/_shared/goal-state.md`](../skills/_shared/goal-state.md) frontmatter rather than an external JSON. Spec-bump warrants its own ADR. +5. **L3 caching.** Full-vault scans at 500-goal scale lean on lychee's cache. Should the plugin ship a `.lycheecache` strategy doc, or leave it to the adopter? Author leans ship the strategy in [`cadence-recipes.md`](cadence-recipes.md) so adopters get a proven recipe. +6. **Heading-anchor algorithm fidelity.** Obsidian's slugify rule is "preserve case, shrink whitespace, drop some specials" — exact rule is not formally specified. The AST walker matches case-insensitively as a pragmatic compromise; if Obsidian changes the rule, the check breaks silently. Track upstream and pin the algorithm in this doc once stabilised. + +## References + +- platers, "obsidian-linter" — community plugin: +- alisonaquinas, "markdownlint-obsidian" — CI-oriented OFM linter: +- lycheeverse, "lychee" — async link checker (Rust): +- portaljs, "remark-wiki-link" — Obsidian-flavour wikilink AST plugin: +- Obsidian Help, "Properties" — property-type rules: +- Obsidian Help, "Internal links" — wikilink and anchor syntax: +- Obsidian Help, "Callouts" — twelve default types and aliases: +- Obsidian Help, "Tags" — tag character rules and nesting: +- Obsidian Forum, "List of all forbidden filename characters" (v1.8.10): +- blacksmithgu, "Obsidian Dataview" — query-language grammar: +- DavidAnson, "markdownlint-cli2" — base lint engine: diff --git a/plugin-v2/docs/obsidian-setup-guide.md b/plugin-v2/docs/obsidian-setup-guide.md new file mode 100644 index 000000000..c724e5445 --- /dev/null +++ b/plugin-v2/docs/obsidian-setup-guide.md @@ -0,0 +1,90 @@ +--- +title: Goal Loop — Obsidian setup guide +folder: plugin-v2/docs +description: Step-by-step setup for adopters who want to use the goal-loop plugin's output as an Obsidian vault. Pairs with obsidian-compatibility.md (contract) and obsidian-enforcement.md (CI). +entry_point: false +--- + +# Goal Loop — Obsidian setup guide + +If you want the plugin's `goals/`, `templates/`, and `docs/` to feel native in Obsidian, this guide gets you there in 10 minutes. It pairs with [`obsidian-compatibility.md`](obsidian-compatibility.md) (what the plugin guarantees) and [`obsidian-enforcement.md`](obsidian-enforcement.md) (how those guarantees are checked). + +## Open the vault + +Two shapes work. Pick the one that matches who you are. + +**Shape A — open `plugin-v2/` as a vault.** Useful for plugin authors and anyone reading the docs alongside the agents, skills, and templates. The graph view shows how docs reference agents, agents reference skills, and skills reference shared contracts. Trade-off: the graph and tag panes carry plugin-internal nodes you may not care about as an adopter. + +**Shape B — open `goals/` as a vault root.** Useful for adopters running real goals — tighter graph, faster indexing, no plugin-internal noise. You lose direct backlink visibility into `docs/` and `templates/`, but the artifacts themselves are self-contained. Recommended for day-to-day loop work. + +You can switch later — Obsidian vaults are just folders. + +## Recommended settings + +Open **Settings** (gear icon, bottom left) and walk through the following panels. + +### Files & Links + +- **New link format** → `Relative path to file`. Matches the plugin's emit shape so renames inside the vault propagate cleanly without rewriting links. +- **Use [[Wikilinks]]** → OFF. The plugin emits Markdown links (`[text](path)`) because they survive outside Obsidian. Turning wikilinks off here means new links you author yourself match the plugin. +- **Detect all file extensions** → OFF. Keeps `.codex/`, `.claude-plugin/`, and other dot-folders hidden from the file explorer and search. +- **Automatically update internal links** → ON. Lets Obsidian fix references when you rename a file in the explorer. +- **Excluded files** → add `archive/**` if you don't want archived briefs and rolled state cluttering search and graph. + +### Editor → Properties + +- **Properties in document** → ON. Surfaces every artifact's frontmatter as Obsidian's structured Properties UI in the sidebar — the audit trail becomes clickable. + +### Editor → Display + +- **Show frontmatter** → ON in Source mode if you want both the Properties UI **and** the raw YAML visible while editing. Off if you prefer the cleaner Reading-view-only experience. + +If Obsidian guesses a property type wrong (rare — usually only when the first artifact carries a malformed value), click the type icon in the property side panel and pin it. The canonical type for each field is documented in [`obsidian-compatibility.md`](obsidian-compatibility.md) §"Property types in the plugin's frontmatter". + +## Recommended community plugins + +None of these are required — the plugin's artifacts render and link correctly with zero community plugins. They are useful enough that most adopters end up installing them. + +- **[Dataview](https://github.com/blacksmithgu/obsidian-dataview)** — portfolio dashboards, stalled-goal queries, outcome rollups. Paste-ready queries in [`dataview-snippets.md`](dataview-snippets.md). +- **[Periodic Notes](https://github.com/liamcain/obsidian-periodic-notes)** — wire recurring daily briefs to the Daily Notes calendar. See [`cadence-recipes.md`](cadence-recipes.md) §"Periodic Notes integration". +- **[Templater](https://github.com/SilentVoid13/Templater)** — adopter-side scaffolding for new goals or notes from inside Obsidian. The plugin itself uses skills, not Templater, but Templater is convenient if you live in the vault. +- **[Tag Wrangler](https://github.com/pjeby/tag-wrangler)** — bulk-rename `goal-loop/...` tags as your project evolves. Saves a tedious find-and-replace if you ever rename a goal slug. + +## What you get out of the box + +These work the moment you open the vault — no plugins, no config beyond the settings above. + +- **Properties UI** — every artifact's frontmatter renders as typed properties in the sidebar. `status`, `current_phase`, `iteration`, timestamps, and lists all show with the right widgets. +- **Tag pane** — the `goal-loop/...` namespace folds into a tree. Click a tag to see every artifact carrying it. +- **Quick Switcher (Ctrl/Cmd-O)** — finds goals by `aliases:` (the intent line). You don't need to remember slugs. +- **Graph view** — each goal becomes a sub-graph once `orientation.md`, `decisions.md`, action logs, and reviews link to each other via the Markdown links the plugin already emits. Filter by tag to scope the graph to one goal. +- **Reading View** — callouts (`> [!warning] Example only`, `> [!info]`, etc.) render with type-coloured borders and icons. The plugin's templates avoid them by default, but worked examples and your own notes can use them. +- **Backlinks pane** — every observation, orientation, decision, action, and review shows reverse edges automatically. + +## What needs the optional plugins + +Add Dataview if you want any of these: + +- Portfolio rollups (active goals, stalled goals, outcomes). +- Recent-reviews digest across the whole tree. +- Per-goal artifact listings as live tables instead of a manual file walk. + +Add Periodic Notes if you want: + +- Daily briefs from a recurring goal to appear in the Daily Notes calendar. +- Click-through from a calendar date to that day's brief. + +## Common gotchas + +- **Link format quirks.** If you switched the link format setting after creating notes, existing links keep their old shape — Obsidian does not retroactively reformat. The "Format → Convert link to wikilink" / "...Markdown link" commands fix individual links on demand. +- **YAML commas.** Obsidian's YAML parser historically splits comma-separated alias-like values even inside quotes ([Obsidian Forum](https://forum.obsidian.md/t/yaml-entry-with-commas-within-quotation-marks-should-produce-a-single-entry/19046)). The plugin uses block-list YAML (`- item` per line) for anything that might contain commas. If you hand-edit, keep block-list form. +- **`.md` extension required.** Obsidian only treats `.md` files as notes. The plugin always emits `.md`; if you author something without the extension, it will not appear in the graph, in search, or in backlinks. +- **Dot-folders hidden by default.** `.codex/`, `.claude-plugin/`, `.git/`, and any other leading-dot folder is hidden unless you turn **Detect all file extensions** on. Keep it off — Obsidian is for vault content, not tool config. +- **Colons in filenames.** macOS, iOS, iPadOS, and Windows forbid `:` in filenames. The plugin already uses `T10-00-00` (dashes) instead of `T10:00:00` (colons) in observation, review, and archive timestamps. If you hand-name a file, follow the same pattern. + +## See also + +- [`obsidian-compatibility.md`](obsidian-compatibility.md) — canonical contract: what the plugin guarantees about its output (property types, link forms, filename rules, tag namespace, recommended vault settings). +- [`obsidian-enforcement.md`](obsidian-enforcement.md) — canonical enforcement strategy: the O1–O12 automated checks that keep the contract honest, the recommended CI tooling, and the adopter-side opt-in script. +- [`dataview-snippets.md`](dataview-snippets.md) — paste-ready Dataview queries for portfolio dashboards, stalled-goal detection, outcome rollups. +- [`cadence-recipes.md`](cadence-recipes.md) — scheduler recipes for recurring goals, including the Periodic Notes integration recipe. diff --git a/plugin-v2/docs/ooda-foundations.md b/plugin-v2/docs/ooda-foundations.md new file mode 100644 index 000000000..e094ff300 --- /dev/null +++ b/plugin-v2/docs/ooda-foundations.md @@ -0,0 +1,113 @@ +--- +title: OODA Foundations +description: One-page primer on John Boyd's OODA loop and how Goal Loop instantiates it. +--- + +# OODA Foundations + +> Background reading for the Goal Loop. For the method itself, see [`method.md`](method.md). + +## Where OODA came from + +The **OODA loop** — Observe, Orient, Decide, Act — is John Boyd's model of decision-making under uncertainty. Boyd was a U.S. Air Force fighter pilot turned strategist; he developed the loop from the 1970s onward in a series of unpublished briefings (collectively known as *A Discourse on Winning and Losing*) and refined it until his death in 1997. The loop began as a description of why one fighter pilot survives an engagement and another does not; it generalised into a model for any contest where adversaries reason and act under incomplete information. + +Boyd's central claim is that **speed of orientation**, not raw speed of action, is what wins. An agent who cycles through OODA faster — and whose orientation is closer to reality — disrupts the opponent's ability to make sense of the situation. Boyd called this "getting inside the adversary's loop". + +Chet Richards's *Certain to Win* is the bridge between Boyd's military framing and the domain-neutral instantiation this plugin ships. Richards translates Boyd's air-combat and grand-strategy claims into knowledge-work language — competing under uncertainty, building shared mental models, holding tempo against rivals who are themselves orienting — and that translation is what licenses the Goal Loop to apply OODA to code, content, research, operations, and governance without retreating to the military case for every example. + +## The four phases + +| Phase | Question | Failure mode if skipped | +|---|---|---| +| **Observe** | What signals exist right now? | Acting on stale or imagined data. | +| **Orient** | What do those signals mean in context, history, and goal? | Reacting to noise; pattern-matching to the wrong template. | +| **Decide** | Given orientation, which option is best? | Drifting; doing whatever is nearest to hand. | +| **Act** | Execute and watch for the result. | Planning forever; never producing feedback. | + +Orient is the loop's centre of gravity. Boyd described it as the implicit synthesis of culture, prior experience, new information, and analysis — the place where the loop most often goes wrong, because flawed orientation produces confident-but-wrong decisions. + +## Why it works under uncertainty + +- **It treats decisions as a stream, not an event.** The loop never finishes; it iterates. A bad decision is a hypothesis to be revised, not a permanent fact. +- **It separates sensing from interpreting.** Many failure modes come from collapsing the two — jumping from raw signal to action without orientation. +- **It privileges tempo.** Faster iterations beat better one-shot plans when the environment changes. +- **It tolerates incomplete information.** The loop assumes you will never have all the data; the discipline is to act on what you have and re-observe. + +## How Goal Loop instantiates OODA + +Goal Loop is OODA with two additions: an **explicit goal contract** at the top of the loop and **structured human gates** between phases. + +| OODA element | Goal Loop instantiation | +|---|---| +| Observe | `observer` subagent(s), one per source, parallel-capable. Output: `observations/.md`. | +| Orient | `orienter` subagent. Output: `orientation.md`. Maps signals back to acceptance criteria. | +| Decide | `decider` subagent. Output: appended `decisions.md` entry with a ranked action set. | +| Act | `actor` subagent. Output: `actions/iter-/.md`. Bounded by the Act gate. | +| Review (added) | `loop-reviewer` subagent. Output: `reviews/.md`. Closes or continues the loop. | +| Goal (added) | `goal-state.md`. Sets intent, constraints, acceptance criteria, mode, cadence. | + +The Review phase is not in Boyd's original four — it is added so the loop has an explicit, auditable close. Boyd assumed the loop never closes (combat does not end politely). Goal Loop is used for bounded problems too, so it needs an explicit "met / not met" check against the acceptance criteria. + +The Goal contract is also additive. Boyd's loops orient against an adversary's behaviour; Goal Loop orients against a declared goal. Both are valid framings, but goals are what most knowledge work actually has. + +See [`method.md`](method.md) for the full state model, phase contracts, and quality gates. + +## What Boyd's actual diagram looks like + +The four-arrow Observe → Orient → Decide → Act loop that circulates in popular treatments is a simplification. Boyd's late 1996 diagram (from *The Essence of Winning and Losing*, the five-page brief he was finalising at the end of his life) is denser. It has **seven feedback arrows**, not three; an **"Implicit Guidance & Control"** channel that runs from Orient back to Observe *and* directly to Act, bypassing Decide; and **"unfolding interaction with environment"** as a continuous input across the whole loop. + +The arrows that matter most beyond the canonical forward chain: + +- **Orient → Observe.** Orientation re-tasks the next observation focus; observation is not a passive scan, it is shaped by what the orienter currently believes matters. Boyd's strongest feedback claim. +- **Decide → Orient.** A rejected decision is information about the orientation. The loop revises its mental model in response to "this option set is unacceptable", not just in response to action results. +- **Act → Orient.** Action results feed back to orientation *during* the cycle, not only at the next iteration. For multi-action sets, results from `a-1` should re-orient before `a-2` runs. +- **Implicit Guidance & Control (Orient → Observe and Orient → Act).** Experienced practitioners act without enumerating options when the situation pattern is known. This is the load-bearing distinction between novice and expert OODA — Klein's *Recognition-Primed Decision* model (`Sources of Power`) is the empirical evidence for it. See §"Implicit guidance & control" below. + +The Goal Loop diagrams in [`method.md`](method.md) — both the ASCII and the Mermaid — show a forward chain with one back-edge (Review → continue → Observe). That single back-edge collapses Boyd's seven feedback arrows into a once-per-iteration channel. The simplification is deliberate (audit trails are cheaper to draw than feedback topologies, and a domain-agnostic plugin without runtime instrumentation cannot meaningfully render Decide↔Orient as a mid-iteration loop) but it is a simplification, not a faithful reproduction. + +For the canonical reproduction of the 1996 diagram, see Osinga, *Science, Strategy and War*, pp. 230-235. Reproductions vary in fidelity across the open web; the book is the durable source. + +## Implicit guidance & control + +The single concept Boyd-readers will miss most in the Goal Loop's diagrams is the **implicit guidance & control** channel — the arrow from Orient that bypasses Decide and reaches Observe and Act directly. Boyd's claim, refined across two decades of briefings: experienced practitioners do not enumerate options before acting in pattern-matched situations. They orient to the pattern, recognise it, and act — Decide degenerates to a one-line check ("is this still the right play?"). Klein's *Sources of Power* is the empirical evidence Boyd never had during his lifetime; Chet Richards's *Certain to Win* is the canonical business-domain translation. + +The Goal Loop **routes every iteration through Decide** with a full ranked proposal set, a per-proposal rationale + confidence + reversibility block, and an explicit act-gate. This is a deliberate trade: auditability over expert-tempo. The cost is that an expert operator who already knows the right play still has to render the play as a ranked-set-of-one and clear the act-gate. The benefit is that every action carries a paper trail an outside auditor can reconstruct. + +The trade is acknowledged, not denied. [`docs/research-goal-oriented-ai.md`](research-goal-oriented-ai.md) §H §"M-1 (decision_mode)" names the recommendation: add a `decision_mode: ranked | rpd` field to `goal-state.md` so an expert operator can opt into Klein's *Recognition-Primed Decision* shortcut on goals where the audit cost outweighs the tempo gain. The recommendation is on the roadmap; the deliberate-and-audited default is shipped. + +**The plugin's implicit-guidance surface, even today, lives in its conventions** — the locked vocabulary in [`method.md`](method.md) §"Naming reference", the kebab-case slug discipline, the template shapes, the orchestrator's gating procedure, the per-agent tool lists. These are shared mental models that let the loop run without explicit per-transition coordination. They are not framed as "implicit guidance" anywhere in the docs, but functionally that is what they are. A faithful Boyd reading of this plugin would recognise the conventions as the implicit-guidance layer; the explicit-discipline layer is everything that lands in `goals//`. + +## Reading references + +- John Boyd — *A Discourse on Winning and Losing* (the original briefings, 1976–1996). Unpublished during Boyd's lifetime; circulated as slide decks. Best entry point is the *Patterns of Conflict* briefing. +- Robert Coram — *Boyd: The Fighter Pilot Who Changed the Art of War*. A biography that situates OODA in Boyd's career and explains the loop's evolution from air-combat to general strategy. +- Frans Osinga — *Science, Strategy and War: The Strategic Theory of John Boyd*. The fullest academic treatment of Boyd's thinking and the source for many "OODA is more than a loop diagram" arguments. + +No URLs are given for the original briefings because Boyd never formally published them; multiple reconstructions exist online and on archive.org but their fidelity varies. Treat the books above as the canonical secondary sources. + +## Further reading + +Primary sources and supporting works, listed by author + title. No URLs are given where the canonical edition is offline or where multiple reconstructions exist with varying fidelity. + +- John Boyd — *Patterns of Conflict* (briefing). +- John Boyd — *The Essence of Winning and Losing* (1996). +- Chet Richards — *Certain to Win: The Strategy of John Boyd, Applied to Business*. +- Frans Osinga — *Science, Strategy and War: The Strategic Theory of John Boyd* (book + companion primer article). +- Grant T. Hammond — *The Mind of War: John Boyd and American Security*. +- Herbert Simon — *Administrative Behavior* (for "bounded rationality"). +- Karl Weick — *Sensemaking in Organizations*. +- Gary Klein — *Sources of Power* (for the Recognition-Primed Decision model). +- Donald Schön — *The Reflective Practitioner*. + +## Adjacent patterns + +OODA is not the only decision-cycle pattern worth knowing. The Goal Loop borrows from OODA because it handles uncertainty and tempo well; other patterns optimise for other regimes. + +- **PDCA (Shewhart / Deming)** — Plan-Do-Check-Act. A quality-control loop developed in industrial process control. PDCA presupposes a stable system whose variance you are trying to reduce; the *Plan* step writes an experiment, *Do* runs it, *Check* compares to baseline, *Act* standardises the improvement. The contrast with OODA is the role of learning by experiment: PDCA is explicit about hypothesis-then-test; OODA's "orient" carries the same load implicitly. Goal Loop's `loop-reviewer` formalises the Check step that OODA leaves implicit. +- **MAPE-K (IBM autonomic computing)** — Monitor, Analyze, Plan, Execute, with a shared *Knowledge* layer. Designed for self-managing systems. The explicit Knowledge layer is what most decision loops lack: a place where prior orientation, model state, and policies persist between cycles. Goal Loop folds Knowledge into two artifacts — long-lived `orientation.md` (current synthesis) and `goal-state.md` (contract + history). The split keeps short-term sensing separate from durable understanding. +- **Cynefin (Snowden)** — A sense-making framework that classifies a situation as *clear*, *complicated*, *complex*, *chaotic*, or *confused* and prescribes a different response per domain. OODA is the right loop in *complex* domains where cause and effect are only knowable in retrospect. PDCA and analysis-first methods are right in *complicated* domains where expertise can map cause to effect. Goal Loop should not be applied uniformly — match the loop to the domain. A clear domain just needs a checklist. +- **Control theory** — Goal Loop reads cleanly as a discrete-time controller. Acceptance criteria are setpoints; observations are sensor reads; decisions select actuator commands; actions move the system; review computes the error and feeds it back into the next orientation. The control-theory framing makes one thing obvious: a loop with no measurable setpoint (a non-falsifiable criterion) is open-loop, and open-loop systems do not converge. +- **Lean Startup Build-Measure-Learn (Ries)** — The entrepreneurial cousin of PDCA. *Build* a minimum viable product, *Measure* validated learning, *Learn* whether to pivot or persevere. Parallel to Goal Loop's "continuous awareness" and "discovery-by-loop" patterns — when the goal is to find product-market fit, each iteration is an explicit experiment whose validated learning becomes the orientation for the next. The same gating discipline applies: do not collapse Build and Measure into a vibe. +- **Wardley Mapping** — A strategic-positioning technique that maps a value chain against a horizontal axis of evolution (genesis → custom → product → commodity). Complementary to Goal Loop as an *orientation* technique: when the goal is strategic (where to invest, what to commoditise, what to differentiate), a Wardley map populates `orientation.md` with structure that signals alone cannot. The map is durable across iterations; the signals are not. + +For where each pattern fits relative to Goal Loop, see [`goal-orientation.md`](goal-orientation.md) and [`usage-patterns.md`](usage-patterns.md). diff --git a/plugin-v2/docs/progress-affordance-recipe.md b/plugin-v2/docs/progress-affordance-recipe.md new file mode 100644 index 000000000..000eeeb7e --- /dev/null +++ b/plugin-v2/docs/progress-affordance-recipe.md @@ -0,0 +1,175 @@ +--- +title: Goal Loop — Progress affordance recipe +folder: plugin-v2/docs +description: Opt-in adopter recipe for surfacing fan-out / async progress during Observe and Act phases. The plugin ships no progress affordance by default; this doc shows how to add one without breaking phase isolation. +entry_point: false +--- + +# Goal Loop — Progress affordance recipe + +> Goal Loop's Observe and Act phases can fan out to N or M concurrent subagents. The plugin ships no progress affordance by default; the fan-in is silent until artifacts land. For long-running observers (parallel-observer dedup at fan-in, deep web fetches, slow `Bash` invocations), adopters often want a "something is happening" signal. This doc gives you two recipes: a file-system primitive (no runtime dependencies) and a hook-based notification (requires Claude Code session hooks). + +The recipes here are **opt-in, adopter-owned**, not plugin-owned. They borrow the same posture as [`hooks-recipes.md`](hooks-recipes.md): the plugin stays pure data + prompts; the adopter wires conveniences into their own harness. Neither recipe is required for correctness; removing them never breaks the loop. + +## Recipe A — `_progress.md` (file-system primitive, no dependencies) + +The recommended baseline. Works in every harness because it relies on the file system alone. + +### Where the file lives + +- During Observe: `goals//observations/_progress.md`. +- During Act: `goals//actions/iter-/_progress.md`. + +The underscore prefix keeps the file out of the artifact namespace so it never collides with an ISO-timestamped observation or an action-id action log. Glob patterns that scan `goals//observations/*.md` should explicitly exclude `_*.md`. + +### Who writes it + +The dispatching skill — [`observe`](../skills/observe/SKILL.md) for the Observe phase, [`act`](../skills/act/SKILL.md) for the Act phase — owns the file. **Single writer per phase.** Subagents never read or write `_progress.md`; the orchestrator never touches it. This is what keeps the affordance compatible with [Article II — Phase Isolation](../memory/constitution.md): the file is the *conductor's* progress log, not a phase artifact. + +### What it contains + +Frontmatter records the iteration, phase, and the subagent roster. The body is a three-bucket roll-up of active / completed / pending subagents. + +```markdown +--- +goal_slug: +iteration: +phase: +started_at: +updated_at: +subagents: + - id: observer-1 + source_id: src-inbox + status: running + started_at: + - id: observer-2 + source_id: src-feed + status: done + started_at: + finished_at: +--- +# Progress — / iter / + +## Active +- `observer-1` (source: `src-inbox`) — running since