From 51e28692fc881080e1d02d0964de363e9522f7cc Mon Sep 17 00:00:00 2001 From: Jonathan Jackson Date: Fri, 22 May 2026 02:21:56 -0600 Subject: [PATCH] fix(decisions-log): enumerate decisions.yaml writes in every phase agent (closes #399) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Phase 2-9 agents never wrote decisions.yaml rows because the procedural authority (per-step `Output:` bullets in `agents/.md`) was silent on them, even though 8 downstream skills carried well-formed Decisions Log catalogs in their SKILL.md. Phase 1 had the canonical pattern but PR #4 of the decisions-log series shipped only the catalogs, not the agent-file enumeration. Result: 22+ completed steps across 6 phases on malaria-itn-app run 20260521-1400 produced zero decision rows. Mirror Phase 1's pattern in every downstream phase. Each Step that maps to a Decisions-Log-carrying skill now enumerates the anchor row IDs: - commcare-setup Step 1 (pdd-to-deliver-app): deliver-unit-count, one-form-per-module-workaround, multimedia-coverage-strategy - commcare-setup Step 2.6 (app-test-cases): test-scenario-count, test-archetype-coverage - connect-setup Step 2 (connect-opp-setup): verification-flags, payment-unit-shape, opportunity-end-date - ocs-setup Step 1 (ocs-agent-setup): system-prompt-baseline, rag-collection-scope, test-prompt-count - synthetic-data-and-workflows Step 1 (synthetic-narrative-plan): persona-count, scenario-count, narrative-arc-shape - solicitation-management Step 1 (solicitation-create): solicitation-type, response-deadline, response-template-choice - execution-manager Step 3 (llo-launch): llo-capacity-actual, day-one-readiness, downstream-handoff-alignment, stop-loss-planning - closeout Step 1 (opp-closeout): closeout-depth, learnings-summary-scope orchestrator-reference.md § Phase Write-Back Contract § Decisions log clause now explicitly names the per-step agent-file Output block as the load-bearing procedural authority — the SKILL.md catalog is a teaching device, not a checklist — so adding a new anchor-row skill in future requires updating BOTH locations. Out of scope (called out for follow-up): - `app-test-cases/SKILL.md` records its rows with `phase: 6-qa-and-training` even though dispatch happens in Phase 3. Phase mismatch noted inline in commcare-setup.md. - Suggested guardrail (downgrade phase verdict when a phase with an anchor catalog writes zero rows) — separate change; the per-step enumeration is the proximate fix. Co-Authored-By: Claude Opus 4.7 (1M context) --- .claude-plugin/marketplace.json | 4 ++-- .claude-plugin/plugin.json | 2 +- VERSION | 2 +- agents/closeout.md | 4 +++- agents/commcare-setup.md | 9 +++++++-- agents/connect-setup.md | 12 +++++++----- agents/execution-manager.md | 4 +++- agents/ocs-setup.md | 8 +++++--- agents/orchestrator-reference.md | 23 ++++++++++++++++++++--- agents/solicitation-management.md | 18 ++++++++++-------- agents/synthetic-data-and-workflows.md | 1 + package.json | 2 +- 12 files changed, 61 insertions(+), 28 deletions(-) diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 767227c9..6f885d95 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -6,13 +6,13 @@ "url": "https://github.com/jjackson" }, "metadata": { - "version": "0.13.326" + "version": "0.13.327" }, "plugins": [ { "name": "ace", "source": "./", - "version": "0.13.326", + "version": "0.13.327", "description": "AI Connect Engine — orchestrates the CRISPR-Connect lifecycle from idea through app building, Connect setup, LLO management, and closeout" } ] diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index a74df9be..39cb7dd9 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "ace", - "version": "0.13.326", + "version": "0.13.327", "description": "AI Connect Engine — orchestrates the CRISPR-Connect lifecycle from idea through app building, Connect setup, LLO management, and closeout", "author": { "name": "Jonathan Jackson", diff --git a/VERSION b/VERSION index 0f9713b5..b1449aaa 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -0.13.326 +0.13.327 diff --git a/agents/closeout.md b/agents/closeout.md index 4f4d9016..3736fd1d 100644 --- a/agents/closeout.md +++ b/agents/closeout.md @@ -24,7 +24,9 @@ You handle the closeout of a completed CRISPR-Connect opportunity. ### Step 1: Invoice and Payment Invoke the `opp-closeout` skill. - Input: opportunity details, invoice data -- Output: invoices pulled, Jira payment ticket created +- Output: + - invoices pulled, Jira payment ticket created + - Appended `closeout-depth`, `learnings-summary-scope` rows in `decisions.yaml` (merge-only; bar criterion per `skills/idea-to-pdd/SKILL.md § Decisions Log Convention`). ### Step 2: LLO Feedback Invoke the `llo-feedback` skill. diff --git a/agents/commcare-setup.md b/agents/commcare-setup.md index 11474168..5123e77a 100644 --- a/agents/commcare-setup.md +++ b/agents/commcare-setup.md @@ -178,7 +178,9 @@ Step 1.5), since `nova-plugin#2` affects every architect dispatch identically — not just builds. - Input: approved PDD from GDrive -- Output: app JSON/CCZ files + summaries written to `ACE//app-summaries/` +- Output: + - app JSON/CCZ files + summaries written to `ACE//app-summaries/` + - From `pdd-to-deliver-app`: appended `deliver-unit-count`, `one-form-per-module-workaround`, `multimedia-coverage-strategy` rows in `decisions.yaml` (merge-only; rows are emitted only when they meet the bar criterion in `skills/idea-to-pdd/SKILL.md § Decisions Log Convention` — the list is a working catalog, not a required set). - **LLM-as-Judge:** unless `--no-evals` was passed, dispatch `pdd-to-learn-app-eval` after the Learn build and `pdd-to-deliver-app-eval` after the Deliver build. Each writes @@ -277,7 +279,10 @@ pre-flight (real failure mode from turmeric run 20260509-0455). See `agents/ace-orchestrator.md § Skill Invocation Discipline`. - Reads: pdd-to-app-journeys.md, both app summaries, Nova blueprints -- Writes: app-test-cases.yaml + recipes/J*.yaml under app-test-cases/ +- Writes: + - app-test-cases.yaml + recipes/J*.yaml under app-test-cases/ + - Appended `test-scenario-count`, `test-archetype-coverage` rows in `decisions.yaml` (merge-only; bar criterion per `skills/idea-to-pdd/SKILL.md § Decisions Log Convention`). + Note: `app-test-cases/SKILL.md` records these rows with `phase: 6-qa-and-training` even though dispatch happens here in Phase 3. That's an upstream `phase:` mismatch in the SKILL.md (see issue #399 follow-up); don't paper over it on the writer side. - Halts on missing inputs or recipe-validation failure Phase 6 shallow runs the smoke recipes; /ace:qa-deep runs them all. diff --git a/agents/connect-setup.md b/agents/connect-setup.md index 3f717b4a..55b23f61 100644 --- a/agents/connect-setup.md +++ b/agents/connect-setup.md @@ -54,11 +54,13 @@ Invoke the `connect-program-setup` skill. Invoke the `connect-opp-setup` skill. - **Input:** program UUID from Step 1; PDD; deployment summary from Phase 3. -- **Output:** Opportunity created with `is_test=true`, verification flags + - payment units configured, **activated**, and ACE test user - (`${ACE_E2E_PHONE}`) pre-invited. Details in - `ACE//runs//4-connect/connect-opp-setup.md` with the - opportunity UUID. +- **Output:** + - Opportunity created with `is_test=true`, verification flags + + payment units configured, **activated**, and ACE test user + (`${ACE_E2E_PHONE}`) pre-invited. Details in + `ACE//runs//4-connect/connect-opp-setup.md` with the + opportunity UUID. + - Appended `verification-flags`, `payment-unit-shape`, `opportunity-end-date` rows in `decisions.yaml` (merge-only; bar criterion per `skills/idea-to-pdd/SKILL.md § Decisions Log Convention` — only rows that meet the bar are emitted). - **Depends on:** Step 1 (needs program UUID); Phase 3 outputs (needs CommCare app metadata). - **Activation:** Phase 4 activates the opp synchronously (Step 6.5 in diff --git a/agents/execution-manager.md b/agents/execution-manager.md index 485e1658..cb2a7b56 100644 --- a/agents/execution-manager.md +++ b/agents/execution-manager.md @@ -71,7 +71,9 @@ Invoke the `llo-uat` skill. ### Step 3: Opportunity Go-Live Invoke the `llo-launch` skill. - Input: UAT results confirming LLO sign-offs -- Output: opportunity activated in Connect, LLOs notified of go-live +- Output: + - opportunity activated in Connect, LLOs notified of go-live + - Appended `llo-capacity-actual`, `day-one-readiness`, `downstream-handoff-alignment`, `stop-loss-planning` rows in `decisions.yaml` (merge-only; bar criterion per `skills/idea-to-pdd/SKILL.md § Decisions Log Convention`). These four rows map 1:1 to `llo-launch-eval`'s viability axis (PR #145) so the rubric has structured input instead of grading on prose. - **Gate (review mode):** Present launch readiness summary for approval before activating - **LLM-as-Judge:** unless `--no-evals` was passed, dispatch `llo-launch-eval` after activation. Writes `verdicts/llo-launch.yaml`. diff --git a/agents/ocs-setup.md b/agents/ocs-setup.md index 2d197e90..a4856de3 100644 --- a/agents/ocs-setup.md +++ b/agents/ocs-setup.md @@ -36,9 +36,11 @@ refuses to proceed without a fresh, passing deep verdict. ### Step 1: Configure the chatbot Invoke the `ocs-agent-setup` skill. - Input: `ACE//` — PDD, training materials, app summaries, opportunity config -- Output: cloned chatbot with opp system prompt, RAG collection indexed, - version published. `ACE//runs//5-ocs/ocs-agent-setup.md` written with - `{experiment_id, public_id, embed_key, collection_id, pipeline_id, version_number}` +- Output: + - cloned chatbot with opp system prompt, RAG collection indexed, + version published. `ACE//runs//5-ocs/ocs-agent-setup.md` written with + `{experiment_id, public_id, embed_key, collection_id, pipeline_id, version_number}` + - Appended `system-prompt-baseline`, `rag-collection-scope`, `test-prompt-count` rows in `decisions.yaml` (merge-only; bar criterion per `skills/idea-to-pdd/SKILL.md § Decisions Log Convention`). - Idempotent: if a bot named `"ACE - "` already exists, resumes from existing config diff --git a/agents/orchestrator-reference.md b/agents/orchestrator-reference.md index c95c270e..1e901298 100644 --- a/agents/orchestrator-reference.md +++ b/agents/orchestrator-reference.md @@ -603,9 +603,26 @@ Scope and `skills/idea-to-pdd/SKILL.md` § Decisions Log Convention § Bar criterion). Each phase's primary writing skill owns the rows it writes. The orchestrator stub-fills + warns post-phase if a phase wrote zero rows AND the calibration set for that phase has any -required rows. PR #1 covers Phase 1 (`idea-to-pdd`); Phase 3–10 writes -ship in PR #3 of the decisions-log series. Schema and YAML helpers -live in `lib/decisions-schema.ts`. +required rows. Schema and YAML helpers live in `lib/decisions-schema.ts`. + +**The procedural authority for each phase is the per-step `Output` +block in its `agents/.md` file**, not the catalog in the writing +skill's `SKILL.md`. The catalog (the `## Decisions Log` section in each +producer skill) is a teaching device — listing the rows that commonly +qualify under the bar for that phase. The agent file's per-step `Output` +bullets are what the dispatched subagent treats as its checklist. +Documented catalogs without a matching per-step bullet produced silent +zero-write failures across Phase 2–9 on the malaria-itn-app run filed +as `jjackson/ace#399`; the fix was the per-step Output enumeration that +now lives in every downstream agent file. When you add a new skill that +writes anchor rows, BOTH must be updated together: the catalog in +`SKILL.md` AND the `Output:` bullet in the dispatching agent file. The +catalog alone is not load-bearing. + +History: PR #1 of the decisions-log series shipped Phase 1 +(`idea-to-pdd` + `pdd-to-work-order`). PR #4 added Decisions Log +catalogs to Phase 3–10 skills but did NOT update the agent files; that +gap was closed by the issue #399 fix. ## Recurring writers — TBD diff --git a/agents/solicitation-management.md b/agents/solicitation-management.md index dc0b4c8c..5224ee9c 100644 --- a/agents/solicitation-management.md +++ b/agents/solicitation-management.md @@ -41,14 +41,16 @@ lifecycle requires explicit human approval and is run manually via Invoke the `solicitation-create` skill. - Input: approved PDD (`inputs/pdd.md`), `opp.yaml` (`connect.program.id`, total_budget) -- Output: `solicitation/published.md`, - `phases.solicitation-management.products.solicitation` populated in - the current run's `run_state.yaml` with - `{solicitation_id, public_url, deadline, status: open, - labs_program_id, ...}`. `selected_llo` is populated by - `solicitation-review` on award at `products.selected_llo`. The labs - program int is cached durably at - `opp.yaml.connect.program.labs_int_id`. +- Output: + - `solicitation/published.md`, + `phases.solicitation-management.products.solicitation` populated in + the current run's `run_state.yaml` with + `{solicitation_id, public_url, deadline, status: open, + labs_program_id, ...}`. `selected_llo` is populated by + `solicitation-review` on award at `products.selected_llo`. The labs + program int is cached durably at + `opp.yaml.connect.program.labs_int_id`. + - Appended `solicitation-type`, `response-deadline`, `response-template-choice` rows in `decisions.yaml` (merge-only; bar criterion per `skills/idea-to-pdd/SKILL.md § Decisions Log Convention`). - **LLM-as-Judge:** unless `--no-evals` was passed, dispatch `solicitation-create-eval` after publish. Writes `verdicts/solicitation-create.yaml`. diff --git a/agents/synthetic-data-and-workflows.md b/agents/synthetic-data-and-workflows.md index 0c6c9936..400cd54f 100644 --- a/agents/synthetic-data-and-workflows.md +++ b/agents/synthetic-data-and-workflows.md @@ -113,6 +113,7 @@ Invoke `synthetic-narrative-plan`. opp.yaml. - Produces `7-synthetic/synthetic-narrative-plan.md` (human narrative) and `7-synthetic/synthetic-narrative-plan.yaml` (the manifest). +- Appends `persona-count`, `scenario-count`, `narrative-arc-shape` rows in `decisions.yaml` (merge-only; bar criterion per `skills/idea-to-pdd/SKILL.md § Decisions Log Convention`). - The manifest schema is identical to `synthetic-data-generate`'s; this skill just authors a richer instance with named FLWs, deliberate anomalies, coaching-arc transcripts. diff --git a/package.json b/package.json index b2161046..ccfc0948 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "ace", - "version": "0.13.326", + "version": "0.13.327", "description": "AI Connect Engine - orchestrator for building Connect Opps using AI", "type": "module", "scripts": {