Repository navigation
SDK lifecycle provenance and context-rich CLI primitives - #801
Conversation
Deliver a cohesive SDK and CLI context-management bundle: completion provenance, lifecycle timestamps, blocker-aware context, relative activity ranges, composable tag filters, missing-parent parity, discoverable mutation guards, dependency refreshes, and stricter quality ratchets.\n\nRegenerate public contracts and changelog output, retain exact 100% coverage, and record the implementation and verification evidence across the canonical PM lineage.
|
Caution The consumer version of Gemini Code Assist on GitHub has been sunset. All code review activity has officially ceased. |
|
@greptileai review\n\n@coderabbitai full review |
📝 WalkthroughWalkthroughThis PR adds completion timestamps and evidence-backed lifecycle reporting, expands CLI contracts, exposes dependency blockers and multi-tag filtering, improves configuration metadata discovery, and records related issue, changelog, dependency, and quality-gate updates. ChangesCompletion and CLI behavior
Estimated code review effort: 4 (Complex) | ~60 minutes Sequence Diagram(s)sequenceDiagram
participant CLI
participant UpdateCommand
participant ItemMetadata
participant SDK
participant ReleaseNotes
CLI->>UpdateCommand: pass --completed-at
UpdateCommand->>ItemMetadata: write completed_at
SDK->>ItemMetadata: resolve completion timestamp
SDK->>ReleaseNotes: provide completion timestamp for bucketing
Possibly related PRs
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✨ Finishing Touches 💡 1📝 Generate docstrings 💡
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
|
✅ Action performedFull review finished. Your included review limit is currently reached under our Fair Usage Limits Policy. This review may still proceed through usage-based billing if eligible. Your next included review will be available in 59 minutes. |
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
Merging this PR will improve performance by 2.19%
|
| Benchmark | BASE |
HEAD |
Efficiency | |
|---|---|---|---|---|
| ⚡ | createQueryFingerprint |
534.1 µs | 522.7 µs | +2.19% |
Tip
Curious why this is faster? Comment @codspeedbot explain why this is faster on this PR, or directly use the CodSpeed MCP with your agent.
Comparing sdk-lifecycle-context-fidelity (575065c) with main (c90adb1)
Reviewer's GuideAdds lifecycle-aware completion timestamps and provenance utilities, surfaces blocker state and IDs in context views, improves list tag filtering and activity range UX, exposes mutation-guard config metadata, aligns parent-reference escape hatches across CLI/SDK/MCP, and refreshes a small set of dev dependencies and quality gates. Sequence diagram for completion-aware lifecycle timestampssequenceDiagram
actor User
participant pm_close as runClose
participant pm_update as runUpdate
participant applyStatus as applyStatusAndCompletionMutations
participant Metadata as ItemMetadata
participant resolver as resolveCompletionTimestamp
participant Memory as buildWorkspaceMemorySnapshot
participant Release as itemChangedInReleaseWindow
User->>pm_close: runClose(options.completedAt)
pm_close->>Metadata: mutateCloseMetadata(closedAt, completedAt)
Note right of Metadata: Sets closed_at and completed_at
User->>pm_update: runUpdate(--completed-at)
pm_update->>applyStatus: applyStatusAndCompletionMutations
applyStatus->>Metadata: metadata.completed_at = resolveIsoOrRelative(...)
Metadata-->>resolver: resolveCompletionTimestamp(item)
resolver-->>Memory: timestamp, source, fallback
Memory->>Memory: buildWorkspaceMemorySnapshot
Metadata-->>Release: itemChangedInReleaseWindow
Release->>Release: prefer completed_at then closed_at then updated_at
Flow diagram for blocker-aware context focus projectionflowchart TD
A[resolveContextFocusGroups
listedItemMetadata,
allItems,
fullCorpus,
blockedIds] --> B[fullCorpusById
Map]
A --> C[projectFocusItem]
C --> D[toContextFocusItem]
D --> E[ContextFocusItem]
C --> F{blockedIds
has item.id?}
F -- no --> E
F -- yes --> G[resolveItemBlockers]
G --> H[blocker_ids =
unresolved blockers]
H --> E
E --> I[formatFocusLine
includes blocked and
blocker_ids tokens]
File-Level Changes
Possibly linked issues
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
Greptile SummaryAdds lifecycle
Confidence Score: 5/5No prior Greptile findings remain and no follow-up-eligible incomplete or unsafe fixes were identified, so the PR appears safe to merge from this review scope. No blocking failure remains under follow-up scope; previous Greptile threads were unavailable or empty and no incomplete or unsafe prior-thread fix was found in the current HEAD.
|
| Filename | Overview |
|---|---|
| src/sdk/lifecycle-completion.ts | New completion-timestamp resolution and evidence-only backfill planning from history terminal transitions. |
| src/cli/commands/update.ts | Status close/reopen clears or sets completed_at; --completed-at correction; allow-missing-parent parent policy override. |
| src/cli/commands/close.ts | Close stamps completed_at (optional override) without clobbering existing completion when not requested. |
| src/cli/commands/context.ts | Focus projection adds blocked flag and unresolved blocker_ids from full corpus. |
| src/sdk/query/list.ts | Multi-tag OR filters, case-insensitive match, unknown_tags warnings. |
| src/sdk/runtime-input.ts | Table-driven MCP option hoisting includes update/close completedAt and allowMissingParent. |
Flowchart
%%{init: {'theme': 'neutral'}}%%
flowchart TD
closeOrUpdate[close / update to terminal] --> stampCompletedAt[stamp completed_at]
stampCompletedAt --> itemDoc[item metadata + history]
itemDoc --> resolveTs[resolveCompletionTimestamp]
resolveTs --> reports[workspace memory / release notes]
deps[unresolved blockers] --> contextFocus[context focus rows]
contextFocus --> agents[blocker_ids in compact context]
Reviews (2): Last reviewed commit: "fix(lifecycle): preserve completion evid..." | Re-trigger Greptile
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 7
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
src/cli/commands/update.ts (1)
1876-1900: 🎯 Functional Correctness | 🟠 Major | ⚡ Quick winStrip
completedAtfrom the pre-update close helper recursion.
otherFieldKeysintentionally leavescompletedAtforrunClose, but when another field is present the recursivepreUpdatestill spreadscontext.optionswithout clearing it. That recursive call clearsstatus, reachesmutateUpdateDocument, and applies the terminal-onlycompletedAtcheck while the item is still non-terminal.🐛 Proposed fix
const preUpdate = await runUpdate( context.id, { ...context.options, status: undefined, closeReason: undefined, message: undefined, + completedAt: undefined, }, context.global, );🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@src/cli/commands/update.ts` around lines 1876 - 1900, Update the pre-update call in the surrounding close helper to clear completedAt alongside status, closeReason, and message before spreading context.options into runUpdate. Keep completedAt available for the subsequent runClose path, while ensuring the recursive preUpdate does not apply it during non-terminal updates.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In @.agents/pm/history/pm-77bmeu.jsonl:
- Around line 8-17: Restore or add a sandbox-safe full-suite coverage command
through the PM CLI, run it, and append its final evidence before the close and
release events without rewriting the append-only history. Update
.agents/pm/history/pm-77bmeu.jsonl lines 8-17 with the linked test and test-run
evidence, then synchronize .agents/pm/chores/pm-77bmeu.toon lines 34-38 so
tests[] and test_runs[] substantiate actual_result and remain reproducible after
pm close and pm release.
In @.agents/pm/issues/pm-bwnclq.toon:
- Line 19: Update the PM item’s expected_result metadata through the pm CLI,
replacing “immutable fact” with “governed completion value” while preserving the
explicit legacy fallback requirement. Regenerate the .toon projection from the
canonical PM item, and do not edit the projection file directly.
In `@sdk/public-surface.json`:
- Around line 226-258: Consolidate the consecutive 2026.7.28 breaking-change
entries in the generated ledger so the PmUpdateManyActionOptions signatures are
included in the existing changes array with the other signatures sharing the
same reason and package version. Update the generator or grouping logic that
produces these entries, rather than manually editing sdk/public-surface.json,
while preserving all listed signatures and metadata.
In `@src/cli/commands/close.ts`:
- Around line 667-673: Update mutateCloseMetadata() in both metadata-update
branches so completed_at is assigned and included in changedFields only when
options.completedAt is provided or the existing completed_at field is absent;
otherwise preserve the stored timestamp during force re-closes. Mirror the
explicit completion guard used in update.ts while leaving status and closed_at
behavior unchanged.
In `@src/cli/register-mutation.ts`:
- Around line 2536-2539: Add the `--completed-at <value>` option to the
`close-many` command alongside its existing options, then pass the parsed value
through `runCloseManyAction` into each underlying `runClose` invocation so bulk
closures preserve the actual completion timestamp.
In `@src/sdk/lifecycle-completion.ts`:
- Around line 76-104: Update planCompletedAtBackfill and its
hasTerminalTransition detection to require evidence that the status immediately
before the detected terminal transition was non-terminal. Derive the predecessor
from the earlier entry state when available, and skip terminal-to-terminal
rewrites so completed_at is not backfilled from their timestamps; preserve
existing handling for genuine non-terminal-to-terminal transitions.
In `@src/sdk/query/list.ts`:
- Line 1960: Update the successful indexed-page path in tryLoadIndexedListPage
to validate options.tag against tags on the items returned by
queryItemMetadataIndex, using runtime.typeRegistry.type_to_folder as needed.
Invoke appendUnknownTagWarning with the indexed results before constructing the
response so unknown_tags warnings are included in both compact and verbose
result paths, while preserving existing warnings behavior.
---
Outside diff comments:
In `@src/cli/commands/update.ts`:
- Around line 1876-1900: Update the pre-update call in the surrounding close
helper to clear completedAt alongside status, closeReason, and message before
spreading context.options into runUpdate. Keep completedAt available for the
subsequent runClose path, while ensuring the recursive preUpdate does not apply
it during non-terminal updates.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository UI (base), Organization UI (inherited)
Review profile: ASSERTIVE
Plan: Pro Plus
Run ID: 30587d22-774c-49e7-86bf-efcde2210628
⛔ Files ignored due to path filters (1)
pnpm-lock.yamlis excluded by!**/pnpm-lock.yaml
📒 Files selected for processing (64)
.agents/pm/chores/pm-77bmeu.toon.agents/pm/extensions/.managed-extensions.json.agents/pm/history/pm-5ecnar.jsonl.agents/pm/history/pm-77bmeu.jsonl.agents/pm/history/pm-b0twiy.jsonl.agents/pm/history/pm-b1zsk9.jsonl.agents/pm/history/pm-bwnclq.jsonl.agents/pm/history/pm-cragzs.jsonl.agents/pm/history/pm-r2suqb.jsonl.agents/pm/issues/pm-5ecnar.toon.agents/pm/issues/pm-b0twiy.toon.agents/pm/issues/pm-b1zsk9.toon.agents/pm/issues/pm-bwnclq.toon.agents/pm/issues/pm-cragzs.toon.agents/pm/issues/pm-r2suqb.toonCHANGELOG.mddocs/COMMANDS.mddocs/CONFIGURATION.mddocs/SDK.mdeslint-suppressions.jsonpackage.jsonscripts/generate-release-notes.mjsscripts/release/static-quality-gate.mtssdk/public-surface.jsonsrc/cli/commands/activity.tssrc/cli/commands/close.tssrc/cli/commands/context.tssrc/cli/commands/copy.tssrc/cli/commands/create.tssrc/cli/commands/update.tssrc/cli/register-list-query.tssrc/cli/register-mutation.tssrc/cli/register-setup.tssrc/cli/registration-helpers.tssrc/core/item/item-format.tssrc/core/schema/fields-file.tssrc/core/shared/constants.tssrc/sdk/cli-contracts/commander-mutation-options.tssrc/sdk/cli-contracts/flag-contracts.tssrc/sdk/cli-contracts/tool-option-contracts.tssrc/sdk/cli-contracts/tool-parameter-tables.tssrc/sdk/cli-contracts/tool-schema.tssrc/sdk/cli-contracts/typed-action-inputs.tssrc/sdk/config.tssrc/sdk/index.tssrc/sdk/lifecycle-completion.tssrc/sdk/query/list.tssrc/sdk/runtime-input.tssrc/sdk/structured-mutations.tssrc/sdk/workspace-memory.tssrc/types.tstests/fixtures/contracts/full.jsontests/integration/mcp-handshake.spec.tstests/integration/release-automation-contract.spec.tstests/integration/release-readiness-runtime.spec.tstests/unit/commands/close-command.spec.tstests/unit/commands/config-key-aliases-search.spec.tstests/unit/commands/context-command.spec.tstests/unit/commands/history-activity-command.spec.tstests/unit/commands/list-command.spec.tstests/unit/commands/update-command.spec.tstests/unit/core/item/item-format-validation.spec.tstests/unit/sdk/lifecycle-completion.spec.tstests/unit/sdk/workspace-memory.spec.ts
💤 Files with no reviewable changes (1)
- eslint-suppressions.json
|
Gemini sunset notice acknowledged: no review evidence was available from that integration, so it was treated as non-actionable rather than as a successful review. |
|
CodeRabbit rate-limit notice acknowledged: the subsequent full review completed successfully and its seven inline findings have each received a usefulness reaction, an inline disposition, and thread resolution. |
|
CodeRabbit invocation acknowledgement noted; the completed review was evaluated against exact head rather than treating the start acknowledgement as review completion. |
|
CodSpeed report acknowledged as useful: the measured 2.43% improvement is consistent with the bundle’s context-efficiency goal, with no performance regression to remediate. |
|
Sourcery reviewer guide acknowledged as useful orientation. Its separate weekly-limit review produced no actionable source finding and is recorded as unavailable rather than green review evidence. |
|
Greptile summary acknowledged as useful and accurate. Its completed exact-head review reported no blocking findings; the lifecycle, context, filtering, configuration, and quality scope matches the delivered bundle. |
|
Codecov result acknowledged as useful: all modified coverable lines are covered and the final local full-suite rerun confirms 100% statements, branches, functions, and lines across 6,497 tests. |
|
Sourcery rate-limit review disposition: non-actionable because no code assessment was produced. No source change is attributed to it; other exact-head reviewers and all repository gates remain authoritative. |
|
CodeRabbit review disposition: useful overall. Four lifecycle findings were accepted and fixed, two suggestions were verified as intentional/non-applicable, and the PM-evidence concern was answered with the sandbox-safety rationale. Every inline comment is reacted to, answered, and resolved. |
Apply exact-head review feedback by preserving governed completion timestamps on force re-close, forwarding completed-at through close-many CLI/SDK/MCP contracts, and requiring genuine transition history for backfill.\n\nClarify the canonical PM contract, regenerate public surfaces and changelog output, and verify the review follow-up at exact 100/100/100/100 coverage.
|
@greptileai review\n\n@coderabbitai full review\n\nReview follow-up head: 575065c. Four accepted lifecycle findings are implemented; two non-applicable findings have inline evidence. Please review the complete updated diff. |
|
✅ Action performedFull review finished. Your included review limit is currently reached under our Fair Usage Limits Policy. This review may still proceed through usage-based billing if eligible. Your next included review will be available in 20 minutes. |
|
Second-round CodeRabbit invocation acknowledged as useful. The seven automated rate-limit replies and their empty review envelopes were each down-voted as transport-only noise; they add no finding and do not change the already-recorded per-thread dispositions. All seven review threads remain resolved, and the updated exact head completed the full check/review watcher with no new actionable thread. |
Outcome
This wide SDK/CLI bundle advances
project management = context managementacross lifecycle provenance, storage, contracts, agent-facing context, mutation safety, dependency hygiene, and release generation.Delivered
completed_atlifecycle timestamps plus SDK provenance and history-evidence backfill planning7d/1wmean look back), adds composable case-insensitive tag filters with unknown-tag diagnostics, and aligns--allow-missing-parentacross CLI/SDK/MCPpm-changelog@2026.7.29; upstream support shipped in Prefer actual completion time for release-window bucketing pm-changelog#107PM lineage
Verification
pnpm test:coverage— 6,497 tests, 100% statements / branches / functions / linespnpm lint,pnpm typecheck,pnpm contracts:check,pnpm quality:docs-skills,pnpm quality:context-evalpnpm security:scan,pnpm audit --prod,pnpm dogfood:package-first,pnpm smoke:external-packages,pnpm smoke:npxpm validate --check-resolution --check-history-drift— zero history drift across 2,183 items (291 pre-existing historical resolution warnings)pm health --check-only— telemetry enabled, redacted, draining, and successfully flushedSummary by cubic
Adds lifecycle-aware completion provenance and richer context primitives to the SDK and CLI to improve reporting accuracy and agent actionability. Reports, release notes, and automation now prefer actual completion time and expose blockers inline, while query UX and governance flags are more consistent.
New Features
completed_atseparate fromclosed_at; stamped on close/create-closed, preserved on copy;pm close/pm close-many/pm updateaccept--completed-at(ISO or relative). SDK addsresolveCompletionTimestampand evidence-onlyplanCompletedAtBackfill; release notes prefercompleted_at; force re-close preserves completion unless overridden.blockedandblocker_idsso agents see actionable blockers without a second command.--fromaccepts bare relative windows like7d/1w; list--tagis repeatable and CSV-aware, case-insensitive, and warns on unknown tags.--allow-missing-parent(parity with create). Config help/results surface mutation-guard settings with canonical dashed keys and typed metadata (canonical_key, choices, min/max).Dependencies
@types/nodeandjscpdto latest compatible patches; keep incompatible majors deferred.pm-changelog@2026.7.29.Written for commit 575065c. Summary will update on new commits.
Summary by Sourcery
Track actual completion timestamps across the SDK and CLI, enrich context and list queries with blocker and tag metadata, and tighten governance and configuration visibility, while keeping dependencies and quality gates up to date.
New Features:
Bug Fixes:
Enhancements:
Build: