Rust workspace scaffold + DDD core skeleton

[devkade]

Summary

Create the Rust workspace scaffold for the #236 TaskStream kernel rewrite.

The scaffold should establish generic workspace folder names, ilchul-* package names, and a DDD-style core module layout without implementing full runtime orchestration.

Parent: #236

Scope

Create the Rust workspace shape:

crates/
  core/          # package: ilchul-core
  store/         # package: ilchul-store
  artifacts/     # package: ilchul-artifacts
  mcp/           # package: ilchul-mcp
  runtime-pi/    # package: ilchul-runtime-pi
  cli/           # package: ilchul-cli
  testkit/       # package: ilchul-testkit

Initial implementation focus:

crates/core

Core modules:

task_stream/
run/
contract/
evidence/
verification/
completion/
artifact/
event/
runtime/
ports/
services/

Constraints

• Use Rust-first implementation.
• Do not move or delete existing TS/Pi surfaces in this issue.
• Workspace folder names stay generic.
• Rust package/crate names use ilchul-*.
• Domain type names stay generic.
• Do not add Pi/GitHub/Discord/CLI transport concerns to core.

Acceptance criteria

• Workspace Cargo.toml exists.
• crates/core exists with package name ilchul-core.
• Placeholder crates exist or are intentionally deferred with documented reason.
• Core module layout reflects DDD domain concepts, not framework layers.
• cargo test --workspace passes.
• cargo fmt --check passes.
• Existing TS verification is not broken.
• README documents the Rust workspace scaffold and SSOT: Ilchul Agent OS — MCP TaskStream control plane MVP #236 boundary.

[devkade]

AI-understood issue summary

Issue #238 is the first scaffold slice for parent #236. It should add a Rust workspace with generic folder names, ilchul-* package names, and an initial ilchul-core DDD-style module skeleton for TaskStream authority concepts. This issue should not implement runtime orchestration, move/delete existing TypeScript/Pi surfaces, or leak Pi/GitHub/Discord/CLI transport details into core.

Why this issue is needed

• Parent SSOT: Ilchul Agent OS — MCP TaskStream control plane MVP #236 defines a Rust-first TaskStream authority kernel, but this repo currently has no root Cargo.toml and no crates/ directory in the working tree research pass. The existing package is TypeScript/Node-first (package.json:2, package.json:6, package.json:24).
• The existing repo already documents a hard core/adapter boundary: core owns generic run/evidence/artifact/completion concepts, while runtime/presentation adapters decide how to expose them (README.md:230, README.md:231, README.md:234). The Rust scaffold gives SSOT: Ilchul Agent OS — MCP TaskStream control plane MVP #236 a place to enforce that boundary before behavior lands.
• Existing architecture docs say src/domain is pure and excludes Pi/filesystem/tmux/git/process dependencies (README.md:282), and existing tests enforce that domain code stays independent from Pi, filesystem, tmux, git commands, and process adapters (test/architecture.test.ts:84, test/architecture.test.ts:86, test/architecture.test.ts:87, test/architecture.test.ts:88, test/architecture.test.ts:89). The Rust core should inherit that boundary.
• Naming policy already says reusable core identifiers should stay semantic rather than product-prefixed (docs/ilchul-naming-policy.md:7, docs/ilchul-naming-policy.md:9, docs/ilchul-naming-policy.md:43, docs/ilchul-naming-policy.md:55). Rust workspace scaffold + DDD core skeleton #238 can establish the intended distinction: folder/module/type names generic, crate/package names ilchul-*.

Why this issue may not be needed

• If the only near-term goal were to keep the existing Pi/Kapi harness working, the current TypeScript repo already has workflow definitions, state/evidence types, tests, and verification gates (src/domain/workflows.ts:10, src/domain/types.ts:197, package.json:34).
• If the Rust rewrite were still speculative, a docs-only boundary could be enough for now. However, SSOT: Ilchul Agent OS — MCP TaskStream control plane MVP #236 explicitly makes Rust the implementation language for the kernel, so a small scaffold issue is useful because it avoids mixing scaffold churn with later domain invariants, storage, MCP, and runtime adapter behavior.
• This issue should remain intentionally small. If implementation starts adding SQLite, MCP tools, Pi runtime dispatch, or completion-decision logic, it will likely duplicate later child issues and make Rust workspace scaffold + DDD core skeleton #238 harder to review.

Expected Outcome

After approval and implementation, the implementation agent should leave the repo with:

1. A root Rust workspace Cargo.toml.
2. crates/core as package ilchul-core.
3. Either placeholder crates for store, artifacts, mcp, runtime-pi, cli, and testkit, or README-documented deferral explaining why this scaffold slice only creates core.
4. ilchul-core module declarations for task_stream, run, contract, evidence, verification, completion, artifact, event, runtime, ports, and services.
5. Minimal compile-safe Rust skeletons only: generic domain names, no transport-specific core types, no runtime orchestration.
6. cargo test --workspace, cargo fmt --check, and existing TS verification (npm run verify) passing.
7. README updated to document the Rust workspace scaffold and the SSOT: Ilchul Agent OS — MCP TaskStream control plane MVP #236 boundary.

Evidence-based implementation plan

Feasibility from research

In-repo reusable material:

• Existing RunContract docs already define the generic ownership split this Rust core should mirror: core owns generic run state projection, evidence records, artifact references, completion criteria, and quality hints; adapters own display/transport (README.md:226, README.md:230, README.md:231, README.md:234).
• Existing TypeScript domain types provide vocabulary to migrate carefully later, including lifecycle statuses, workflow IDs, artifacts, evidence records, worker refs, and workflow state (src/domain/types.ts:1, src/domain/types.ts:13, src/domain/types.ts:49, src/domain/types.ts:72, src/domain/types.ts:74, src/domain/types.ts:197). Use these as naming/context references only; do not port behavior into Rust workspace scaffold + DDD core skeleton #238.
• Existing TaskGraph/domain code shows the repo’s preference for explicit generic concepts and ports such as Decomposer, Scheduler, WorkerRuntime, Verifier, and GateEngine (src/domain/task-graph.ts:21, src/domain/task-graph.ts:37, src/domain/task-graph.ts:41, src/domain/task-graph.ts:60, src/domain/task-graph.ts:77, src/domain/task-graph.ts:93). This supports the requested ports/ and services/ core module names.
• Existing architecture tests enforce semantic, non-product-prefixed generic names in internal helpers (test/architecture.test.ts:64, test/architecture.test.ts:66, test/architecture.test.ts:67, test/architecture.test.ts:68, test/architecture.test.ts:69, test/architecture.test.ts:70, test/architecture.test.ts:71) and domain independence from adapter/process dependencies (test/architecture.test.ts:84, test/architecture.test.ts:86, test/architecture.test.ts:87, test/architecture.test.ts:88, test/architecture.test.ts:89). The Rust core scaffold should add equivalent tests or at least avoid violating these rules.
• Existing verification is npm run verify, which runs tests, typecheck, unused checks, and quality budgets (package.json:34; README.md:359, README.md:361, README.md:365). Rust workspace scaffold + DDD core skeleton #238 must keep this green in addition to new Cargo checks.
• Existing README layout docs must be updated when new repo structure appears; current layout has no crates/ entry (README.md:287, README.md:289, README.md:301, README.md:302, README.md:303, README.md:304, README.md:305, README.md:306).

External sources investigated:

• Cargo supports workspaces as collections of packages managed together, with a root [workspace], members, shared Cargo.lock, and common target output: Workspaces - The Cargo Book - https://doc.rust-lang.org/cargo/reference/workspaces.html.
• Cargo workspace members can be declared with paths/globs such as members = ["member1", "path/to/member2", "crates/*"], which supports the requested crates/<name> layout: Workspaces - The Cargo Book - https://doc.rust-lang.org/cargo/reference/workspaces.html.
• cargo test is the official Cargo test runner, and workspace testing should be invoked through Cargo for all workspace packages: cargo test - The Cargo Book - https://doc.rust-lang.org/cargo/commands/cargo-test.html.
• cargo fmt formats Rust bin/lib files using rustfmt, and the Rustfmt README documents cargo fmt --all -- --check; the issue’s cargo fmt --check acceptance can be satisfied by using the project’s chosen command consistently: cargo fmt - The Cargo Book - https://doc.rust-lang.org/cargo/commands/cargo-fmt.html and GitHub - rust-lang/rustfmt: Format Rust code - https://github.com/rust-lang/rustfmt.
• Rust package/crate/module terminology supports a package with one library crate rooted at src/lib.rs, which fits crates/core/src/lib.rs declaring the requested modules: Packages and Crates - The Rust Programming Language - https://doc.rust-lang.org/book/ch07-01-packages-and-crates.html.
• I also saw scaffold/generator-style crates/tools in search results, but this issue only needs a small, repo-specific workspace skeleton. no suitable external library found

Concrete step-by-step plan for the implementation agent

1. Start from a clean read of the current tree. Before editing, inspect git status --short and preserve any pre-existing human changes. This planning pass observed unrelated local changes, so the implementation agent should not overwrite them.
2. Add the root Rust workspace manifest. Create Cargo.toml with a virtual [workspace], resolver = "2", and explicit members for the crates that are created in this slice. Use Cargo workspace semantics from Workspaces - The Cargo Book - https://doc.rust-lang.org/cargo/reference/workspaces.html.
3. Create crates/core as ilchul-core. Add crates/core/Cargo.toml with [package] name = "ilchul-core", a current Rust edition, and no unnecessary dependencies. Add crates/core/src/lib.rs as the crate root per Packages and Crates - The Rust Programming Language - https://doc.rust-lang.org/book/ch07-01-packages-and-crates.html.
4. Declare the DDD concept modules. In lib.rs, declare exactly the issue’s modules: task_stream, run, contract, evidence, verification, completion, artifact, event, runtime, ports, and services. Keep names generic, consistent with the naming policy (docs/ilchul-naming-policy.md:43, docs/ilchul-naming-policy.md:55).
5. Keep module contents minimal and compile-safe. Add placeholder module files with concise module docs and, only if needed for compiler/test usefulness, empty marker structs/enums or simple tests. Do not add Pi/GitHub/Discord/CLI fields, process/tmux concepts, SQLite, MCP, or runtime dispatch behavior in this issue; existing repo boundaries show those belong outside core (README.md:231, README.md:234, README.md:282; test/architecture.test.ts:84).
6. Decide placeholder crates conservatively. Either create empty compile-safe crates for store, artifacts, mcp, runtime-pi, cli, and testkit with package names ilchul-store, ilchul-artifacts, ilchul-mcp, ilchul-runtime-pi, ilchul-cli, and ilchul-testkit, or document in README that they are deferred because Rust workspace scaffold + DDD core skeleton #238’s implementation focus is crates/core. If placeholder crates are created, keep them dependency-free unless Rust requires otherwise.
7. Add README documentation. Update README layout/architecture sections to add Cargo.toml, crates/, crates/core, and any placeholder/deferred crates. Explicitly state the SSOT: Ilchul Agent OS — MCP TaskStream control plane MVP #236 boundary: Rust core is for generic TaskStream authority concepts; TypeScript/Pi surfaces remain in place and are not moved by Rust workspace scaffold + DDD core skeleton #238. This follows the repo instruction to keep README aligned with implementation.
8. Add lightweight scaffold tests if useful. A simple Rust unit test can assert exported marker constants/types exist for each module, but avoid testing future behavior not implemented in this scaffold. If no Rust behavior exists beyond module compilation, cargo test --workspace itself is enough for the Rust scaffold gate.
9. Run verification in this order. Run cargo fmt --check or cargo fmt --all -- --check consistently with the manifest, then cargo test --workspace, then npm run verify. Existing TS verification is required by issue acceptance and currently maps to npm test && npm run check && npm run check:unused && npm run quality:budgets (package.json:34).
10. Keep the final implementation report scoped. Report created files, whether placeholder crates were created or deferred, Cargo/TS verification output, and any remaining risks. Do not claim runtime/MCP/storage/completion behavior exists unless implemented by later issues.

Risks / assumptions surfaced by research

• The scaffold is feasible with Cargo alone; adding a scaffold generator would add unnecessary dependency/supply-chain surface for little benefit. no suitable external library found
• If the implementation creates placeholder crates for every listed package, cargo test --workspace and cargo fmt --check should include them all. If it defers placeholders, README must state the reason because the issue explicitly allows placeholders to be “intentionally deferred with documented reason.”
• The repo’s existing TypeScript architecture tests enforce domain purity only for src/domain; they will not automatically protect the new Rust core. The implementation agent should avoid adapter leakage by construction, and a later issue can add Rust-specific architecture checks if needed.
• Parent SSOT: Ilchul Agent OS — MCP TaskStream control plane MVP #236 says DDD should guide module boundaries but not dogmatic Clean Architecture. For Rust workspace scaffold + DDD core skeleton #238, that means concept modules first, not domain/application/infrastructure folders.

Assumptions / human decisions to resolve asynchronously before /approve

• Assumption: use Cargo’s default current stable edition for new crates unless maintainers specify an MSRV/edition before /approve.
• Assumption: placeholder crates are acceptable if dependency-free and clearly marked as future-adapter surfaces; otherwise they may be deferred with README documentation.
• No blocking human decision is required before /approve for a conservative scaffold-only implementation.

Approval reminder

Implementation starts only after a human comment containing /approve. This is a planning handoff only; the implementation agent will use this comment plus the issue body/discussion as its starting context.

Agent Signature

[devkade]

/approve