[#200] Generate cartoon-aware agent instructions for OWS stories

[realproject7]

Summary

• Add per-story CLAUDE.md generation with content-type-specific writing instructions
• Fiction: prose workflow guidance (structure.md format, genesis hook, plot chapters, publish rules)
• Cartoon: cut-based planning, clean-image-first workflow, character bible, visual style guide, lettering handoff, episode workflow, publish markdown constraints
• Instructions written on terminal spawn (for existing stories) and metadata update
• Skip-if-unchanged marker detection avoids unnecessary rewrites
• 9 vitest unit tests covering fiction vs cartoon output, marker detection, and regeneration

Test plan

• npm run typecheck passes
• npm run lint passes (no new warnings)
• npm run test passes (57 tests, including 9 new instruction tests)
• Fiction instructions contain prose sections, do NOT contain cartoon terms
• Cartoon instructions contain cuts.json, character bible, clean-image rules, lettering handoff
• Cartoon instructions explicitly prohibit baking text into images
• writeStoryInstructions skips write when marker already matches
• writeStoryInstructions regenerates when contentType changes

Closes #200

🤖 Generated with Claude Code

[project7-interns]

Verdict: REQUEST CHANGES

Summary

The cartoon/fiction instruction content itself matches the #200 direction, but the write path can destructively overwrite an existing story-local CLAUDE.md that was not generated by this feature. Because terminal spawn now triggers this for existing stories, a user-authored file in a story directory can be replaced simply by opening that story terminal.

Findings

• [high] overwrites any existing whose first line does not match the expected generated marker.
  • File:
  • Suggestion: Treat unmarked files as user-owned and do not overwrite them automatically. Only skip when the marker matches, regenerate when the first line has a marker for another content type, and preserve or move aside unmarked files. Add a test covering an existing unmarked CLAUDE.md so terminal spawn/metadata update cannot erase user notes.

Decision

Requesting changes. The implementation should be non-destructive for existing story data before this can merge. CI was still in progress at review time, but this issue is independent of CI.

[realproject7]

@re2 verdict: APPROVE

Reviewed:

• Instruction content — Fiction: Covers structure.md format, genesis hook, plot chapter rules, character count limits, and publish immutability. Clean and focused on prose workflow.
• Instruction content — Cartoon: Comprehensive coverage of cut-based planning (plot-NN.cuts.json), character bible, visual style guide, clean-image-first workflow, lettering handoff, episode format, bubble/lettering conventions, and publish markdown constraints. Explicitly prohibits baking dialogue/text into images with clear exceptions (in-scene text). Episode workflow (Plan → Generate → Review → Letter → Upload → Compose → Preview → Publish) is well-structured.
• Marker-based skip: <!-- plotlink-ows:story-instructions:{contentType} --> on the first line avoids unnecessary rewrites. Correctly regenerates when contentType changes. Good approach.
• Integration points: writeStoryInstructions called (1) on terminal spawn for existing stories (correctly gated behind !isNewStory to avoid writing to root STORIES_DIR), and (2) on metadata POST endpoint after writeStoryMeta. Both are the right trigger points.
• Import structure: readStoryMeta imported from ./stories in terminal.ts — cross-route import of a utility function, not the Hono app. Acceptable.
• Tests: 9 tests cover fiction content, cartoon content, negative assertions (fiction doesn't contain cartoon terms), marker skip, marker regeneration on type change, and API endpoint isolation. Solid coverage.
• No regressions: Fiction path unchanged, existing stories without .story.json default to fiction per PR [#199] Add PlotLink contentType metadata to OWS New Story flow #212, instructions auto-generated on first terminal spawn.

No issues found.

[project7-interns]

Correction to the request-changes review body above, with code identifiers restored:

Verdict: REQUEST CHANGES

Summary

The cartoon/fiction instruction content itself matches the #200 direction, but the write path can destructively overwrite an existing story-local CLAUDE.md that was not generated by this feature. Because terminal spawn now triggers this for existing stories, a user-authored file in a story directory can be replaced simply by opening that story terminal.

Findings

• [high] writeStoryInstructions overwrites any existing CLAUDE.md whose first line does not match the expected generated marker.
  • File: app/lib/generate-story-instructions.ts:212
  • Suggestion: Treat unmarked CLAUDE.md files as user-owned and do not overwrite them automatically. Only skip when the marker matches, regenerate when the first line has a plotlink-ows:story-instructions: marker for another content type, and preserve or move aside unmarked files. Add a test covering an existing unmarked CLAUDE.md so terminal spawn/metadata update cannot erase user notes.

Decision

Requesting changes. The implementation should be non-destructive for existing story data before this can merge. CI was still in progress at review time, but this issue is independent of CI.

[realproject7]

@re2 re-review verdict: APPROVE

Fix correctly addresses @re1's finding. The added guard if (!firstLine.startsWith(MARKER_PREFIX)) return; ensures user-owned unmarked CLAUDE.md files are never overwritten. The function now only writes when: (1) no CLAUDE.md exists, or (2) the file already has a PlotLink marker but the contentType changed. MARKER_PREFIX extracted as a constant for the prefix check — clean.

New regression test "preserves user-owned unmarked CLAUDE.md" directly covers the reported scenario. 10 tests total, all passing.

Previous approval stands with this fix applied.

[project7-interns]

Verdict: APPROVE

Summary

The requested non-destructive behavior is fixed. writeStoryInstructions now preserves unmarked story-local CLAUDE.md files, still skips matching generated files, and still regenerates PlotLink-marked files when the content type changes.

Findings

• No blocking findings.

Decision

Approved. The #200 instruction content covers fiction vs cartoon output, the terminal/metadata write triggers are scoped, the regression test covers existing unmarked CLAUDE.md preservation, and CI is passing.