Consolidate the native migration roadmap and simplified cache design

This commit is contained in:
2026-11-20 03:42:51 +00:00
parent c03d0bb987
commit 2eaea2b1fd
3 changed files with 653 additions and 385 deletions

View File

@@ -2,49 +2,29 @@
## Purpose And Status
Working notepad for the CommandKit decisions that will be incorporated into the
[master PromptKit-native migration roadmap](promptkit.md). Record the proposal,
open questions, evidence, and decisions here as we discuss them.
Discussion record for the decisions incorporated into the
[master native migration roadmap](promptkit.md). That roadmap now owns the
selected design, remaining choices, implementation phases, removal inventory,
and acceptance criteria. This notepad retains discussion detail and evidence;
it is not a second implementation checklist.
**Direction agreed:** Make a full cutover to a CommandKit-native application as
part of the same migration as modern PromptKit, in separate, reviewable
implementation steps. Adopt CommandKit's public-facing conventions and
recommendations to the fullest extent. Bring its design decisions forward and
complete adoption before the overall cutover.
**Direction agreed and incorporated:** Make a full cutover to native CommandKit,
ConfigKit, and PromptKit workflows in one coordinated migration. Adopt upstream
public conventions fully. CLI backward compatibility is a non-goal; provide
release migration guidance instead.
The master roadmap currently places CommandKit in a subsequent Phase 7 and leaves
its details in U10. That sequencing has not yet been revised. Item 6 selects how
to incorporate the agreed decisions into its dependency baseline, implementation
phases, removal inventory, and acceptance criteria while preserving remaining
choices explicitly. No application or dependency changes have been implemented
through this discussion.
All six items below are incorporated, including the accepted-artifact cache,
small completion report and native text template, debug inventory/depth,
`/tmp/notarius-debug` default, `latest`, and explicit-empty directory behavior.
No application or dependency changes have been implemented through this
planning work. Implementation remains pending.
Item 1 selects the dependency versions and standard capabilities, including
PromptKit v0.23.3 in place of the master roadmap's initial v0.23.2 target.
Item 2 selects the application command structure and input conventions. Item 3
selects native composition, shared loaders, and application preflight. Item 4
selects artifact-first output, a small native completion report, and outcomes.
Item 5 selects conditional debug capture through the shared `--debug` flag,
native diagnostics, and a run/operation bundle with a `latest` symlink. Its
capture inventory, depth, and
explicit-empty directory behavior are resolved below. Item 6 selects verification,
migration guidance, and incorporation into the master roadmap; that incorporation
is still pending.
The cache follow-up in item 4 replaces the earlier checkpoint design with an
accepted-artifact cache keyed by initial message content. The output/report
direction is settled: deliver artifacts as files and render a small structured
completion value through CommandKit, with a native text template for ordinary
human output. Detailed diagnostics belong in optional debug capture. Function
signatures, debug filenames other than `latest`, and similar implementation
details do not reopen the selected architecture. Broader PromptKit choices
remain with the master roadmap.
The PromptKit ownership direction remains in force. The revised
[cache decision](promptkit-architecture-discussion.md#5-accepted-artifact-cache)
supersedes earlier checkpoint matching and provenance requirements. Master-roadmap
incorporation is pending, including U1 (the upstream content-hash capability),
U8 (cache migration), U9 (records/reporting), and U10 (CommandKit adoption).
The roadmap resolves U10's CommandKit scope, tracks the pending upstream
message-content hash in U1, replaces U8's checkpoint design, and narrows U9 to
implementation details within the agreed output/debug contracts. Schema handling,
role-specific correction/fallback policy, worker defaults, and concrete cache
controls/transition remain visible there. Item-level directions below record the
accepted design; the roadmap is the authority for sequencing and current status.
## Agreed Proposal
@@ -129,8 +109,8 @@ Two application needs already identified for deliberate treatment are:
4. Complete command and reporting migration before final end-to-end verification
and migration documentation.
Item 6 selects the replacement phase sequence for incorporation into the master
roadmap. The master roadmap has not yet been updated.
Item 6 records the incorporation decision. The master roadmap now owns the
resulting six-phase sequence; implementation is pending.
## 1. Adoption Scope And Dependency Baseline
@@ -201,11 +181,10 @@ The standard capability suite needs no identified upstream addition. The later
cache decision does require a native message-content hash, which is not the
existing v0.23.3 rendered-prompt hash. Confirm the supplying API/release before
implementing cache lookup; the version table remains the reviewed baseline, not
a claim that the new hash is already available. On roadmap
reconciliation, incorporate these versions into U1, replace U10's open standard
capability selection with this decision, and incorporate the application wiring
and presentation decisions from items 2–5. Retire superseded durable-record
requirements as directed by item 6.
a claim that the new hash is already available. The master roadmap now records
this baseline, the pending upstream requirement, the resolved CommandKit scope,
and the application wiring/presentation decisions. Superseded durable-record
requirements have been removed from that plan.
## 2. Native Command Surface And Inputs
@@ -352,8 +331,8 @@ Application handlers still validate meaningful input combinations and translate
typed inputs into pipeline selections. Native `--debug` supplies reporting
behavior and conditional artifact capture as selected in item 5.
Items 3–4 select loader behavior, the small completion report, and native outcome
presentation. Reconcile U9 with these decisions rather than expanding durable
metadata.
presentation. The master roadmap limits U9 to implementation details within
these decisions.
Evidence: [CommandKit command/input conventions](../../../commandkit/docs/cli.md#registered-command-syntax),
[reusable PromptKit flags](../../../commandkit/docs/consumers/guide.md#request-builders-and-loading),
@@ -570,7 +549,7 @@ model execution or a claim of validation under a changed policy.
Concrete cache flags and legacy-checkpoint handling remain implementation-planning
choices. The output/report discussion must not reintroduce cache metadata solely
to populate a report. The master roadmap still needs this replacement policy.
to populate a report. The master roadmap now incorporates this replacement policy.
### Artifacts Are The Deliverable
@@ -760,8 +739,8 @@ The current [run-result contract](../integrations/run-result.md) and
[CLI failure mapping](../internal/cli.md#failure-mapping-and-terminal-reporting)
document migration impact. Item 6 of the
[PromptKit discussion record](promptkit-architecture-discussion.md#6-inspection-and-execution-bookkeeping)
retains the native bookkeeping boundary. Reconcile U9 with this simpler contract,
including retirement of superseded durable-record requirements.
retains the native bookkeeping boundary. The master roadmap now incorporates
this contract and retires superseded durable-record requirements.
## 5. Debug Capture And Optional Diagnostics
@@ -1137,8 +1116,8 @@ The current [debug lifecycle](../internal/state.md#debug-bundles) and
**Discussion / decision:** Agreed. Complete one coordinated native cutover, with
CommandKit composition introduced early, verification focused on Notarius's
integration and domain responsibilities, and practical release migration guidance.
Incorporate these decisions into the existing master roadmap; another replacement
document is unnecessary. Implementation and master-roadmap incorporation are pending.
These decisions are incorporated into the existing master roadmap; no replacement
document was needed. Implementation is pending.
### Focused Verification Of Application Behavior
@@ -1225,39 +1204,22 @@ Keep future behavior in roadmap documents until implemented.
### Incorporation Into The Master Roadmap
Replace the deferred CommandKit Phase 7 with adoption throughout the existing
master roadmap. Use this phase sequence:
**Completed:** The [master roadmap](promptkit.md#implementation-sequence) now
integrates CommandKit throughout six phases, beginning with native composition
and shared loaders, proving a representative pipeline through the new CLI, and
finishing cache/output/capture integration before final verification. The old
separate Phase 7 is retired.
1. Establish the agreed dependency baseline and remaining contract decisions.
2. Build native application composition, shared loaders, standard commands, and
the dedicated preflight package alongside native source assembly.
3. Prove a representative native pipeline through the actual command surface,
including reporting and useful debug capture.
4. Migrate remaining roles and remove the adapter, scheduler, retry machinery,
and custom CLI infrastructure.
5. Complete cache migration, the selected output/report contract, and capture behavior.
6. Verify the assembled application and finish migration documentation.
Its dependency baseline includes the selected versions and pending upstream hash
request. U10 is resolved; U8 now concerns cache operation/transition, and U9
concerns implementation details within the selected output/debug contracts.
Earlier receipt/manifest inventories are retired. Remaining schema, correction,
fallback, worker, and cache-transition choices are explicit in its
[unresolved-choice table](promptkit.md#unresolved-choices).
Each phase delivers a reviewable result with appropriate verification. Tests and
documentation proceed throughout; the final phase checks integration and
completeness. The phases do not require separate releases or an intermediate
compatibility framework.
Resolve U1's dependency baseline and U10's CommandKit scope from items 1–4. Narrow
U9 to item 4's selected artifact-first output/completion contract and item 5's
debug implementation details within the resolved inventory, depth, and controls.
Retire earlier receipt/manifest field inventories rather than treating them as
unresolved requirements to recreate.
Update U1 for the upstream message-content hash and replace U8's checkpoint
identity/provenance plan with the accepted-artifact cache decision.
Reconcile removal inventory and acceptance criteria, including old
inspection-command and machine-output compatibility assumptions. Preserve
unresolved schema handling, role-specific retry/fallback policy, worker defaults,
checkpoint transition choices, and other concrete choices until actually settled.
Once incorporated, the master roadmap owns implementation sequencing and status;
both migration notepads remain discussion records. Do not maintain competing
implementation checklists in the notepads.
The master roadmap owns sequencing and implementation status. This notepad and
the PromptKit discussion remain discussion records, not competing implementation
checklists.
### Completion Checks