@felixdotgo/aidlc-kit 0.1.1 → 0.2.0

package/docs/coordination-service.md

@@ -1,7 +1,7 @@
 # AI-DLC Coordination service
 
 > [!WARNING]
-> The coordination service (and the end-to-end loop that builds on it) is **experimental and unfinished**: it contains known bugs and rough edges. The package is pre-1.0 (`0.x`), so setup flags, `mcp.*`/`loop.*` configuration, endpoints, environment variables, and storage behaviour can change incompatibly in any release before `1.0.0`. Do not treat it as a stable dependency yet.
+> The coordination service and the **fleet** end-to-end loop are **experimental and still under active development**: they contain known bugs and rough edges. The package is pre-1.0 (`0.x`), so setup flags, `mcp.*`/`loop.*` configuration, endpoints, environment variables, and storage behaviour can change incompatibly in any release before `1.0.0`. Do not treat it as a stable dependency yet.
 
 The optional AI-DLC Coordination service is a separate Docker-deployable authority for a workflow workspace. It is disabled by default: without an enabled `mcp` block, installed lifecycle scripts remain local and make no network calls.
 
@@ -10,11 +10,11 @@ The optional AI-DLC Coordination service is a separate Docker-deployable authori
 Preview a configuration first. Outside an interactive terminal, provide all four selection flags.
 
 ```sh
-npx --package @felixdotgo/aidlc-kit@0.1.1 aidlc-kit mcp setup . --dry-run \
+npx --package @felixdotgo/aidlc-kit@0.2.0 aidlc-kit mcp setup . --dry-run \
   --deployment docker --storage sqlite --bind localhost --workspace engineering
 ```
 
-This command uses the npm package at version `0.1.1`. To run from a source checkout instead, see the [development guide](./development.md).
+This command uses the npm package at version `0.2.0`. To run from a source checkout instead, see the [development guide](./development.md).
 
 Remove `--dry-run` and confirm to create `.agents/aidlc-coordination/` and update `.agents/config.json`. Setup does not start Docker. Copy `.env.example` to a secret-managed `.env`, review it, then start explicitly:
 
@@ -70,16 +70,18 @@ node .agents/aidlc/scripts/remote-state.mjs gate approve <task-id> --snapshot <s
 
 The second command checks that the snapshot remains current and uses the reviewer-only service operation. At G2 it also verifies that the snapshot's integration commit still matches the live remote branch. Protect the integration branch against writes outside the lead so it cannot change between verification and approval. The review message is the source provenance; the token authenticates the reviewer client, while the client operator remains responsible for using the user's actual later reply.
 
-Run the packaged fleet process on a lead machine and worker machines under a process supervisor. Point every process to the same `AIDLC_FLEET_URL` and workspace, but give each its own role token. On the lead, set `AIDLC_FLEET_WORKER_IDS` (comma-separated), `AIDLC_FLEET_INTEGRATION_BRANCH`, and optionally `AIDLC_FLEET_AGENT` (`codex`, `claude`, or `opencode`); `AIDLC_FLEET_WORKER_PROVIDERS` can override the provider per worker. The `job_schedule` tool accepts the same three agent values, but worker containers reject `opencode` with `OpenCode workers require file-based credentials and are not available in isolated containers yet`. The explicit blocker is reported when the job executes; there is no silent host fallback. On each worker, set its matching `AIDLC_FLEET_WORKER_ID` and `AIDLC_FLEET_WORKTREES_ROOT`:
+Run the packaged fleet process on a lead machine and worker machines under a process supervisor. Point every process to the same `AIDLC_FLEET_URL` and workspace, but give each its own role token. On the lead, set `AIDLC_FLEET_WORKER_IDS` (comma-separated), `AIDLC_FLEET_INTEGRATION_BRANCH`, and optionally `AIDLC_FLEET_AGENT` (`codex`, `claude`, or `opencode`); `AIDLC_FLEET_WORKER_PROVIDERS` can override the provider per worker. The `job_schedule` tool accepts the same three agent values, and worker containers run all of them, including `opencode` (authenticated from the environment key matching the `AIDLC_OPENCODE_MODEL` prefix: `openai/` → `OPENAI_API_KEY`, `anthropic/` → `ANTHROPIC_API_KEY`, otherwise `OPENCODE_API_KEY`). On each worker, set its matching `AIDLC_FLEET_WORKER_ID`, `AIDLC_FLEET_WORKTREES_ROOT`, and `AIDLC_FLEET_PROJECT_ROOT`. The worker's provider comes from `AIDLC_FLEET_WORKER_AGENT` (or `AIDLC_FLEET_AGENT`, or its entry in `AIDLC_FLEET_WORKER_PROVIDERS`); a worker with a provider rejects jobs for another provider. `AIDLC_WORKER_DOCKER_IMAGE` is optional when the provider is known: the image is then `loop.workerImage[provider]` from the project config or the default `aidlc-worker-<provider>:local`, built from the packaged Dockerfile when missing. Either way it is resolved to its immutable `sha256:` image id before any job runs:
 
 ```sh
 node dist/services/aidlc-coordination/src/fleet-run.mjs feature <feature-id>
 node dist/services/aidlc-coordination/src/fleet-run.mjs worker
 ```
 
-`coordinator <task-id>` runs one task. `--once` processes a bounded polling pass for supervision or diagnostics. Defaults are four worker jobs per feature, five-minute leases with one-minute heartbeat, 12 turns per phase or assignment, 10 minutes per turn, and two consecutive stalls. Set `AIDLC_FLEET_MAX_WORKERS`, `AIDLC_FLEET_LEASE_MS`, `AIDLC_FLEET_HEARTBEAT_MS`, `AIDLC_FLEET_MAX_TURNS`, `AIDLC_FLEET_TURN_TIMEOUT_MS`, and `AIDLC_FLEET_MAX_STALL_TURNS` to change them. Feature mode dispatches dependency-ready tasks in order from one integration checkout; independent items within the active task can use several machines concurrently. After a lost worker report, the lead checks remote Git state and stops for reconciliation if the outcome is ambiguous. Set `AIDLC_FLEET_CODE_ONLY_RETRY=1` to permit an automatic retry only after the prior turn's timeout window has elapsed and Git confirms that no branch was published.
+`coordinator <task-id>` runs one task. `--once` processes a bounded polling pass for supervision or diagnostics. Defaults are four worker jobs per feature, five-minute leases with one-minute heartbeat, 12 turns per phase or assignment, 10 minutes per turn, and two consecutive stalls. Set `AIDLC_FLEET_MAX_WORKERS`, `AIDLC_FLEET_LEASE_MS`, `AIDLC_FLEET_HEARTBEAT_MS`, `AIDLC_FLEET_MAX_TURNS`, `AIDLC_FLEET_TURN_TIMEOUT_MS`, and `AIDLC_FLEET_MAX_STALL_TURNS` to change them. Feature mode dispatches dependency-ready tasks in order from one integration checkout; independent items within the active task can use several machines concurrently. The coordinator never dispatches two items whose owned paths overlap by path segment (`src` overlaps `src/a.ts`, not `srcx`) at the same time; the later item waits for a following pass. With `MCP_FLEET_ENABLED=1`, the service also refuses to approve the Approve plan gate for a plan with such overlaps or with unscoped open items (`PARTITION_OVERLAP`, `PARTITION_SCOPE` are errors). After a lost worker report, the lead checks remote Git state and stops for reconciliation if the outcome is ambiguous. Set `AIDLC_FLEET_CODE_ONLY_RETRY=1` to permit an automatic retry only after the prior turn's timeout window has elapsed and Git confirms that no branch was published.
 
-The coordinator and feature commands return when a task reaches a human gate; feature mode stops before dispatching further tasks. After the reviewer acts, restart the command to continue. Command events and command-failure diagnostics report status and exit code without the command text or its output. Worker progress observes changes to file content as well as paths.
+The coordinator and feature commands return when a task reaches a human gate; feature mode stops before dispatching further tasks. After the reviewer acts, restart the command to continue.
+
+For unattended operation on the lead machine, use the shared loop daemon instead of a hand-run supervisor: `aidlc-kit loop start --mode fleet` preflights the service and the remote integration branch, then runs the supervisor for each fleet loop-owned task (created with `aidlc-kit loop intake --mode fleet` or the dashboard **New task**) until its next gate, releases the supervisor lease, and re-claims the task on a later poll once the reviewer has approved. The daemon takes `loop.limits` and `loop.pollMs` from `.agents/config.json` as defaults for the `AIDLC_FLEET_*` limits, and never passes `AIDLC_FLEET_REVIEWER_TOKEN` to a lead or worker process. See the [loop runbook](./loop-runbook.md#fleet-multi-machine). Command events and command-failure diagnostics report status and exit code without the command text or its output. Worker progress observes changes to file content as well as paths.
 
 ## Shared coordination board
 
@@ -96,3 +98,13 @@ The service checks lifecycle invariants across the whole before/after snapshot,
 In default shared-token mode, these guards keep remote history tamper-evident but do not authenticate approvals: `source` remains provenance supplied by a client. Fleet mode binds separate lead, worker, and reviewer credentials to server-side roles, and only a reviewer credential can call the atomic gate approval tool. The service cannot inspect client project artifacts, so the lead must run local artifact checks before publishing a review snapshot; the service enforces structural gate readiness and snapshot revision at approval.
 
 `work_item_request` is intentionally only a credential-free preflight for Jira, Trello, or GitHub Issues. It reports the required environment variable names and never returns a reusable token, Authorization header, or token-bearing URL. External updates remain opt-in and must be made outside the lifecycle transaction.
+
+## Service health, logging, and image
+
+The service exposes an unauthenticated, static `GET /healthz` that returns `200 {"ok":true}` without reading state, version, or workspace data. It is registered before the auth middleware and is used by the container `HEALTHCHECK` and compose healthchecks.
+
+Every request emits one compact JSON line to stderr on response finish, of the form `{"ts":...,"method":...,"path":...,"status":...,"principal":...,"ms":...}` (principal is the fleet principal id when present, otherwise omitted). Logging never includes headers, request bodies, Authorization headers, or tokens.
+
+The McpServer version is read from the `version` field of the `package.json` next to the service root (`new URL("../package.json", import.meta.url)`), falling back to `"0.0.0-dev"` when missing or unreadable. In source checkouts the service package has no version field, so the fallback applies; the bundled image receives the package version through build-time injection.
+
+The container image is now built in two stages (both `node:24-bookworm-slim`, so the `better-sqlite3` ABI matches), installs dependencies in the build stage, and runs as the non-root `node` user with a `HEALTHCHECK` against `/healthz`. The compose `aidlc-coordination` and `fleet-coordination` services also define matching healthchecks.

package/docs/design-decisions.md

@@ -0,0 +1,83 @@
+# Design decisions (ADR-lite)
+
+Numbered decisions adopted by the project. Each entry records context, decision, and consequences. Cross-reference [Architecture](./architecture.md) for module boundaries and source-to-consumer flow.
+
+## D1. Dual lifecycle cores with conformance instead of codegen
+
+- **Context:** Installed projects must run lifecycle scripts with no dependencies; the package CLI itself is TypeScript and needs types.
+- **Decision:** Keep two cores — TypeScript in `src/state.ts` and a dependency-free ESM mirror in `assets/aidlc/scripts/lib/store.mjs` plus a committed byte-identical copy in `services/aidlc-coordination/src/lifecycle-core.mjs` — enforced by `lifecycle-core-conformance` (byte-identity + property/fuzz) rather than codegen.
+- **Consequences:** Parity is checked, not generated; a change to one core requires `npm run sync-core` and conformance tests. Cheaper than a build-time codegen step in a no-dep runtime.
+
+## D2. Single JSON state with file lock and archive catalog
+
+- **Context:** The workflow is local-first with no registry or database dependency in consumer projects.
+- **Decision:** Canonical state is one JSON file (`.agents/data/state/aidlc-state.json`) serialized by a file lock (`.aidlc-state.lock` + guard), with terminal records archived under `.agents/data/state/backups/` and digest-verified.
+- **Consequences:** Simple backup/restore and git diffing; contention is explicit and bounded by the 5s/30s lock defaults; not suited to high-concurrency multi-writer workloads beyond the lock.
+
+## D3. Append-only evidence with append-order boundaries
+
+- **Context:** Verification/review outcomes must be auditable and not rewritten by later runs.
+- **Decision:** Evidence is append-only; current-build boundaries are defined by append order, not wall-clock timestamps.
+- **Consequences:** Re-running a check appends a new record; "latest" means latest in append order. Tampering requires rewriting the whole state file, which the lock and digest checks make detectable.
+
+## D4. Human-only upgrades
+
+- **Context:** Workflow upgrades touch managed assets and state; silent or automated upgrades risk data loss.
+- **Decision:** `upgrade` rejects `--yes`/`--force`, requires an interactive TTY, and asks the human to type the target version. No background checks or postinstall.
+- **Consequences:** Upgrades are auditable and intentional; CI cannot auto-upgrade; rollback uses the upgrade journal.
+
+## D5. Local-first / no-registry policy
+
+- **Context:** Consumer projects must operate offline; status/doctor must not phone home.
+- **Decision:** `remoteUpdates: false` by default; status and doctor never consult a registry. Fleet is opt-in and separately deployed.
+- **Consequences:** No surprise network calls; version drift is detected locally; fleet authority is explicit via `AIDLC_FLEET_URL`.
+
+## D6. Compact code style in the installed kernel
+
+- **Context:** Phase packets have a 16,000-character budget; installed scripts must fit.
+- **Decision:** The installed kernel uses compact style (phase-packet budget 16,000 chars); package and service code do not follow it.
+- **Consequences:** Two style regimes; contributors must not "pretty-print" installed scripts in ways that bloat packets; mandatory sections are never truncated.
+
+## D7. Machine-enforced repair bounds
+
+- **Context:** Repair loops can run indefinitely without a hard stop.
+- **Decision:** Three failed verify records per affected area, or two failed review records, in the current build flip `nextAction` to `blocked` and add a `REPAIR_BOUND` error to the Review implementation gate check.
+- **Consequences:** The model cannot self-approve past the bound; a durable handoff is required. Legacy G2 waits migrated by schema v4 are exempt once.
+
+## D8. Assignment records are operational metadata
+
+- **Context:** Worker assignment state must not become a second lifecycle authority.
+- **Decision:** Assignment records (`.agents/data/assignments/`) are operational metadata only; canonical task state remains the authority.
+- **Consequences:** Assignment corruption or loss does not invalidate the task; reconciliation (`assignment.mjs reconcile`) is required before dispatch.
+
+## D9. Configured commands as executable + args arrays
+
+- **Context:** Shell strings are unsafe and non-portable.
+- **Decision:** Project-configured commands are stored and executed as executable + args arrays; shell strings are rejected.
+- **Consequences:** No shell injection; commands must be invoked explicitly; cross-platform behaviour is predictable.
+
+## D10. Task language `vi` / `en`
+
+- **Context:** Task artifacts and prompts need a declared language; broader i18n is not yet justified.
+- **Decision:** Task language is restricted to `vi` or `en`; further extensibility is deferred.
+- **Consequences:** New languages require a schema and conformance change; existing tasks keep their declared language.
+
+## D11. Optional `$schema` reference in generated config
+
+- **Context:** Offline-first tooling needs schema validation without network.
+- **Decision:** Generated config may include a relative `$schema` reference pointing at the local schema; it is optional.
+- **Consequences:** Editors get validation offline; missing reference degrades gracefully.
+
+## D12. Timing-safe comparison for all coordination auth
+
+- **Context:** Non-fleet coordination endpoints must not leak tokens via timing.
+- **Decision:** Non-fleet coordination auth uses the same timing-safe comparison as the fleet path.
+- **Consequences:** One auth implementation; no fast-path bypass; consistent with the service's credential model.
+
+## How to add a decision
+
+1. Record the decision in canonical state via `decision set` so it is tracked with the task that introduced it.
+2. Cite the source (file, PR, or task id) and present it at Approve plan (G1) for review.
+3. Append a numbered entry here following the Context / Decision / Consequences shape, and link from [Architecture](./architecture.md) when it changes a boundary.
+
+See [Architecture](./architecture.md) for the module and ownership boundaries these decisions protect.

package/docs/development.md

@@ -15,12 +15,23 @@ npm install
 
 Codex, Claude Code, or OpenCode are optional for manually exercising real evaluator drivers. Ordinary build, lint, and unit-test work does not need external model credentials. OpenCode driver runs also need `AIDLC_OPENCODE_MODEL` set to a `provider/model[#variant]` value.
 
+## Platform support
+
+Node.js 20.17 or newer is required on every platform. Linux and macOS are fully supported and tested. Windows is best-effort: win32 path separators are handled in `src/state/guards.ts`, `src/profiles.ts`, and the installed `assets/aidlc/scripts/lib/store.mjs`/`context-runtime.mjs`, and the state lock uses `process.kill(pid, 0)` for liveness; the lock and path handling are not exercised on Windows in CI. Loop and fleet features require Docker and a POSIX shell (`loop-local-workers.mjs` rejects non-Linux hosts).
+
+| Platform | Status | Notes |
+| --- | --- | --- |
+| Linux | Supported | Full CI coverage; Docker worker isolation available. |
+| macOS | Supported | Full test coverage; POSIX shell recipes apply. |
+| Windows | Best-effort | Use WSL or Git Bash for the local build recipe; lock/path code handles win32 separators but is untested. |
+| Loop / fleet | Linux only | Requires Docker + POSIX shell; `AIDLC_TEST_WORKER_IMAGE`/`AIDLC_WORKER_DOCKER_IMAGE` for e2e. |
+
 ## Repository layout
 
 ```text
 assets/aidlc/                Source workflow contracts, schemas, and installed scripts
 skills/                      Source thin phase adapters
-src/                         TypeScript package CLI, installer, lifecycle, profiles, and migrations
+src/                         TypeScript package CLI (src/cli/), installer + shared planning core, lifecycle domain (src/model/, src/state/), profiles, and migrations
 dev/evaluator/               Development-only evaluator harness and runners
 scripts/build-assets.mjs     Bundles workflow assets for package distribution
 test/unit/                   Unit and installed-runtime parity tests
@@ -35,6 +46,7 @@ The asset build copies `assets/aidlc/` and `skills/` into `dist/assets/.agents/`
 | Command | Purpose |
 | --- | --- |
 | `npm run build` | Rebuild bundled workflow assets and compile TypeScript into `dist/`. |
+| `npm run sync-core` | Copy `assets/aidlc/scripts/lib/store.mjs` to `services/aidlc-coordination/src/lifecycle-core.mjs` byte-identically. |
 | `npm run lint` | Type-check without emitting files. |
 | `npm test` | Build, then run every compiled unit test with Node's test runner. |
 | `node --test dist/test/unit/<file>.test.js` | Run a focused compiled test after building. |
@@ -74,7 +86,7 @@ To test the package before release, create its `.tgz` archive and run the local
 
 ```sh
 npm pack
-npx --package felixdotgo-aidlc-kit-0.1.1.tgz -- aidlc-kit init .
+npx --package felixdotgo-aidlc-kit-0.2.0.tgz -- aidlc-kit init .
 ```
 
 `npx` runs the archive without publishing it. Run the command from the directory containing the archive. Use a disposable project instead of `.` if you do not want the command to write workflow files into the current directory.
@@ -95,6 +107,8 @@ The TypeScript implementation powers the package CLI. Installed projects use a d
 
 Likewise, a public configuration or schema change must update its validator, JSON schema, installed assets, package inventory, documentation, and tests together.
 
+The dual-core sync rule: after editing `assets/aidlc/scripts/lib/store.mjs`, run `npm run sync-core` so `services/aidlc-coordination/src/lifecycle-core.mjs` stays byte-identical.
+
 ## Code style and conventions
 
 Adopted as the project baseline (approved decision `D1-convention-standard` on task `refactor-source-readability`):
@@ -118,3 +132,14 @@ Adopted as the project baseline (approved decision `D1-convention-standard` on t
 - Treat human-gated lifecycle transitions as atomic, auditable state operations.
 
 Read [Architecture](./architecture.md) before changing a module boundary, migration, installed script, or bundle layout.
+
+## Contributing to prompt assets
+
+Prompt assets are the installed workflow contracts under `assets/aidlc/` (notably `orchestrator.md` and `phase-*.md`). They feed the phase packets generated by `context.mjs`.
+
+- Keep them compact: the default phase-packet budget is 16,000 characters (`config.context.maxChars`). Optional rules and diagnostics are omitted first; the next-action contract, full phase contract, approved decisions, safety/spec anchors, task state, and applicable latest evidence are mandatory and are never truncated — if they do not fit, packet generation fails instead.
+- Heading invariants are enforced by `gate-check.mjs`:
+  - Intent (`G0_confirm`): `## 📋 Problem`, `## 🗺️ Affected areas`, `## 💭 Assumptions`, `## ❓ Open questions`, `## 🎯 Scope`.
+  - Design (`G1_review`): `## 🧩 Solution per affected area`, `## 📌 Spec traceability`, `## 🔗 Cross-service contracts`, `## ⚠️ Risks / edge cases`.
+- When changing contracts, run `npm run release:check` (`--adapters opencode`) and the evaluator suite; update docs and tests in the same change.
+- Never duplicate canonical agent instructions in overview docs; point to the installed assets instead. See [Design decisions](./design-decisions.md) (D6) for the compact-style rationale.