Consolidate the native migration roadmap and simplified cache design
This commit is contained in:
@@ -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
|
||||
|
||||
|
||||
@@ -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
Reference in New Issue
Block a user