Skip to content

Phase 14 — Two-tier provenance for inception items#279

Open
leeovery wants to merge 14 commits into
idea/inception-pr-13-docsfrom
idea/inception-pr-14-provenance
Open

Phase 14 — Two-tier provenance for inception items#279
leeovery wants to merge 14 commits into
idea/inception-pr-13-docsfrom
idea/inception-pr-14-provenance

Conversation

@leeovery
Copy link
Copy Markdown
Owner

@leeovery leeovery commented May 15, 2026

Summary

  • Adds a description field (paragraph or two) to every inception item alongside summary. Every write surface — initial inception, refinement Add, research-analysis, gap-analysis, topic split, discussion elevation, and direct-entry — now populates both fields from the same source material in the same Claude turn.
  • Direct-entry now derives summary + description from the user's opening response: ensure-inception-item accepts both as optional parameters; workflow-discussion-entry and workflow-research-entry derive them silently before invoking the reference.
  • Entry skills read description from the manifest and append a Description block to the handoff for every non-continue source branch, so research/discussion sessions open grounded rather than blank. Legacy items with null description fall through silently — block omitted, no header with empty body.
  • Refinement gains a new Edit Description operation that mirrors Edit Summary (batched STOP gate, single set ... description per topic, session-log entry, single commit).
  • discovery.cjs now exposes description on each map item so the new Edit Description op can show the current value.
  • design.md data-model bullets gain description as a peer field. No migration to back-fill — legacy items stay null until the user edits via refinement.

Test plan

  • node --test tests/scripts/test-*.cjs — 639 passing
  • Migration tests regression — all pass
  • Knowledge tests regression — all pass
  • Manual smoke: fresh epic → inception persist writes description; refinement Add writes description; refinement Edit Description preserves other fields; /continue-epic on a topic with research-analysis source has description set
  • Manual smoke: discussion handoff includes Description block when description present; omits it for legacy null description
  • Manual smoke: direct-entry d/discuss and r/research populate summary and description, opening session is grounded

🤖 Generated with Claude Code

leeovery and others added 14 commits May 15, 2026 14:42
@leeovery @claude
inception(ensure-inception-item): accept optional summary and descrip…
7f27d22 
…tion arguments

Direct-entry items currently land on the discovery map with routing + source
only — no descriptive context. Phase 14 extends the reference signature so
callers that have material to derive from (the user's opening response to
"what topic?") can back-fill summary and description at creation time. Both
parameters are optional and only written when supplied and non-empty, so the
existing call sites that don't supply them stay unchanged.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@leeovery @claude
inception(confirm-and-persist): write description alongside summary o…
ddf89c3 
…n initial-session topics

Initial-session topics now carry a description field in addition to summary.
Both are derived from the same conversation in the same Claude turn; the
working list keeps its compact form and description is generated only at
persist time.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@leeovery @claude
inception(map-operations): write description on refinement Add; add E…
afd0503 
…dit Description operation

Section D. Add now writes description alongside summary on refinement-added
topics. New section I. Edit Description mirrors Edit Summary: batched STOP
gate, single `set ... description` per topic, session-log entry, single
commit. Done renumbered to J. Operations matrix gains the Edit Description
row; lifecycle table records `any` (non-destructive, no gate).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@leeovery @claude
inception(research-analysis): write description on surfaced inception…
bb8dd39 
… items

Each new inception item surfaced by research-analysis now carries a
description field — a richer extract from the analysis cache than the
one-line summary. Entry skills load it as opening context when the user
later picks the topic up for discussion.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@leeovery @claude
inception(discussion-gap-analysis): write description on surfaced inc…
e08af62 
…eption items

Gap-analysis-surfaced topics now carry description alongside summary,
extracted from the analysis output. Loaded by discussion-entry as
opening context.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@leeovery @claude
inception(topic-splitting): write description on new inception item
5941760 
A research split creates a new inception item; the same turn that generates
the summary now also generates a description from the extracted thread
content.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@leeovery @claude
inception(discussion-session): write description on elevated inceptio…
06ba340 
…n item

Topic elevation now writes description alongside summary on the new
inception item, derived from the elevation context.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@leeovery @claude
inception(discussion-entry,research-entry): derive summary and descri…
1245bfa 
…ption from direct-entry opening response

On the no-topic path, the entry skill now silently derives summary and
description from the user's opening response in the same Claude turn that
kebab-cases the response, then passes both to ensure-inception-item. The
topic-resolved path is unchanged — when the caller already named the topic,
no derivation runs and ensure-inception-item creates the item with routing
+ source only.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@leeovery @claude
inception(discussion-entry,research-entry): load inception descriptio…
898d769 
…n into session handoff

Every source branch except continue now reads description from the
inception item and appends a Description block to the handoff when
non-empty. Legacy items with null description fall through silently —
the block is omitted, no header with empty body, no regression.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@leeovery @claude
inception(discovery): include description in per-item map output
24a8741 
Per-item map shape gains a description field — refinement's Edit
Description op reads it from discovery_map[].description to surface the
current value when proposing edits. Legacy/migration-seeded items default
to null.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@leeovery @claude
inception(design.md): note description field in discovery-map data model
72e5f94 
Add description as a peer bullet under per-item fields — Phase 14 promotes
description to a first-class field alongside summary.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@leeovery @claude
docs(discovery-map): record PR #279 for Phase 14
a8006ee 
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@leeovery @claude
inception(discussion-entry,research-entry): gate description load on …
94c11d6 
…work_type and exists probe

The original handoff-load instruction told Claude to bare-get the
description for every non-continue source, which would have failed on
two real-world paths: (1) non-epic work units have no inception phase at
all, so the path resolves nowhere and the CLI errors out; (2) epic items
created before Phase 14, or via paths that didn't supply description,
have no description subkey on the item — same error.

Both cases now gate cleanly: work_type must be epic, and exists must
return true on the description subkey. Either failing → omit the
Description block, no error surfaced.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@leeovery @claude
inception(summary-backfill): extend to derive and write description f…
8066c91 
…or migration-seeded items

continue-epic Step 6 already handles legacy/migration-seeded items missing
summary by drafting one from the source files (research/discussion).
Phase 14 added the description field but left this backfill flow
summary-only, so migrated epics would never populate description without
the user manually triggering refinement's Edit Description op for each
topic.

The fix:

- Step 6 filter now catches items missing summary OR description (was
  summary only). This brings in both freshly-migrated items and items
  that were backfilled before Phase 14 (summary present, description
  null) — the latter get one re-entry through the flow to populate
  description, then drop out.
- summary-backfill.md derives description in section A alongside summary
  (when null), tracks needs_summary / needs_description per item, and
  writes only the newly-drafted fields in section D.
- The batch review (section B) keeps showing summaries only — description
  is paragraphs and would bloat the view. The user can refine via Edit
  Description in refinement later if the auto-draft falls short.
- continue-epic discovery.cjs exposes description per item so Step 6's
  filter can read it.
- Test for the legacy-recovery filter contract is expanded to cover the
  Phase 14 fixture shapes: migrated-summary-no-description (new — re-enters
  the flow for description) and migrated-fully-populated (excluded).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@leeovery