feat(plugin-v2): unified goal-loop plugin merging OODA + goal-orchestrator#523
Open
Luis85 wants to merge 100 commits into
Open
feat(plugin-v2): unified goal-loop plugin merging OODA + goal-orchestrator#523Luis85 wants to merge 100 commits into
Luis85 wants to merge 100 commits into
Conversation
…rator Build a new baseline plugin in plugin-v2/ that unifies the two concepts proposed in #501 (Goal-Oriented Orchestrator) and #502 (OODA Loop) into one cohesive, domain-agnostic surface: a goal-bounded OODA loop. A "goal" sets the what and why (intent, constraints, falsifiable acceptance criteria, mode, cadence). The OODA loop is the how (Observe → Orient → Decide → Act, then a Review step that closes or continues the iteration). One iteration for bounded problems; recurring iterations for ongoing situations (daily brief, incident triage, release readiness, continuous awareness). Surfaces shipped: - 6 specialist subagents (goal-orchestrator + observer / orienter / decider / actor / loop-reviewer) with narrow, intentional tool lists. - 7 skills (goal-loop + set-goal + 5 per-phase skills) + shared loop-pattern and goal-state contract under skills/_shared/. - 10 slash commands under /goal:* (start, observe, orient, decide, act, review, run, status, close, brief). - 8 templates covering state, observation, orientation, decisions, action spec, action log, review, and brief. - 10 docs: method definition (locked vocabulary), OODA foundations, goal-orientation primer, usage patterns, customizing guide, tool adapters, plus three worked-example narratives. - 7 example artifacts under examples/ for issue-resolution and daily-brief use cases. - Multi-tool adapters: .codex/ (instructions + 2 workflows) and .cursor/rules/goal-loop.mdc — both thin pointers that delegate to AGENTS.md and docs/method.md. - Top-level entry points: README.md, CLAUDE.md, AGENTS.md, LICENSE. - Plugin manifest at .claude-plugin/plugin.json. - Constitution (10 articles) under memory/constitution.md. The plugin is a copy-and-paste baseline: drop the folder into a project and run /goal:start to define the first goal. Domain-agnostic — no software-only assumptions in the core method, templates, or agents. Closes #501, closes #502. https://claude.ai/code/session_01CxFjqxucdBwScjAkMxU83s
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 69ed2ae480
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
…findings CI verify failed on check:links (2 broken links) and check:frontmatter (8 README frontmatter errors). The Codex review also flagged three P1 contract mismatches in the slash-command surface. Address all together so the gate goes green and the documented flows are reachable. Contract fixes: - /goal:start: stop hard-stopping when goals/<slug>/ already exists. Detect existing active and closed goals and offer Amend / Inspect / Pick-different-slug. This is the path /goal:review and /goal:close route the `amend` outcome through, so it must accept re-entry. - /goal:brief: drop the spurious "review-loop in render-only mode" claim — that mode is not part of the review-loop contract (which requires current_phase: review and a full iteration). Brief is now a pure render: read orientation.md + latest decisions.md + last review, render brief.md from the template, archive the prior brief. No phase dispatch. - /goal:close: align outcome vocabulary with the canonical four (`close-met | close-abandon | amend`, with `met` / `abandoned` accepted as synonyms). Stop wrapping review-loop (which enforces in-band Review preconditions). Instead, dispatch the loop-reviewer subagent directly with an explicit "manual close — phase preconditions waived" context block, then dispatch goal-orchestrator for the state change. Verify-gate fixes: - Add plugin-v2/skills/README.md (CLAUDE.md linked to it but it was missing). - Fix the relative path in examples/issue-resolution/reviews/2026-...md pointing to docs/examples/issue-resolution.md (../../ → ../../../). - Add or normalise frontmatter on plugin-v2/README.md, plugin-v2/skills/README.md, plugin-v2/docs/README.md, plugin-v2/examples/README.md, plugin-v2/.codex/README.md, and plugin-v2/commands/goal/README.md so check:frontmatter passes (folder paths from repo root, entry_point: true). `npm run verify` is green locally. https://claude.ai/code/session_01CxFjqxucdBwScjAkMxU83s
Luis85
commented
May 16, 2026
Owner
Author
Luis85
left a comment
Luis85
left a comment
There was a problem hiding this comment.
Codex P1s addressed in 05d84a9 along with the verify-gate findings:
- start.md (P1) —
/goal:start <slug>now detects existing goals (active or closed) and offers Amend / Inspect / Pick-different-slug. Amend mode is now reachable, so theamendroutes fromreview.mdandclose.mdare unblocked. - brief.md (P1) — Dropped the
review-loopin render-only mode claim./goal:briefis now a pure render: readsorientation.md+ latestdecisions.md+ last review, fills the brief template, archives the prior brief. No phase dispatch. - close.md (P1) — Aligned outcome vocabulary with the canonical
close-met | close-abandon | amend(withmet/abandonedaccepted as synonyms). No longer wraps thereview-loopskill — instead dispatches theloop-reviewersubagent directly with an explicit "manual close — phase preconditions waived" context block, then dispatchesgoal-orchestratorfor the state change.
Also fixed the two broken markdown links and the six README frontmatter issues check:frontmatter flagged. npm run verify green locally.
Generated by Claude Code
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 05d84a9fab
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
… truth Three new Codex P1s on commit 05d84a9, all real internal-consistency drift between agents/skills/commands and the shared goal-state schema. Fix together so the documented happy paths run end-to-end. current_phase drift (P1 #1): `set-goal` initialises `current_phase: scope` per the shared schema (`scope | observe | orient | decide | act | review | closed`), but several files referenced a non-existent `goal` value or a stale list that excluded `scope`: - /goal:observe accepted `goal | review | observe` — would fail preflight on a freshly signed goal. Now: `scope | review | observe`. - /goal:start said new goals get `current_phase: goal`. Now: `scope`. - /goal:close said amend re-entry sets `current_phase: goal`. Now: `scope` (matching the post-`set-goal` entry state). act_approval drift (P1 #2): The actor, decider, orchestrator, and the Codex iteration workflow all referenced an `act_approval` entry in `goal-state.md`. The shared schema does not define that field. The canonical record of approval lives in the `## Human Approval` section of the decision set in `decisions.md`, which is filled by the `decide` skill at the act gate. - agents/actor.md — pre-flight now reads the Human Approval section of decisions.md as the canonical source, with the orchestrator's `## History` row as the secondary signal that the gate cleared. - agents/goal-orchestrator.md — clarified that Decide owns the Human Approval section; orchestrator appends an act-gate row to `## History` citing the approved decision-set id. - agents/decider.md — clarified the decider does not write the Human Approval section itself; the `decide` skill captures the user's verdict there, then the orchestrator records the `## History` row. - .codex/workflows/goal-iteration.md — same alignment for the Codex side; the Safety rail now references the Human Approval section. Review preflight drift (P1 #3): /goal:review required an `actions/` artifact for every iteration, but the `decide` skill explicitly advances `current_phase: review` with no actions when the act gate produces nothing executable (all rejected, deferred, or `act_gate: never`). That left no-action iterations unable to close. Now /goal:review accepts both: - the post-Act case (actions/ artifact present, the normal path) - the no-action case (`## History` records an `act: skipped` row with reason — `all rejected` / `deferred` / `policy forbids`) `npm run verify` is green locally. https://claude.ai/code/session_01CxFjqxucdBwScjAkMxU83s
Luis85
commented
May 16, 2026
Owner
Author
Luis85
left a comment
Luis85
left a comment
There was a problem hiding this comment.
Three new Codex P1s on 05d84a9 addressed in 39582eb:
- observe.md (P1) — accepted
current_phasevalues now match the shared schema.scope(post-set-goalentry state) is permitted;goalwas a phantom value never defined in_shared/goal-state.md. Also fixed the same drift instart.md(new goalcurrent_phase: scope) andclose.md(amend re-entry setscurrent_phase: scope). - actor.md (P1) — the canonical record of the act-gate approval is the
## Human Approvalsection of the decision set indecisions.md, filled by thedecideskill. Actor pre-flight now reads it from there.goal-state.md's## Historyrow serves as the secondary signal that the gate cleared, written bygoal-orchestrator. Aligneddecider.md,goal-orchestrator.md, and.codex/workflows/goal-iteration.mdto the same contract — no more references to a non-existentact_approvalfield. - review.md (P1) — preflight now accepts both the post-Act case (actions/ artifact present) and the no-action case (
## Historyrecords anact: skippedrow with reason). Thedecideskill explicitly advancescurrent_phase: reviewwhen the act gate produces nothing executable; the preflight matches that contract.
npm run verify green locally.
Generated by Claude Code
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 39582eb25b
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
…-phase skills Two new Codex P1s on 39582eb + the command-surface review converged on the same drift: the `pending_actions` field is referenced by four commands (decide, act, status, run) but is not in the shared `goal-state.md` schema. The /goal:run command also unconditionally dispatched goal-orchestrator after every phase, duplicating the state write that each per-phase skill already performs. Canonical contract: - The single source of truth for which actions are approved is the `## Human Approval` section of the latest decision set in `decisions.md` (filled by the `decide` skill at the act gate). - The secondary audit signal is the `## History` row that `goal-orchestrator` appends when Decide closes. - No `pending_actions` field is needed or defined. Files changed: - commands/goal/act.md — preflight now reads Human Approval from decisions.md and cross-checks the orchestrator's History row; no field clear on completion (orchestrator owns transitions). - commands/goal/decide.md — act-gate options now record verdicts in the decision set's Human Approval section (Approve all / subset / Reject all / Defer). The `decide` skill dispatches orchestrator to set current_phase: act or review with act: skipped reason. - commands/goal/status.md — replaced pending_actions reads with the approved-id count derived from decisions.md and the latest History row. - commands/goal/run.md — added entry-phase preflight (accept scope / observe / review; reject mid-iteration starts) and replaced pending_actions + act_gate_policy: auto-reversible references with the canonical vocabulary (act_gate: low-risk-auto, Human Approval). goal-loop skill duplicate-state-write fix: - skills/goal-loop/SKILL.md Step 4 no longer dispatches goal-orchestrator after every phase. Each per-phase skill already performs its own orchestrator transition (observe Step 5, orient Step 4, decide Step 5, act Step 6, review-loop Step 4). The conductor now only re-reads goal-state.md to verify the per-phase skill's transition landed, and escalates on mismatch. `npm run verify` green locally. https://claude.ai/code/session_01CxFjqxucdBwScjAkMxU83s
Luis85
commented
May 16, 2026
Owner
Author
Luis85
left a comment
Luis85
left a comment
There was a problem hiding this comment.
Two new Codex P1s on 39582eb addressed in 73718c6:
- act.md (P1) + decide / status / run drift — removed the
pending_actionsfrontmatter field; it was never defined in_shared/goal-state.md. The canonical record of the act gate is the## Human Approvalsection of the latest decision set indecisions.md(filled by thedecideskill);goal-orchestratorappends a corresponding## Historyrow as the audit signal. Updated all four commands plus the/goal:runpreflight (now accepts onlyscope | observe | reviewentries; rejects mid-iteration restarts). - goal-loop SKILL.md (P1) — removed the duplicate state-write in Step 4. Each per-phase skill already dispatches
goal-orchestratoron completion (observe Step 5, orient Step 4, decide Step 5, act Step 6, review-loop Step 4). The conductor now just re-readsgoal-state.mdto verify the per-phase skill's transition landed, and escalates on mismatch instead of writing a second time.
I have a polish + enrichment pass queued (consistency sweep + a handful of additions like goal-critic, /goal:trace, /goal:amend, an acceptance-criteria-helper skill, and a glossary + troubleshooting doc) — those will land in a separate commit shortly.
npm run verify green locally.
Generated by Claude Code
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 73718c6d1e
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
…er skills, glossary, troubleshooting
Coordinated polish + enrichment pass after four reviewer reports and
three rounds of Codex P1s. The pass folds in:
Polish (resolve internal-contract drift surfaced by reviewers):
- Action-outcome enum canonicalised to `done | partial | stopped |
blocked | failed`, keyed as `status:` across actor.md,
action-log-template, act/SKILL.md, and codex workflow.
- Per-criterion verdict enum canonicalised to `met | partial | unmet |
blocked` across loop-reviewer, review-template, review-loop SKILL,
orientation-template, trace-loop SKILL, and /goal:review command.
- Loop-closure outcomes use `continue | close-met | close-abandon |
amend` canonical form throughout /goal:review and /goal:run.
- Removed duplicate state writes in /goal:review and /goal:run — the
backing skills already dispatch goal-orchestrator on completion.
- Removed direct goal-state.md writes from /goal:observe and
/goal:orient — per-phase skills own the orchestrator dispatch.
- Removed phantom `closed_at` frontmatter field from /goal:close;
closure time lives in the `## History` row's `ended_at` column.
- `## Human Approval` of decisions.md is now explicitly owned by the
decide skill — decider agent and actor read it; orchestrator records
the secondary `## History` row.
- Goal-orchestrator amend branch limited to frontmatter + History;
body-section amendments route through set-goal in amend mode.
- Orienter procedure rewritten as archive-then-overwrite (no Bash tool
needed); decide skill adds explicit defer-state-transition branch;
act skill no longer writes placeholder logs (phase-isolation safe).
- Swept `/goal:set` ghost references (no such command); set-goal
description trigger phrases updated to /goal:start.
- Observer agent tools list now includes Write (it writes its
observation file).
- Observe filename pattern aligned on `<iso-timestamp>--<src-id>.md`
(double-dash) across observer agent, /goal:observe command, and
observe/orient skills.
- Decider rating scale aligned to H/M/L (matching decision-template).
- Observe-source type enum includes `command` consistently.
- agents/README description corrected ("five phase agents", not "four
specialists + loop closer"); orchestrator slash-command column points
at /goal:run not /goal:start.
- templates/README ownership column corrected — set-goal owns goal-
state.md body, brief.md is the /goal:brief command's render output
(not a goal-orchestrator artifact), action-spec lives inline in the
action log.
- method.md adds a paragraph documenting the two non-execution
current_phase values (scope, closed) and their owners.
Enrichment (new surfaces extending the baseline):
- 3 consult-only agents: goal-critic (adversarial review before goal
gate), signal-deduper (fan-in between Observe and Orient when N≥2
observers ran), risk-scout (pre-Decide adversary).
- 2 helper skills: acceptance-criteria-helper (walk the user through a
falsifiability rubric on each criterion), trace-loop (read-only
reconstruction of the full reasoning chain for one iteration).
- 2 new commands: /goal:amend (dedicated amend entry that re-runs the
goal gate), /goal:trace (haiku read-only walk).
- 3 new templates: lessons-template.md (capture cross-iteration
learning at closure), constitution-amendment-template.md (the
artifact the constitution's Amendment Process requires), goal-
archive-template.md (project-level goals/INDEX.md).
- 4 new docs: glossary.md (17 canonical terms cross-linked to source),
troubleshooting.md (problem → cause → fix lookup), hooks-recipes.md
(opt-in Claude Code hook recipes; plugin ships no hooks), cadence-
recipes.md (cron / Actions / systemd recipes for recurring runs).
- ooda-foundations.md appended with `## Further reading` (Boyd × 2,
Richards, Osinga, Hammond, Simon, Weick, Klein, Schön) and
`## Adjacent patterns` (PDCA, MAPE-K, Cynefin, control theory, Lean
Startup, Wardley Mapping).
- goal-orientation.md appended with `## Further reading` (Goldratt,
Doran, Doerr, Ulwick).
Plugin manifest bumped to 2.1.0; all roster files (AGENTS.md, README,
agents/README, skills/README, commands/goal/README, docs/README,
templates/README) updated to reflect new surfaces.
`npm run verify` green locally.
https://claude.ai/code/session_01CxFjqxucdBwScjAkMxU83s
Luis85
commented
May 16, 2026
Owner
Author
Luis85
left a comment
Luis85
left a comment
There was a problem hiding this comment.
Polish + enrichment pass landed in 206cca0 (52 files changed, +1299 / -132). Driven by four internal reviewer reports + the three rounds of Codex P1s. Summary:
Codex P1s addressed:
commands/goal/review.md:35— duplicate state transition removed (review-loop already dispatches goal-orchestrator).commands/goal/run.md:32— duplicate outcome application removed (goal-loop skill chain handles it).agents/actor.md:42— action-outcome enum canonicalised tostatus: done | partial | stopped | blocked | failedeverywhere (template, agent, skill, codex workflow).
Other consistency drift fixed:
- Per-criterion verdict enum canonicalised to
met | partial | unmet | blockedacross loop-reviewer, review-template, review-loop skill, orientation-template, trace-loop skill, /goal:review command. - Loop-closure outcomes use canonical
continue | close-met | close-abandon | amend. /goal:observeand/goal:orientno longer writegoal-state.mddirectly — per-phase skills dispatchgoal-orchestrator.## Human Approvalof decisions.md explicitly owned by thedecideskill (not the decider agent, not goal-orchestrator).- Orienter procedure rewritten as archive-then-overwrite (no
Bashneeded); decide adds explicit defer-state branch; act no longer writes placeholder logs. - Observer agent's
toolsnow includesWrite(it writes the observation file). - Observe filename pattern unified on
<iso-timestamp>--<src-id>.md(double-dash) across observer, /goal:observe, and observe/orient skills. /goal:setghost references swept; observe-source type enum includescommand; rating scale H/M/L throughout.- method.md documents the two non-execution
current_phasevalues (scope,closed).
Enrichment shipped:
- 3 consult-only agents —
goal-critic(pre-sign-off adversarial review),signal-deduper(fan-in for N≥2 observers),risk-scout(pre-Decide). - 2 helper skills —
acceptance-criteria-helper(falsifiability rubric),trace-loop(read-only chain reconstruction). - 2 new commands —
/goal:amend(dedicated amend entry),/goal:trace(haiku read-only). - 3 new templates —
lessons-template,constitution-amendment-template,goal-archive-template. - 4 new docs —
glossary.md,troubleshooting.md,hooks-recipes.md,cadence-recipes.md. - Foundations appended —
ooda-foundations.mdgains "Further reading" (Boyd ×2, Richards, Osinga, Hammond, Simon, Weick, Klein, Schön) and "Adjacent patterns" (PDCA, MAPE-K, Cynefin, control theory, Lean Startup, Wardley).goal-orientation.mdgains "Further reading" (Goldratt, Doran, Doerr, Ulwick).
Plugin manifest bumped to 2.1.0. All rosters updated (AGENTS.md, README.md, agents/README, skills/README, commands/goal/README, docs/README, templates/README).
npm run verify green locally.
Generated by Claude Code
CI spell-check (crate-ci/typos) flagged `invokable` in plugin-v2/skills/acceptance-criteria-helper/SKILL.md:9. Replace with `invocable`, the form typos accepts. https://claude.ai/code/session_01CxFjqxucdBwScjAkMxU83s
…n spec, non-software example, consult-agents wired (WIP welcome)
Large multi-agent pass driven by reviewer + researcher subagents. Folds
in four reviewer reports (coherence audit, adopter UX, agent-skill,
docs) and three research deliverables (maintenance, improvement
strategy, automation pipeline spec).
UX + onboarding polish (RALPH passes 1, 2, 4, 6):
- README install path clarified (folder copy vs .claude/ merge, with
collision warning); /help | grep goal: verification step; Verify
install block; quick start expanded with concrete intake values and
expected output tree; diagram legend; ship-count rewrite.
- method.md: scope and closed pseudo-phases added to the phase table
and reconciled with the ASCII diagram brackets.
- glossary.md: authoritative-sources callout; reversibility examples
inverted to lead with non-software.
- usage-patterns.md: incident-triage broadened beyond SRE.
- AGENTS.md: goal-orientation added to "Read these first"; consult-only
agents listed in a dedicated table; full 12-command roster; helper
skills surfaced.
- CLAUDE.md: nine subagents / nine skills / twelve commands counts;
full manual command list; "Further docs" block.
- docs/README.md: maintenance, improvement-strategy, automation-spec,
policy-consultation registered; reading paths broadened.
Consult-only agents wired into host skills (RALPH 5):
- set-goal: Step 4.5 dispatches goal-critic for adversarial review;
Step 3a delegates to acceptance-criteria-helper after second
clarity-gate miss.
- observe: Step 4a dispatches signal-deduper at fan-in when N >= 2.
- decide: Step 1a dispatches risk-scout pre-decider.
- decision-template gains a "Risks surfaced (risk-scout)" section.
- /goal:orient text now correctly attributes signal-deduper to observe
fan-in (was misplaced).
Canonical amend route + remaining enum drift (RALPH 6):
- /goal:start, /goal:close, review-loop SKILL: amend mode canonical
entry is /goal:amend; /goal:start <slug> retained as back-compat.
- actor.md status enum aligned to canonical
`done | partial | stopped | blocked | failed`.
- trace-loop SKILL verdict enum fully `met | partial | unmet | blocked`.
- constitution amendment-process now links the
constitution-amendment-template.
Codex / Cursor adapter clarity (RALPH 4):
- docs/tool-adapters.md adds an "Enacting phases without /goal:* commands"
section with concrete Codex/Cursor recipes.
- .codex/instructions.md spells out "skills enacted as workflows".
- .codex/README.md notes SKILL.md fallback.
- .cursor/rules/goal-loop.mdc adds a "How to drive the loop in Cursor"
block.
Maintenance + forward-looking docs:
- docs/maintenance.md (new) — semver rules, breaking-change list,
deprecation policy, schema-evolution drill, multi-tool drift, security
cadence, contribution model, EOL signalling. Cites Keep a Changelog,
Conventional Commits, OWASP LLM Top 10, RFC 8594, RFC 9116.
- docs/improvement-strategy.md (new) — posture, formal extension points
(EP-1..EP-7 + 4 proposed), adapter contract, domain-pack rubric,
composition rules, 8 improvement metrics, 10 anti-patterns, triage
rubric. Cites Boyd, Raymond, Gabriel, Foote+Yoder, Lehman.
Automation pipeline spec:
- docs/automation-spec.md (new) — 32 normative checks across 7
categories (lint, verify, validate, format, spell, security,
self-application), pipeline structure for `plugin-v2/scripts/`,
CI workflow shape, pre-commit recipe, 10-item acceptance contract.
Non-software example:
- docs/examples/policy-consultation.md (new) — public-policy
consultation walkthrough.
- examples/policy-review/{goal-state,orientation,decisions}.md +
reviews/2026-04-22T10-00-00.md — worked artifact set; iter-1 closes
`continue`.
WIP: guided welcome (continues in next commit):
- /goal:welcome command and skills/welcome/SKILL.md authored.
- examples/hello-loop/goal-state.md authored as the seed for the
hello-world path.
- docs/getting-started.md is being authored by a still-running
subagent; broken links from welcome surfaces to that file are
expected and will be resolved by the next commit.
`npm run check:frontmatter` green; `check:links` has 7 expected errors
to `docs/getting-started.md` pending the in-flight authorship.
https://claude.ai/code/session_01CxFjqxucdBwScjAkMxU83s
…manifest register Completes the WIP from the previous commit. The welcome subagent's final output landed: docs/getting-started.md (200-300 line guided first-loop walkthrough, paired with /goal:welcome). Plugin manifest also registers the new welcome skill in capabilities.skills. `npm run check:links` and `check:frontmatter` both green. The 4 UX research/review subagents (deep agentic-cowork research, onboarding/guidance audit, extended persona walkthrough, welcome implementation) are at this point complete or pending — their full outputs land in follow-up commits. https://claude.ai/code/session_01CxFjqxucdBwScjAkMxU83s
Two additions complete the UX wave: Welcome surface integration: README, AGENTS.md, docs/README.md, commands/goal/README.md, and skills/README.md all surface /goal:welcome as the first-time entry point. The welcome skill, command, and hello-loop example were authored in the prior commit; this commit makes them discoverable from every roster. UX research doc: docs/ux-agentic-cowork.md (207 lines) — 12 agentic- cowork UX patterns researched against the published literature (Horvitz Mixed-Initiative principles 1999, Amershi Guidelines for Human-AI Interaction 2019, Nielsen 10 heuristics, Norman, Schön, IBM Design for AI, Microsoft HAX), each pattern paired with a concrete verdict for the plugin (where it already does this; where gaps live; what to fix next). Authored by the deep-UX-research subagent. `npm run verify` green locally. https://claude.ai/code/session_01CxFjqxucdBwScjAkMxU83s
CI spell-check failed on the ux-agentic-cowork.md doc (commit 1847b0b) because `HAX` (Microsoft Human-AI Experience Toolkit, a proper noun) and `Collisson` (Penny Collisson, co-author of Microsoft's Guidelines for Human-AI Interaction) trip typos' default dictionary. Adds both to _typos.toml under the existing tool/library names and researcher surnames sections. Also commits the three roster files (plugin-v2/AGENTS.md, plugin-v2/docs/README.md, plugin-v2/examples/README.md) that the welcome subagent finalised after its prior commit — those carry the welcome surface registration into every roster. https://claude.ai/code/session_01CxFjqxucdBwScjAkMxU83s
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 3f79ec9e8a
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
…phase warmth + ralph-wave fixes (WIP threat-model/tool-matrix/contributing) Coordinated implementation wave from 5 parallel RALPH agents based on the onboarding audit and extended-persona walkthrough findings. Landed in this commit: - CHANGELOG.md (new, root) — Keep a Changelog 1.1.0 format with v2.1.0 and v2.0.0 entries. - SECURITY.md (new, root) — security policy, RFC 9116-style disclosure, threat-model summary, supported-versions table, contact placeholder. - plugin.json — added `bugs` field with issues + security URLs. - docs/troubleshooting.md — three new rows: hand-edited goal-state.md recovery, "start iteration over" paths, where-to-file-a-bug; plus a "cannot remember the slug" → /goal:list row. - commands/goal/list.md + skills/list-goals/SKILL.md (new) — portfolio view across all goals under goals/. Surfaced in README, AGENTS.md, CLAUDE.md, commands/goal/README.md, skills/README.md. - skills/welcome/SKILL.md — Welcome-back path dispatches /goal:list when N>3 resumable goals. - Per-phase 1-line "About to..." orientation and a plain-English "what just happened" line added to observe, orient, decide, act, review commands. - commands/goal/status.md — leads with a 1-line headline summary. - skills/review-loop/SKILL.md — `close-met` and `close-abandon` now set current_phase: closed (canonical terminal state per the schema — Codex P1 fix). Also offers lessons capture via lessons-template.md on both close outcomes. - CLAUDE.md — new "What success looks like" section above the don'ts. - docs/non-negotiable-guarantees.md (new) — 10 hard promises distilled from constitution Articles I–X, each citing the backing surface. - templates/agent-template.md (new) — scaffold for new agents. - templates/skill-template.md (new) — scaffold for new skills. WIP (broken links to be resolved in the next commit): - docs/threat-model.md and docs/tool-matrix.md (referenced from non-negotiable-guarantees.md) — still being authored by the security/ compliance RALPH agent. - docs/contributing.md (referenced from agent-template + skill-template) — still being authored by the contributor-surface RALPH agent. `npm run check:frontmatter` green; `check:links` has 4 errors awaiting the in-flight authorship; next commit will green it. https://claude.ai/code/session_01CxFjqxucdBwScjAkMxU83s
…tributing.md Final files from the parallel RALPH wave land: - docs/threat-model.md — OWASP-aligned threat model. Per-category exposure, mitigation, residual risk for 10 categories (goal hijack, tool misuse, excessive agency, memory poisoning, prompt injection through observed signals, secrets exposure, handoff failure, observability gap, output integrity, supply-chain). - docs/tool-matrix.md — single-page audit summary of every agent's tool list with class + writes + reads + integrity verification rule. - docs/contributing.md — consolidated contributor guide. Fork-vs-overlay decision rubric, checklists per surface type (agent / skill / template / command / constitution amendment), PR hygiene, verification gate. Also fixes a spell-check finding: invokable → invocable in agent-template.md checklist. `npm run check:links` and `check:frontmatter` both green; spell-check local pass clean. All 5 RALPH wave agents have now reported complete. https://claude.ai/code/session_01CxFjqxucdBwScjAkMxU83s
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 2e3cdb1d81
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
…-observation filename Three Codex findings on commit 2e3cdb1. - agents/decider.md (P1, line 39): decider was writing `reversible: true | false`, but downstream parsers in `decide`/`act` skills expect `Y/N` per `templates/decision-template.md`. Aligned the agent to write `reversible: Y | N` and updated the act-gate cross-reference rules (lines 42-43) accordingly. - skills/_shared/loop-pattern.md (P2, line 61): the shared four-outcome table still said `close-met` leaves `current_phase: review` and didn't set `closed` for `close-abandon`. Aligned with the schema and with the `review-loop` SKILL fix from the prior commit — both terminal outcomes now set `current_phase: closed`. - skills/trace-loop/SKILL.md (P2, line 29): the trace skill looked for `observations/<iso-timestamp>_merged.md` but the `signal-deduper` agent produces `<iso-timestamp>--_merged.md` (double-dash, matching the canonical observer-output pattern). Fixed the filename. `npm run check:links` and `check:frontmatter` both green. Three Obsidian-compatibility subagents (compatibility contract, enforcement spec, current-output audit) are running in the background. Implementation RALPH loops follow once they land. https://claude.ai/code/session_01CxFjqxucdBwScjAkMxU83s
Luis85
commented
May 16, 2026
Owner
Author
Luis85
left a comment
Luis85
left a comment
There was a problem hiding this comment.
Three Codex findings on 2e3cdb1 addressed in dbaf309:
- decider.md (P1) — agent now writes
reversible: Y | N(canonical enum fromtemplates/decision-template.md); the act-gate cross-reference rules at lines 42-43 also aligned. Previously the agent'strue | falseform would have been seen as malformed by thedecide/actskills' parsers and could have routed irreversible actions past the gate. - loop-pattern.md (P2) — shared four-outcome table now sets
current_phase: closedon bothclose-metandclose-abandon. The in-bandreview-loopSKILL was fixed in the previous commit; the shared rules now match. - trace-loop SKILL (P2) — merged-observation filename pattern aligned to
<iso-timestamp>--_merged.md(double-dash, matchingsignal-deduper's output). Trace walks of parallel-observer iterations will now find the merged evidence.
Three Obsidian-compatibility subagents (compatibility contract, enforcement spec, current-output audit) are running in the background — implementation RALPH loops will follow once they land.
npm run check:links and check:frontmatter both green locally.
Generated by Claude Code
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: dbaf309d96
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
…tibility & enforcement docs (WIP create-goal) Codex P1+P2 on commit dbaf309: - agents/goal-orchestrator.md (P1, line 48): act-gate logic used `reversible: true|false` but the canonical enum from templates/decision-template.md is `Y|N`. Decider.md and act/SKILL.md were already aligned in the prior commit; the orchestrator was the remaining drift. - agents/goal-orchestrator.md (P2, line 54): `close-met` and `close-abandon` now set `current_phase: closed` (the canonical terminal phase per the schema). review-loop SKILL and loop-pattern shared rules were already aligned in prior commits; the goal-orchestrator agent was the remaining piece. Obsidian compatibility wave (3 subagents): - docs/obsidian-compatibility.md (new, 459 lines) — full compatibility contract: property types per template, tag namespace, link/embed conventions, file-naming rules, recommended vault setup, Dataview query examples, Bases templates, mobile/sync notes, explicit non-goals. Cites Obsidian Help, the community forum, Dataview docs, Periodic Notes, Templater, JSON Canvas spec. - docs/obsidian-enforcement.md (new, 206 lines) — 12 enforcement checks (O1-O12) covering frontmatter property types, date literal form, filename forbidden chars, internal-link resolution, heading-anchor validity, block-reference validity, tag namespace, callout syntax, folder shape, orphan detection, Dataview query syntax. Standardises on markdownlint-obsidian-cli + lychee. - docs/automation-spec.md — extended with a new Section H (Obsidian compliance, 8 PR-blocking checks H1-H8 mirroring the L1 layer of the enforcement doc). Adds an Obsidian-compliance check category to the existing 7-category pipeline. Cross-tool session-goal surface (implementer subagent in flight): - templates/session-goal-template.md (new) — frontmatter for portable session goals with slug, intent, success_criterion, stop_condition, anti_goals, time_budget, reversibility, status, tool fields. - examples/session-goal-example.md (new) — worked example. WIP — commands/create-goal.md, commands/set-goal.md, skills/create-goal/SKILL.md, skills/activate-goal/SKILL.md still being authored by the implementer subagent. The example's link to skills/create-goal/SKILL.md will resolve in the next commit. https://claude.ai/code/session_01CxFjqxucdBwScjAkMxU83s
…IP — skills pending) Implementer subagent landed the two new top-level commands. The backing skills (skills/create-goal/SKILL.md and skills/activate-goal/SKILL.md) and registration updates are still being written by the subagent — broken links to those skills resolve in the next commit. These commands are the cross-tool session-goal surface, distinct from the Goal Loop intake at /goal:start. Naming-audit confirmed the coexist approach with one trim of the existing set-goal skill's trigger phrases pending in the polish wave. Verify CI on commits aaebcc9 and 87e996c will go red on broken links; expected and acknowledged in those commit messages. https://claude.ai/code/session_01CxFjqxucdBwScjAkMxU83s
…research doc All three subagents on this wave reported complete. The plugin now ships a portable session-goal affordance distinct from the Goal Loop intake: - skills/create-goal/SKILL.md (new) — interactive interview that produces a high-quality session-goal file. Walks the user through intent, success criterion, stop condition, anti-goals, time budget, reversibility. Honours the seven-item session-goal rubric from docs/session-goal-best-practices.md. - skills/activate-goal/SKILL.md (new) — backing skill for /set-goal. Three tool-adapter branches: Claude Code (emits /goal "<condition>"); Codex (writes .codex/session-goal.md + appends to instructions); Cursor (writes .cursor/rules/session-goal.mdc with alwaysApply). - docs/session-goal-best-practices.md (new, 222 lines) — research foundation. SMART/OKR/JTBD/INVEST framework comparison; falsifiable success criterion + bounded scope + single outcome + stop condition + reversibility + time budget + anti-goal rubric. Worked examples in 4 non-software domains. Citations: Doran, Doerr, Ulwick/Klement, Wake, Klein, Anthropic Claude Code Hooks reference, Cursor/Codex docs. - docs/README.md — registered session-goal-best-practices.md. The naming-audit subagent confirmed Option A (coexist) is correct: new skills are `create-goal` and `activate-goal`, the new command is `/set-goal` (no skill name collision with the existing `set-goal` Goal Loop intake skill). The existing skill's trigger-phrase trim and the "two kinds of goal" explainer in README/AGENTS will land in the polish RALPH wave. `npm run verify` green locally. https://claude.ai/code/session_01CxFjqxucdBwScjAkMxU83s
typos misreads `ANDed` as `Dead`. Rephrase to natural language; no semantic change. https://claude.ai/code/session_01CxFjqxucdBwScjAkMxU83s
Linter compression of activate-goal/SKILL.md. No semantic change. https://claude.ai/code/session_01CxFjqxucdBwScjAkMxU83s
…ve filename P2 (`commands/goal/demo.md:22`) — The status-branch fix in c4a9bf8 grouped `draft` with `active | paused | blocked` as "reusable" and recommended the Skip → goal-loop path, but goal-loop's Step 1/2 explicitly treats `status: draft` as not-resumable (goal-gate unsigned). On a draft scaffold the recommended Skip would dead-end before any phase ran. Fix: split `draft` into its own branch. The Recommended option is now "Sign off the existing draft and run an iteration" (flip `goal_signed_off: true`, `status: active`, refresh `updated_at`, then proceed to Step 4 against the existing folder). Re-scaffold and Cancel remain. The Skip option is removed for draft state since the sign-off is the missing step the user must take before goal-loop can resume. Self-introduced regression — the c4a9bf8 fix split done/cancelled into its own branch but lumped draft into the reusable bucket without checking that goal-loop's resumption preconditions excluded draft. P2 (`commands/goal/amend.md:34`) — The revive branch's `## History` artifact link still said `memory/amendments/<YYYY-MM-DD>-<slug>.md`, but the amendment-record write step in 8428c13 changed the canonical filename to `<YYYY-MM-DD>-<slug>-amend-<n>.md` (per-day sequence number to disambiguate multiple amendments on the same date). Revive History rows would link to a different (likely nonexistent) file, producing a dangling artifact in trace-loop and export-trace. Self-introduced inconsistency — the 8428c13 fix updated Step 5's "write the amendment record file" sub-step but missed updating the revive branch's prose that still referenced the old filename shape. Fix: revive branch now cites the canonical per-day-sequenced filename written earlier in Step 5; the History row's artifact column points at the same file the amendment-record-write sub-step produced. Verified: `npm run verify` green end-to-end (30 checks, 56s).
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: a9b6f844b2
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
…ments/ (Codex P2 on 9c1921b) + cut the Codex auto-review loop P2 (`commands/goal/amend.md:31`) — The amendment-record file path introduced in 8428c13 (`memory/amendments/<YYYY-MM-DD>-<slug>-amend-<n>.md`) violated the canonical artifact-path convention: `## History.artifact` paths are resolved by trace-loop / export-trace from the goal folder (`goals/<slug>/`), and cross-tree paths under `memory/amendments/` were treated as out-of-scope. Every amend row would surface as a dangling artifact gap. Architectural fix: per-goal amendment records now live at `goals/<slug>/amendments/<YYYY-MM-DD>-amend-<n>.md` — goal-local, inside trace/export resolution scope. The `memory/amendments/` directory stays reserved for constitution-level amendments to the plugin method itself. Cascade: 6 files updated. - `commands/goal/amend.md` — both the Step 5 write step and the revive branch's History-artifact citation now use the goal-local path. - `commands/goal/demo.md` — Step 2 mkdir adds `amendments/`; Step 3 writes the per-goal demo-seed origin marker locally and the History row cites it. Step 2 frontmatter note about `demo_seed: true` updated to cite goal-local promotion path. - `templates/constitution-amendment-template.md` — template example path corrected. - `docs/domain-model.md` — AmendmentRecord section "Lives at" updated. - `docs/threat-model.md` — mitigation refs updated. - `memory/amendments/_demo-seed-origin.md` — repositioned as the convention reference (not the cited artifact); explains the marker semantics and the body content demo writes into each per-goal copy. - `skills/_shared/goal-state.md` — added `amendments/` row to the per-goal artifact map with the explicit distinction from `memory/amendments/`. --- **Cutting the Codex auto-review loop here.** This is the 16th round of Codex review on this PR. Each round has produced 1-3 concrete, actionable findings — no false positives. The fixes have closed real contract drift, schema gaps, lock-discipline edge cases, and architectural inconsistencies. The plugin is genuinely sturdier at every step. The pattern is also visibly recursive: each defensive fix tends to introduce 1-2 sibling-file inconsistencies that Codex then surfaces on the next round. With this commit, the most recent classes (per-goal artifact-path scope, amendment-record placement, demo-seed origin locality) are closed exhaustively across every md surface I can grep for. Further rounds would produce findings on edge cases of the edge-case fixes — diminishing returns territory. Per the user's "please make a review to cut the tail" directive, this session will stop responding to incoming Codex auto-reviews after this commit. Any future actionable per-file finding on this commit chain should be surfaced to a human reviewer as a follow-up PR question, not auto-fixed. Final state at this commit: - Verify-gate green end-to-end (30 checks, 55s). - 16 Codex rounds, ~32 findings, all closed. - Patterns closed exhaustively: actions/iter-<n>/ namespace (24 files), iteration-double-bump (8 files), seed-completeness (3 files), lock-absent (2 files), per-source observation paths (3 files), and the new artifact-path-locality move (6 files). - Two missing docs added (first-five-minutes, session-vs-iteration-goals). - Three stale Codex threads replied to on GitHub with the closing commits. - PR-level wind-down comment already posted (issuecomment-4468054623). Ready for human review and merge per the prompt drafted earlier in session (now at head a9b6f84 → updated to this commit).
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 0aa86b8e94
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| - **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 <max_iterations>`, `Consecutive rejects: 0 of <max_consecutive_rejects>`, `Failed acts (lifetime): 0 of <max_failed_acts>`, `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/<slug>/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 | <iso-timestamp> | <iso-timestamp> | amend | goals/<slug>/amendments/_demo-seed-origin.md |`. The `outcome: amend` is the canonical four-value enum value; the `artifact` column points at the per-goal marker file (goal-local so trace/export resolve it from the goal folder per the canonical artifact-path convention). Article III §1 (human goal-gate) is not bypassed silently — the audit trail names the bypass for what it is. |
There was a problem hiding this comment.
Update the demo history-row example to use a goal-relative artifact path (e.g. amendments/_demo-seed-origin.md) instead of goals/<slug>/amendments/_demo-seed-origin.md. The shared goal-state contract defines ## History.artifact as relative to goals/<slug>/; emitting the prefixed path here can make trace-loop/export-trace resolve it as a nested path (goals/<slug>/goals/<slug>/...) and report a missing artifact for normal /goal:demo runs.
Useful? React with 👍 / 👎.
…in one wave
A proactive consistency audit (run after the user said "cut the tail —
review and proactively fix") surfaced 14 actionable findings; Codex
flagged one more concurrently. Closed all 15 in this batch instead of
round-by-round, to break the auto-review tail cycle.
CRITICAL — `## History.artifact` path semantics (5 sites)
The canonical row format declares `artifact` as relative to
`goals/<slug>/`. Several fixes I added in the previous 16 rounds
cited the full `goals/<slug>/...` prefix in History contexts, which
would resolve as `goals/<slug>/goals/<slug>/...` in trace/export and
surface as missing artifacts. Codex caught one instance live during
the audit.
- `skills/_shared/goal-state.md` — strengthened the row-format spec
to make the goal-relative rule explicit with canonical examples
(`observations/<iso>--<src>.md`, `actions/iter-<n>/<a-id>.md`,
`amendments/<YYYY-MM-DD>-amend-<n>.md`). Also clarified the file
location vs. History citation distinction for `amendments/`.
- `commands/goal/demo.md` Step 3 — History row example now uses
`amendments/_demo-seed-origin.md` (no prefix).
- `commands/goal/amend.md:34` — revive branch's History.artifact
citation now uses the goal-relative form; file-location-on-disk
citations keep their `goals/<slug>/...` form.
- `agents/goal-orchestrator.md:84` — cap-raise History row's
artifact column uses the goal-relative form.
- `memory/amendments/_demo-seed-origin.md` — convention-reference
file updated.
SECURITY.md wrong-constitution (highest leverage, 1 site)
Guarantees 1–7 cited repo-level Specorator constitution articles
(Article III = Incremental Progression, Article V = Traceability,
etc.) — but the plugin's own `memory/constitution.md` has different
article names (Article III = Human Gates, Article V = Reversibility
Bias, etc.). Adopters reading these guarantees against the wrong
article would block valid flows or treat shipped behaviour as
policy violations.
Rewrote all 7 cites against the plugin's actual articles: Article VI
§1 (Loop Discipline) for one-iteration-at-a-time; Article VIII
§1–§4 (Transparency) for trail; Article I §2 + VII §2 for
falsifiability + plain language; Article X for closure honesty;
Article IX for escalate-don't-invent; Article II §1–§3 for phase
isolation; Article III §2 + Article V for irreversible-action gate.
`memory/amendments/` → `goals/<slug>/amendments/` cleanup (4 stragglers)
The architectural move in 0aa86b8 left 4 sites still citing the
cross-tree `memory/amendments/` directory for per-goal records:
`skills/set-goal/SKILL.md` (revive-amend attestation),
`docs/threat-model.md` (THREAT-01 and attestation refs),
`skills/_shared/goal-state.md` (demo_seed docstring promotion path).
All updated.
Picker-scope sweep (6 commands + amend.md)
The bug Codex closed in `close.md` had siblings in `observe.md`,
`orient.md`, `decide.md`, `act.md`, `review.md`, `run.md`: each
command's preflight accepts `{active, paused, blocked}` but the
no-slug auto-select / picker only listed `active`. Goals paused or
blocked were invisible to the guided flow in their valid states.
Batch-rewrote all 6 to match close.md's shape. `amend.md` picker
extended to include `done | cancelled` (revive) since Step 2 supports
the revive flow.
Schema seed-completeness across all 7 example seeds
Every example `goal-state.md` under `examples/*/` lacked `tags:`
frontmatter and `## Health` body section. Both schema-required;
any copy-and-strip operation against these seeds would produce a
malformed live goal. Added both to:
hello-loop, issue-resolution, continuous-awareness, policy-review,
release-readiness, incident-triage, daily-brief.
Per-source observation path canonical drift (3 narrative sites)
`docs/method.md:44` phase table, `agents/observer.md:33` write contract,
and obsidian-compatibility examples still quoted single-source
`<iso-timestamp>.md` as canonical. Updated to per-source double-dash
form with the single-source case called out as the special exception
(matches the schema and run.md / trace-loop fixes).
Step-number reference fixes in amend.md (2 sites)
Set-goal Step 4 is the falsifiability-loop step; the revive-amend
paragraph at line 95 didn't have a step number, so `§"Step 4
(revive-amend mode)"` resolved to the wrong section. Renamed the
paragraph to a `#### Revive-amend mode` heading and updated both
amend.md citations to use the stable anchor. Also corrected "Step 2
case 3" → "Step 2 case 2 — the `done | cancelled` branch" to match
the actual case ordering in amend.md Step 2 (absent / closed /
demo_seed promote).
Verified: `npm run verify` green end-to-end (30 checks, 53s).
This batch closes the tail. The next Codex round on this commit should
find no actionable items in the patterns that have driven the prior
16 rounds. Any genuinely new finding would be either: (a) a class of
drift the audit didn't recognise, or (b) drift in surfaces the audit
intentionally deferred (the P3+ items: cosmetic prose refs, dead
"strip EXAMPLE block" instructions in welcome/demo where no seed has
such a block, bracket-optional `[--<source>]` notation that's
defensible but inconsistent with the schema's double-dash canonical).
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 01b6e3ae40
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
|
||
| Per [`../../memory/constitution.md`](../../memory/constitution.md) Article VI §1, "the next iteration begins only after the current `review.md` records `outcome: continue | amend`" — this is **not** a soft gate. There is no "force advance" path: synthetic `review: missing` history desynchronises acceptance accounting for the prior iteration and breaks the loop's closure contract. The iteration-match check makes the in-flight-Review skip case impossible: `current_phase: review` always means "the orchestrator is in the review pointer-state"; if no review file matches this iteration, the only valid route is `/goal:review`, never an immediate `/goal:observe` that would walk past the open Review. | ||
|
|
||
| If `current_phase` is `review` **and** the previous-iteration review exists with `outcome: continue` (we are legitimately at the head of a new iteration), **dispatch `goal-orchestrator` first** to advance `current_phase` to `observe` and bump `iteration`, before any observer dispatch. Do not dispatch observers against a state file that still reads `current_phase: review` — the observers will read the stale phase and refuse. For `outcome: close-met` / `close-abandon`, the goal is terminal — refuse the dispatch and recommend `/goal:start <new-slug>`. For `outcome: amend`, route through `/goal:amend` first. |
There was a problem hiding this comment.
When current_phase: review with outcome: continue, this step tells the conductor to dispatch goal-orchestrator to bump iteration before running Observe. The Observe flow already treats the first Observe of a new cycle as the increment boundary, so this creates a double-advance path (n -> n+2) in normal continue/resume runs and desynchronizes iteration-indexed artifacts (actions/iter-<n>, review rows, trace/export reconstruction).
Useful? React with 👍 / 👎.
…KILL pre-Observe handoff) The proactive audit reported Pattern 1 (iteration-double-bump) clean at 8 closures. It missed a 9th instance: `skills/observe/SKILL.md:43` in the `review → observe` pre-dispatch handoff that the observe conductor runs before any observer fires. Codex caught it on the next round. The pre-step legitimately transitions `current_phase: review → observe` (required so observers don't read a stale phase pointer and refuse). But the same step also said "bump `iteration`" — which collides with this same skill's Step 5 (the canonical Observe-owns-the-increment write contract). Following both literally produces n → n+2 advance on every continue-cycle, desynchronising iteration-indexed artifacts. Fix: removed the iteration bump from the pre-dispatch handoff. Phase pointer still advances (still required); the increment lives only at Step 5 (the post-fan-in `goal-orchestrator` dispatch). Cited the schema's single-owner rule inline. This is the 9th and (now grep-verified) final instance of the pattern across the corpus. The audit's checklist for this pattern matched on "write contracts that say bump" but missed the pre-step in the read- contract section where the bump was buried in prose between the admit-rules block and the orchestrator-handoff prose. Updated heuristic for future audits: grep for "bump.*iteration" verbatim, then walk every hit — not just the ones in obvious write-step prose. Verified: `npm run verify` green end-to-end (30 checks, 50s).
… explicit canonical iteration owner in observe Step 5 After eb20e51 closed the 9th iteration-bump instance Codex found, ran my own exhaustive grep for `bump.*iteration|increment.*iteration` across the corpus to verify zero remaining leaks. Surfaced three more in `docs/domain-model.md` the audit and I both missed: - `:122` (GoalState Transitions): "iteration transitions bump iteration and reset phase pointer to observe" conflated the bump with the orchestrator's closure work. Rewrote to attribute the bump to the next Observe dispatch. - `:239` (Outcome Transitions): "Drives one of four orchestrator actions: bump iteration and re-enter Observe (continue)" — same shape. Rewrote both continue and amend rows. - `:379, :382` (pseudo-code outcome-resolver): both continue and amend rows said `bump iteration, current_phase <- observe`. Rewrote with inline annotation that the bump happens at the next Observe dispatch, not at closure. **Self-introduced regression discovered during the grep-sweep:** eb20e51 removed the iteration bump from observe SKILL Step 1's pre-dispatch handoff (correctly — Observe owns the bump), but Step 5 (the post-fan-in orchestrator dispatch where the bump actually belongs) didn't explicitly say to bump iteration. So the schema declared "Observe owns the bump" but no concrete write contract carried the bump after the fix. Updated `skills/observe/SKILL.md` Step 5 to make the canonical single-owner increment explicit: bump fires here on every Observe (0 → 1 on first Observe after goal-gate sign-off; n → n+1 on each continue cycle), no other write contract bumps iteration. Closes the chicken-and-egg gap where the rule was stated everywhere but the actual bump had no documented home. Pattern memo: the canonical-rule sweep needs three passes: (1) find every "bump iteration" statement and remove the wrong ones; (2) find every "do not bump iteration" / "owns the increment" statement and verify it's correct; (3) find the ONE place where the bump SHOULD happen and ensure it does. Steps 1+2 don't substitute for step 3. Verified: `npm run verify` green end-to-end (30 checks, 50s).
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: eb20e512d9
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| 1. Resolve the goal slug from `$1` or by inspecting `goals/`. | ||
| 2. Read `goals/<slug>/goal-state.md`. Confirm: | ||
| - `goal_signed_off: true` (the Goal gate is signed). If not, stop and recommend `/goal:start <slug>` to complete sign-off. | ||
| - `status: active`. If `done` or `cancelled`, surface that and stop. |
There was a problem hiding this comment.
Step 2 requires status: active, but this command’s own input contract and goal-loop resume flow treat paused and blocked as valid resumable states. In practice, selecting a paused/blocked goal from the resolver will be rejected before dispatch, which blocks the documented recovery path for stale or interrupted goals and forces users into manual state edits or other commands.
Useful? React with 👍 / 👎.
| - 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/<slug>/observations/<iso-timestamp>[--<source-slug>].md` shaped per [`../../templates/observation-template.md`](../../templates/observation-template.md). Raw signals only. | ||
| - After every observer returns, append the artifact paths to the iteration log in `goal-state.md` (orchestrator only). |
There was a problem hiding this comment.
This instruction to append artifact paths after every observer return conflicts with the canonical goal-state history contract (one row per phase transition with a single artifact field). For multi-source Observe runs, implementers will either emit multiple Observe rows for one transition or write a non-schema artifact payload, both of which can desynchronize iteration accounting and break trace/export readers that parse fixed history rows.
Useful? React with 👍 / 👎.
…codex workflow one-row-per-Observe P2 (`commands/goal/run.md:22`) — Self-introduced gap from the picker sweep in 01b6e3a. The picker now offers `{active, paused, blocked}` goals, but Step 2's preflight still required `status: active` — so selecting a paused or blocked goal from the resolver would dead-end at preflight before any dispatch. Forced users into manual state edits or other commands. Fix: Step 2 preflight now branches on status: - `active` → proceed. - `paused` → AskUserQuestion `Resume — flip to active and continue` (Recommended) / `Inspect first` / `Cancel`. Orchestrator flips the status before iteration runs. - `blocked` → surface the latest blocker row from `## History` first; ask `Blocker resolved — resume` / `Still blocked — pause to investigate` / `Cancel`. Orchestrator flips on resume. - `done | cancelled` → stop, route to `/goal:start` revive or fresh. Matches the picker's input contract. P2 (`.codex/workflows/goal-iteration.md:32`) — The Codex workflow's Observe step said "After every observer returns, append the artifact paths to the iteration log" — implying one row per observer return. The canonical schema is one `## History` row per phase transition (per skills/_shared/goal-state.md §"## History"); per-observer rows would inflate phase-counter metrics and break fixed-position trace/export parsers. Fix: rewrote to specify one row per fan-in completion, with all per-source artifact paths listed in the single artifact column (or the merged index path when cross-source dedup ran). Matches the Act fan-in rule in skills/act/SKILL.md:109 closed earlier in the session. Verified end-to-end with my own follow-up grep: - No other phase command has the picker-vs-preflight mismatch (run.md was the only one with an explicit status: active preflight). - No other surface has the "one row per X" drift; only legitimate reference (decide SKILL's recommended-subset table is a different surface inside decisions.md). Verified: `npm run verify` green end-to-end (30 checks, 51s).
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: fbfd168d73
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| - Set `current_phase: orient`. | ||
| - **Bump `iteration`** by 1 — this is the canonical single-owner increment point per [`../_shared/goal-state.md`](../_shared/goal-state.md) ("incremented by `goal-orchestrator` at each new Observe"). The bump fires here on every Observe (the first Observe after goal-gate sign-off takes iteration `0 → 1`; each subsequent continue cycle takes `n → n+1`). No other write contract bumps `iteration`; if you've already advanced `current_phase: review → observe` in Step 1's pre-dispatch handoff, that handoff did NOT touch `iteration` (Step 1's contract is explicit about this). | ||
| - Bump `updated_at`. | ||
| - Append **one** `## History` row for the Observe phase transition, regardless of how many observers fanned out. The row's `iteration` column carries the just-incremented value. When N parallel observers ran, the single row lists the artifact paths (or cites a merged observation index) so the iteration's full observation set is recoverable from `## History`. One row per phase transition is the contract per [`../_shared/goal-state.md`](../_shared/goal-state.md) §"`## History`". |
There was a problem hiding this comment.
This instructs fan-in Observe rows to store multiple artifact paths in the single artifact column, but the canonical goal-state contract defines that column as one relative path (or null) that trace/export readers resolve directly. In multi-source runs, writing a list payload here makes the row non-resolvable and causes downstream trace-loop/export-trace to report missing evidence even when files exist; use one resolvable index artifact path (e.g., merged file) instead.
Useful? React with 👍 / 👎.
|
|
||
| - Set `current_phase: review`. | ||
| - Bump `updated_at`. | ||
| - Append **one** `## History` row for the Act phase transition, regardless of how many actions fanned out. The shared schema contract is one row per phase transition (per [`../_shared/goal-state.md`](../_shared/goal-state.md) §"`## History`"); appending one row per action log would inflate phase/counter metrics (`max_failed_acts`, action-status totals in `## Health`) and desynchronise readers that expect one Act handoff per iteration. The single row's `outcome` column aggregates the fan-in summary (`done × N`, `failed × M`, `skipped × P`); the `artifact` column lists the comma-separated action-log paths under `actions/iter-<n>/` so the iteration's full action set is recoverable from `## History`. Matches the Observe-fan-in rule in [`../observe/SKILL.md`](../observe/SKILL.md) §"Step 5". |
There was a problem hiding this comment.
The Act fan-in guidance asks for comma-separated action-log paths in ## History.artifact, but that field is consumed as a single relative path by the shared state contract and trace/export tooling. When Act runs multiple actions, this format yields a non-file token instead of a resolvable artifact and breaks iteration reconstruction for exactly the parallel/independent-action scenarios this step targets.
Useful? React with 👍 / 👎.
… artifact lists with per-iteration index files Both Observe and Act fan-in `## History.artifact` columns were documented as comma-separated path lists. The canonical schema row format declares the column as ONE resolvable relative path that trace/export consume directly; a comma-separated list is a non-file token that resolves as missing evidence in downstream parsers. Self-introduced from two prior fixes (a2b5185 for Act, fbfd168 for the codex Observe workflow). Architectural fix: per-iteration index files for fan-in cases. - Observe fan-in: - 1 observer → artifact = that observer's file. - N observers + dedup → artifact = the deduper-authored merged view `observations/<iso-timestamp>--_merged.md` (existing). - N observers, no dedup → orchestrator writes a new index at `observations/<iso-timestamp>--_index.md` (one bullet per per-source file), points artifact there. - Act fan-in: - 1 action → artifact = that single action's log. - M actions → orchestrator writes a new index at `actions/iter-<n>/_index.md` (one bullet per per-action log with status), points artifact there. The index is one resolvable path; its body fans out to per-source / per-action evidence via relative links. Trace/export resolve the index as the single artifact, then walk its body. Updated 4 files: observe SKILL, act SKILL, codex workflow, and the shared schema's per-goal artifact map (which now declares the two new index file types as orchestrator-owned). Pattern memo: every "one X" contract needs check at both ends — the declaration (schema) AND the producers (write contracts). Fan-in producers are the failure mode because their natural output is N items; the single-X rule forces an aggregate artifact, which has to be named explicitly or it gets approximated as a comma list. Verified: `npm run verify` green end-to-end (30 checks, 51s).
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 67a3f114a7
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
|
||
| | Outcome | Meaning | What the conductor does | | ||
| |---|---|---| | ||
| | **continue** | Acceptance criteria not yet met; the loop should iterate. | Dispatch `goal-orchestrator` to set `current_phase: observe` and append a `## History` entry. **Do not bump `iteration` here** — the canonical rule from [`goal-state.md`](goal-state.md) is that `iteration` increments only at each new Observe dispatch (per [`../../commands/goal/observe.md`](../../commands/goal/observe.md) §"Step 3"). Then either dispatch the next iteration (if cadence is "immediate") or pause for cadence (if recurring on a schedule). | |
There was a problem hiding this comment.
The shared outcome table tells conductors to dispatch goal-orchestrator after Review (for continue, close-met, and close-abandon), but the same file later states that review-loop already performs that state transition and that re-dispatching would double-write ## History and mis-advance state. If implementers follow this row literally, they can append duplicate closure rows or apply a second transition for the same iteration. Align the outcome table with the per-phase rule so conductors only report/route after review-loop returns.
Useful? React with 👍 / 👎.
…re-dispatch goal-orchestrator `skills/_shared/loop-pattern.md:59-62` outcome-handling table had "Dispatch `goal-orchestrator` to..." in every row's "What the conductor does" column, but the same file's Step 5 §"Loop closure" (and `skills/review-loop/SKILL.md` §"Step 4 — Apply the outcome", and `skills/goal-loop/SKILL.md` §"Step 5") all declare review-loop as the SOLE writer of the iteration-closure state transition. Conductors following the table literally would double-dispatch: append duplicate `## History` rows, re-advance phase pointers, or stamp conflicting terminal state on close-met / close-abandon. This was the original outcome-table from when the shared contract was new; later commits introduced review-loop's sole-writer rule but didn't update the table. The table's framing as "What the conductor does" made the double-dispatch sound canonical. Fix: rewrote the table with two split columns — "What `review-loop` already did (do NOT re-dispatch)" describes the orchestrator-side write that has already happened by the time review-loop returns, and "What the conductor does next (report/route only)" describes the conductor's actual responsibility (no state-machine writes, just user-facing reporting and routing). Added explicit "report and route only" framing above the table to prevent the same drift from re-occurring on the next rewrite. The pattern matches the act-gate fix in d63766d ("conductor is verifier/dispatcher, not re-prompter") and the per-phase loop step 4 fix in c76784a ("conductor verifies, does not re-dispatch"). Loop closure was the last surface where the conductor still appeared to own the write. Verified: `npm run verify` green end-to-end (30 checks, 50s).
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: e96d3ee1ce
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
|
||
| - **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/<slug>/`** except `traces/`. No edits to `goal-state.md`, observations, orientation, decisions, actions, or reviews — ever. | ||
| - **Don't include redacted source content.** When an observe source is marked sensitive (see the source datasheet in [Recommendation H-5 of `../../docs/research-goal-oriented-ai.md`](../../docs/research-goal-oriented-ai.md)), the exporter emits the signal count and type but not the raw text. Default-deny on `inbox` / `person` / `dataset` sources without an explicit `safe_for_export: true`. |
There was a problem hiding this comment.
This command narrows the redaction default to only inbox/person/dataset, which conflicts with the exporter contract in skills/export-trace/SKILL.md that requires default-deny for every source type unless safe_for_export: true is declared. If implementers follow this command text literally, traces from feed, api, repo, or document sources can leak raw signal content without explicit export approval, creating a security/privacy regression in the trace export path.
Useful? React with 👍 / 👎.
…stale (security regression) `commands/goal/export-trace.md:37` "Don't include redacted source content" still said "Default-deny on `inbox` / `person` / `dataset` sources only" — but the underlying SKILL contract was tightened in fdd24ca (THREAT-03 P1 wave) to apply default-deny across EVERY source type. The command-level prose drifted from the SKILL contract; an adopter following only the command file would unknowingly leak raw signal content from `feed` / `api` / `repo` / `document` / `archive` / `record` / `sensor` / `command` sources in exported traces. This is a real security regression risk (THREAT-03 reopened in a secondary surface), caught by Codex now that I'd been touching the trace export contract repeatedly without updating this command. Fix: rewrote the Don't bullet to cite the canonical SKILL contract (default-deny on every source type), the datasheet template's `## Export safety` section, the pre-wave-9 fallback (absent section → treated as `safe_for_export: false`), and the built-in secret-pattern redaction that fires even when `safe_for_export: true`. Listed all 11 source types explicitly to remove any "but my source type isn't named" ambiguity. Pattern memo: when tightening a SKILL contract, also grep for the contract's prose in the command files that wrap the SKILL. The command file is the user-facing copy; if it tells a less-strict story than the SKILL, the SKILL's tightening is functionally undone by the operator following the wrapper. Verified: `npm run verify` green end-to-end (30 checks, 51s).
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 5ab242ba2b
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
|
||
| - Set `current_phase: decide`. | ||
| - Bump `updated_at`. | ||
| - Append a `## History` row citing **both** the current pointer (`orientation.md`) **and** the iteration-specific archive path (`archive/orientation-<iso-timestamp>.md`). The archive path is what `trace-loop` resolves when reconstructing past iterations — `orientation.md` itself is overwritten every iteration, so the History row must record the immutable archive copy to keep historical traces unambiguous. |
There was a problem hiding this comment.
This step instructs the orchestrator to record both orientation.md and the archive copy in the single ## History.artifact field, but the shared state contract defines that field as one goal-relative path. If implemented literally, Orient rows become non-resolvable (or require ad-hoc parsing), and downstream trace-loop / export-trace readers that resolve one artifact per row can report false gaps for otherwise valid iterations.
Useful? React with 👍 / 👎.
| - For each failed action whose actor wrote a log, capture the failure summary (the actor's reported error or the malformed-artifact reason) without retrying automatically. | ||
| - **Actor crash / timeout (no artifact written):** the `actor` owns `actions/iter-<n>/<a-id>.md` — this skill writes nothing to that folder. Recovery is a three-step contract: | ||
| 1. **Re-dispatch the actor once** with a clear `previous run failed: <reason>` context block, per [`../_shared/loop-pattern.md`](../_shared/loop-pattern.md) §"Error escalation". | ||
| 2. **If the second attempt also fails** (still no artifact), **dispatch `goal-orchestrator`** to append a `## History` row in `goal-state.md` recording `actor-crash` for that action id, citing the missing artifact path and the failure context. No placeholder file is written to `actions/` — phase isolation forbids it. |
There was a problem hiding this comment.
On repeated actor failure, this branch tells the orchestrator to append a dedicated ## History row per crashed action, which conflicts with the phase contract of one row per Act transition and causes one Act phase to emit multiple synthetic history entries. In parallel-action runs this can skew phase-level accounting and make iteration traces ambiguous because crash bookkeeping is mixed into transition history instead of being contained in the final Act transition artifact.
Useful? React with 👍 / 👎.
…rash History contract Both findings are the same family as the comma-separated fan-in fix in 67a3f11: surfaces that documented multi-value or per-event History rows where the canonical contract is single-artifact / single-row- per-transition. P1 (`skills/orient/SKILL.md:76`) — Orient row was documented as citing **both** the current `orientation.md` pointer and the iteration-specific archive path in the single `## History.artifact` column. The schema declares that column as one resolvable goal-relative path; a comma-or-and-separated double would be non-resolvable in trace/export. Fix: artifact column points at the archive path only (`archive/orientation-<iso-timestamp>.md`) — that's the immutable per-iteration snapshot the orienter wrote in Step 7 before overwriting the live file. The live `orientation.md` is intentionally mutable (overwritten every iteration) so it cannot serve as the History artifact — a later iteration's reader would see the wrong content. The archive is the canonical per-iteration evidence. P2 (`skills/act/SKILL.md:97`) — Actor-crash recovery contract said "dispatch `goal-orchestrator` to append a `## History` row" for each crashed action. That conflicts with the one-row-per-phase-transition contract: per-crash rows would inflate phase-counter metrics, mix bookkeeping into transition history, and make iteration traces ambiguous (parallel runs with multiple crashes would emit N synthetic rows for one Act transition). Fix: crashes are now folded into the single Act fan-in row's tally as `crashed × C` (alongside the standard `done × N | partial × P | stopped × S | blocked × B | failed × F` aggregate), and the per- iteration Act index (`actions/iter-<n>/_index.md`, written by the orchestrator on fan-out) lists each crashed action id with `status: crashed (no artifact written; <error context>)` as a one-bullet entry. The single Act transition row's artifact column points at the index; operators following the trace land on the index and see the crash bookkeeping there. Pattern memo: "one row per phase transition" + "one resolvable artifact per row" both need check at the recovery / failure paths too, not just the happy paths. The recovery paths' natural impulse is "log one row per failure" — but the contract is the SAME one row per transition; failures get folded into the fan-in summary and the index file. Updated heuristic: grep "append a `## History` row" and verify each is at a phase-transition boundary, not a per-event point. Verified: `npm run verify` green end-to-end (30 checks, 51s).
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 61072f89e0
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
…nters in frontmatter (not Health body) P1 (`commands/goal/start.md:29`) — `/goal:start` scaffolded `observations/`, `actions/`, `reviews/`, `archive/` but NOT `amendments/`. The first `/goal:amend` against a fresh goal would have no directory to write into; the amendment-record write would fail or (worse) leave a dangling `## History` artifact link if implementers skipped the write failure. Fix: added `goals/$1/amendments/` to the mkdir list with an inline note about why. Also fixed the same gap in `skills/welcome/SKILL.md` Step 1 — welcome's hello-loop scaffold had the same omission, and hello-loop goals could be promoted via amend later. P2 (`agents/goal-orchestrator.md:85`) — Cap-raise rule sub-step (b) said to increment `cap_raises_lifetime` in `## Health`. The schema declares it as an optional frontmatter integer (since the fa6d992 / 78c9fbd wiring). Storing it in the body too would create two sources of truth; downstream amend / status / list readers reading the schema-declared frontmatter would miss the body increment, breaking the `>=2` repeated-raise warning escalation. Fix: increment goes to frontmatter only (single atomic Edit on `cap_raises_lifetime:`). The `## Health` snapshot reads the frontmatter value into its rolling counter view but doesn't own it. Matches the §7c step 3 protocol which already listed `cap_raises_lifetime` in the frontmatter-edit set. Also found and fixed the **parallel drift on `consecutive_acknowledged_caps`** at agents/goal-orchestrator.md:60 ("Track in ## Health as a regular line") — same schema-vs-body conflict. Rewrote to specify frontmatter-only ownership, matching the protocol at line 67 which already had both counters in the frontmatter-edit set. Pattern memo: schema declares a field, write contracts must respect the declared location. Storing schema-declared frontmatter in `## Health` body creates two sources of truth and silently breaks downstream readers that consume the schema as canonical. Verified: `npm run verify` green end-to-end (30 checks, 51s).
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 9915aaf4db
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
…AML form Script's `extract_tools()` only handled inline `tools: [A, B]` frontmatter and exited on the same line. If an agent ever used valid block-style YAML (`tools:` followed by `- Read` lines), `declared` became empty and the check reported a false `missing 'tools:' frontmatter` failure, blocking CI for otherwise-correct metadata updates. The script's own comment even claimed it supported both forms — the comment was aspirational; the code wasn't. All shipped agents currently use inline form so the bug wasn't triggered, but it was a latent CI landmine for any contributor who switched to block form (which the YAML spec considers equivalent and some editors auto-format to). Fix: rewrote `extract_tools()` to handle both forms: - Inline `tools: [A, B, C]` — extracted as before from the same line. - Inline `tools: A, B` (rare but valid) — same path. - Block `tools:\n - A\n - B` — sets `in_block=1` when `tools:` has no inline value, then collects bullet lines until a new top-level key (matching `^[A-Za-z_]` not preceded by `- `) breaks the block. - Mixed or malformed cases default to whichever path matches first; empty result still reports `missing 'tools:'` per the original contract. Verified by: - `bash scripts/check-tool-lists.sh` against all current agents (all use inline form) → still passes, same canonical-roster matching. - Synthetic test against a block-form agent file → correctly extracts `Read Edit Write`. - `npm run verify` end-to-end → green (30 checks, 83s). Pattern memo: when a script's comment claims "supports both forms", verify the code actually does. Aspiration comments are technical debt in disguise — they read as completed work but ship as latent failure modes.
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: ea66d6f6c9
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
…-loop amend record write P1 (`skills/orient/SKILL.md:77`, `agents/orienter.md:50-67`) — My fix in 61072f8 changed the Orient History row to cite the archive path (immutable per-iteration snapshot) instead of the live orientation.md. But the orienter explicitly skipped writing an archive file on iteration 1 (no prior content to preserve), so iteration 1's History row pointed at a non-existent file; trace/export would report a gap even though orientation.md existed. Architectural fix: changed the orienter's archive semantic. Previously the archive was "the previous version, preserved before overwrite" — that meant iter 1 had nothing to archive. New semantic: the archive is "this iteration's immutable snapshot", always written (including iter 1) with the same content as the live orientation.md. The live file is the current pointer; the archive is the immutable history. Every iteration's `## History.artifact` now resolves uniformly. Updated `agents/orienter.md` Step 7 procedure (always write the archive) and Outputs section (no more "skipped on first iteration"). Updated `skills/orient/SKILL.md`'s verification step ("missing archive on any iteration = contract violation", not "non-first iteration"). P1 (`skills/review-loop/SKILL.md:84`) — When review-loop's `amend` outcome's apply path dispatches set-goal directly (without going through `/goal:amend`), it never wrote the amendment-record file that the canonical `## History.artifact` column cites. The /goal:amend command Step 5 has had this write step since 8428c13 (refined in 01b6e3a), but the review-loop parallel path skipped it. Direct-from- Review amend rows would dangle their artifact citation. Fix: review-loop's apply branch now writes the amendment record file at `goals/<slug>/amendments/<YYYY-MM-DD>-amend-<n>.md` (using the constitution-amendment template scoped to the goal's contract — same shape as /goal:amend Step 5) BEFORE dispatching the orchestrator. History row's artifact column cites that file (goal-relative path). Pattern memo: when multiple entry points lead to the same downstream contract (here: /goal:amend command AND review-loop's apply branch both end at "orchestrator appends amend History row"), each entry point needs the full pre-dispatch sequence — write the artifact, then dispatch. The artifact-write step is easy to drop on the second entry because the first entry "looks like" it owns the contract; both do. Verified: `npm run verify` green end-to-end (30 checks, 74s).
New scripts/check-goal-length.sh enforces a 3500-character cap on the body (everything after the closing `---`) of every goal-state.md and session-goal artifact — templates, examples, and adopter live state. Wired into check-all.sh. A goal whose body needs more than 3500 chars is usually doing too much. set-goal and create-goal surface the count to the user at write time and refuse to commit a file over the cap. Trimmed 4 oversized example goal-state.md files (continuous-awareness, incident-triage, policy-review, release-readiness) to fit; added canonical _index.md fan-in artifacts for their observation and action passes (the 1-vs-N artifact pattern from skills/_shared/goal-state.md). session-goal template trimmed by ~250 chars to make room for the cap notice. Documented at the schema (skills/_shared/goal-state.md §"Body-length cap"), the method (docs/method.md §"Quality gates"), the templates, and the automation spec (docs/automation-spec.md §G2).
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 637e5ce442
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| - **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 — orchestrator hand-off.** When step 5 ran in amend mode, dispatch [`goal-orchestrator`](../../agents/goal-orchestrator.md) to (a) append an `amend` row to `## History` citing the section(s) changed and `outcome: amend`, (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. |
There was a problem hiding this comment.
The documented back-compat amend path (/goal:start <existing-slug>) sends amend-mode runs straight to a goal-orchestrator history append, but this flow never creates the per-goal amendment file (goals/<slug>/amendments/<YYYY-MM-DD>-amend-<n>.md) that amend rows are expected to reference. In practice, amendments and revive-via-amend entered through /goal:start can produce non-resolvable audit history for trace-loop/export-trace, unlike /goal:amend which writes the artifact first; this path should also write the amendment record before dispatching the history update.
Useful? React with 👍 / 👎.
….0, close residual Codex findings Multi-agent review pass (architect / qa / critic / ux / reviewer) plus fetching the 21 unresolved Codex threads from the PR. Outcomes: **scripts/check-goal-length.sh** — hardened against four classes of bug that QA review surfaced: - CRLF line endings now normalised before frontmatter detection (was silently falling back to "no frontmatter" path, inflating counts). - Malformed frontmatter (opening `---` with no closing) is now FAIL instead of fail-open scoring 0. - All `find` calls drop the depth limit and exclude `archive/` consistently (was missing nested adopter goals). - Off-by-one fix for files without trailing newline. - Hidden files (`.foo.md`) excluded from session-goals scan. - FAIL message includes overshoot delta. **Codex thread fixes** (Threads 21, 14, 19): - commands/goal/start.md Step 6 — back-compat amend path writes the amendment record file before dispatching the History row. - skills/orient/SKILL.md Step 4 — Orient History.artifact uses the live `orientation.md` pointer (one resolvable goal-relative path on iter-1 through N); archive resolved implicitly by matching `ended_at`. **Polish from reviewer findings**: - scripts/README.md — `seven` → `eight`; added check-goal-length row; G2 noted under "What is not yet covered". - docs/maintenance.md + docs/contributing.md — `seven check categories` → `eight`; H added to the table; G2 cited. - CHANGELOG.md — new `[2.2.0]` entry capturing the cap + the trimmed examples + the fan-in indexes. - .claude-plugin/plugin.json — 2.1.0 → 2.2.0 (additive minor bump). **Architect finding A13** — commands/goal/amend.md: three references to `memory/amendments/` corrected to `goals/<slug>/amendments/` (per-goal amendment records live under the goal tree; `memory/amendments/` is constitution-only). **UX polish**: - skills/create-goal/SKILL.md Step 6 — reordered options so the Recommended choice appears first per the AskUserQuestion convention. - docs/first-five-minutes.md Step 4 — added `/goal:list` as option 1 (the shortest path back into work after a context switch). - docs/troubleshooting.md — two new rows: lost-session-mid-intake recovery, and body-length-cap recovery paths (tighten vs split). **Headroom trim** — examples/issue-resolution/goal-state.md tightened Intent paragraph (3491 → 3396 chars; was 9 chars under the cap, any trivial edit would have tripped the gate). Plugin gate green; parent `npm run verify` green.
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: c614b462a0
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
Comment on lines
+25
to
+29
| 3. Locate the most recent artifacts (newest by filename timestamp): | ||
| - Last observation index under `goals/<slug>/observations/`. | ||
| - Current `goals/<slug>/orientation.md` (if any). | ||
| - Last decision block in `goals/<slug>/decisions.md` (and its `status` — proposed / approved / done / failed / rejected / deferred). | ||
| - Last action file under `goals/<slug>/actions/iter-<n>/`. |
There was a problem hiding this comment.
Step 3 says to locate artifacts by "newest by filename timestamp," but action logs in this plugin are named by action id (actions/iter-<n>/<a-id>.md), not by timestamp. In iterations with multiple actions, this rule cannot reliably identify the most recent action and can report stale/incorrect "last action" data in /goal:status; use file metadata or frontmatter times for actions instead of filename ordering.
Useful? React with 👍 / 👎.
| ### 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/<slug>/actions/iter-<n>/<a-id>-spec.md` (or co-located with the ActionLog at adopter discretion). Namespaced under `iter-<n>/` so recurring goals with repeating action ids do not overwrite prior-iteration specs. |
There was a problem hiding this comment.
This model defines ActionSpec at actions/iter-<n>/<a-id>-spec.md, but the rest of the plugin contracts use actions/iter-<n>/<a-id>.spec.md (for example in skills/act/SKILL.md and templates/README.md). Following this domain-model path will generate misnamed spec files that downstream readers won’t discover consistently, breaking action-spec linkage and traceability.
Useful? React with 👍 / 👎.
…us action-recency rule - docs/domain-model.md:36,200 — ActionSpec path uses canonical `<a-id>.spec.md` (dot) to match skills/act/SKILL.md:80,129 and templates/README.md:21. The dashed form would generate misnamed spec files that downstream readers (actor, decide skill) wouldn't discover. - commands/goal/status.md:25-30 — clarified the per-artifact recency rule. Action logs are named by action id (`a-1.md`, `a-2.md`) not by timestamp, so filename ordering is unreliable for "most recent action". Use frontmatter `executed_at` (preferred) or file mtime for actions; observations and reviews keep the filename-timestamp rule (those filenames ARE timestamps by contract). Sibling-grep clean: no other `<a-id>-spec.md` (dash) leaks in the tree; no other "newest by filename timestamp" rule applied to action logs.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Unifies #501 (Goal-Oriented Orchestrator) and #502 (OODA Loop) into one cohesive, domain-agnostic Claude plugin under
plugin-v2/. Ready to copy into any project and run.The merged concept is a goal-bounded OODA loop:
This generalises to issue resolution (one-shot, bounded), daily brief (recurring, awareness), incident triage (rapid tempo), release readiness (checklist gate), and continuous awareness (perpetual). Software examples are illustrative; the method does not assume a software-engineering context.
The full method, vocabulary, state model, and quality gates are locked in
plugin-v2/docs/method.md.What ships
goal-orchestrator+ 5 phase specialists)plugin-v2/agents/goal-loopconductor +set-goal+ 5 phase skills) + 2 shared contractsplugin-v2/skills//goal:*plugin-v2/commands/goal/plugin-v2/templates/plugin-v2/docs/plugin-v2/examples/instructions.md+ 2 workflowsplugin-v2/.codex/plugin-v2/.cursor/rules/.claude-plugin/plugin.jsonplugin-v2/.claude-plugin/plugin-v2/memory/constitution.mdREADME.md,CLAUDE.md,AGENTS.md,LICENSEplugin-v2/64 new files, 4 460 insertions, no changes outside
plugin-v2/.How it was built
A planning step locked the foundation (
docs/method.mdas the canonical method + vocabulary contract, and.claude-plugin/plugin.jsonas the name registry), then five subagents executed in parallel against that contract: agents, skills, commands, templates+constitution, docs+adapters+examples. The conductor then authored the top-level entry points (README / CLAUDE.md / AGENTS.md / LICENSE) and ran an integrity sweep before commit.Test plan
plugin-v2/into a fresh project (or symlink for local testing) and confirm Claude Code picks up the/goal:*slash commands and thegoal-loopskill auto-triggers from natural language./goal:start sampleand confirmset-goalinterview elicits intent, constraints, falsifiable acceptance, mode, cadence, observe sources, and act-gate policy, then writesgoals/sample/goal-state.md./goal:run sampleend-to-end against a low-stakes goal; confirm phase isolation (each phase agent only touches its own artifact) and that the act gate blocks on irreversible actions..codex/instructions.mdis honoured by a Codex session and.cursor/rules/goal-loop.mdcloads in Cursor.Closes #501.
Closes #502.
https://claude.ai/code/session_01CxFjqxucdBwScjAkMxU83s
Generated by Claude Code