Merge pull request #128 from drpedapati/codex/image-slide-artifact-routing

fix(agent): preserve image-generated slide intent

Author: drpedapati

.agents/skills/ship-job/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: ship-job
+description: Ship a SciClaw software change through an isolated worktree, implementation, pruning, verification, commit, push, draft pull request, CI closeout, and independent review. Use when asked to ship a job, complete a change through PR, prepare a release candidate, or follow the repository's happy path toward Homebrew release and Data3 deployment.
+---
+
+# Ship job
+
+Deliver a reviewable packet, not uncommitted local work. Keep implementation in an isolated worktree and preserve unrelated changes.
+
+## Authority boundary
+
+Invocation authorizes implementation, commit, push, and a draft PR. It does not by itself authorize merge, tag creation, release publication, Homebrew tap mutation, or deployment. Treat those as explicit post-review gates.
+
+## Workflow
+
+1. Reconfirm the requested outcome, acceptance criteria, exclusions, and authority.
+2. Inspect the repository root, remotes, worktrees, dirty state, base commit, related PRs, and repository guidance.
+3. Create a unique branch and isolated worktree from the evidence-backed base. Reconfirm isolation before every edit, test, commit, and publish operation.
+4. Read the governing code, tests, specifications, and skills. Implement the smallest cohesive change.
+5. Prune the complete diff: remove dead code, duplicate paths, abandoned attempts, unnecessary abstractions, stale documentation, and generated debris.
+6. Run focused tests followed by the broadest practical suite. Inspect formatting, build, `git diff --check`, status, and the complete diff. Visually inspect real renders for visual work.
+7. Perform a pre-publish review. Fix material findings and rerun affected checks.
+8. Commit only intended files, push the branch, and open a draft PR against the verified base.
+9. Add a standalone independent-review packet using `references/external-review-prompt.md` and record the closeout using `references/correspondence-template.md`.
+10. Monitor CI, mergeability, and in-scope feedback. Fix branch-caused failures without silently expanding scope.
+11. Report the ordered merge train and the next authorized action.
+
+## SciClaw release continuation
+
+When the user separately authorizes merge, release, or deployment, read `references/sciclaw-release.md` completely and follow its gates. Never tag a commit other than the reviewed merge head. Use Homebrew as the deployment source of truth; never hot-copy or symlink a development binary into the service path.
+
+## Completion contract
+
+A ship job is incomplete without:
+
+- isolated worktree and branch;
+- pruned and verified change;
+- commit and push;
+- draft PR;
+- independent-review prompt on the branch or PR;
+- CI/review status and merge train;
+- explicit limitations and next safe action.
+
+Final reporting must include worktree, branch, base, commit, PR, verification, evidence, limitations, review packet path, merge train, and the next gate.

.agents/skills/ship-job/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Ship Job"
+  short_description: "Ship reviewed changes through a draft PR"
+  default_prompt: "Use $ship-job to deliver this change through a verified draft pull request."

.agents/skills/ship-job/references/correspondence-template.md

@@ -0,0 +1,16 @@
+# Ship closeout
+
+Record:
+
+1. answer first: ready for review or blocked;
+2. user-visible outcome;
+3. concise architecture and intentional cleanup;
+4. worktree, branch, base, head, PR, and dirty state;
+5. ordered merge train and blockers;
+6. verification commands and observed outcomes;
+7. external evidence and visual inspection where applicable;
+8. limitations and excluded work;
+9. next authorized gate;
+10. completed independent-review prompt.
+
+Do not include secrets, credentials, PHI, or raw tokens.

.agents/skills/ship-job/references/external-review-prompt.md

@@ -0,0 +1,18 @@
+# Independent review prompt
+
+```text
+Act as an independent senior engineer reviewing this SciClaw pull request. Do not trust the implementer's summary as proof. Inspect the exact base/head commits, full diff, tests, prompt assembly, runtime skill routing, packaging, and cited evidence.
+
+Submit findings as a GitHub review. Approve only when no material findings remain; request changes for merge blockers; comment when evidence is incomplete. Do not merge or push fixes.
+
+Verify:
+1. The diff matches the requested behavior without unrelated changes.
+2. Removed prompt language is absent from runtime, templates, documentation, and tests.
+3. Artifact routing distinguishes standalone images, slide assets, editable PowerPoint, and complete image-generated slides.
+4. Tests would fail for the prior behavior and cover important negative cases.
+5. Provider image transport, persistence, and Discord attachment behavior remain intact.
+6. Homebrew/release implications and rollback are accurately described.
+7. No dead code, duplicate paths, stale attempt leftovers, secrets, or generated debris remain.
+
+Return: verdict, findings by severity with file/line references, evidence and commands rerun, unverified claims, and minimal remediation before merge.
+```

.agents/skills/ship-job/references/sciclaw-release.md

@@ -0,0 +1,62 @@
+# SciClaw release and deployment continuation
+
+Read this only after the draft PR is verified and the user has separately authorized the applicable merge, release, or deployment operation.
+
+## Merge gate
+
+1. Refresh the exact PR head, review decision, mergeability, and CI.
+2. Require no unresolved material review findings.
+3. Merge only with explicit authorization.
+4. Record the resulting `main` commit. All tags and release artifacts must derive from that commit.
+
+## Version gate
+
+1. Inspect the latest stable and development tags; never guess the next version.
+2. Use a new patch version after any change to an earlier canary. Never move or rewrite a published tag.
+3. Update release notes and public documentation when the change is user-visible.
+
+## Release paths
+
+Prefer the repository workflow:
+
+```bash
+make release-dispatch RELEASE_TAG=vX.Y.Z
+```
+
+For a development canary, use the repository's development release target with a fresh `-dev.N` tag. For a stable local release, `make release-local RELEASE_TAG=vX.Y.Z` requires a clean tree.
+
+Verify the GitHub workflow created the expected tag, binaries, checksums, release, and—only for a stable non-draft release—the Homebrew tap update.
+
+## Homebrew deployment contract
+
+Follow `docs/ops/brew-only-deployment-contract.md` completely. On Data3, use Linuxbrew's resolved paths.
+
+1. Snapshot the current version, resolved binary, service binding, model status, and gateway health.
+2. Run `brew update` and upgrade the intended `sciclaw` or `sciclaw-dev` formula.
+3. Refresh/reinstall the service using the active Brew binary, then restart it.
+4. Verify the binary resolves under the Brew Cellar/opt path and the service uses the same installation.
+5. Run `sciclaw doctor`, `sciclaw status`, and `sciclaw models status`.
+6. Confirm Discord reconnects and execute a narrow live canary in the intended routed workspace.
+
+Do not overwrite configuration, workspace state, credentials, routing, or memory during upgrade.
+
+### Existing workspace guidance refresh
+
+Onboarding does not overwrite an existing workspace `AGENTS.md`. For this release, inspect the active DEB guidance at `/home/ernie/Dropbox/sciclaw/deb-sciclaw/AGENTS.md` after taking a timestamped backup. If it contains the obsolete image-generation sentence, replace only that sentence with the new `image-generation` skill routing from the installed workspace template. Show the exact diff, verify the obsolete wording is absent, and preserve every unrelated workspace instruction. Do not replace the whole file.
+
+Confirm the routed DEB workspace contains the released `skills/image-generation/SKILL.md`. If it is missing, use the released SciClaw skill installation/doctor repair path; do not copy it from a development checkout.
+
+## Imagery-routing acceptance
+
+For image-generation changes, test distinct products in a fresh DEB session:
+
+1. standalone illustration;
+2. visual asset intended for a slide;
+3. editable PowerPoint improvement;
+4. complete image-generated 16:9 slide using supplied PowerPoint content.
+
+The complete-slide case must retain an action title, concise audience-facing wording, an integrated exhibit or analogy, and a clear takeaway. It must not silently return a wordless illustration or switch to editable PowerPoint.
+
+## Rollback
+
+Record the previous formula version and service state before deployment. If the canary fails, restore the prior Brew version using the documented contract, refresh the service, and verify gateway recovery. Do not repair a failed release with a hot-copied binary.

.gitignore

@@ -75,7 +75,11 @@ auth.json
 
 # Local agent scratch
 .agent/
-.agents/
+.agents/*
+!.agents/skills/
+.agents/skills/*
+!.agents/skills/ship-job/
+!.agents/skills/ship-job/**
 .cache/
 .claude/
 .factory/

AGENTS.md

@@ -0,0 +1,5 @@
+# Repository agent guidance
+
+For end-to-end implementation and pull-request work, use the vendored repository skill at `.agents/skills/ship-job/SKILL.md`. Read it completely before changing files, and use `.agents/skills/ship-job/references/sciclaw-release.md` for any separately authorized merge, release, Homebrew, or Data3 deployment operation.
+
+Repository-local guidance takes precedence over similarly named user-level skill copies for work in this repository.

cmd/picoclaw/main.go

@@ -82,6 +82,7 @@ var baselineScienceSkillNames = []string{
 	"quarto-authoring",
 	"pandoc-docx",
 	"imagemagick",
+	"image-generation",
 	"beautiful-mermaid",
 	"explainer-site",
 	"experiment-provenance",

docs/issues/gpt55-image-generation-rfc.md

@@ -208,7 +208,7 @@ Files (expected):
 
 - `pkg/tools/generate_image.go` (+ tests)
 - Register in `pkg/agent/loop.go` `createToolRegistry`
-- `skills/image-gen/SKILL.md` (routing + provenance notes)
+- `skills/image-generation/SKILL.md` (final-artifact routing)
 - AGENTS.md baseline skill bullet
 - Config knobs (optional): enable flag, default model `gpt-image-2`, default size/quality, output dir
 
@@ -264,7 +264,7 @@ Only after Phase 0 proves Codex or API-key Responses works:
 
 1. **OAuth vs API key:** Can Codex backend host `image_generation` for sciClaw OAuth users? Unknown until smoke-tested.
 2. **Cost / abuse:** Image gen is expensive; need enable flag + maybe per-workspace allowlist.
-3. **Scientific integrity:** Generated illustrations must not be presented as real experimental data. Skill copy must say so.
+3. **Final-artifact routing:** Image generation must preserve the requested product. A standalone image, a visual asset for a larger artifact, an editable PowerPoint, and a complete image-generated slide are distinct outputs and must not be substituted for one another.
 4. **Vendor SDK age:** Vendored `openai-go/v3` documents older GPT Image models in some comments; Image API may still accept `gpt-image-2` via raw HTTP even if SDK enums lag. Prefer thin HTTP client in the tool (like `WeatherForecastTool`) or bump vendor.
 5. **PHI mode:** Local models cannot call OpenAI image APIs; tool must no-op/error clearly in PHI mode.
 6. **Cursor skill confusion:** Higgsfield / GenerateImage skills live in the IDE, not sciClaw. Document that they are out of scope for runtime chat.

docs/ops/correspondence-image-slide-artifact-routing.md

@@ -0,0 +1,116 @@
+# Image-generated slide artifact routing closeout
+
+## Answer first
+
+Ready for independent review in draft PR [#128](https://github.com/drpedapati/sciclaw/pull/128). The implementation is committed and pushed; merge, release, Homebrew publication, and Data3 deployment have not been performed.
+
+## What changed
+
+SciClaw now routes image generation by the requested final product instead of allowing tool salience to switch between a wordless illustration and an editable PowerPoint. The obsolete “real experimental data” warning was removed from runtime guidance, workspace templates, and the image-generation RFC policy. A built-in `image-generation` skill distinguishes four products: standalone image, visual asset for another artifact, editable presentation, and complete worded image-generated slide.
+
+The complete-slide contract encodes the successful DEB stress-capacity pattern: 16:9 composition, action title, concise audience-facing wording, integrated exhibit or visual analogy, and clear takeaway. Provider image transport, persistence, and Discord attachment code are unchanged.
+
+The repository now vendors `.agents/skills/ship-job/`, and root `AGENTS.md` points repository work to that copy. Its SciClaw continuation gates merge, versioning, release, Homebrew deployment, surgical DEB workspace guidance refresh, canary verification, and rollback.
+
+## Repository position
+
+- Repository: `https://github.com/drpedapati/sciclaw`
+- Worktree: `/Users/ernie/Developer/sciclaw/.worktrees/image-slide-artifact-routing`
+- Branch: `codex/image-slide-artifact-routing`
+- Base: `main` at `8b9a9df8670e93ef5e233aa2c2ad5cc7bc7a7743`
+- Reviewed implementation commit: `8d3cae4c`
+- Pull request: [#128](https://github.com/drpedapati/sciclaw/pull/128)
+
+This correspondence is a packet-only follow-up to the reviewed implementation commit. Review the current PR head to include this document.
+
+## Merge train
+
+One car: PR #128, `main` → `codex/image-slide-artifact-routing`. It has no branch or PR prerequisite. Safe order is review and green CI, then an explicitly authorized merge. Release and deployment follow only after that merge.
+
+## Verification
+
+- `go test ./pkg/agent ./pkg/providers ./pkg/workspacetpl/...` — passed.
+- `go test ./... -count=1` — passed sequentially across all packages.
+- `go vet ./...` — passed.
+- `go build ./cmd/picoclaw` — passed.
+- `git diff --check` — passed.
+- `uv run --with pyyaml python .../quick_validate.py .agents/skills/ship-job` — valid.
+- `uv run --with pyyaml python .../quick_validate.py skills/image-generation` — valid.
+- Independent standards review — initial duplication concern fixed; re-review found no material findings.
+- Independent spec review — DEB refresh, academic hierarchy, and routing-test gaps fixed; re-review found no material gaps.
+
+One timing-sensitive binary-inspection test was killed while four Go workloads ran concurrently. The isolated test passed, and the complete suite then passed sequentially. This was treated as resource contention, not hidden as a green first run.
+
+## Limits
+
+- No merge, tag, GitHub release, Homebrew tap update, or deployment has occurred.
+- Live four-mode DEB acceptance requires the released binary and refreshed routed workspace, so it remains a post-release canary.
+- The provider does not persist an internal rewritten image prompt; this change does not claim prompt-level reproducibility beyond saved user/session context.
+
+## Next safe action
+
+Run the independent GitHub review below against the current PR head and close CI. If no material findings remain, request explicit merge authorization. After merge, use `.agents/skills/ship-job/references/sciclaw-release.md` for a separately authorized release and Data3 deployment.
+
+## Independent review prompt
+
+```text
+Act as an independent senior engineer reviewing a proposed SciClaw change. Do not trust the implementer's summary as proof. Inspect the repository, exact PR diff, tests, prompt assembly, skills, packaging, and cited evidence yourself.
+
+When finished, submit findings on the pull request as a GitHub review. Approve only if no material findings remain; request changes for merge blockers; comment when evidence is incomplete. Do not merge, push fixes, or resolve your own findings.
+
+Repository: drpedapati/sciclaw — https://github.com/drpedapati/sciclaw
+Pull request: #128 — https://github.com/drpedapati/sciclaw/pull/128
+Base branch and commit: main at 8b9a9df8670e93ef5e233aa2c2ad5cc7bc7a7743
+Head branch: codex/image-slide-artifact-routing; inspect the current PR head
+Worktree: /Users/ernie/Developer/sciclaw/.worktrees/image-slide-artifact-routing
+
+Job requested:
+Vendor the ship-job development skill inside SciClaw and point repository guidance to it. Remove the misleading generated-image provenance warning. Preserve working provider transport. Route standalone images, slide assets, editable PowerPoint, and complete worded image-generated slides as distinct products. Complete-slide mode must encode the successful DEB stress-capacity communication hierarchy. Prepare the verified draft PR and a gated Brew/Data3 continuation without merging or deploying.
+
+Material constraints:
+- No provider image transport, media persistence, or Discord attachment rewrite.
+- No merge, release, Homebrew mutation, or production deployment in this PR run.
+- Existing DEB guidance must be refreshed surgically after release; unrelated workspace instructions must survive.
+
+Implemented design:
+The runtime hosted-tool note and workspace template route to one canonical built-in image-generation skill. That skill owns the detailed four-product contract and presentation hierarchy. Baseline onboarding installs it. Negative regression tests prevent restoration of the removed warning and assert all four routes. A repo-local ship skill owns PR closeout and a separately gated SciClaw release continuation.
+
+Changed-file map:
+- pkg/agent/loop.go: concise hosted-tool routing pointer.
+- pkg/agent/context_test.go: prompt, template, and canonical-skill regressions.
+- skills/image-generation/SKILL.md: four-product source of truth.
+- cmd/picoclaw/main.go: baseline skill installation.
+- pkg/workspacetpl/templates/workspace/AGENTS.md: workspace routing pointer.
+- docs/issues/gpt55-image-generation-rfc.md: replace obsolete policy.
+- .agents/skills/ship-job/** and AGENTS.md: vendored development workflow and pointer.
+- .gitignore: allow only the vendored ship skill beneath otherwise local `.agents` state.
+
+Claims requiring independent verification:
+1. Runtime/template/skill guidance no longer contains the obsolete warning except negative test literals.
+2. All four requested artifact modes, academic hierarchy, 16:9 complete-slide contract, and DEB reference are protected by meaningful tests.
+3. Provider transport and outbound attachment behavior are unchanged.
+4. Existing DEB workspace remediation is bounded, diff-verified, and release-gated.
+
+Tests reported:
+- go test ./... -count=1 — pass
+- go vet ./... — pass
+- go build ./cmd/picoclaw — pass
+- git diff --check — pass
+- both SKILL.md packages pass quick_validate.py
+
+External ground truth:
+The DEB Discord thread produced a successful complete image-generated stress-capacity slide only after the user explicitly distinguished it from both a wordless conceptual image and an editable PowerPoint. The implementation uses that communication hierarchy as a qualitative reference, not a pixel snapshot.
+
+Known limitations:
+- Live DEB four-mode acceptance is a post-release canary.
+- Internal provider-rewritten image prompts are not persisted.
+
+Review tasks:
+1. Confirm the diff matches requested behavior without broader changes.
+2. Flag dead code, dual policies, or leftovers from earlier attempts.
+3. Trace runtime prompt assembly and baseline skill installation.
+4. Check failure modes, workspace migration safety, packaging, and rollback.
+5. Confirm tests fail for old behavior and cover important negatives.
+6. Reproduce critical claims where practical.
+7. Report findings by severity with file/line references.
+```