Documentation and migration notes for #236 reset

[devkade]

Summary

Document the #236 architecture reset and the relationship between Rust core, MCP control plane, Pi/TS facade, and legacy workflow surfaces.

Parent: #236

Scope

Update:

README.md
docs/architecture/taskstream-kernel.md
docs/architecture/core-adapter-boundary.md
docs/migration/legacy-ts-facades.md

Must explain

• Rust-first kernel decision.
• DDD over dogmatic Clean Architecture.
• Generic folders with ilchul-* package names.
• Core/adapters/facades boundary.
• Filesystem artifacts vs canonical DB state.
• Runtime output vs completion decision.
• Old roadmap issues are design reference, not active implementation owners.

Acceptance criteria

• README matches implementation.
• Docs state current SSOT: Ilchul Agent OS — MCP TaskStream control plane MVP #236 architecture, not aspirational legacy behavior.
• Old Kapi/RunContract/DAG language is framed as legacy/reference where applicable.

[devkade]

AI-understood issue summary

Issue #246 asks for documentation and migration notes that make the #236 architecture reset understandable and current. The implementation agent should update README.md and add the requested architecture/migration docs so readers understand the new Rust-first TaskStream kernel direction, the MCP control plane, the Pi/TypeScript facade boundary, and how older Kapi/RunContract/DAG roadmap language should now be treated as legacy/reference rather than the active implementation spine.

Why this issue is needed

• The current README still opens as # Kapi and describes a Pi-native thin workflow harness (README.md:1, README.md:3, README.md:7), while SSOT: Ilchul Agent OS — MCP TaskStream control plane MVP #236 defines the new SSOT identity as Ilchul with a Rust TaskStream authority kernel, MCP control-plane adapter, Pi/TS facade surface, and filesystem artifacts as projections.
• Existing docs already contain pieces of the migration story, but they are scattered: the naming policy distinguishes Ilchul product/docs vocabulary from stable Kapi compatibility surfaces (docs/ilchul-naming-policy.md:7-docs/ilchul-naming-policy.md:11), the runtime config doc preserves .kapi as historical state while routing active state to .ilchul (docs/ilchul-runtime-config.md:20-docs/ilchul-runtime-config.md:27), and the learning-runtime doc separates completion authority, runtime readiness authority, and advisory evaluation authority (docs/learning-runtime-boundaries.md:112-docs/learning-runtime-boundaries.md:119).
• The requested target docs are currently absent: docs/architecture/taskstream-kernel.md, docs/architecture/core-adapter-boundary.md, and docs/migration/legacy-ts-facades.md were not found in the checkout.

Why this issue may not be needed

• If Rust workspace scaffold + DDD core skeleton #238-End-to-end coding_test_fix TaskStream fixture #245 are intentionally expected to land first, writing definitive architecture docs now may get ahead of implementation. The conservative path is to label documents as the SSOT: Ilchul Agent OS — MCP TaskStream control plane MVP #236 reset design/migration contract where code is not yet present, rather than imply shipped Rust behavior.
• Some boundary material already exists in current docs: README explains the current TS-layer architecture (README.md:280-README.md:285), RunContract boundary (README.md:224-README.md:244), and project layout (README.md:287-README.md:307); docs/learning-runtime-boundaries.md also defines a future RunState envelope and authority separation (docs/learning-runtime-boundaries.md:21-docs/learning-runtime-boundaries.md:47, docs/learning-runtime-boundaries.md:74-docs/learning-runtime-boundaries.md:84). So the issue is mostly consolidation/realignment, not new product behavior.

Expected Outcome

• README.md clearly states the current SSOT: Ilchul Agent OS — MCP TaskStream control plane MVP #236 direction and distinguishes current TypeScript/Pi harness behavior from planned/active Rust TaskStream kernel work.
• New docs exist at:
  • docs/architecture/taskstream-kernel.md
  • docs/architecture/core-adapter-boundary.md
  • docs/migration/legacy-ts-facades.md
• The docs preserve compatibility guidance: no broad kapi -> ilchul replacement, .kapi is preserved as historical local state, existing /kapi-*/kapi-agent surfaces remain stable unless a scoped migration issue changes them (docs/ilchul-naming-policy.md:29-docs/ilchul-naming-policy.md:39, docs/ilchul-naming-policy.md:57-docs/ilchul-naming-policy.md:69).
• Old Kapi/RunContract/DAG language is explicitly framed as legacy/current facade/reference material where appropriate, not as the new Rust kernel authority.

Evidence-based implementation plan

Feasibility and research findings

In-repo reusable material exists; this is not a blank documentation effort:

• Current README has the old/current Kapi overview and durable-mode/CLI details to preserve as compatibility/facade context (README.md:1-README.md:7, README.md:32-README.md:35, README.md:52-README.md:65).
• Current README already states important authority boundaries: worker output is incomplete until reviewed and verified (README.md:102-README.md:108), RunContract is a projection over existing state rather than a durable contract.json authority (README.md:224-README.md:226), and external GitHub workflow semantics stay outside core (README.md:234-README.md:236).
• Current architecture/test code reinforces domain/adapter separation: domain code must not import Pi, filesystem, tmux, git commands, or process adapters (test/architecture.test.ts:84-test/architecture.test.ts:90), and external capabilities are expected in adapters/presentation (test/architecture.test.ts:97-test/architecture.test.ts:104).
• Current TS domain/application code can be cited as legacy/current-facade contrast: RunContractView is projected from WorkflowState (src/domain/run-contract.ts:49-src/domain/run-contract.ts:86), TaskGraph models DAG execution primitives (src/domain/task-graph.ts:21-src/domain/task-graph.ts:43), and createLocalWorkflowService wires the TypeScript service/store/adapters (src/adapters/workflow-service-factory.ts:7-src/adapters/workflow-service-factory.ts:18).
• The repository currently has no active Rust workspace files in this checkout (find . ... -name Cargo.toml -o -name '*.rs', excluding references//node_modules, returned no files), so docs should not claim shipped Rust crates unless implementation lands before this docs change.

External references checked:

• Model Context Protocol Architecture overview - https://modelcontextprotocol.io/docs/learn/architecture — MCP is a client/server architecture with hosts, clients, and servers, a JSON-RPC data layer, lifecycle management, and server primitives for tools/resources/prompts; useful for explaining why SSOT: Ilchul Agent OS — MCP TaskStream control plane MVP #236 uses MCP as a control-plane adapter rather than embedding UI/runtime concerns in core.
• Workspaces - The Cargo Book - https://doc.rust-lang.org/cargo/reference/workspaces.html — Cargo workspaces manage one or more packages together, can share a root Cargo.lock, support crates/* members, and allow shared package metadata/dependencies/lints; useful for documenting the generic folder / ilchul-* crate-name decision.
• Use Domain Analysis to Model Microservices - Microsoft Learn - https://learn.microsoft.com/en-us/azure/architecture/microservices/model/domain-analysis — DDD emphasizes ubiquitous language, bounded contexts, and architecture characteristics matched to domain concerns; useful for explaining “DDD over dogmatic Clean Architecture.”

no suitable external library found

Step-by-step instructions for the implementation agent

1. Start from SSOT: Ilchul Agent OS — MCP TaskStream control plane MVP #236 as the source-of-truth text. Use SSOT: Ilchul Agent OS — MCP TaskStream control plane MVP #236’s identity, MVP boundary, core/adapter boundary, language, storage, event, TaskStream/RunState, and non-goal sections as the content source. Keep the important phrase Turn은 실행의 리듬이고, Event는 책임의 기록이다. if it helps explain event-vs-turn semantics.
2. Update README.md without erasing compatibility facts. Replace or preface the opening Kapi-centric narrative (README.md:1-README.md:7) with an Ilchul/SSOT: Ilchul Agent OS — MCP TaskStream control plane MVP #236 reset overview, then keep existing Kapi CLI/workflow details as current legacy/TS facade compatibility where still true (README.md:52-README.md:65, README.md:269-README.md:285). Add links to the three new docs in the Layout section near existing docs links (README.md:287-README.md:307).
3. Create docs/architecture/taskstream-kernel.md. It should explain the Rust-first kernel decision, MVP shape (one human goal -> one TaskStream -> one Run -> one RuntimeSession -> evidence -> verification -> kernel-owned CompletionDecision), canonical DB/store vs filesystem artifacts, event policy, completion authority, and why runtime output is evidence/input rather than completion authority. Ground the storage/artifact discussion in existing .ilchul and artifact-boundary docs (docs/ilchul-runtime-config.md:20-docs/ilchul-runtime-config.md:75) and current authority separation (docs/learning-runtime-boundaries.md:112-docs/learning-runtime-boundaries.md:119).
4. Create docs/architecture/core-adapter-boundary.md. It should define core-owned concepts, adapter-owned concepts, dependency rules, and DDD-style boundary rationale. Use the current TS architecture/test boundaries as continuity evidence (README.md:280-README.md:285, test/architecture.test.ts:84-test/architecture.test.ts:104) and external DDD/MCP references above to explain the intended Rust core + MCP adapter split.
5. Create docs/migration/legacy-ts-facades.md. It should classify existing TS/Pi/Kapi/RunContract/DAG surfaces as: retained compatibility surfaces, legacy/reference docs, facade/shim candidates, and non-authoritative implementation references. Cite the naming policy compatibility matrix (docs/ilchul-naming-policy.md:29-docs/ilchul-naming-policy.md:39, docs/ilchul-naming-policy.md:90-docs/ilchul-naming-policy.md:97) and current TS surfaces such as src/cli/runctl-cli.ts:56-src/cli/runctl-cli.ts:80, src/domain/run-contract.ts:49-src/domain/run-contract.ts:86, and src/domain/task-graph.ts:21-src/domain/task-graph.ts:43.
6. Avoid broad renames. The implementation agent should not mechanically replace Kapi with Ilchul. Keep persisted/workflow identifiers, slash commands, and kapi-agent naming unless issue Documentation and migration notes for #236 reset #246 explicitly scopes a textual explanation change; this follows docs/ilchul-naming-policy.md:7-docs/ilchul-naming-policy.md:11 and docs/ilchul-naming-policy.md:99-docs/ilchul-naming-policy.md:108.
7. Validation recommended for a docs-only implementation: run npm run check and at least a targeted docs/contract grep for stale claims. If the docs update touches README claims that tests assert indirectly, run npm test or the targeted test/architecture.test.ts suite. If the implementation agent adds Rust workspace docs before Rust files exist, explicitly phrase them as architecture/reset docs, not as shipped behavior.

Risks / assumptions surfaced by research

• Risk: README may become aspirational if it says the Rust kernel already exists. Current checkout has no Rust files outside references, so use current/future wording carefully.
• Risk: Legacy Kapi docs are still useful for users of existing /kapi-* workflows; deleting or renaming them broadly would violate the naming policy.
• Risk: Issue Documentation and migration notes for #236 reset #246 depends on SSOT: Ilchul Agent OS — MCP TaskStream control plane MVP #236 and overlaps with Rust workspace scaffold + DDD core skeleton #238-End-to-end coding_test_fix TaskStream fixture #245. If those implementation issues land first, the docs should be reconciled with actual crate/module names before closing.

Assumptions / human decisions to resolve asynchronously before /approve

• Assumption: The docs should describe the SSOT: Ilchul Agent OS — MCP TaskStream control plane MVP #236 reset as the active architecture direction, while clearly labeling unimplemented Rust crates as planned/design unless already present when implementation starts.
• Assumption: No public command rename is requested by Documentation and migration notes for #236 reset #246; /kapi-*, kapi-agent, and existing serialized workflow IDs remain compatibility surfaces.
• Human decision before /approve if desired: whether the README title should immediately change from # Kapi to # Ilchul, or use a transitional title such as # Ilchul (Kapi compatibility harness).

Approval reminder

Implementation starts only after a human comment containing /approve. The implementation agent will use this comment as its self-contained handoff.

Agent Signature

[devkade]

AI-understood issue summary

Issue #246 is a docs/migration slice for the #236 architecture reset. The implementation agent should update README.md and create/update the requested architecture docs so the repo explains the Rust-first TaskStream kernel, MCP control plane, Pi/TypeScript facade boundary, filesystem-artifact vs canonical-store split, runtime-output vs completion-decision distinction, and legacy status of older Kapi/RunContract/DAG roadmap language.

Why this issue is needed

• Current README still presents the shipped product primarily as “Kapi,” a Pi-native TypeScript workflow harness (README.md:1, README.md:3, README.md:7), while SSOT: Ilchul Agent OS — MCP TaskStream control plane MVP #236 defines the active Ilchul/Rust TaskStream reset.
• Existing docs already contain reusable constraints that should be preserved: Ilchul is product/docs/brand vocabulary, broad kapi -> ilchul replacement is forbidden, and .ilchul is active storage while .kapi remains historical local state (docs/ilchul-naming-policy.md:7, docs/ilchul-naming-policy.md:10, docs/ilchul-naming-policy.md:11).
• Existing architecture-adjacent docs already separate runtime/advisory signals from completion authority (docs/learning-runtime-boundaries.md:80, docs/learning-runtime-boundaries.md:102, docs/learning-runtime-boundaries.md:106, docs/learning-runtime-boundaries.md:116; docs/runcontract-presets.md:11, docs/runcontract-presets.md:12). Documentation and migration notes for #236 reset #246 should carry those distinctions into the SSOT: Ilchul Agent OS — MCP TaskStream control plane MVP #236 Rust/MCP framing.
• Research found that docs/architecture/ and docs/migration/ are absent in this checkout, so the requested docs will need to be created.

Why this issue may not be needed

• Some boundary docs already exist (docs/ilchul-naming-policy.md, docs/learning-runtime-boundaries.md, docs/runcontract-presets.md, README runtime/supervisor sections). If SSOT: Ilchul Agent OS — MCP TaskStream control plane MVP #236 implementation is still changing, broad docs could drift quickly.
• Current code/package metadata still reflects the pre-SSOT: Ilchul Agent OS — MCP TaskStream control plane MVP #236 TypeScript/Pi harness and compatibility surfaces (package.json:2, package.json:8, package.json:9; src/domain/run-contract.ts:3, src/domain/run-contract.ts:86). Docs must avoid implying the Rust kernel/MCP server already ships unless implementation exists.

Expected Outcome

A reader should understand that #236 is the active architecture direction; Rust core owns TaskStream state, evidence, verification, and completion decisions; MCP is the control-plane adapter; Pi/TS is a facade/runtime adapter; filesystem files are artifacts/projections rather than canonical authority; runtime output is only evidence/candidate output; and old Kapi/RunContract/DAG roadmap language is legacy/reference unless explicitly re-homed under #236.

Evidence-based implementation plan

Feasibility grounded in research

Reusable in-repo material exists:

• Naming/migration policy: docs/ilchul-naming-policy.md:7, docs/ilchul-naming-policy.md:8, docs/ilchul-naming-policy.md:10, docs/ilchul-naming-policy.md:57, docs/ilchul-naming-policy.md:59, docs/ilchul-naming-policy.md:65, docs/ilchul-naming-policy.md:92, docs/ilchul-naming-policy.md:93, docs/ilchul-naming-policy.md:94.
• Current runtime/supervisor behavior: README.md:54, README.md:84, README.md:90, README.md:104, README.md:105, README.md:107, README.md:108.
• RunContract/projection boundary: README.md:224, README.md:226, README.md:230, README.md:236, README.md:238, README.md:242; docs/runcontract-presets.md:3, docs/runcontract-presets.md:5, docs/runcontract-presets.md:11, docs/runcontract-presets.md:12, docs/runcontract-presets.md:16.
• Completion/evidence authority language: docs/learning-runtime-boundaries.md:38, docs/learning-runtime-boundaries.md:39, docs/learning-runtime-boundaries.md:74, docs/learning-runtime-boundaries.md:80, docs/learning-runtime-boundaries.md:84, docs/learning-runtime-boundaries.md:102, docs/learning-runtime-boundaries.md:106, docs/learning-runtime-boundaries.md:116.
• Current compatibility code facts: package.json:2, package.json:8, package.json:9; src/domain/run-contract.ts:3, src/domain/run-contract.ts:49, src/domain/run-contract.ts:86, src/domain/run-contract.ts:244; src/adapters/registry-store.ts:10, src/adapters/registry-store.ts:75, src/adapters/registry-store.ts:100.

External references found:

• Workspaces - The Cargo Book - https://doc.rust-lang.org/cargo/reference/workspaces.html
• Tools - Model Context Protocol - https://modelcontextprotocol.io/specification/draft/server/tools
• Overview - Model Context Protocol - https://modelcontextprotocol.io/specification/2025-06-18/basic/index
• SQLite As An Application File Format - https://www.sqlite.org/appfileformat.html
• Appropriate Uses For SQLite - https://www.sqlite.org/whentouse.html
• Domain-Driven Design Reference: Definitions and Pattern Summaries - https://www.domainlanguage.com/wp-content/uploads/2016/05/DDD_Reference_2015-03.pdf

No suitable external library found. This is a documentation/migration-notes issue; external material is useful as reference documentation, not as a dependency to add.

Step-by-step plan for the implementation agent

1. Preserve current compatibility facts before editing. Public runtime CLI is ilchul with internal runctl naming (README.md:54, package.json:8), and kapi-review remains an external review integration (package.json:9). Do not do broad rename churn; the policy forbids broad kapi -> ilchul replacement (docs/ilchul-naming-policy.md:10).
2. Create docs/architecture/taskstream-kernel.md, docs/architecture/core-adapter-boundary.md, and docs/migration/legacy-ts-facades.md if still absent.
3. Update README.md with a concise SSOT: Ilchul Agent OS — MCP TaskStream control plane MVP #236 architecture-reset section that distinguishes current shipped TypeScript/Pi harness behavior from the approved Rust-first TaskStream direction, then links to the new docs. Keep the README aligned with current implementation.
4. In docs/architecture/taskstream-kernel.md, document the SSOT: Ilchul Agent OS — MCP TaskStream control plane MVP #236 flow: one human goal → one TaskStream → one Run → one RuntimeSession → evidence → verification → kernel-owned CompletionDecision. Reuse the completion-authority language from docs/learning-runtime-boundaries.md:80, docs/learning-runtime-boundaries.md:102, docs/learning-runtime-boundaries.md:106, and docs/learning-runtime-boundaries.md:116. Use Cargo workspace/package terminology consistently with Workspaces - The Cargo Book.
5. In docs/architecture/core-adapter-boundary.md, define core-owned concepts (TaskStream, Run, RuntimeSession, EvidenceRecord, VerificationResult, CompletionDecision) and adapter-owned surfaces (MCP, SQLite store adapter, filesystem artifact adapter, Pi/TS facade, future runtimes). Align with existing “external meanings stay in adapters” language (docs/runcontract-presets.md:13, README.md:236, README.md:238) and MCP terminology from the MCP docs above.
6. In docs/migration/legacy-ts-facades.md, explain that existing Kapi/RunContract/DAG/Pi TypeScript surfaces are compatibility facades or design references unless re-homed under SSOT: Ilchul Agent OS — MCP TaskStream control plane MVP #236. Reuse naming-policy and product-audit constraints (docs/ilchul-naming-policy.md:31, docs/ilchul-naming-policy.md:39, docs/ilchul-naming-policy.md:92, docs/ilchul-naming-policy.md:94; docs/product-name-audit.md:101, docs/product-name-audit.md:103, docs/product-name-audit.md:104, docs/product-name-audit.md:107, docs/product-name-audit.md:112, docs/product-name-audit.md:113).
7. Make filesystem-vs-canonical-state language precise. Existing repo behavior uses .ilchul filesystem registry/artifact roots today (README.md:84, README.md:195, src/adapters/registry-store.ts:10, src/adapters/registry-store.ts:75, src/adapters/registry-store.ts:100), while SSOT: Ilchul Agent OS — MCP TaskStream control plane MVP #236 points toward a kernel-owned canonical SQLite/store with filesystem artifacts/projections. Document this as migration direction, not already-shipped behavior. Use the SQLite references above for wording.
8. Add a legacy roadmap note/table saying older roadmap issues such as Kapi → Ilchul RunContract Harness roadmap #114, Roadmap: objective-driven learning parallel runtime harness #167, Design: define integration, repair, and supersession semantics #190, Sub-roadmap: DAG runtime phase 4 — IntegrationCandidate and repair loop #195, and Design: define safe cleanup semantics for leftover issue worker tmux sessions #201 are design references, not active implementation owners, unless SSOT: Ilchul Agent OS — MCP TaskStream control plane MVP #236 explicitly adopts a piece of them.
9. Verification before PR closeout: run at least npm run check, perform a readthrough/grep for overclaims like “Rust kernel is shipped” if not true, and run any relevant docs/quality script from package.json:24-package.json:34 if the implementation agent changes doc tooling or examples.

Risks / assumptions from research

• Overclaim risk: current repo is still TypeScript/Pi-centered (package.json:5, package.json:16, package.json:17), so docs must label Rust/MCP as SSOT: Ilchul Agent OS — MCP TaskStream control plane MVP #236 direction until implemented.
• Compatibility risk: broad renames could break /kapi-*, persisted workflow IDs, review checks, or historical state (docs/ilchul-naming-policy.md:31, docs/ilchul-naming-policy.md:33, docs/ilchul-naming-policy.md:35, docs/ilchul-naming-policy.md:65).
• Authority-model risk: RunContract/TaskGraph docs can accidentally become a second source of truth; existing docs say projections summarize/steer but must not become durable authority (docs/runcontract-presets.md:11, docs/runcontract-presets.md:12; docs/learning-runtime-boundaries.md:84).

Assumptions / human decisions to resolve asynchronously before /approve

• Assumption: SSOT: Ilchul Agent OS — MCP TaskStream control plane MVP #236 is the SSOT for this docs slice even where current code is still TypeScript-first.
• Assumption: creating docs/architecture/ and docs/migration/ is acceptable because the issue names files there and those directories are absent.
• Optional human decision: whether README should be retitled from # Kapi to # Ilchul in this docs-only slice, or keep # Kapi plus a SSOT: Ilchul Agent OS — MCP TaskStream control plane MVP #236 reset notice until Rust/MCP code lands.

Approval reminder

Implementation starts only after a human comment containing /approve. At that point, the implementation agent will use this comment as the self-contained handoff.

Agent Signature

[devkade]

/approve