Merge pull request #727 from AssetOverflow/docs/proposal-artifact-substrate-v1
docs(workbench): define proposal artifact substrate v1
This commit is contained in:
Shay
GitHub
commit
eeba99e8af
4 changed files with 1789 additions and 36 deletions
|
|
@ -84,6 +84,48 @@ Defines:
|
|||
|
||||
---
|
||||
|
||||
## Proposal Artifact Substrate
|
||||
|
||||
- `proposal-artifact-substrate-v1.md`
|
||||
|
||||
Defines:
|
||||
|
||||
- the universal proposal artifact envelope
|
||||
- subject-specific proposal adapters
|
||||
- proposal-only vs ratification-enabled capability levels
|
||||
- safety, validation, affected-artifact, and checksum-impact report shapes
|
||||
- the migration path for math, cognition, CORE-Logos, packs, and future modalities
|
||||
|
||||
---
|
||||
|
||||
## Wave M Consolidation / B3.5
|
||||
|
||||
- `wave-m-consolidation-b3.5.md`
|
||||
|
||||
Defines:
|
||||
|
||||
- the route-registry unification plan
|
||||
- calibration as a first-class evidence subject
|
||||
- the B4 leeway-feasibility gate
|
||||
- the UI/UX guide requirement
|
||||
- the Phase A residue ledger before further complexity
|
||||
|
||||
---
|
||||
|
||||
## CORE-Logos Studio
|
||||
|
||||
- `core-logos-studio-plan.md`
|
||||
|
||||
Defines:
|
||||
|
||||
- the `/logos` Studio route concept
|
||||
- pack identity, lexicon, glosses, morphology, alignment, holonomy, safety, and patch-forge tabs
|
||||
- CORE-Logos evidence subjects
|
||||
- read-only readers and proposal-only draft endpoint direction
|
||||
- the handler-family admission sequence for future ratification
|
||||
|
||||
---
|
||||
|
||||
## UI Component Map
|
||||
|
||||
- `ui-component-map.md`
|
||||
|
|
@ -218,39 +260,3 @@ The correct operator reaction to the workbench should be:
|
|||
not:
|
||||
|
||||
> “Cool chatbot.”
|
||||
|
||||
---
|
||||
|
||||
# W-027 Frontend Shell Runbook
|
||||
|
||||
Start the full local workbench (API + frontend):
|
||||
|
||||
```bash
|
||||
# Terminal 1 — API
|
||||
uv run core workbench api # http://127.0.0.1:8765
|
||||
|
||||
# Terminal 2 — Frontend
|
||||
cd workbench-ui
|
||||
pnpm install
|
||||
pnpm dev # http://127.0.0.1:5173
|
||||
```
|
||||
|
||||
Use a custom API URL:
|
||||
|
||||
```bash
|
||||
VITE_WORKBENCH_API_URL=http://127.0.0.1:9000 pnpm dev
|
||||
```
|
||||
|
||||
View the Branch 1 design baseline:
|
||||
|
||||
```bash
|
||||
cd workbench-ui
|
||||
pnpm preview # Navigate to /preview
|
||||
```
|
||||
|
||||
Detect TypeScript ↔ Python schema drift:
|
||||
|
||||
```bash
|
||||
uv run python scripts/dump-api-schemas.py
|
||||
cd workbench-ui && pnpm test
|
||||
```
|
||||
|
|
|
|||
655
docs/workbench/core-logos-studio-plan.md
Normal file
655
docs/workbench/core-logos-studio-plan.md
Normal file
|
|
@ -0,0 +1,655 @@
|
|||
# CORE-Logos Studio — UI/UX and Engineering Plan
|
||||
|
||||
**Status:** Proposed architecture / design plan
|
||||
**Scope:** Workbench CORE-Logos / packs / language-manifold engineering surface
|
||||
**Branch:** `docs/proposal-artifact-substrate-v1`
|
||||
**No code changes in this document.**
|
||||
|
||||
---
|
||||
|
||||
## Purpose
|
||||
|
||||
CORE-Logos must become more than a pack manifest viewer.
|
||||
|
||||
The current Workbench Packs route gives operators useful identity/checksum visibility, but it does not yet provide an active engineering environment for viewing, developing, adjusting, linking, inspecting, analyzing, and safety-checking CORE-Logos pack contents.
|
||||
|
||||
This plan defines the next product shape: **CORE-Logos Studio**.
|
||||
|
||||
The Studio is the place where an operator can understand and evolve the linguistic substrate through reviewable proposal artifacts, without violating CORE's proposal-before-mutation doctrine.
|
||||
|
||||
---
|
||||
|
||||
## Product thesis
|
||||
|
||||
CORE-Logos is not a localization layer, dataset browser, translation table, or decorative theological page.
|
||||
|
||||
It is the Workbench surface for the language/manifold substrate:
|
||||
|
||||
```text
|
||||
English operational articulation
|
||||
Hebrew depth-root compression
|
||||
Koine Greek depth-relation precision
|
||||
cross-language alignment as resonance
|
||||
holonomy as proof that meaning survived the path
|
||||
```
|
||||
|
||||
The UI should make this role legible and usable.
|
||||
|
||||
---
|
||||
|
||||
## Governing doctrine
|
||||
|
||||
This plan inherits:
|
||||
|
||||
- ADR-0015: language packs are deterministic, checksummed, compiled linguistic manifolds.
|
||||
- ADR-0160: Workbench is audit-native; proposal before mutation.
|
||||
- ADR-0162: design is structural truth, not dashboard theater.
|
||||
- ADR-0173: Workbench may only apply through admitted handlers.
|
||||
- Proposal Artifact Substrate v1: CORE-Logos changes begin as `proposal_only` artifacts.
|
||||
- `CLAUDE.md`: pack mutation is proposal-only until reviewed; filesystem/pack changes require explicit trust boundaries.
|
||||
|
||||
---
|
||||
|
||||
## Current state
|
||||
|
||||
Current pack UI is mostly:
|
||||
|
||||
```text
|
||||
pack list
|
||||
→ manifest detail
|
||||
→ checksum metadata
|
||||
→ raw JSON
|
||||
→ pack evidence subject
|
||||
```
|
||||
|
||||
That is necessary but not sufficient.
|
||||
|
||||
The full CORE-Logos engineering surface needs:
|
||||
|
||||
```text
|
||||
manifest
|
||||
→ lexicon
|
||||
→ glosses
|
||||
→ morphology
|
||||
→ alignment edges
|
||||
→ frames/compositions
|
||||
→ holonomy cases
|
||||
→ safety report
|
||||
→ proposal artifact forge
|
||||
→ ratification corridor only after handlers are admitted
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Route shape
|
||||
|
||||
Add a dedicated route:
|
||||
|
||||
```text
|
||||
/logos
|
||||
```
|
||||
|
||||
UI label:
|
||||
|
||||
```text
|
||||
CORE-Logos
|
||||
```
|
||||
|
||||
or:
|
||||
|
||||
```text
|
||||
CORE-Logos Studio
|
||||
```
|
||||
|
||||
The existing `/packs` route can remain the broader inventory view. `/logos` is the active engineering studio for language-manifold packs.
|
||||
|
||||
---
|
||||
|
||||
## Layout
|
||||
|
||||
Recommended page layout:
|
||||
|
||||
```text
|
||||
+-----------------------------------------------------------------------+
|
||||
| TopBar / Wrong=0 / Runtime / Command Palette |
|
||||
+-------------+-------------------------------------------+-------------+
|
||||
| Pack | Studio Workspace | Evidence |
|
||||
| Universe | | Inspector |
|
||||
| | Overview / Identity / Lexicon / ... | |
|
||||
+-------------+-------------------------------------------+-------------+
|
||||
| Safety + proposal status strip |
|
||||
+-----------------------------------------------------------------------+
|
||||
```
|
||||
|
||||
### Left rail — Pack Universe
|
||||
|
||||
Shows:
|
||||
|
||||
- English operational/base packs
|
||||
- Hebrew depth-root packs
|
||||
- Koine Greek depth-relation packs
|
||||
- math/cognition packs if relevant
|
||||
- runtime packs if relevant
|
||||
- safety verdict
|
||||
- count badges for entries/edges/cases
|
||||
|
||||
### Center — Studio Workspace
|
||||
|
||||
Tabbed engineering surface for selected pack.
|
||||
|
||||
### Right inspector — Evidence projection
|
||||
|
||||
Selection publishes evidence subjects for packs, entries, morphology records, alignment edges, holonomy cases, and proposal drafts.
|
||||
|
||||
### Bottom strip — Safety/proposal status
|
||||
|
||||
Persistent summary:
|
||||
|
||||
```text
|
||||
selected pack · checksum status · gate/OOV status · proposal mode · no mutation / proposal-only / ratification-enabled
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Tabs
|
||||
|
||||
### 1. Overview
|
||||
|
||||
Purpose: explain what role this pack plays.
|
||||
|
||||
Show:
|
||||
|
||||
- pack role
|
||||
- language
|
||||
- script
|
||||
- version
|
||||
- determinism class
|
||||
- gate state
|
||||
- OOV policy
|
||||
- entry counts
|
||||
- alignment edge counts
|
||||
- holonomy case counts
|
||||
- safety verdict
|
||||
|
||||
The Overview should make the tri-language model felt:
|
||||
|
||||
```text
|
||||
English → operational articulation
|
||||
Hebrew → depth-root compression
|
||||
Koine Greek → depth-relation precision
|
||||
```
|
||||
|
||||
### 2. Identity
|
||||
|
||||
Purpose: show the pack passport.
|
||||
|
||||
Show:
|
||||
|
||||
- manifest
|
||||
- source manifest
|
||||
- checksum fields
|
||||
- declared files
|
||||
- domain contract
|
||||
- eval lanes
|
||||
- reviewers
|
||||
- known gaps
|
||||
- source digests
|
||||
|
||||
Raw manifest remains available through StableJsonViewer.
|
||||
|
||||
### 3. Lexicon
|
||||
|
||||
Purpose: engineering view of lexical entries.
|
||||
|
||||
Show columns:
|
||||
|
||||
- entry ID
|
||||
- surface
|
||||
- lemma
|
||||
- language
|
||||
- POS
|
||||
- semantic domains
|
||||
- morphology ID
|
||||
- provenance IDs
|
||||
- epistemic status
|
||||
- safety flags
|
||||
|
||||
Required interactions:
|
||||
|
||||
- search surface/lemma/domain
|
||||
- filter by epistemic status
|
||||
- filter dangling morphology links
|
||||
- group by semantic domain
|
||||
- select entry as evidence subject
|
||||
- copy entry pointer
|
||||
|
||||
No direct edit/save.
|
||||
|
||||
### 4. Glosses
|
||||
|
||||
Purpose: view and analyze gloss surfaces separately from lexical identity.
|
||||
|
||||
Show:
|
||||
|
||||
- gloss ID
|
||||
- entry ID / lemma link
|
||||
- gloss text
|
||||
- source/provenance
|
||||
- status
|
||||
- checksum coverage
|
||||
|
||||
Gloss changes are a candidate for the first low-risk handler family, but only after handler admission.
|
||||
|
||||
### 5. Morphology
|
||||
|
||||
Purpose: reveal ordered operator composition.
|
||||
|
||||
For Hebrew:
|
||||
|
||||
```text
|
||||
root → stem → prefix/suffix/inflection chain
|
||||
```
|
||||
|
||||
For Greek:
|
||||
|
||||
```text
|
||||
lemma → case/aspect/voice/mood/clause role
|
||||
```
|
||||
|
||||
Show:
|
||||
|
||||
- morphology entries
|
||||
- linked lexicon entries
|
||||
- root clusters
|
||||
- stem/operator chain
|
||||
- dangling links
|
||||
- order-sensitive rendering
|
||||
|
||||
Selection publishes `logos_morphology` evidence subject.
|
||||
|
||||
### 6. Alignment
|
||||
|
||||
Purpose: cross-language resonance graph.
|
||||
|
||||
Show:
|
||||
|
||||
- source ID
|
||||
- target ID
|
||||
- relation
|
||||
- weight
|
||||
- evidence IDs
|
||||
- target pack
|
||||
- invalid target warnings
|
||||
|
||||
Use deterministic layout only. No force-directed movement.
|
||||
|
||||
Questions this tab must answer:
|
||||
|
||||
```text
|
||||
What does this Hebrew root align with?
|
||||
What Greek relation carries the same structural pressure?
|
||||
What English articulation surface receives it?
|
||||
What evidence supports the edge?
|
||||
```
|
||||
|
||||
Selection publishes `logos_alignment_edge` evidence subject.
|
||||
|
||||
### 7. Holonomy
|
||||
|
||||
Purpose: proof that meaning survived the path.
|
||||
|
||||
Show holonomy cases as proof cards:
|
||||
|
||||
```text
|
||||
Hebrew path
|
||||
↘
|
||||
resonance / distinction proof
|
||||
↗
|
||||
Greek path English path
|
||||
```
|
||||
|
||||
Each case shows:
|
||||
|
||||
- source refs
|
||||
- pack IDs
|
||||
- expected relation
|
||||
- negative refs
|
||||
- tolerance
|
||||
- actual proof status if computed
|
||||
- missing proof evidence if absent
|
||||
|
||||
No success state may be rendered if proof status is absent.
|
||||
|
||||
Selection publishes `logos_holonomy_case` evidence subject.
|
||||
|
||||
### 8. Safety
|
||||
|
||||
Purpose: make admissibility visible before any change.
|
||||
|
||||
Checks:
|
||||
|
||||
- safe pack ID
|
||||
- manifest present
|
||||
- declared files present
|
||||
- checksum matches
|
||||
- gloss/frame/composition checksum matches when declared
|
||||
- OOV policy valid for role
|
||||
- gate policy valid
|
||||
- no dangling morphology links
|
||||
- no invalid alignment targets
|
||||
- no missing holonomy refs
|
||||
- epistemic status counts
|
||||
- speculative entries
|
||||
- contested/falsified entries
|
||||
- known gaps
|
||||
|
||||
Safety verdicts:
|
||||
|
||||
```text
|
||||
clear
|
||||
warning
|
||||
failed
|
||||
unknown
|
||||
```
|
||||
|
||||
Unknown is not clear. Warning is not clear. Failed blocks handler routing.
|
||||
|
||||
### 9. Patch Forge
|
||||
|
||||
Purpose: active engineering without unsafe mutation.
|
||||
|
||||
Supported proposal drafts:
|
||||
|
||||
```text
|
||||
lexicon_add
|
||||
lexicon_update
|
||||
lexicon_remove
|
||||
gloss_add
|
||||
gloss_update
|
||||
morphology_add
|
||||
morphology_update
|
||||
alignment_edge_add
|
||||
alignment_edge_update
|
||||
holonomy_case_add
|
||||
holonomy_case_update
|
||||
frame_add
|
||||
composition_add
|
||||
```
|
||||
|
||||
Every draft produces a `ProposalArtifact` with:
|
||||
|
||||
- proposed payload
|
||||
- evidence pointers
|
||||
- patch preview
|
||||
- safety report
|
||||
- checksum impact prediction
|
||||
- suggested CLI/PR instructions
|
||||
- `capability_level = proposal_only`
|
||||
|
||||
The button label must be:
|
||||
|
||||
```text
|
||||
Draft proposal
|
||||
```
|
||||
|
||||
Not:
|
||||
|
||||
```text
|
||||
Save
|
||||
Apply
|
||||
Commit
|
||||
```
|
||||
|
||||
### 10. Ratification Corridor
|
||||
|
||||
Purpose: future handler-enabled path.
|
||||
|
||||
Initially absent for CORE-Logos proposal-only drafts.
|
||||
|
||||
When a handler family is admitted, the corridor may appear only for proposals whose:
|
||||
|
||||
- handler is admitted,
|
||||
- preconditions pass,
|
||||
- safety report is clear or explicitly allowed by handler policy,
|
||||
- target files/checksums are known,
|
||||
- audit event sink is available,
|
||||
- replay/pack verification boundary is named.
|
||||
|
||||
---
|
||||
|
||||
## Evidence subjects
|
||||
|
||||
Add subjects through the Workbench evidence model:
|
||||
|
||||
```text
|
||||
logos_pack
|
||||
logos_entry
|
||||
logos_gloss
|
||||
logos_morphology
|
||||
logos_alignment_edge
|
||||
logos_holonomy_case
|
||||
logos_patch_proposal
|
||||
```
|
||||
|
||||
Each subject must have:
|
||||
|
||||
- stable ID
|
||||
- route/address grammar
|
||||
- right-inspector projection
|
||||
- raw JSON access
|
||||
- copyable pointer
|
||||
|
||||
Suggested addresses:
|
||||
|
||||
```text
|
||||
logos:<pack_id>
|
||||
logos:<pack_id>:entry:<entry_id>
|
||||
logos:<pack_id>:gloss:<gloss_id>
|
||||
logos:<pack_id>:morphology:<morphology_id>
|
||||
logos:<pack_id>:alignment:<edge_id>
|
||||
logos:<pack_id>:holonomy:<case_id>
|
||||
logos-proposal:<proposal_id>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Backend readers
|
||||
|
||||
Initial read-only endpoints:
|
||||
|
||||
```text
|
||||
GET /logos/packs
|
||||
GET /logos/packs/{pack_id}
|
||||
GET /logos/packs/{pack_id}/contents
|
||||
GET /logos/packs/{pack_id}/safety
|
||||
GET /logos/packs/{pack_id}/alignment
|
||||
GET /logos/packs/{pack_id}/holonomy
|
||||
```
|
||||
|
||||
Proposal-only endpoint:
|
||||
|
||||
```text
|
||||
POST /logos/packs/{pack_id}/proposals/draft
|
||||
```
|
||||
|
||||
The draft endpoint must not write to language-pack source files. It may return a proposal artifact and patch preview.
|
||||
|
||||
---
|
||||
|
||||
## Data shapes
|
||||
|
||||
### `LogosPackOverview`
|
||||
|
||||
```text
|
||||
pack_id
|
||||
language
|
||||
role
|
||||
script
|
||||
version
|
||||
determinism_class
|
||||
gate_engaged
|
||||
oov_policy
|
||||
lexicon_count
|
||||
gloss_count
|
||||
morphology_count
|
||||
frame_count
|
||||
composition_count
|
||||
alignment_edge_count
|
||||
holonomy_case_count
|
||||
safety_status
|
||||
manifest_digest
|
||||
```
|
||||
|
||||
### `LogosPackContents`
|
||||
|
||||
```text
|
||||
pack_id
|
||||
manifest
|
||||
lexicon
|
||||
glosses
|
||||
morphology
|
||||
frames
|
||||
compositions
|
||||
alignment_edges
|
||||
holonomy_cases
|
||||
```
|
||||
|
||||
### `LogosSafetyReport`
|
||||
|
||||
```text
|
||||
pack_id
|
||||
checksum_status
|
||||
oov_policy_ok
|
||||
gate_policy_ok
|
||||
path_safety_ok
|
||||
dangling_morphology_links
|
||||
invalid_alignment_targets
|
||||
missing_holonomy_refs
|
||||
epistemic_status_counts
|
||||
speculative_entries
|
||||
contested_entries
|
||||
falsified_entries
|
||||
known_gaps
|
||||
verdict
|
||||
```
|
||||
|
||||
### `LogosPatchProposal`
|
||||
|
||||
Should be represented through the universal `ProposalArtifact` envelope with `subject.kind = logos_pack`.
|
||||
|
||||
---
|
||||
|
||||
## Handler family order
|
||||
|
||||
Handler admission should be incremental.
|
||||
|
||||
Suggested sequence:
|
||||
|
||||
1. `gloss_add` / `gloss_update`
|
||||
2. `lexicon_add` with speculative status only
|
||||
3. morphology attach/update
|
||||
4. alignment edge add/update
|
||||
5. holonomy case add/update
|
||||
6. coherent/admissible promotion only after stricter review path
|
||||
|
||||
Each handler family requires its own proof pack.
|
||||
|
||||
Required proof obligations:
|
||||
|
||||
- no direct UI file write
|
||||
- safe pack ID enforcement
|
||||
- deterministic ordering
|
||||
- checksum update correctness
|
||||
- pack compile/verify pass
|
||||
- no OOV policy regression
|
||||
- no depth-language fallback collapse
|
||||
- no silent epistemic promotion
|
||||
- audit event emission
|
||||
- replay reconstruction
|
||||
|
||||
---
|
||||
|
||||
## Design language
|
||||
|
||||
CORE-Logos Studio should feel like an instrument, not an illustration.
|
||||
|
||||
Allowed motifs:
|
||||
|
||||
- ordered morphology chains
|
||||
- deterministic alignment diagrams
|
||||
- holonomy proof cards
|
||||
- checksum seals
|
||||
- evidence rails
|
||||
- status badges with text labels
|
||||
- patch previews
|
||||
|
||||
Forbidden motifs:
|
||||
|
||||
- glowing brains
|
||||
- mystical particles
|
||||
- generic neural-network webs
|
||||
- force-directed graph animation
|
||||
- decorative theological imagery that is not structurally meaningful
|
||||
- save/apply buttons before handler admission
|
||||
|
||||
---
|
||||
|
||||
## Implementation sequence
|
||||
|
||||
### L0 — This plan
|
||||
|
||||
Documentation only.
|
||||
|
||||
### L1 — Logos read models
|
||||
|
||||
Add backend schemas/readers for overview, contents, and safety.
|
||||
|
||||
### L2 — Logos route shell
|
||||
|
||||
Add route, pack universe rail, overview, identity, safety status.
|
||||
|
||||
### L3 — Contents tabs
|
||||
|
||||
Lexicon, glosses, morphology, selection evidence subjects.
|
||||
|
||||
### L4 — Alignment / holonomy tabs
|
||||
|
||||
Deterministic diagrams and proof cards.
|
||||
|
||||
### L5 — Safety report
|
||||
|
||||
Full pack safety panel.
|
||||
|
||||
### L6 — Patch Forge
|
||||
|
||||
Proposal-only drafting through universal `ProposalArtifact` envelope.
|
||||
|
||||
### L7 — Handler family 1
|
||||
|
||||
Admit the first minimal CORE-Logos handler family only after ADR/tests.
|
||||
|
||||
---
|
||||
|
||||
## Acceptance standard
|
||||
|
||||
CORE-Logos Studio is real when an operator can:
|
||||
|
||||
```text
|
||||
open /logos
|
||||
select he_logos_micro_v1
|
||||
inspect identity, lexicon, morphology, alignment, holonomy, and safety
|
||||
select a speculative or linked entry
|
||||
see its evidence chain and safety status
|
||||
draft a proposed alignment/gloss/morphology correction
|
||||
preview JSONL patch and checksum impact
|
||||
see that no pack file has been mutated
|
||||
copy the ratification/PR instructions
|
||||
```
|
||||
|
||||
The operator should leave knowing exactly what can be trusted, what is only proposed, and what cannot yet be applied.
|
||||
|
||||
---
|
||||
|
||||
## Final design sentence
|
||||
|
||||
CORE-Logos Studio is where the language substrate stops being hidden infrastructure and becomes a lawful engineering instrument.
|
||||
781
docs/workbench/proposal-artifact-substrate-v1.md
Normal file
781
docs/workbench/proposal-artifact-substrate-v1.md
Normal file
|
|
@ -0,0 +1,781 @@
|
|||
# Proposal Artifact Substrate v1
|
||||
|
||||
**Status:** Proposed planning substrate
|
||||
**Scope:** Workbench / teaching / proposal artifacts / future CORE-Logos Studio
|
||||
**Branch:** `docs/proposal-artifact-substrate-v1`
|
||||
**No ADR number assigned in this document.** This is a consolidation plan and implementation brief. A numbered ADR may ratify it later if the design survives review.
|
||||
|
||||
---
|
||||
|
||||
## Purpose
|
||||
|
||||
CORE has reached the point where `proposal` cannot remain a page-specific idea or a math-specific workflow. Proposal artifacts are the system's lawful bridge between:
|
||||
|
||||
```text
|
||||
engine observation
|
||||
→ structured hypothesis
|
||||
→ evidence-bearing proposed change
|
||||
→ operator review
|
||||
→ ratified mutation, if and only if an admitted handler exists
|
||||
→ deterministic replay / audit reconstruction
|
||||
```
|
||||
|
||||
The current implementation has one deep corridor — math proposals — and one shallower corridor — cognition teaching proposals. CORE-Logos / pack proposals are not yet forged through this substrate at all. That split was historically reasonable: math had ratification handlers that were already proven and narrowly admitted by ADR-0173. But keeping separate proposal pipelines would now create architectural drift.
|
||||
|
||||
This document defines the next substrate: one universal `ProposalArtifact` envelope, with subject-specific adapters and subject-specific validators, while preserving every existing trust boundary.
|
||||
|
||||
The goal is not to grant new mutation power. The goal is to make every proposed change pass through the same evidence, validation, safety, replay, handler, and audit spine.
|
||||
|
||||
---
|
||||
|
||||
## Governing constraints read before this plan
|
||||
|
||||
This plan is constrained by the following prior doctrine.
|
||||
|
||||
### CORE pillars and runtime invariants
|
||||
|
||||
From `README.md` and `CLAUDE.md`:
|
||||
|
||||
- CORE is a deterministic cognitive field system, not a transformer wrapper or generic chatbot.
|
||||
- The field invariant remains load-bearing: `versor_condition(F) < 1e-6` / `||F * reverse(F) - 1||_F < 1e-6`.
|
||||
- Coherence is constructed, not monitored and repaired.
|
||||
- Mechanical Sympathy, Semantic Rigor, and Third Door remain the design filter.
|
||||
- Learning must be reviewed and auditable.
|
||||
- Pack mutation is proposal-only until reviewed.
|
||||
- No parallel correction or learning path.
|
||||
- If a visualization is load-bearing, the underlying data must first exist as deterministic JSON/JSONL/Markdown.
|
||||
- Any path touching packs, logs, dynamic imports, or filesystem paths must state its trust boundary.
|
||||
|
||||
### ADR-0160 — Workbench v1
|
||||
|
||||
- Workbench is an operator/auditor interface, not a chat clone.
|
||||
- It must answer: what happened, why allowed, what evidence supports it, can it replay, did it mutate anything, who/what ratifies next.
|
||||
- V1 is read-only by default.
|
||||
- Proposal before mutation and replay before persuasion are product doctrine.
|
||||
- Mutating proposals, corpus, packs, workflows, or engine state requires a later ADR and explicit gates.
|
||||
|
||||
### ADR-0161 — HITL async queue
|
||||
|
||||
- The HITL queue is a deterministic projection over append-only sources, not a new persistence substrate.
|
||||
- Queue identity is `proposal_id`.
|
||||
- Pending proposals never become active truth.
|
||||
- There are no proposal-on-proposal dependencies.
|
||||
- CI may stage artifacts and open PRs but may not ratify.
|
||||
- Pack mutation queue remains out of scope in ADR-0161.
|
||||
|
||||
### ADR-0162 — Workbench design system
|
||||
|
||||
- Design is a trust surface, not styling.
|
||||
- Stable JSON viewing must be deterministic, lossless, copyable, diffable, and large-document safe.
|
||||
- Empty/error/loading states must name next action, mutation status, reproducer, and safe retry semantics.
|
||||
- No animated cognition theater, no dashboard soup, no color-only state encoding.
|
||||
- Proposal queue and ratification components must preserve auditability and keyboard-first operation.
|
||||
|
||||
### ADR-0172 — math corpus decomposition mechanism
|
||||
|
||||
- Proposal artifacts must carry structured reasoning traces.
|
||||
- Operators review the trace, not a black-box conclusion.
|
||||
- Reasoning traces are content-addressable and replayable.
|
||||
- Tier 2 proposals must include self-test evidence before HITL review.
|
||||
- Operator verdicts are future teaching signals; rejection/refinement rationale is part of the learning loop.
|
||||
|
||||
### ADR-0173 — Workbench ratification trust boundary
|
||||
|
||||
- The Workbench is a local keyboard accelerator over existing local ratification handlers.
|
||||
- It is not a fourth ratification surface and not a new trust boundary.
|
||||
- Existing admitted handlers may be driven by `POST /math-proposals/{id}/ratify` only because they already preserve the same evidence, preconditions, exceptions, and append-only JSONL effects as CLI/Python entrypoints.
|
||||
- The amendment is narrow. It does not admit new mutation paths, new corpora, new pack types, remote operator auth, or unproven handlers.
|
||||
- No auto-ratify. No batch ratification in v1. No bypass of handler preconditions.
|
||||
|
||||
### ADR-0015 — CORE-Logos language packs
|
||||
|
||||
- A language pack is not a dataset or translation table.
|
||||
- It is a deterministic, checksummed, compiled linguistic manifold.
|
||||
- Pack contents include manifest, lexicon, morphology, grammar attractors, cross-language resonance edges, and holonomy alignment cases.
|
||||
- OOV policy, ordering, morphology, alignment, and holonomy proof cases are load-bearing.
|
||||
- Unknown depth-language surfaces must not silently collapse to fallback points.
|
||||
|
||||
---
|
||||
|
||||
## Problem statement
|
||||
|
||||
The Workbench currently exposes proposal artifacts unevenly:
|
||||
|
||||
```text
|
||||
math proposals → deep artifact record + UI detail + ratification corridor
|
||||
cognition proposals → queue projection + replay/provenance inspection + CLI fallback
|
||||
CORE-Logos packs → manifest/checksum inspection only, no proposal forge
|
||||
future modalities → no proposal path yet
|
||||
```
|
||||
|
||||
This split is a historical implementation sequence, not the desired architecture.
|
||||
|
||||
The risk is that each subject grows its own lifecycle:
|
||||
|
||||
```text
|
||||
math proposal lifecycle
|
||||
cognition proposal lifecycle
|
||||
pack proposal lifecycle
|
||||
vision proposal lifecycle
|
||||
```
|
||||
|
||||
That would violate the Workbench's evidence-manifold direction and eventually create contradictory semantics for state, review, safety, replay, and ratification.
|
||||
|
||||
The correct shape is:
|
||||
|
||||
```text
|
||||
one universal proposal artifact lifecycle
|
||||
+ subject-specific proposal payloads
|
||||
+ subject-specific validators
|
||||
+ subject-specific handlers
|
||||
+ one Workbench review language
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Decision
|
||||
|
||||
Introduce a universal `ProposalArtifact` substrate as the single Workbench-facing envelope for all proposed changes.
|
||||
|
||||
The envelope standardizes identity, subject, evidence, reasoning, validation, affected artifacts, safety checks, handler routing, ratification status, and audit references.
|
||||
|
||||
The envelope does **not** standardize the domain payload itself. Math, cognition, CORE-Logos, vision, audio, and future subjects may each define typed payloads and validation reports. What is universal is the review spine.
|
||||
|
||||
---
|
||||
|
||||
## Core distinction: proposal artifact vs ratification handler
|
||||
|
||||
A proposal artifact is an evidence-bearing candidate for review.
|
||||
|
||||
A ratification handler is a pre-admitted local mutation path that can apply a candidate after all preconditions pass.
|
||||
|
||||
These must remain separate.
|
||||
|
||||
```text
|
||||
ProposalArtifact exists → reviewable
|
||||
ProposalArtifact validates → still not applied
|
||||
ProposalArtifact routes to admitted handler → apply may be enabled
|
||||
No admitted handler → proposal-only / CLI fallback / future ADR required
|
||||
```
|
||||
|
||||
This distinction is the core safety boundary for CORE-Logos. A browser may help draft a Logos proposal before a handler exists. It must not apply that proposal until an admitted handler exists and tests prove the same invariants as the CLI path.
|
||||
|
||||
---
|
||||
|
||||
## Universal proposal envelope
|
||||
|
||||
The implementation should converge toward this shape. Field names may be refined during implementation, but the sections are load-bearing.
|
||||
|
||||
```text
|
||||
ProposalArtifact:
|
||||
proposal_id: str
|
||||
schema_version: str
|
||||
subject: ProposalSubject
|
||||
state: pending | accepted | rejected | withdrawn | deferred | unknown
|
||||
capability_level: inspect_only | proposal_only | ratification_enabled
|
||||
source: ProposalSource
|
||||
proposed_change: ProposedChange
|
||||
reasoning_trace: ReasoningTrace | None
|
||||
evidence_pointers: tuple[EvidencePointer, ...]
|
||||
validation: ValidationReport | None
|
||||
replay_evidence: ReplayEvidence | None
|
||||
safety_report: SafetyReport | None
|
||||
affected_artifacts: tuple[AffectedArtifact, ...]
|
||||
checksum_impacts: tuple[ChecksumImpact, ...]
|
||||
handler_route: HandlerRoute | None
|
||||
suggested_cli: str | None
|
||||
audit_refs: tuple[AuditRef, ...]
|
||||
ui_disclosure: ProposalDisclosure
|
||||
```
|
||||
|
||||
### `ProposalSubject`
|
||||
|
||||
```text
|
||||
ProposalSubject:
|
||||
kind: math | cognition | logos_pack | pack | vision | audio | sensorimotor | runtime_policy | unknown
|
||||
subject_id: str
|
||||
partition: str
|
||||
display_name: str
|
||||
```
|
||||
|
||||
Examples:
|
||||
|
||||
```text
|
||||
math / shape_category=multi_quantity_composition
|
||||
cognition / TeachingChainProposal
|
||||
logos_pack / he_logos_micro_v1 / alignment_edge_add
|
||||
logos_pack / grc_logos_micro_v1 / holonomy_case_add
|
||||
```
|
||||
|
||||
### `capability_level`
|
||||
|
||||
This field prevents the UI from implying authority it does not have.
|
||||
|
||||
| Level | Meaning | UI may do |
|
||||
|---|---|---|
|
||||
| `inspect_only` | Artifact can be inspected but not changed from Workbench. | Read, copy evidence, navigate, show CLI fallback. |
|
||||
| `proposal_only` | Workbench may draft or preview a proposal artifact, but cannot apply it. | Structured editor, validation preview, patch preview, export/copy CLI. |
|
||||
| `ratification_enabled` | A handler exists and was admitted by ADR/tests. | Enable ratify/reject/defer controls subject to preconditions. |
|
||||
|
||||
No route may render a `Ratify` affordance unless `capability_level == ratification_enabled` and `handler_route` is present and admitted.
|
||||
|
||||
### `ProposedChange`
|
||||
|
||||
```text
|
||||
ProposedChange:
|
||||
change_kind: str
|
||||
payload: object
|
||||
payload_digest: str
|
||||
human_summary: str
|
||||
```
|
||||
|
||||
This keeps payload type open while making the envelope hashable and inspectable.
|
||||
|
||||
### `EvidencePointer`
|
||||
|
||||
```text
|
||||
EvidencePointer:
|
||||
pointer_id: str
|
||||
evidence_hash: str | None
|
||||
source_path: str | None
|
||||
json_pointer: str | None
|
||||
trace_hash: str | None
|
||||
description: str | None
|
||||
```
|
||||
|
||||
Evidence may point to audit rows, eval cases, refusal records, trace rows, pack entries, alignment edges, holonomy cases, or prior proposal verdicts.
|
||||
|
||||
### `ReasoningTrace`
|
||||
|
||||
Reuse ADR-0172's concept: a stable sequence of typed reasoning steps.
|
||||
|
||||
```text
|
||||
ReasoningTrace:
|
||||
trace_id: str
|
||||
steps: tuple[ReasoningStep, ...]
|
||||
```
|
||||
|
||||
The Workbench reviews the trace and the evidence, not merely the conclusion.
|
||||
|
||||
### `ValidationReport`
|
||||
|
||||
```text
|
||||
ValidationReport:
|
||||
validator_id: str
|
||||
verdict: pass | warning | fail | not_run
|
||||
checks: tuple[ValidationCheck, ...]
|
||||
```
|
||||
|
||||
Subject adapters define checks, but the envelope provides a uniform report surface.
|
||||
|
||||
### `SafetyReport`
|
||||
|
||||
```text
|
||||
SafetyReport:
|
||||
verdict: clear | warning | failed | unknown
|
||||
wrong_zero_risk: none | bounded | live | unknown
|
||||
mutation_boundary: none | proposal_only | admitted_handler | forbidden
|
||||
checks: tuple[SafetyCheck, ...]
|
||||
```
|
||||
|
||||
This is the field that prevents proposal UI from becoming persuasion theater.
|
||||
|
||||
### `AffectedArtifact`
|
||||
|
||||
```text
|
||||
AffectedArtifact:
|
||||
path: str
|
||||
artifact_kind: str
|
||||
before_digest: str | None
|
||||
after_digest: str | None
|
||||
mutation_mode: proposal_only | append_only | replace | unknown
|
||||
```
|
||||
|
||||
For proposal-only flows, `after_digest` may be predicted, not applied. The UI must label predicted digests as predicted.
|
||||
|
||||
### `ChecksumImpact`
|
||||
|
||||
```text
|
||||
ChecksumImpact:
|
||||
manifest_path: str | None
|
||||
field: str
|
||||
before: str | None
|
||||
after: str | None
|
||||
status: unchanged | predicted | applied | not_applicable
|
||||
```
|
||||
|
||||
### `HandlerRoute`
|
||||
|
||||
```text
|
||||
HandlerRoute:
|
||||
handler_id: str
|
||||
admitted_by: str
|
||||
route: str
|
||||
required_preconditions: tuple[str, ...]
|
||||
dry_run_supported: bool
|
||||
```
|
||||
|
||||
No `HandlerRoute` means no Workbench ratification.
|
||||
|
||||
---
|
||||
|
||||
## Universal lifecycle
|
||||
|
||||
Every proposal artifact moves through the same conceptual phases.
|
||||
|
||||
```text
|
||||
drafted
|
||||
→ validated
|
||||
→ replayed_or_checked
|
||||
→ safety_reviewed
|
||||
→ routed_or_blocked
|
||||
→ operator_decision
|
||||
→ audit_recorded
|
||||
→ replay_reconstructible
|
||||
```
|
||||
|
||||
The stored state alphabet may remain ADR-0057-compatible where required. The Workbench can render additional transient UI dispositions, but durable state must not silently widen without a ratifying ADR.
|
||||
|
||||
### Drafted
|
||||
|
||||
A candidate exists. It may come from the engine, CLI, Workbench forge, a demo, or a future modality compiler.
|
||||
|
||||
### Validated
|
||||
|
||||
Subject-specific validators run. This may be syntax/schema validation, replay equivalence, pack checksum verification, morphology-link verification, holonomy proof status, or eval impact analysis.
|
||||
|
||||
### Replayed or checked
|
||||
|
||||
Not every subject has turn replay. The universal phase is evidence re-checking:
|
||||
|
||||
- math: replay equivalence / wrong=0 gate / two-arm confirmation
|
||||
- cognition: teaching-chain replay equivalence
|
||||
- CORE-Logos: pack compile/verify, morphology links, alignment targets, holonomy cases, checksum impacts
|
||||
- modalities: deterministic compiler replay / content-addressed delta replay
|
||||
|
||||
### Safety reviewed
|
||||
|
||||
Safety report names mutation boundary, wrong=0 risk, partition risk, path safety, checksum risk, OOV/gate risk, and any missing proof obligations.
|
||||
|
||||
### Routed or blocked
|
||||
|
||||
If an admitted handler exists, the proposal may show a ratification corridor. If not, the proposal remains proposal-only with a CLI/export/follow-up path.
|
||||
|
||||
### Operator decision
|
||||
|
||||
Operator may ratify, reject, defer, withdraw, or refine depending on admitted state machine for the subject. This document does not widen durable state by itself.
|
||||
|
||||
### Audit recorded
|
||||
|
||||
Every action that crosses a mutation boundary emits audit/telemetry per ADR-0173. Proposal-only draft creation should also be recordable once the substrate is implemented, but it must be labeled as non-mutating.
|
||||
|
||||
### Replay reconstructible
|
||||
|
||||
Given the artifact sources and proposal logs, the Workbench projection must be reconstructible without hidden UI state.
|
||||
|
||||
---
|
||||
|
||||
## Subject adapters
|
||||
|
||||
The universal envelope is consumed through adapters. Each adapter names source files, validators, safety checks, handler status, and UI affordances.
|
||||
|
||||
### Math adapter
|
||||
|
||||
Current maturity: `ratification_enabled` for admitted claim classes.
|
||||
|
||||
Sources:
|
||||
|
||||
- `teaching/math_proposals/proposals.jsonl`
|
||||
- ratified math lexicon/frame/composition artifacts
|
||||
- eval/audit reports
|
||||
|
||||
Existing strengths:
|
||||
|
||||
- self-contained JSONL proposal records
|
||||
- evidence pointers
|
||||
- reasoning trace steps
|
||||
- wrong=0 assertion
|
||||
- replay equivalence hash
|
||||
- handler dispatch for LexicalClaim, FrameClaim, CompositionClaim
|
||||
- Workbench ratify/reject/defer UI
|
||||
|
||||
Required migration:
|
||||
|
||||
- wrap existing `MathProposalDetail` into `ProposalArtifact`
|
||||
- retain existing routes for compatibility during migration
|
||||
- expose `capability_level=ratification_enabled` only for admitted handlers
|
||||
- populate `affected_artifacts` and `checksum_impacts` after handler dry-run or predicted receipt support exists
|
||||
- connect audit events back into proposal timeline
|
||||
|
||||
No behavior change in the migration PR. The first math adapter PR should be read-model-only.
|
||||
|
||||
### Cognition adapter
|
||||
|
||||
Current maturity: `inspect_only`, moving to `ratification_enabled` only after Surface C parity is proven.
|
||||
|
||||
Sources:
|
||||
|
||||
- `teaching/proposals/proposals.jsonl`
|
||||
- contemplation reports
|
||||
- replay evidence
|
||||
- operator transition records
|
||||
|
||||
Required work:
|
||||
|
||||
- wrap `ProposalDetail` into `ProposalArtifact`
|
||||
- populate artifact references instead of returning empty `artifact_refs`
|
||||
- add review history / timeline projection
|
||||
- prove Surface C parity before enabling Workbench ratification
|
||||
- preserve ADR-0057 / ADR-0161 state reconstruction
|
||||
|
||||
### CORE-Logos adapter
|
||||
|
||||
Current maturity: no proposal forge yet. Target next state: `proposal_only` first, not ratification-enabled.
|
||||
|
||||
Sources:
|
||||
|
||||
- `language_packs/data/<pack_id>/manifest.json`
|
||||
- `lexicon.jsonl`
|
||||
- `glosses.jsonl`
|
||||
- morphology files
|
||||
- `alignment.jsonl`
|
||||
- frame/composition files when present
|
||||
- holonomy proof cases
|
||||
- pack validators / compiler checks
|
||||
|
||||
Initial change kinds:
|
||||
|
||||
```text
|
||||
lexicon_add
|
||||
lexicon_update
|
||||
lexicon_remove
|
||||
gloss_add
|
||||
gloss_update
|
||||
morphology_add
|
||||
morphology_update
|
||||
alignment_edge_add
|
||||
alignment_edge_update
|
||||
holonomy_case_add
|
||||
holonomy_case_update
|
||||
frame_add
|
||||
composition_add
|
||||
```
|
||||
|
||||
Initial UI capability:
|
||||
|
||||
```text
|
||||
structured proposal drafting
|
||||
schema validation
|
||||
safety report
|
||||
checksum impact prediction
|
||||
patch preview
|
||||
suggested CLI / PR instructions
|
||||
no apply button
|
||||
```
|
||||
|
||||
Handler admission comes later, one handler family at a time.
|
||||
|
||||
Required safety checks:
|
||||
|
||||
- safe pack ID
|
||||
- manifest present
|
||||
- declared source file present
|
||||
- checksum matches or predicted checksum is clearly labeled
|
||||
- OOV policy valid for role
|
||||
- depth pack fail-closed when gate engaged
|
||||
- no dangling morphology links
|
||||
- no invalid alignment targets
|
||||
- no holonomy case with missing refs
|
||||
- epistemic-status distribution visible
|
||||
- known gaps carried forward
|
||||
- no silent promotion from speculative to coherent
|
||||
|
||||
### General pack adapter
|
||||
|
||||
The broader `packs` route may remain an inventory view. Any pack mutation or patching path should reuse the CORE-Logos adapter where applicable and the universal proposal envelope always.
|
||||
|
||||
### Future modality adapters
|
||||
|
||||
Audio, vision, environment, and sensorimotor proposal artifacts must enter through the same envelope. Because these substrates are gated and often afferent-only, initial capability should usually be `inspect_only` or `proposal_only`.
|
||||
|
||||
No modality adapter may imply decode, actuation, or motor authority unless the governing ADR admits it.
|
||||
|
||||
---
|
||||
|
||||
## Workbench UX substrate
|
||||
|
||||
The Workbench should render proposal artifacts through shared components rather than per-domain bespoke pages.
|
||||
|
||||
### Shared components
|
||||
|
||||
```text
|
||||
ProposalArtifactHeader
|
||||
ProposalSubjectBadge
|
||||
CapabilityLevelBadge
|
||||
ProposalEvidenceRail
|
||||
ReasoningTraceViewer
|
||||
ValidationReportPanel
|
||||
SafetyReportPanel
|
||||
AffectedArtifactsPanel
|
||||
ChecksumImpactPanel
|
||||
HandlerRoutePanel
|
||||
RatificationCorridor
|
||||
ProposalTimeline
|
||||
SuggestedCliPanel
|
||||
PatchPreviewPanel
|
||||
```
|
||||
|
||||
### Design rules
|
||||
|
||||
- Every proposal screen names mutation status.
|
||||
- Every disabled ratification affordance names the failed precondition.
|
||||
- Every unknown or missing proof renders as unknown/missing, not as green.
|
||||
- Draft/preview/predicted/applied must be visibly distinct in text, not color only.
|
||||
- `StableJsonViewer` remains the raw artifact trust surface.
|
||||
- No auto-ratify, no batch ratification, no hidden background jobs.
|
||||
- No direct pack editing UI.
|
||||
- No route-specific proposal semantics that contradict the shared envelope.
|
||||
|
||||
---
|
||||
|
||||
## Backend API direction
|
||||
|
||||
The future API should converge toward generic proposal endpoints while preserving old endpoints during migration.
|
||||
|
||||
Read-only / projection:
|
||||
|
||||
```text
|
||||
GET /proposal-artifacts
|
||||
GET /proposal-artifacts/{proposal_id}
|
||||
GET /proposal-artifacts/{proposal_id}/timeline
|
||||
GET /proposal-artifacts/{proposal_id}/artifacts
|
||||
```
|
||||
|
||||
Subject-specific draft endpoints may exist when they do not mutate substrate artifacts:
|
||||
|
||||
```text
|
||||
POST /logos/packs/{pack_id}/proposals/draft
|
||||
POST /proposal-artifacts/{proposal_id}/validate
|
||||
```
|
||||
|
||||
Ratification remains subject to admitted handler routes:
|
||||
|
||||
```text
|
||||
POST /proposal-artifacts/{proposal_id}/ratify
|
||||
```
|
||||
|
||||
But this generic route must refuse unless `handler_route` is admitted for the proposal subject and all preconditions pass. The route may initially be omitted entirely until generic routing is proven.
|
||||
|
||||
During migration, existing math routes remain valid:
|
||||
|
||||
```text
|
||||
GET /math-proposals
|
||||
GET /math-proposals/{id}
|
||||
POST /math-proposals/{id}/ratify
|
||||
POST /math-proposals/{id}/reject
|
||||
POST /math-proposals/{id}/defer
|
||||
```
|
||||
|
||||
The adapter layer can translate those into the universal envelope without changing behavior.
|
||||
|
||||
---
|
||||
|
||||
## Trust boundary matrix
|
||||
|
||||
| Subject | Initial capability | May draft in UI? | May apply in UI? | Gate to enable apply |
|
||||
|---|---:|---:|---:|---|
|
||||
| Math / admitted handlers | `ratification_enabled` | No new drafting in this slice | Yes, existing narrow path | Existing ADR-0173 + handler tests |
|
||||
| Math / unsupported change kind | `proposal_only` or `inspect_only` | Later | No | New handler ADR/tests |
|
||||
| Cognition teaching proposal | `inspect_only` | No | Not yet | Surface C parity tests + implementation |
|
||||
| CORE-Logos pack proposal | `proposal_only` | Yes, after forge PR | No | New handler family ADR/tests |
|
||||
| General pack mutation | `proposal_only` | Later | No | Reviewed handler path |
|
||||
| Vision/audio modality proposal | `inspect_only` first | Later | No | Dedicated modality ADR/tests |
|
||||
| Runtime policy / identity | `inspect_only` unless separately ratified | No by default | No | Dedicated governance ADR |
|
||||
|
||||
---
|
||||
|
||||
## Implementation sequence
|
||||
|
||||
### S0 — This plan
|
||||
|
||||
Create this document. No code. No schema changes. No mutation path.
|
||||
|
||||
### S1 — Universal envelope schemas, read-only only
|
||||
|
||||
Add Python and TypeScript read-model schemas for `ProposalArtifact`, `ProposalSubject`, `SafetyReport`, `ValidationReport`, `AffectedArtifact`, `ChecksumImpact`, and `HandlerRoute`.
|
||||
|
||||
No endpoints apply anything.
|
||||
|
||||
Acceptance:
|
||||
|
||||
- schema drift tests cover TS/Python mirrors
|
||||
- no new mutation routes
|
||||
- existing math/cognition endpoints unchanged
|
||||
|
||||
### S2 — Proposal artifact projection endpoint
|
||||
|
||||
Add a read-only endpoint that projects existing math and cognition proposals into the universal envelope.
|
||||
|
||||
```text
|
||||
GET /proposal-artifacts
|
||||
GET /proposal-artifacts/{id}
|
||||
```
|
||||
|
||||
Acceptance:
|
||||
|
||||
- math proposal count matches `/math-proposals`
|
||||
- cognition proposal count matches `/proposals`
|
||||
- unsupported handlers render `capability_level != ratification_enabled`
|
||||
- missing artifacts render absence explicitly
|
||||
|
||||
### S3 — Shared UI components
|
||||
|
||||
Build the shared proposal artifact components and render them behind a feature flag or route-internal experiment.
|
||||
|
||||
Acceptance:
|
||||
|
||||
- no existing ProposalsRoute behavior removed
|
||||
- every component has empty/error/loading state where applicable
|
||||
- no color-only status
|
||||
- keyboard focus works
|
||||
- raw JSON still available
|
||||
|
||||
### S4 — Math adapter migration
|
||||
|
||||
Render math proposals through the universal proposal artifact components while preserving existing ratification behavior.
|
||||
|
||||
Acceptance:
|
||||
|
||||
- existing math ratify/reject/defer tests still pass
|
||||
- `RatificationCorridor` remains gated by pending + replay equivalent + admitted handler
|
||||
- no unsupported handler becomes enabled
|
||||
- target path/evidence hash after apply is surfaced in timeline or result panel
|
||||
|
||||
### S5 — Cognition adapter depth
|
||||
|
||||
Populate artifact refs, review history, and proposal timeline for cognition proposals. Do not enable Workbench ratification until Surface C parity is proven.
|
||||
|
||||
Acceptance:
|
||||
|
||||
- artifact_refs no longer always empty when source artifacts exist
|
||||
- review_history is visible
|
||||
- CLI fallback remains available
|
||||
- Workbench ratify button absent or disabled with clear reason
|
||||
|
||||
### S6 — CORE-Logos proposal forge, proposal-only
|
||||
|
||||
Add proposal-only drafting for CORE-Logos changes.
|
||||
|
||||
Acceptance:
|
||||
|
||||
- structured editor produces proposal artifact only
|
||||
- no language pack file is mutated
|
||||
- safety report includes pack-specific checks
|
||||
- checksum impacts are predicted and labeled predicted
|
||||
- patch preview is visible
|
||||
- suggested CLI/PR instructions are visible
|
||||
- no `Ratify` affordance exists
|
||||
|
||||
### S7 — CORE-Logos handler families, one at a time
|
||||
|
||||
Admit one handler family per ADR/brief/PR sequence.
|
||||
|
||||
Suggested order:
|
||||
|
||||
1. `gloss_add` / `gloss_update`
|
||||
2. `lexicon_add` with speculative status only
|
||||
3. morphology link attach/update
|
||||
4. alignment edge add/update
|
||||
5. holonomy case add/update
|
||||
6. coherent/admissible status promotion only after a stricter review path exists
|
||||
|
||||
Each family must prove:
|
||||
|
||||
- append-only or deterministic file rewrite discipline
|
||||
- checksum update correctness
|
||||
- pack compile/verify pass
|
||||
- no depth-language OOV collapse
|
||||
- no silent epistemic promotion
|
||||
- rollback/replay reconstruction
|
||||
- audit event emission
|
||||
|
||||
---
|
||||
|
||||
## Acceptance gates for this substrate
|
||||
|
||||
This substrate is ready to implement when reviewers agree the following are true:
|
||||
|
||||
1. The universal envelope does not widen durable proposal state without ADR review.
|
||||
2. The universal envelope does not grant new mutation authority.
|
||||
3. Math remains behavior-identical after adapter projection.
|
||||
4. Cognition remains inspect-only until Surface C parity tests exist.
|
||||
5. CORE-Logos begins proposal-only, not ratification-enabled.
|
||||
6. Every proposal artifact can name evidence, validation, safety, affected artifacts, and handler status.
|
||||
7. Missing evidence renders as missing, not as success.
|
||||
8. Every route using the substrate preserves ADR-0162 empty/error/loading doctrine.
|
||||
9. Every mutation-capable route names the handler, preconditions, target artifact, audit event, and replay boundary.
|
||||
10. No UI path can apply a subject whose handler is not admitted.
|
||||
|
||||
---
|
||||
|
||||
## Explicit no-go list
|
||||
|
||||
- No direct pack editor.
|
||||
- No generic `apply_patch` endpoint.
|
||||
- No browser write to `language_packs/data/*`.
|
||||
- No ratification affordance for proposal-only subjects.
|
||||
- No auto-ratify.
|
||||
- No batch ratification.
|
||||
- No hidden background validation that changes files.
|
||||
- No new durable proposal state names without ADR review.
|
||||
- No pack checksum rewrite from UI until a handler family admits it.
|
||||
- No using `ratifier_kind` as permission logic.
|
||||
- No treating Workbench as remote operator auth.
|
||||
- No proposal-on-proposal dependency chain.
|
||||
- No visualization as proof without deterministic underlying artifact.
|
||||
|
||||
---
|
||||
|
||||
## CORE-Logos implication
|
||||
|
||||
CORE-Logos Studio should be the first major consumer after math/cognition are projected into the envelope.
|
||||
|
||||
The Studio should not create a separate Logos proposal system. It should create Logos proposal artifacts using this universal envelope:
|
||||
|
||||
```text
|
||||
CORE-Logos proposed change
|
||||
→ subject = logos_pack
|
||||
→ change_kind = lexicon_add | morphology_add | alignment_edge_add | holonomy_case_add | ...
|
||||
→ evidence pointers
|
||||
→ safety report
|
||||
→ checksum impact
|
||||
→ patch preview
|
||||
→ handler route absent
|
||||
→ capability_level = proposal_only
|
||||
```
|
||||
|
||||
Only after a specific Logos handler family is admitted may that family become `ratification_enabled`.
|
||||
|
||||
This keeps CORE-Logos functional for active engineering and development while preserving the safety boundary that made math ratification lawful.
|
||||
|
||||
---
|
||||
|
||||
## Open questions
|
||||
|
||||
1. Should universal `deferred` be a durable state, or remain a Workbench UI disposition backed by existing state/log semantics?
|
||||
2. Should proposal draft artifacts live under a new `proposal_artifacts/` tree, or remain subject-owned until ratified?
|
||||
3. Should `POST /proposal-artifacts/{id}/validate` be read-only by contract, or should validation always be a fresh read endpoint with query parameters?
|
||||
4. What is the smallest CORE-Logos handler family safe enough to ratify first: gloss updates, lexicon additions as speculative, or holonomy case additions?
|
||||
5. Should operator rejection/refinement attach to reasoning-trace step IDs universally, not just math Tier 2?
|
||||
|
||||
None of these open questions block S1/S2 read-only projection.
|
||||
|
||||
---
|
||||
|
||||
## Final design sentence
|
||||
|
||||
A proposal artifact is CORE's lawful way to say:
|
||||
|
||||
> “The engine has seen enough to suggest a change, but not enough to become the change.”
|
||||
|
||||
The Workbench's job is to make that distinction impossible to miss.
|
||||
311
docs/workbench/wave-m-consolidation-b3.5.md
Normal file
311
docs/workbench/wave-m-consolidation-b3.5.md
Normal file
|
|
@ -0,0 +1,311 @@
|
|||
# Wave M Consolidation / B3.5 — Workbench Mastery Before Next Complexity
|
||||
|
||||
**Status:** Proposed planning slice
|
||||
**Scope:** Workbench UI/UX architecture, route substrate, evidence subjects, calibration discipline, B4 readiness
|
||||
**Branch:** `docs/proposal-artifact-substrate-v1`
|
||||
**No code changes in this document.**
|
||||
|
||||
---
|
||||
|
||||
## Purpose
|
||||
|
||||
Before Workbench Phase B4 or Phase C adds more visible complexity, the existing Workbench substrate must be metabolized into one coherent product architecture.
|
||||
|
||||
Recent Workbench waves successfully made determinism, replay, demos, calibration, and wrong=0 discipline visible. But the surface has outgrown parts of its original route, command, evidence-subject, and documentation substrate. This document captures the consolidation plan discussed after Wave M B3.
|
||||
|
||||
The intent is not to slow momentum. The intent is to prevent Workbench from becoming a set of individually-good screens that contradict each other at the navigation, evidence, or authority layer.
|
||||
|
||||
---
|
||||
|
||||
## Governing doctrine
|
||||
|
||||
This slice inherits:
|
||||
|
||||
- ADR-0160: Workbench is an operator/auditor interface, not a chat clone.
|
||||
- ADR-0162: design is a trust surface; every route must honor empty/error/loading contracts.
|
||||
- ADR-0173: ratification authority is narrow and handler-bound.
|
||||
- `CLAUDE.md`: no hidden mutation, no visualization as proof without deterministic artifact, no parallel learning path.
|
||||
- Wave M worthiness plan: make calibration/serving discipline and cognition substrate visible without reimplementing engine math in the frontend.
|
||||
|
||||
---
|
||||
|
||||
## Current diagnosis
|
||||
|
||||
### 1. The route substrate has drifted
|
||||
|
||||
The Workbench now has more routes than the original route/navigation assumptions. The UI has grown to include Demos and Calibration, but command-palette entries, landing-route preferences, keyboard assumptions, docs, and route conformance lists can drift unless there is a single source of truth.
|
||||
|
||||
This is not only a convenience bug. In Workbench, navigation is evidence access. If a route exists in LeftNav but not in command search, or exists in App routing but not in docs, the product is teaching operators an inconsistent map of its own evidence manifold.
|
||||
|
||||
### 2. Calibration is visible, but not yet fully evidence-native
|
||||
|
||||
Calibration classes and serving metrics are visible, and wrong=0 is now a felt global presence. But calibration class selection is not yet a first-class evidence subject with a URL-addressable inspector projection.
|
||||
|
||||
That means calibration is still partly a page-local experience, not fully part of the Evidence Chain Rail.
|
||||
|
||||
### 3. B4 is conceptually right but data-shape risky
|
||||
|
||||
B4 wants the Replay/Proposals evidence rails to explain why approximation/leeway was granted: class, license, theta, disclosure, and relation to HITL ratification.
|
||||
|
||||
That is the right product idea. But the UI must not invent the tuple. If turn/proposal schemas do not carry those fields in typed form, B4 needs a backend/schema/read-model slice first.
|
||||
|
||||
### 4. Documentation is behind the product
|
||||
|
||||
A UI/UX guide was discussed as necessary for external evaluators and new operators. It must reflect the current route count and current capabilities, including what is absent.
|
||||
|
||||
Old documentation that says eleven routes while the app has twelve is worse than missing documentation: it trains reviewers to distrust the map.
|
||||
|
||||
### 5. Phase A residue should be either finished or explicitly deferred
|
||||
|
||||
Some design-mastery items remain partially open, such as density preferences, broader deterministic-DAG consumers, and route/keyboard command truth. These should be resolved or named before moving into the next layer.
|
||||
|
||||
---
|
||||
|
||||
## Decision
|
||||
|
||||
Insert a consolidation slice before building more complexity:
|
||||
|
||||
```text
|
||||
Wave M B3.5 — Workbench Consolidation
|
||||
```
|
||||
|
||||
This slice standardizes route truth, evidence-subject truth, calibration evidence integration, B4 feasibility, and operator documentation.
|
||||
|
||||
It must be small enough to review, but serious enough to prevent architectural drift.
|
||||
|
||||
---
|
||||
|
||||
## Deliverable 1 — Route registry unification
|
||||
|
||||
Create one route registry that can be consumed by:
|
||||
|
||||
- `App` route declarations
|
||||
- `LeftNav`
|
||||
- `CommandPalette`
|
||||
- global keyboard help
|
||||
- landing route preferences
|
||||
- route conformance tests
|
||||
- UI/UX guide route table
|
||||
|
||||
The registry should identify:
|
||||
|
||||
```text
|
||||
id
|
||||
path
|
||||
label
|
||||
description
|
||||
left_nav_visible
|
||||
command_palette_visible
|
||||
landing_route_allowed
|
||||
keyboard_shortcut
|
||||
route_conformance_required
|
||||
```
|
||||
|
||||
### Critical rule
|
||||
|
||||
If there are more routes than single-digit keyboard shortcuts, the UI must say so honestly.
|
||||
|
||||
Good:
|
||||
|
||||
```text
|
||||
Pinned route shortcuts: Chat through Settings
|
||||
All routes searchable in Command Palette
|
||||
```
|
||||
|
||||
Bad:
|
||||
|
||||
```text
|
||||
Navigate to every route with 1–10
|
||||
```
|
||||
|
||||
when there are more than ten routes.
|
||||
|
||||
### Acceptance
|
||||
|
||||
- Command palette contains every command-visible route.
|
||||
- Landing route dropdown includes every landing-eligible route.
|
||||
- Demos and Calibration cannot silently fall out of command/search surfaces.
|
||||
- Route conformance fixtures derive from or assert against the registry.
|
||||
- Tests fail if a route is added to App without updating the registry.
|
||||
|
||||
---
|
||||
|
||||
## Deliverable 2 — Calibration evidence subject
|
||||
|
||||
Add calibration to the evidence model.
|
||||
|
||||
Suggested subject:
|
||||
|
||||
```text
|
||||
calibration_class
|
||||
```
|
||||
|
||||
Possible address:
|
||||
|
||||
```text
|
||||
calibration:<class_name>
|
||||
```
|
||||
|
||||
or, if using URL path semantics:
|
||||
|
||||
```text
|
||||
/calibration?inspect=calibration:<class_name>
|
||||
```
|
||||
|
||||
The selected class should publish an evidence subject and render in the RightInspector / EvidenceChainRail.
|
||||
|
||||
### Inspector projection
|
||||
|
||||
Show only fields carried by the backend read model:
|
||||
|
||||
- class name
|
||||
- correct / wrong / refused / committed counts
|
||||
- Wilson floor / reliability floor
|
||||
- propose threshold and license
|
||||
- serve threshold and license
|
||||
- coverage
|
||||
- source digest / report path if available
|
||||
- explicit absence for unavailable proof
|
||||
|
||||
### Acceptance
|
||||
|
||||
- Selecting a calibration class updates evidence subject.
|
||||
- Deep link restores selected calibration evidence subject.
|
||||
- RightInspector handles the subject without falling to raw unknown.
|
||||
- Evidence Chain Rail names calibration as serving-discipline evidence, not runtime truth.
|
||||
- Missing data renders as missing/unknown, not as green.
|
||||
|
||||
---
|
||||
|
||||
## Deliverable 3 — B4 leeway feasibility gate
|
||||
|
||||
Before implementing B4 UI annotations, prove the source tuple exists in typed data.
|
||||
|
||||
Required tuple:
|
||||
|
||||
```text
|
||||
class_name
|
||||
license: PROPOSE | SERVE | blocked | unknown
|
||||
theta / threshold context
|
||||
claim/disclosure: approximate | verified | proposal_only | none
|
||||
source digest / calibration evidence reference
|
||||
```
|
||||
|
||||
If this tuple is not present in `ChatTurnResult`, `TurnJournalEntry`, `ProposalDetail`, `MathProposalDetail`, or a lawful backend join, create B4a first.
|
||||
|
||||
### B4a — backend/schema/read-model first
|
||||
|
||||
B4a should add only the read model needed to explain leeway honestly.
|
||||
|
||||
No frontend card should explain what the data model cannot prove.
|
||||
|
||||
### Acceptance
|
||||
|
||||
- A served-with-leeway fixture renders class + threshold + license + disclosure.
|
||||
- A fully verified turn renders no leeway annotation.
|
||||
- If any tuple field is absent, UI renders explicit absence.
|
||||
- No frontend-only inference of class/license/theta.
|
||||
|
||||
---
|
||||
|
||||
## Deliverable 4 — UI/UX guide
|
||||
|
||||
Create or update:
|
||||
|
||||
```text
|
||||
docs/workbench/UI-UX-GUIDE.md
|
||||
```
|
||||
|
||||
This guide should be accurate enough for:
|
||||
|
||||
- a new operator,
|
||||
- an external evaluator,
|
||||
- an implementation agent,
|
||||
- a design reviewer,
|
||||
- or a sponsor doing due diligence.
|
||||
|
||||
Required sections:
|
||||
|
||||
1. What Workbench is and is not.
|
||||
2. How to run it.
|
||||
3. The evidence model.
|
||||
4. Current route map from the route registry.
|
||||
5. What each route proves.
|
||||
6. What each route does not prove.
|
||||
7. Evidence subjects and address grammar.
|
||||
8. Command palette and keyboard model.
|
||||
9. Empty/error/loading doctrine.
|
||||
10. Proposal vs ratification boundary.
|
||||
11. Calibration / wrong=0 discipline.
|
||||
12. CORE-Logos / packs current state and next state.
|
||||
13. Known absences and follow-up items.
|
||||
|
||||
### Acceptance
|
||||
|
||||
- Route count matches code.
|
||||
- Calibration and Demos are included.
|
||||
- The guide distinguishes visible checks from actionable engineering flows.
|
||||
- Missing features are named, not implied.
|
||||
|
||||
---
|
||||
|
||||
## Deliverable 5 — Phase A residue ledger
|
||||
|
||||
Before Phase C, create a small checklist ledger that says whether each residue item is implemented, deferred, or superseded.
|
||||
|
||||
Known residue:
|
||||
|
||||
- density preferences
|
||||
- command palette route drift
|
||||
- landing route drift
|
||||
- deterministic DAG consumers beyond proposal chain
|
||||
- calibration evidence subject
|
||||
- UI/UX guide
|
||||
- route registry
|
||||
- B4 source tuple
|
||||
|
||||
### Acceptance
|
||||
|
||||
Each item has:
|
||||
|
||||
```text
|
||||
status: implemented | deferred | superseded | blocked
|
||||
reason
|
||||
next PR if any
|
||||
```
|
||||
|
||||
This avoids rediscovering the same gaps after each wave.
|
||||
|
||||
---
|
||||
|
||||
## No-go list
|
||||
|
||||
- No visual-only B4 leeway card.
|
||||
- No frontend inference of calibration license.
|
||||
- No route added in one place only.
|
||||
- No command help that advertises shortcuts that do not exist.
|
||||
- No hidden mutation or apply affordance.
|
||||
- No vague “soon” docs; every absence must be named as absent.
|
||||
- No Workbench route that cannot answer at least one ADR-0160 audit question.
|
||||
|
||||
---
|
||||
|
||||
## Implementation order
|
||||
|
||||
Recommended small PR sequence:
|
||||
|
||||
1. **B3.5-a — route registry**
|
||||
2. **B3.5-b — calibration evidence subject**
|
||||
3. **B3.5-c — B4 feasibility / schema audit**
|
||||
4. **B3.5-d — UI/UX guide**
|
||||
5. **B3.5-e — Phase A residue ledger**
|
||||
|
||||
B4 should not start until B3.5-c says the tuple exists or B4a creates it.
|
||||
|
||||
---
|
||||
|
||||
## Final design sentence
|
||||
|
||||
Workbench must not merely have many powerful screens. It must have one coherent evidence grammar.
|
||||
|
||||
B3.5 is the slice that makes the grammar true before the next layer speaks through it.
|
||||
Loading…
Reference in a new issue