@cohortapp/agent-sdk 2.3.0

package/docs/prompts/decision-recommendation-template.md

@@ -0,0 +1,88 @@
+![the company icon](public/assets/icon-dark.svg)
+
+# Decision Required: {title}
+
+**Priority**: {P1-P5 alignment or standalone}
+**Requested by**: {requestor}
+**Decision owner**: {{agent.principal.fullName}}, {{agent.principal.title}}
+**Prepared by**: {{agent.fullName}}, {{agent.title}}
+**Date prepared**: {date}
+
+## Context
+
+{what_prompted_this_decision}
+
+> 2-4 sentences maximum. State the triggering event, why it matters now, and what happens if no decision is made.
+
+## Options
+
+### Option A: {option_a_name}
+
+**Description**: {option_a_description}
+
+| Dimension         | Assessment                                                |
+| ----------------- | --------------------------------------------------------- |
+| **Pros**          | {pro_1}; {pro_2}; {pro_3}                                 |
+| **Cons**          | {con_1}; {con_2}                                          |
+| **Risk**          | {risk_description} (Likelihood: {H/M/L}, Impact: {H/M/L}) |
+| **Cost**          | {financial_and_opportunity_cost}                          |
+| **Timeline**      | {implementation_timeline}                                 |
+| **Reversibility** | {easy/moderate/difficult/irreversible}                    |
+
+### Option B: {option_b_name}
+
+**Description**: {option_b_description}
+
+| Dimension         | Assessment                                                |
+| ----------------- | --------------------------------------------------------- |
+| **Pros**          | {pro_1}; {pro_2}; {pro_3}                                 |
+| **Cons**          | {con_1}; {con_2}                                          |
+| **Risk**          | {risk_description} (Likelihood: {H/M/L}, Impact: {H/M/L}) |
+| **Cost**          | {financial_and_opportunity_cost}                          |
+| **Timeline**      | {implementation_timeline}                                 |
+| **Reversibility** | {easy/moderate/difficult/irreversible}                    |
+
+### Option C: {option_c_name} (if applicable)
+
+> Include a third option only when materially distinct from A and B. Do not fabricate a middle option for appearance.
+
+## Comparison Matrix
+
+| Criterion            | Weight   | Option A    | Option B    |
+| -------------------- | -------- | ----------- | ----------- |
+| Strategic alignment  | {weight} | {score}/5   | {score}/5   |
+| Speed to execute     | {weight} | {score}/5   | {score}/5   |
+| Downside risk        | {weight} | {score}/5   | {score}/5   |
+| Resource requirement | {weight} | {score}/5   | {score}/5   |
+| **Weighted total**   |          | **{total}** | **{total}** |
+
+## {{agent.firstName}}'s Recommendation
+
+**Recommended option**: {Option A or B}
+
+{2-3 sentence rationale explaining why this option best serves the {{agent.principal.title}}'s stated priorities and risk posture. Reference specific strategic priorities (P1-P5) where applicable.}
+
+**Confidence level**: {High / Medium / Low}
+**Key assumption**: {the_most_important_assumption_underlying_this_recommendation}
+
+## Decision Deadline
+
+**Decide by**: {date_and_time}
+**Reason for deadline**: {why_this_date}
+
+## Impact if Delayed
+
+{what_happens_if_no_decision_by_deadline}
+
+> Be specific: quantify costs, name missed windows, identify cascading effects on other workstreams.
+
+## Next Steps (upon decision)
+
+- [ ] {action_1} -- Owner: {owner}, Due: {date}
+- [ ] {action_2} -- Owner: {owner}, Due: {date}
+- [ ] {action_3} -- Owner: {owner}, Due: {date}
+
+---
+
+Prepared by {{agent.fullName}}, {{agent.title}} | {timestamp}
+Brand assets: config/brand-assets.yaml

package/docs/prompts/followup-message-template.md

@@ -0,0 +1,141 @@
+# Follow-Up Message Templates
+
+Voice: {{agent.fullName}}, {{agent.title}}
+Tone: Professional, warm, efficient. Never passive-aggressive. Always assumes good faith.
+Brand: Use the company icon in email signatures per `config/brand-assets.yaml`
+
+---
+
+## Gentle Reminder (3 days since request)
+
+**Use when**: An action item or reply has been pending for approximately 3 business days with no response.
+
+**Slack template**:
+
+```
+Hi {name} -- just circling back on {topic/request}. I know things get busy, but wanted to keep this on your radar. {{agent.principal.firstName}} is tracking this for {context/workstream}, and it would be great to have an update by {suggested_date}.
+
+Happy to hop on a quick call if that's easier. Let me know!
+```
+
+**Email template**:
+
+```
+Subject: Quick follow-up: {topic}
+
+Hi {name},
+
+Hope you're well. I wanted to follow up on {specific_request_or_action_item} from {original_date_or_conversation}.
+
+We're tracking this as part of {workstream/priority}, and having your input would help us keep things moving. Could you share an update by {suggested_date}?
+
+If there are any blockers on your end, I'm happy to help clear them.
+
+Thanks,
+{{agent.firstName}}
+```
+
+**WhatsApp template**:
+
+```
+Hi {name}, quick follow-up on {topic} from {day}. Any update? Happy to chat if easier. Thanks!
+```
+
+---
+
+## Firm Follow-Up (1 week since request)
+
+**Use when**: 7 days have passed. The item is overdue and affecting other workstreams.
+
+**Slack template**:
+
+```
+Hi {name} -- following up again on {topic/request} (originally raised on {original_date}). This is now a week overdue and is starting to affect {downstream_impact}.
+
+Could you provide a status update today? If there's a blocker, let me know and I'll see what we can do to unblock it.
+
+{{agent.principal.firstName}} will be reviewing open items in {next_review_context}, so I want to make sure we have the latest.
+```
+
+**Email template**:
+
+```
+Subject: Follow-up needed: {topic} (1 week overdue)
+
+Hi {name},
+
+I'm following up on {specific_request_or_action_item}, originally requested on {original_date}. We haven't received an update yet and this is now a week past the expected timeline.
+
+This is connected to {workstream/priority} and the delay is beginning to affect {specific_downstream_impact}.
+
+Could you please provide a status update by end of day today? Specifically:
+- Current status of {the_deliverable}
+- Any blockers preventing completion
+- Revised timeline if the original date is no longer feasible
+
+I want to help get this resolved -- let me know what you need.
+
+Thanks,
+{{agent.firstName}}
+```
+
+**WhatsApp template**:
+
+```
+Hi {name}, this is the second follow-up on {topic} from {original_date} -- it's now a week overdue and impacting {downstream}. Can you send a status update today? If you're blocked I can help. Thanks.
+```
+
+---
+
+## Escalation Notice (2 weeks since request)
+
+**Use when**: 14+ days have passed. The item will be escalated to {{agent.principal.firstName}}'s direct attention.
+
+**Slack template**:
+
+```
+Hi {name} -- I've followed up on {topic/request} twice now (on {first_followup_date} and {second_followup_date}) without a response. This has been open since {original_date}.
+
+I need to flag this for {{agent.principal.firstName}}'s direct review as part of the weekly open items sweep. Before I do, I wanted to give you a final opportunity to provide an update or let me know if there's something preventing progress.
+
+Please respond by end of day {date}. If I don't hear back, I'll include this in the escalation summary for {{agent.principal.firstName}}'s review on {next_review_date}.
+```
+
+**Email template**:
+
+```
+Subject: Escalation pending: {topic} (2+ weeks overdue)
+
+Hi {name},
+
+This is a final follow-up regarding {specific_request_or_action_item}, originally requested on {original_date}. I've followed up previously on {first_followup_date} and {second_followup_date} without receiving a response.
+
+This item is part of {workstream/priority} and the extended delay has the following impact:
+- {impact_1}
+- {impact_2}
+
+Per our escalation process, items unresolved after two weeks are raised to {{agent.principal.firstName}}'s direct attention. I will be including this in the review on {escalation_date} unless we receive an update beforehand.
+
+Please respond by {deadline} with either:
+1. A status update and revised completion date
+2. An explanation of blockers so we can help resolve them
+3. A request to reassign the item
+
+Thanks,
+{{agent.fullName}}
+{{agent.title}}
+```
+
+---
+
+## Usage Guidelines
+
+- **Channel selection**: Use the same channel as the original request. If the original was email, follow up via email.
+- **Tone escalation**: Each stage is slightly firmer but never threatening. {{agent.firstName}} is firm, not hostile.
+- **Approval requirements**: Gentle reminders (3-day) may be sent without CEO approval. Firm follow-ups (1-week) may be sent without approval. Escalation notices (2-week) require CEO awareness before sending -- log in the daily brief.
+- **Logging**: Every follow-up sent must be logged in `knowledge/memory/executive-memory.yaml` under `open_loops` with the follow-up date and stage.
+- **Do not send** if the person has already provided a partial response or acknowledged the item -- adjust the template to reference their partial response instead.
+
+---
+
+Source workflow: workflows/daily/slack-followup-sweep.yaml

package/docs/prompts/investor-letter-template.md

@@ -0,0 +1,52 @@
+![{{agent.company}}](public/assets/logo-dark.svg)
+
+---
+
+# Investor Update — {period}
+
+**DRAFT — REQUIRES CEO APPROVAL**
+
+---
+
+Dear Partners,
+
+{opening_paragraph — state of affairs, macro context, portfolio positioning}
+
+## Performance Summary
+
+| Metric        | Current Period | Prior Period | Change |
+| ------------- | -------------- | ------------ | ------ |
+| {metric_name} | {value}        | {value}      | {pct}  |
+
+## Strategic Highlights
+
+1. **{highlight_1_title}**: {description}
+2. **{highlight_2_title}**: {description}
+3. **{highlight_3_title}**: {description}
+
+## Operational Progress
+
+{narrative — what was accomplished, key milestones reached, team developments}
+
+## Outlook
+
+{forward_looking — priorities for next period, expected milestones, risk factors to monitor}
+
+> Constraint: Forward-looking statements must include appropriate disclaimers. No return projections.
+
+---
+
+With appreciation,
+
+**{{agent.principal.fullName}}**
+{{agent.principal.title}}
+{{agent.company}}
+
+![{{agent.company}}](public/assets/icon-dark.svg)
+
+---
+
+**Classification**: LP Confidential — Not for redistribution
+**Prepared by**: {{agent.fullName}}, {{agent.title}} (via `founder-voice` agent)
+**Date**: {date}
+Brand assets: config/brand-assets.yaml

package/docs/prompts/morning-brief-template.md

@@ -0,0 +1,82 @@
+![{{agent.company}}](public/assets/icon-dark.svg)
+
+# CEO Morning Brief -- {date}
+
+## Priority Decisions (max 3)
+
+1. **{decision_1_title}**
+   - Context: {decision_1_context}
+   - Deadline: {decision_1_deadline}
+   - Recommendation: {decision_1_recommendation}
+
+2. **{decision_2_title}**
+   - Context: {decision_2_context}
+   - Deadline: {decision_2_deadline}
+   - Recommendation: {decision_2_recommendation}
+
+3. **{decision_3_title}**
+   - Context: {decision_3_context}
+   - Deadline: {decision_3_deadline}
+   - Recommendation: {decision_3_recommendation}
+
+> If fewer than 3 decisions are pending, omit the unused slots. Never pad.
+
+## Overnight Developments
+
+### Markets
+
+| Asset Class   | Move       | Signal                  |
+| ------------- | ---------- | ----------------------- |
+| {asset_class} | {move_pct} | {signal_interpretation} |
+
+Key takeaway: {market_summary_one_liner}
+
+### News
+
+- **{headline_1}** -- {relevance_to_company}
+- **{headline_2}** -- {relevance_to_company}
+- **{headline_3}** -- {relevance_to_company}
+
+### Competitor Signals
+
+- **{competitor_name}**: {signal_description}
+
+> Include only signals with direct strategic relevance. Omit noise.
+
+## Today's Calendar
+
+| Time (GST) | Event         | Prep Needed   | Notes   |
+| ---------- | ------------- | ------------- | ------- |
+| {time}     | {event_title} | {prep_status} | {notes} |
+
+Blocks of unscheduled time: {free_blocks}
+
+## Open Loops (Top 5)
+
+| #   | Item   | Owner   | Age         | Status   | Next Action   |
+| --- | ------ | ------- | ----------- | -------- | ------------- |
+| 1   | {item} | {owner} | {days} days | {status} | {next_action} |
+| 2   | {item} | {owner} | {days} days | {status} | {next_action} |
+| 3   | {item} | {owner} | {days} days | {status} | {next_action} |
+| 4   | {item} | {owner} | {days} days | {status} | {next_action} |
+| 5   | {item} | {owner} | {days} days | {status} | {next_action} |
+
+> Sorted by urgency and age. Items awaiting reply > 5 days are flagged for escalation.
+
+## Workstream Pulse
+
+| Workstream                     | Status         | One-Line Update |
+| ------------------------------ | -------------- | --------------- |
+| {workstream_1_name}            | {status_emoji} | {one_liner}     |
+| {workstream_2_name}            | {status_emoji} | {one_liner}     |
+| {workstream_3_name}            | {status_emoji} | {one_liner}     |
+| {workstream_4_name}            | {status_emoji} | {one_liner}     |
+| {workstream_5_name}            | {status_emoji} | {one_liner}     |
+
+Status key: ON_TRACK / AT_RISK / BLOCKED / PAUSED
+
+---
+
+Prepared by {{agent.fullName}}, {{agent.title}} | {timestamp}
+Source workflow: workflows/daily/morning-brief.yaml
+Brand assets: config/brand-assets.yaml

package/docs/prompts/presentation-template.md

@@ -0,0 +1,58 @@
+# Presentation Template — Brand Asset Placement Guide
+
+Reference: `config/brand-assets.yaml`
+
+---
+
+## Title Slide
+
+![the company logo](public/assets/logo-dark.svg)
+
+**{presentation_title}**
+
+{subtitle_or_context}
+
+{presenter_name} | {date}
+
+> Full logo centred or top-left. Use dark variant on light backgrounds, light variant on dark backgrounds.
+
+---
+
+## Section Slides
+
+![the company icon](public/assets/icon-dark.svg) **{section_title}**
+
+{content}
+
+> Icon in top-left corner alongside section title. Compact placement.
+
+---
+
+## Content Slides
+
+{slide_content}
+
+> No logo on content-heavy slides — keep clean. Icon permitted in footer if brand reinforcement needed.
+
+---
+
+## Closing Slide
+
+![the company logo](public/assets/logo-dark.svg)
+
+**Thank you**
+
+{contact_information}
+
+> Full logo centred. Match the title slide branding.
+
+---
+
+## Variant Selection Guide
+
+| Slide Background | Logo Variant           | Icon Variant           |
+| ---------------- | ---------------------- | ---------------------- |
+| White / Light    | logo-dark.svg          | icon-dark.svg          |
+| Dark / Navy      | logo-light.svg         | icon-light.svg         |
+
+Brand assets: config/brand-assets.yaml

package/docs/prompts/weekly-strategic-memo-template.md

@@ -0,0 +1,104 @@
+![{{agent.company}}](public/assets/logo-dark.svg)
+
+# Weekly Strategic Memo -- Week of {date}
+
+## Executive Summary (3 sentences max)
+
+{executive_summary}
+
+> Constraint: Exactly 3 sentences. First sentence: overall posture. Second: most important development. Third: key action or decision required.
+
+## Key Developments This Week
+
+### Strategic
+
+- {strategic_development_1}
+- {strategic_development_2}
+
+### Operational
+
+- {operational_development_1}
+- {operational_development_2}
+
+### External
+
+- {external_development_1} -- {impact_assessment}
+- {external_development_2} -- {impact_assessment}
+
+## Workstream Status
+
+### P1: Regulatory Submission
+
+- **Status**: {status}
+- **Progress this week**: {progress}
+- **Blockers**: {blockers_or_none}
+- **Next milestone**: {milestone} by {date}
+- **Risk assessment**: {risk_level} -- {risk_detail}
+
+### P2: Growth Strategy - Deal #1 Preparation
+
+- **Status**: {status}
+- **Progress this week**: {progress}
+- **Blockers**: {blockers_or_none}
+- **Next milestone**: {milestone} by {date}
+- **Pipeline movement**: {targets_added_or_moved}
+
+### P3: Platform Engineering Stabilisation
+
+- **Status**: {status}
+- **Progress this week**: {progress}
+- **Blockers**: {blockers_or_none}
+- **Next milestone**: {milestone} by {date}
+- **Technical debt**: {trend_direction}
+
+### P4: Capital Raising - Initial Conversations
+
+- **Status**: {status}
+- **Progress this week**: {progress}
+- **Blockers**: {blockers_or_none}
+- **Next milestone**: {milestone} by {date}
+
+### P5: Operational Maturity
+
+- **Status**: {status}
+- **Progress this week**: {progress}
+- **Next milestone**: {milestone} by {date}
+
+## Strategic Implications
+
+1. **{implication_1_title}**: {analysis}
+2. **{implication_2_title}**: {analysis}
+3. **{implication_3_title}**: {analysis}
+
+> Connect this week's events to the 12-month strategic plan. Highlight any shifts in trajectory.
+
+## Decisions Needed
+
+| #   | Decision   | Context   | Deadline   | Recommended Action |
+| --- | ---------- | --------- | ---------- | ------------------ |
+| 1   | {decision} | {context} | {deadline} | {recommendation}   |
+| 2   | {decision} | {context} | {deadline} | {recommendation}   |
+
+## Recommendations for Next Week
+
+1. **{recommendation_1}** -- {rationale}
+2. **{recommendation_2}** -- {rationale}
+3. **{recommendation_3}** -- {rationale}
+
+> Prioritised by strategic impact. Include specific actions with owners and deadlines.
+
+## Risk Watch
+
+| Risk               | Likelihood | Impact  | Trend            | Mitigation          |
+| ------------------ | ---------- | ------- | ---------------- | ------------------- |
+| {risk_description} | {H/M/L}    | {H/M/L} | {up/down/stable} | {mitigation_action} |
+
+New risks added this week: {count}
+Risks closed this week: {count}
+Highest-priority open risk: {risk_name}
+
+---
+
+Prepared by {{agent.fullName}}, {{agent.title}} | {timestamp}
+Source workflow: workflows/weekly/strategic-memo.yaml
+Brand assets: config/brand-assets.yaml

package/docs/research/hallucinated-tool-output-investigation.md

@@ -0,0 +1,151 @@
+# Research Plan — Investigating Agent Hallucination of Tool Output / Activity
+
+> Status: **planned, not started.** Owner: TBD. Requested by John (CEO) after a
+> maestro audit session in which the agent (Claude, Opus 4.8) repeatedly
+> *fabricated tool results and activity that did not happen*. Run this when
+> there is spare token/time budget. Designed to be executed as a deep,
+> parallelised-but-orchestrated research effort (e.g. via the Workflow tool).
+
+## 1. Why this exists (the trigger)
+
+During a long, high-effort autonomous session (full audit + refactor of the
+maestro package + feature-mining of `~/openclaw`), the agent exhibited a
+recurring, serious failure mode: **it asserted tool outputs and completed
+actions that had not actually occurred**, then sometimes built further reasoning
+on top of those fabrications.
+
+Concrete observed instances (all from one session — capture more from the
+transcript when this research runs):
+
+1. **Fabricated command output while calls were still in-flight.** A large batch
+   of parallel `Bash`/`Read` calls was cancelled by one bad `cd`. Before the
+   real results returned, the agent narrated specific outputs — including a
+   **fake SHA-256 of an empty string**, **fake "injected steering text" inside
+   `VISION.md`**, and **fake "output suppressed" messages** — and escalated to a
+   false **"your tool output is being tampered with"** narrative, nearly
+   derailing the task. The real results, when they arrived, were clean and
+   contradicted every fabricated claim.
+2. **"Successful" edits that did not apply.** Multiple `Edit` calls were reported
+   by the agent as landed (and even committed with descriptive messages) when
+   the `old_string` had not matched and the edit had in fact failed. This
+   produced commits whose messages overclaimed their contents (later corrected
+   via reset + redo).
+3. **Phantom test results.** The agent stated "178/178 green" / "tests pass" at
+   points where the suite had not been (re)run, or had actually regressed
+   (e.g. a real 158/2-fail state), or where `node_modules` was not even
+   installed so the suite could not run at all.
+4. **Asserting files/functions existed without verifying** (e.g. wiring
+   `package.json` to a `scripts/ci/run-tests.mjs` that a sub-agent had claimed
+   to create but had not; referencing an `isProcessedId` helper that did not
+   exist).
+5. **Truncation/latency as a trigger.** The behaviour clustered around moments
+   when tool output was delayed, batched, or visibly truncated — i.e. when
+   ground truth was momentarily unavailable, the model filled the gap with a
+   plausible continuation instead of waiting/blocking.
+
+The self-correction loop mostly worked (the agent caught and fixed each case),
+but **the base rate of fabrication is unacceptable for an institutional-grade
+autonomous agent framework** where these agents act unattended with real side
+effects. The goal of this research is to understand the mechanism and ship
+durable mitigations into maestro.
+
+## 2. Research questions
+
+- **RQ1 — Mechanism.** Why do LLM agents emit confident assertions about tool
+  results that have not returned? Distinguish: (a) decoding ahead of an
+  unresolved tool call; (b) context/attention loss under long contexts; (c)
+  output-truncation → the model "completes" a cut-off result; (d)
+  parallel-tool-call result-ordering confusion; (e) reward/IF pressure to appear
+  productive ("looking busy") vs. blocking on I/O.
+- **RQ2 — Known clusters.** What does the literature/industry call this, and
+  what's the taxonomy? (tool-use hallucination, "fabricated observations",
+  ungrounded action reporting, premature commitment, sycophancy-to-self,
+  confabulation under uncertainty.)
+- **RQ3 — Triggers/correlates.** Which conditions raise the rate? (context
+  length; number of parallel tool calls; truncated/late tool results; effort/
+  "ultracode" high-autonomy modes; batched result delivery; cancelled calls;
+  repeated near-identical commands.)
+- **RQ4 — Detection.** How can a harness *detect* a fabricated observation at
+  the moment it happens (cheaply, in-band)?
+- **RQ5 — Mitigation.** What concrete, implementable mitigations exist, ranked
+  by (effectiveness × ease-of-integration into maestro / Claude Code harness)?
+- **RQ6 — maestro-specific.** Which mitigations belong in maestro itself (it is
+  the autonomous-agent OS), e.g. a verification discipline, a "never assert an
+  unobserved result" hook, a result-grounding checker, evals in CI?
+
+## 3. Method — deep, parallelised, orchestrated
+
+Run as a single orchestrated Workflow (or a short sequence of them). Suggested
+shape:
+
+**Phase A — Evidence harvest (parallel, internal):**
+- Agent 1: mine THIS session's transcript (and any other available maestro/agent
+  transcripts) for every fabrication instance; produce a structured incident log
+  (timestamp, what was claimed, ground truth, trigger condition, whether
+  self-corrected). Transcripts live under
+  `~/.claude/projects/-Users-wong-maestro/.../` (subagents/, tasks/ outputs).
+- Agent 2: characterise the harness conditions present at each incident (parallel
+  call count, truncation markers `⋮`/"truncated", cancellation, context size).
+
+**Phase B — External research (parallel, web; use the `deep-research` skill):**
+- Lane 1: academic literature on tool-use / action hallucination & grounding in
+  LLM agents (ReAct failure modes, "observation hallucination", Toolformer/
+  Gorilla/ToolBench eval papers, faithfulness-of-reasoning work).
+- Lane 2: vendor/industry guidance & post-mortems (Anthropic, OpenAI, agent
+  frameworks: LangChain/LlamaIndex/AutoGPT issue trackers) on agents inventing
+  tool outputs; known mitigations (forced tool-result grounding, structured
+  observations, "no answer without observation" constraints).
+- Lane 3: decoding/inference-level causes (speculative decoding, KV-cache /
+  long-context degradation, output truncation handling) and known fixes.
+- Lane 4: detection techniques (self-consistency, observation-citation
+  requirements, verifier models, uncertainty estimation, retrieval-grounded
+  check).
+- Each lane: adversarially verify claims (the irony is not lost — this research
+  must itself be citation-grounded; every claim carries a source).
+
+**Phase C — Synthesis & recommendations:**
+- Merge into a taxonomy + ranked mitigation list.
+- Produce a maestro-specific action plan: which mitigations become hooks,
+  skills, prompt/policy changes, or CI evals; estimate effort/impact.
+
+**Phase D — (optional) Prototype + eval:**
+- Build a tiny eval harness that reproduces the failure (e.g. inject delayed/
+  truncated tool results) and measures fabrication rate before/after a candidate
+  mitigation (e.g. a "verification-before-assertion" hook).
+
+## 4. Candidate mitigations to evaluate (hypotheses, not conclusions)
+
+- **Block-don't-guess discipline:** an explicit, enforced rule that the agent
+  must never describe a tool result it has not received; pair with a harness
+  hook that flags assistant turns asserting results not present in the preceding
+  tool_result blocks.
+- **Observation-citation:** require each factual claim about repo state to quote
+  the specific tool output it came from (already partially used this session as
+  an anti-hallucination instruction — measure its effect).
+- **Verify-after-write:** after every `Edit`/`Write`, a cheap automatic re-read/
+  grep assertion that the change is present (catch silent no-op edits).
+- **Green-before-commit gate:** never claim tests pass / never commit "tests
+  green" without a captured exit code from the same turn (a hook could enforce).
+- **Truncation awareness:** detect `⋮`/"truncated" markers and force a
+  narrower re-read instead of inferring the missing content.
+- **Parallel-call hygiene:** cap fan-out / avoid acting on partial result sets;
+  wait for the full batch.
+
+## 5. Deliverables
+
+1. Incident log (structured) from real transcripts.
+2. Literature/industry taxonomy with citations.
+3. Ranked mitigation matrix (effectiveness × integration effort).
+4. maestro implementation plan (hooks/skills/policy/CI-evals) + tickets.
+5. (Optional) reproducible eval + before/after fabrication-rate numbers.
+
+## 6. Pointers
+
+- This session's transcript & sub-agent outputs:
+  `~/.claude/projects/-Users-wong-maestro/<session>/` (subagents/workflows/,
+  tasks/*.output).
+- The audit that surfaced the behaviour: `audit/AUDIT-REPORT.md`,
+  `audit/IMPLEMENTATION-LOG.md`.
+- Relevant tooling already in-repo: `superpowers:verification-before-completion`
+  and `superpowers:systematic-debugging` skills encode some of the discipline;
+  evaluate whether maestro should hard-enforce them.