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

View File

@@ -2,20 +2,17 @@
## Purpose And Status
The original decisions in items 1–6 were incorporated into the
[PromptKit-native architecture migration roadmap](promptkit.md). That roadmap
is the implementation plan and owns current unresolved choices, sequencing,
acceptance criteria, and implementation status.
The decisions in items 1–6, the subsequent CommandKit discussion, and the
simplified cache/output designs are incorporated into the
[master native migration roadmap](promptkit.md). It owns the selected target,
unresolved choices, sequencing, acceptance criteria, and implementation status.
The subsequent CommandKit discussion replaces item 5's checkpoint proposal with
the accepted-artifact cache below and clarifies PromptKit's execution ownership.
Those updates have not yet been incorporated into the master roadmap. They
supersede its earlier checkpoint matching and provenance requirements. The
[CommandKit notepad](commandkit-migration-discussion.md) records the related CLI
and debug decisions. Its [item 4](commandkit-migration-discussion.md#4-reports-machine-output-and-outcomes)
selects artifact files and a small native completion report, superseding earlier
mandatory manifest, receipt, and durable-execution-record proposals here and in
the master roadmap.
The [CommandKit discussion record](commandkit-migration-discussion.md) retains
the related CLI, preflight, output, debug, and migration rationale. The master
roadmap replaces earlier checkpoint matching/provenance proposals with the
accepted-artifact cache and retires mandatory manifests, extensive receipts,
and durable execution ledgers. The upstream message-content hash remains pending;
incorporation does not claim it is already available or implemented.
This document retains the discussion, rationale, and evidence, including item 7's
completed Audita comparison. Item-level questions and follow-ups below record
@@ -475,7 +472,7 @@ This is a concrete upstream hash requirement. The reviewed PromptKit v0.23.3
hashing the entire `PreparedRun` would include volatile execution metadata.
Neither is the selected key. Expose the content hash through native preparation
rather than implementing another message-hashing policy in Notarius. Confirm
the supplying upstream API/release during roadmap incorporation; do not claim
the supplying upstream API/release before cache implementation; do not claim
the proposed field already exists or silently substitute a broader fingerprint.
### Compute Early, Store After Acceptance
@@ -548,10 +545,10 @@ compatibility requirement. Select straightforward cache reuse/bypass/refresh
controls and legacy-file handling during implementation planning; do not infer
new flag spellings or a migration framework from this decision.
**Follow-up:** Incorporate this design and the upstream hash requirement into the
master roadmap. Verify that a downstream failure leaves earlier accepted
artifacts reusable, corrected answers are stored under the initial hash, changed
messages miss, settings-only changes can hit, and a hit makes no model calls or
**Follow-up:** The master roadmap now includes this design and the upstream hash
requirement. During implementation, verify that a downstream failure leaves
earlier accepted artifacts reusable, corrected answers are stored under the
initial hash, changed messages miss, settings-only changes can hit, and a hit makes no model calls or
new semantic-validation claims. Keep output/report contract decisions separate.
## 6. Inspection And Execution Bookkeeping
@@ -670,7 +667,7 @@ Evidence: [current inspection wrapper](../../internal/framework/llm/promptkit_in
Select application scope and observer/group enrollment for the agreed diagnostics.
Implement the selected completion report and retire superseded manifest, receipt,
and execution-ledger machinery. Coordinate command migration and debug capture
with the CommandKit notepad and master roadmap reconciliation. The core
with the incorporated design in the master roadmap. The core
bookkeeping ownership change needs no new PromptKit capability; any remaining
upstream request should identify a concrete unmet requirement.

File diff suppressed because it is too large Load Diff