@felixdotgo/aidlc-kit 0.0.1

package/docs/configuration.md

@@ -0,0 +1,72 @@
+# Configuration
+
+Each installed project owns its workflow configuration at `.agents/config.json`. It selects topology profiles, specification roots, safe verification commands, and local rules without changing the package-managed kernel. The package supports only Codex and Claude Code.
+
+## Minimal configuration
+
+```json
+{
+  "schemaVersion": 2,
+  "extends": ["topology/single"],
+  "specs": { "roots": ["docs/specs"] },
+  "commands": {
+    "test": { "command": "npm", "args": ["test"] },
+    "lint": { "command": "npm", "args": ["run", "lint"] }
+  },
+  "rules": { "include": [".agents/project/rules/*.md"] },
+  "risk": { "default": "normal" },
+  "context": { "maxChars": 16000 },
+  "agentState": {}
+}
+```
+
+Commands are stored as executable and argument arrays. Do not replace them with shell strings: this keeps execution inspectable and avoids accidental shell interpretation.
+
+G0, G1, and G2 always require explicit human approval. Configuration cannot auto-pass a gate.
+
+## Configuration layers
+
+Values resolve in this order, with the later applicable layer taking precedence:
+
+```text
+kernel → built-in topology → local profile parents/child → project config/rules → approved task decisions
+```
+
+Built-in topology profiles are:
+
+- `topology/generic`
+- `topology/single`
+- `topology/workspace`
+- `topology/git-submodules`
+
+Arrays are stable-deduplicated. Command keys are last-wins, so a project can replace a profile command intentionally. Validate the resolved profile chain with:
+
+```sh
+npx --package @felixdotgo/aidlc-kit@0.0.1 aidlc-workflow profile validate .
+```
+
+This command uses the npm package at version `0.0.1`. To run from a source checkout instead, see the [development guide](./development.md).
+
+## Rules, project data, and managed assets
+
+| Location | Ownership | Use it for |
+| --- | --- | --- |
+| `.agents/aidlc/` | Package managed | Kernel contracts, phases, schemas, and dependency-free runtime scripts. |
+| `.agents/data/` | Project owned | Lifecycle state, task artifacts, indexes, memory, and evidence. |
+| `.agents/project/` | Project owned | Profiles, rules, and project-specific evaluation material. |
+
+Keep business/domain rules in `.agents/project/rules/`. Do not edit managed kernel files to customise a project; a later installation or human-run upgrade may report conflicts for modified managed content.
+
+## Agent permissions
+
+The Codex adapter installs `.codex/config.toml` with `approval_policy = "on-request"` and `sandbox_mode = "workspace-write"`, plus `.codex/rules/aidlc.rules`. The execpolicy allowlists only the six lifecycle entry points under `node .agents/aidlc/scripts/`, allowing AI-DLC state transitions without granting general command approval. Each allowed lifecycle command must be run as its own exec invocation: joining commands with `&`, `&&`, `;`, or `|` creates shell command segments that are not covered by a single prefix rule. Codex loads this project config only after the user trusts the project; network access stays disabled unless the project separately enables it. Claude Code installs `.claude/settings.local.json` and phase skills that allow only `node .agents/aidlc/scripts/*`, so lifecycle state updates do not require repeated confirmation while general Bash commands remain unapproved.
+
+## Context and risk
+
+`context.maxChars` bounds a phase packet. The runtime preserves lifecycle instructions, approved decisions, and mandatory invariants; it fails clearly rather than silently truncating required contract content.
+
+Set the default risk level deliberately. Planning, migrations, cross-service contracts, and security-sensitive changes deserve a stronger reviewer or an explicit human decision even when the configuration default is normal.
+
+## Optional AI-DLC Coordination
+
+`mcp` is absent (or `{ "enabled": false }`) by default. An enabled configuration requires an HTTP(S) `endpoint` and non-empty `workspace`; it may also name a token environment variable, polling interval from 1,000 to 3,600,000 ms, and the enabled Jira/Trello/GitHub Issues preflight providers. See [AI-DLC Coordination service](./coordination-service.md) for the remote-authority and deployment contract.

package/docs/coordination-service.md

@@ -0,0 +1,42 @@
+# AI-DLC Coordination service
+
+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.
+
+## Safe setup
+
+Preview a configuration first. Outside an interactive terminal, provide all four selection flags.
+
+```sh
+npx --package @felixdotgo/aidlc-kit@0.0.1 aidlc-workflow mcp setup . --dry-run \
+  --deployment docker --storage sqlite --bind localhost --workspace engineering
+```
+
+This command uses the npm package at version `0.0.1`. 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:
+
+```sh
+docker compose --env-file .agents/aidlc-coordination/.env -f .agents/aidlc-coordination/compose.yaml up -d
+```
+
+Use SQLite only on the local Docker volume. Use PostgreSQL for multiple hosts. A network bind requires `MCP_STATE_AUTH_TOKEN` and TLS/reverse-proxy termination; never commit either the `.env` file or provider credentials.
+
+## State and synchronization contract
+
+When enabled, the remote workspace is canonical. Import/export is an explicit recovery or migration action; there is no background dual-write or local fallback during an outage. Clients pull a revision or poll `state_events_since`; the service provides neither realtime subscriptions nor push notifications.
+
+## Shared coordination board
+
+The opt-in service also provides a small workspace-scoped Kanban board that is separate from lifecycle state. Board tasks may link to an AI-DLC task ID or artifact, but board writes, comments, and claims cannot mutate lifecycle state, approve a gate, or rewrite project files.
+
+`board_get`, `board_apply`, `task_thread_get`, `task_comment_add`, `task_claim`, and `coordination_events_since` are bounded MCP tools. Tasks use `backlog`, `ready`, `in_progress`, `blocked`, `done`, or `cancelled`, plus priority, labels, assignees, and renewable one-minute-to-one-hour claims. Mutations require an expected board revision, idempotency key, actor ID, and role. A conflicting live claim is rejected.
+
+Threads are short append-only comments with author type, optional mentions, and `question`, `status`, `handoff`, or `decision` intent. They never carry credentials, hidden reasoning, general chat, or gate approvals. Clients poll compact cursor events, coalesce and debounce them, then read details only for assignment, mention, watched-task, explicit-user, or claim-expiry activity. A notice always requires a fresh revision check before action.
+
+Every `state_apply` write needs an `expectedRevision`, an `idempotencyKey`, and an absolute `clientProjectRoot`. The root is used only to format portable `nextActions` with absolute script paths and an explicit `--root`; it does not grant the server filesystem access or authority over that path. A stale revision returns the current projection for pull/rebase, and a retry with the same idempotency key returns the original committed result. Successful responses include `nextActions` for touched tasks so remote callers follow the same item loop and stop classifications as the local CLI.
+
+The service checks lifecycle invariants across the whole before/after snapshot, not only touched task IDs. Existing evidence is append-only: the prior evidence array must remain an exact structural prefix (compared field-wise, so re-serialization key order does not matter, while record order still does). A validated `blocked_on_user` wait cannot be deleted, and while a task waits its readiness-bearing state (items, decisions, artifacts, and every other non-evidence field) is frozen; only evidence may be appended. Leaving a wait requires, in the same mutation, one of: a passing approval for that exact gate, gate-bound cancellation diagnostic evidence with a non-empty source, or a sourced closure/handoff record (`closed`/`superseded` with closure metadata, or `paused` with handoff metadata). The one compatibility recovery mirrors the local CLI: an invalid wait at the gateless wrap phase may return to `active` with no appended evidence; it is not a human approval. A snapshot that requests or holds `blocked_on_user` while shared lifecycle predicates still require planning, items, verification, review, or an unexhausted repair bound is rejected. The `legacyG2Wait` repair-bound exemption marker is migration-owned: the service stamps it only when upgrading a stored pre-v4 row, and rejects any client mutation that creates or changes it. SQLite uses an immediate transaction and busy timeout; PostgreSQL locks the workspace row in a transaction.
+
+These guards keep remote history tamper-evident, but they do not authenticate approvals. The `source` on an approval record is provenance supplied by the client, not an authenticator: any client holding the shared token can append a well-formed approval and leave a wait. The service never runs the local `checkGate` against client artifacts (it has no access to `clientProjectRoot`), so gate predicates are enforced structurally at wait entry and through the parked-state freeze, not re-verified from artifacts at exit. Treat MCP approval records exactly like the local `gate approve --source` honor system, behind a token you protect.
+
+`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.

package/docs/development.md

@@ -0,0 +1,106 @@
+# Development guide
+
+This guide is for contributors to `@felixdotgo/aidlc-kit`. It covers local setup, source ownership, and the rules that keep the package runtime and installed workflow behaviour aligned.
+
+## Requirements and dependencies
+
+- Node.js 20.17 or newer is required by the package runtime.
+- npm installs the repository development dependencies.
+- `@inquirer/prompts` is the runtime dependency for interactive CLI prompts; installed lifecycle scripts remain dependency-free.
+- Development uses TypeScript and `@types/node` as declared in `package.json`.
+
+```sh
+npm install
+```
+
+Codex or Claude Code are optional for manually exercising real evaluator drivers. Ordinary build, lint, and unit-test work does not need external model credentials.
+
+## 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
+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
+docs/                        User, operator, and contributor documentation
+dist/                        Generated TypeScript and bundled assets; do not hand-edit
+```
+
+The asset build copies `assets/aidlc/` and `skills/` into `dist/assets/.agents/`. At install time, the package writes the workflow to a consumer project's `.agents/aidlc/` and `.agents/skills/` locations. Always state which of these three layouts—source, bundle, or installed project—you mean in code or documentation.
+
+## Local commands
+
+| Command | Purpose |
+| --- | --- |
+| `npm run build` | Rebuild bundled workflow assets and compile TypeScript into `dist/`. |
+| `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. |
+| `npm run release:check` | Run the repository release-evidence policy check. |
+
+Run the narrowest relevant test while iterating, then run `npm test` and `npm run lint` before handing off a non-trivial change. See [Testing and release](./testing-and-release.md) for the package smoke test and evaluator.
+
+## Local build and registry-free installation
+
+Use this fast smoke test to install workflow assets from the current checkout into a disposable consumer project. It invokes the freshly compiled CLI directly, so the consumer installation does not use `npm install`, `npx`, a published package, or an npm registry. Repository bootstrap and build still use npm and the dependencies already installed in this checkout.
+
+Run the following POSIX shell commands from the repository root:
+
+```sh
+AIDLC_REPO="$(pwd)"
+AIDLC_LOCAL_PROJECT="$(mktemp -d "${TMPDIR:-/tmp}/aidlc-local-project.XXXXXX")"
+
+npm run build
+node "$AIDLC_REPO/dist/src/cli.js" init "$AIDLC_LOCAL_PROJECT" --agent codex --dry-run
+node "$AIDLC_REPO/dist/src/cli.js" init "$AIDLC_LOCAL_PROJECT" --agent codex --yes
+node "$AIDLC_REPO/dist/src/cli.js" status "$AIDLC_LOCAL_PROJECT"
+node "$AIDLC_REPO/dist/src/cli.js" doctor "$AIDLC_LOCAL_PROJECT" --strict
+node "$AIDLC_LOCAL_PROJECT/.agents/aidlc/scripts/state.mjs" task list --root "$AIDLC_LOCAL_PROJECT"
+
+printf 'Local test project: %s\n' "$AIDLC_LOCAL_PROJECT"
+```
+
+The dry run previews the managed writes before `--yes` applies them. `status` describes the installed version and adapters, `doctor --strict` is the integrity check, and the final command confirms that the copied dependency-free lifecycle runtime can read its canonical state without the package CLI.
+
+Always use a new empty directory and inspect the printed path before removing it manually. Do not point this recipe at a real project unless its managed files and workflow state are intentional test targets. Reusing a fixture across package versions triggers the human-only upgrade protection by design. On Windows, use WSL or Git Bash for the snippet, or create a temporary directory in PowerShell and pass its absolute path to the same Node commands.
+
+This direct-`dist` smoke verifies the compiled checkout, but it does not verify the published file allowlist, package bin metadata, or tarball exclusions. Before release, also run the separate [package smoke test](./testing-and-release.md#package-smoke-test), which packs and extracts a local tarball without installing or fetching the package from a registry.
+
+## Run `npx` from a local package archive
+
+To test the package before release, create its `.tgz` archive and run the local archive with `npx`:
+
+```sh
+npm pack
+npx --package felixdotgo-aidlc-kit-0.0.1.tgz -- aidlc-workflow 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.
+
+## Ownership boundaries
+
+The package has three ownership layers:
+
+1. Package-managed kernel assets installed under `.agents/aidlc/`.
+2. Project-owned configuration, profiles, rules, and evaluation material under `.agents/project/`.
+3. Project-owned task state and derived data under `.agents/data/`.
+
+Do not introduce a second lifecycle board or hand-edit canonical state. The installed lifecycle scripts are dependency-free so consumer projects do not need this package to operate after installation.
+
+## Mirrored runtime behaviour
+
+The TypeScript implementation powers the package CLI. Installed projects use a dependency-free mirror under `assets/aidlc/scripts/`. Changes to shared lifecycle, state, gate, profile, or context behaviour must preserve parity between these paths and add coverage for both package and installed-runtime execution.
+
+Likewise, a public configuration or schema change must update its validator, JSON schema, installed assets, package inventory, documentation, and tests together.
+
+## Safe implementation rules
+
+- Resolve all project-relative paths through the shared path helpers; reject traversal and symlink escape.
+- Keep installation, migration, and upgrade plans deterministic and conflict-first.
+- Preserve project-owned configuration and state when changing managed assets.
+- Do not add remote profile discovery, runtime asset downloads, executable plugin hooks, registry checks, or shell-string command execution.
+- 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.

package/docs/operating-workflow.md

@@ -0,0 +1,87 @@
+# Operating the workflow
+
+`aidlc-kit` gives an agent a repeatable delivery lifecycle. It separates intent, design, implementation, and final review so a human explicitly approves the points where scope or risk changes.
+
+## Lifecycle at a glance
+
+```text
+request → clarify → G0 → plan → G1 → build and verify → G2 → wrap → done
+```
+
+| Stage | Result | Human action |
+| --- | --- | --- |
+| Clarify | Intent, scope, assumptions, and open questions | Approve G0. |
+| Plan | Design, decisions, work items, and verification plan | Resolve decisions and approve G1. |
+| Build | Approved change, verification, and adversarial review | Review the completed change at G2. |
+| Wrap | Delivery notes, lessons, and residual risk | Runs only after G2 approval. |
+
+An agent continues after each non-terminal transition and after every item or evidence mutation. Completing one work item is a progress update, not a turn boundary: the agent consumes the returned `nextAction` and continues through the remaining items, verification, and review. It stops only for a gate that is ready for human action, a durable blocker, a terminal non-success outcome, or successful completion.
+
+## Parallel workstreams
+
+At any phase, the lead agent may use the orchestration contract to delegate independent, bounded workstreams when the host has spare worker capacity. The lead keeps one slot, assigns explicit ownership and completion criteria, and integrates returned work before relying on it. It remains the only writer for task state, evidence, review artifacts, and gates. In build, a batch may contain only items with non-overlapping file/area ownership; shared surfaces, integration, task-wide verification, and adversarial review remain lead-owned. Parallel work never changes the approval or lifecycle requirements described below.
+
+## Starting work
+
+After installation, make a normal change request to the selected coding agent. For example:
+
+```text
+Add rate limiting to the login endpoint using the AI-DLC workflow.
+```
+
+The adapter creates a task, writes an intent brief, and presents G0. Do not treat a partial implementation as approved work before G1, and do not treat a passing test as approval at G2.
+
+## State and review artifacts
+
+Each installed project owns its data under `.agents/data/`. Package-managed workflow instructions live under `.agents/aidlc/`; project configuration, local rules, and evidence are project-owned. The package supports Codex and Claude Code only. Do not hand-edit lifecycle state: use the installed scripts instead.
+
+```sh
+node .agents/aidlc/scripts/state.mjs task list --limit 20
+node .agents/aidlc/scripts/state.mjs task find --query "rate limiting" --include-archive
+node .agents/aidlc/scripts/state.mjs task show <task-id>
+node .agents/aidlc/scripts/state.mjs task next <task-id>
+node .agents/aidlc/scripts/gate-view.mjs <task-id>
+```
+
+`task next` is the authoritative instruction for what happens next. `gate-view` renders the review packet consistently for G0, G1, and G2.
+
+Lifecycle options support both `--name value` and `--name=value` in any order. Invalid options and command shapes fail before lock or state access. From a project subdirectory, an omitted `--root` selects the nearest ancestor containing `.agents/aidlc/`; outside an installed project the command fails without creating `.agents`. Use explicit `--root` to select a different installed project.
+
+Every `state.mjs` and `task-next.mjs` command returns one JSON envelope `{ok, result, nextAction?}`. Rendering, gate-check, and context commands may produce Markdown or plain text. All failures use one-line `{ok: false, error}` records on stderr with typed exit codes (`1` expected, `2` continuation guard, `3` crash). During build, the action identifies the next `in_progress` or `todo` item; after all items are terminal it still returns `run_phase` until verification, adversarial review, and G2 preparation finish. Before any final response, the agent runs `task-next.mjs <task-id> --require-stop` and parses its machine-readable `continuation` object; exit code `2` (`continuation.code = CONTINUATION_REQUIRED`) means it must execute `continuation.command` instead of replying. This guard is detection, not hard prevention: no package-owned hook can intercept a message the model host has already emitted, so the residual risk is a premature final response that the host must recover from by running `task next <task-id>` in its very next turn and executing the returned command — never by re-approving a gate. Creating a new task while another is actionable is likewise fail-closed at the local CLI: `task create` rejects it until the agent passes the returned `--switch-from` acknowledgement with explicit user direction, which stamps a resume-marker diagnostic on the acknowledged task instead of mutating it. The optional AI-DLC Coordination service does not enforce this switch guard; remote `upsertTask`/`replaceState` can still add tasks alongside actionable work, so MCP-backed hosts rely on the adapter protocol for switch discipline.
+
+## Gates and approvals
+
+Approval is an explicit human action. When the agent receives an approval, it records the approval and advances the lifecycle atomically:
+
+```sh
+node .agents/aidlc/scripts/state.mjs gate approve <task-id> --gate <gate-name> --source "<explicit approval>"
+```
+
+Do not invent approvals or approve unresolved design decisions. Approval evidence can be created only by `gate approve`; generic evidence recording cannot manufacture it. A passing G1 approval starts a build boundary. Verification, adversarial review, and G2 approval used to enter wrap must all belong to the current boundary.
+
+`--source` records provenance; it is not authentication or proof of consent. The local CLI enforces lifecycle structure, while the host agent must call `gate approve` only in a later user turn that explicitly assents to the gate currently shown.
+
+A reopened plan invalidates the prior G1 and G2 approvals, resets every non-deferred build item to `todo`, and requires current-build verification and review. Evidence is append-only, so the runtime identifies the current boundary by evidence order instead of trusting timestamps. For each affected area, at least one `test` or `lint` result is required and the latest result of every verification kind present must pass; one kind cannot hide a failure in the other.
+
+Terminal archiving commits the immutable record before the compact catalog. A retry may recover the narrow interrupted-write window only when the catalog still proves the same task is active and the unreferenced record has the same stable identity. Other archive conflicts require investigation rather than overwrite. Rendered workplans are derived views and are replaced atomically under the same state lock when rendered by the standalone command.
+
+## Blocked work and successors
+
+`blocked_on_user` means a valid human gate is ready; wrap has no human gate and rejects it. The status command validates gate prerequisites before persisting it, and `gate-view` refuses to present an active or unready task. Ordinary exits from a validated human-gate wait require audited reason and source metadata plus diagnostic evidence; sourced closure and handoff records provide the corresponding terminal trail. The two compatibility paths are migration-stamped legacy G2 waits and recovery of an invalid `wrap`/`none` wait; neither is a human approval. The `legacyG2Wait` marker is written only by state-schema migration (`state.mjs state migrate` or a human-run installer upgrade), only exempts a still-ready pre-existing wait from the repair bound, and is cleared by every route out of the wait. Repair bounds are machine-enforced: three failed verify records per area or two failed review records in the current build flip `nextAction` to `blocked` and close G2 with `REPAIR_BOUND` until a durable handoff is recorded. It does not mean a failed change is waiting for a rubber stamp. When verification or review cannot pass, the workflow records a durable handoff and offers structured options.
+
+```sh
+node .agents/aidlc/scripts/state.mjs task handoff <task-id> --kind <kind> --reason "<reason>" --source "<evidence>"
+node .agents/aidlc/scripts/state.mjs task reopen <task-id> --to plan --reason "<reason>" --source "<explicit request>"
+node .agents/aidlc/scripts/state.mjs task close <task-id> --reason "<reason>" --source "<explicit request>"
+```
+
+If work continues in a fresh task, create that task at G0 and link it as a successor. `closed` and `superseded` are terminal non-success outcomes; they do not transfer approvals or imply a completed delivery.
+
+## Operational rules
+
+- The installed workflow never downloads runtime assets or checks a registry.
+- Only a human may initiate or apply workflow upgrades.
+- Keep task artifacts and verification evidence honest; a status label never substitutes for test or review evidence.
+- Put project-specific behaviour in project configuration or local rules, not in the package-managed workflow kernel.
+
+See [Configuration](./configuration.md) for project customisation and [Command reference](./command-reference.md) for package commands.

package/docs/testing-and-release.md

@@ -0,0 +1,113 @@
+# Testing and release
+
+Use the smallest relevant verification while developing, then complete the repository checks before a release review.
+
+## Standard verification
+
+```sh
+npm run build
+npm run lint
+npm test
+```
+
+`npm test` rebuilds the package before running compiled unit tests. The tests cover CLI and installer behaviour, state and gate transitions, migration safety, managed content, profiles/context, evaluator logic, and installed-runtime parity.
+
+If a test depends on child processes and a sandbox returns `EPERM`, rerun it in an appropriate local environment before deciding that the product failed.
+
+## Focused tests
+
+Build first, then invoke a compiled test file directly:
+
+```sh
+npm run build
+node --test dist/test/unit/installer.test.js
+```
+
+Choose the test closest to the changed boundary. For example, use installer tests for package inventory or documentation assertions, upgrade tests for migration semantics, and lifecycle-runtime tests when touching installed scripts. Continuation changes must also run `continuation-guard`, multi-item lifecycle runtime, context, and local/MCP lifecycle conformance coverage.
+
+## Package smoke test
+
+Release verification must exercise the tarball rather than the source tree. From the repository root, build and pack locally, extract the archive, then run the extracted CLI against a clean temporary consumer project.
+
+```sh
+AIDLC_PACK_DIR="$(mktemp -d /tmp/aidlc-pack.XXXXXX)"
+AIDLC_EXTRACT_DIR="$(mktemp -d /tmp/aidlc-extract.XXXXXX)"
+AIDLC_TEST_PROJECT="$(mktemp -d /tmp/aidlc-project.XXXXXX)"
+
+npm run build
+npm pack --pack-destination "$AIDLC_PACK_DIR"
+tar -xzf "$AIDLC_PACK_DIR/felixdotgo-aidlc-kit-0.0.1.tgz" -C "$AIDLC_EXTRACT_DIR"
+node "$AIDLC_EXTRACT_DIR/package/dist/src/cli.js" init "$AIDLC_TEST_PROJECT" --agent codex --dry-run
+node "$AIDLC_EXTRACT_DIR/package/dist/src/cli.js" init "$AIDLC_TEST_PROJECT" --agent codex --yes
+node "$AIDLC_EXTRACT_DIR/package/dist/src/cli.js" status "$AIDLC_TEST_PROJECT"
+node "$AIDLC_EXTRACT_DIR/package/dist/src/cli.js" doctor "$AIDLC_TEST_PROJECT" --strict
+```
+
+Keep the printed temporary paths until inspection is complete. Remove them manually afterwards. Do not reuse a smoke-test project for a different package version; the installer intentionally refuses implicit upgrades.
+
+Check that the tarball contains the public CLI, bundled assets, and documentation, but not `dist/dev/`, evaluator runners, evaluator schemas, or evaluator configuration.
+
+## Development-only evaluator
+
+The evaluator under `dev/evaluator/` is repository and CI infrastructure. It is compiled for tests but excluded from the published package.
+
+```sh
+npm run build
+node dist/dev/evaluator/cli.js list
+node dist/dev/evaluator/cli.js run --runner local-simulated
+```
+
+Runners exchange JSON, and reports capture transport, transcript, normalised events, usage, and diagnostics. Real Codex or Claude runs can consume credentials and model budget; they are not required for ordinary development verification.
+
+The release-eligible suite includes `build-multi-item-continuation`, which starts with three canonical build items and requires one agent run to complete all of them, record verification/review evidence, and stop only at a ready G2. This complements unit guards by exercising the model-facing continuation contract.
+
+The release checker validates required evidence according to the configured adapter policy. This repository's script uses the Codex-only policy:
+
+```sh
+npm run release:check
+```
+
+It reads local evaluation evidence from `.agents/project/release-eval.json` and fails closed if required evidence or integrity thresholds are missing.
+
+## Release readiness
+
+Before an authorised release, complete:
+
+1. `npm test`
+2. `npm run lint`
+3. The local tarball smoke test
+4. `npm run release:check`
+5. A review of the generated package contents and documentation links
+
+Publishing, tagging, committing, and pushing are separate human-authorised actions. A passing verification run is not delivery authority.
+
+## First npm publication
+
+The first release is `@felixdotgo/aidlc-kit@0.0.1`, with public access and the `latest` dist-tag. Complete the release checks and the project's human review gates before publishing.
+
+From the repository root, sign in to an npm account with permission to publish to the `@felixdotgo` scope and confirm the active account:
+
+```sh
+npm login --registry https://registry.npmjs.org
+npm whoami --registry https://registry.npmjs.org
+npm view @felixdotgo/aidlc-kit@0.0.1 version --registry https://registry.npmjs.org
+```
+
+An unpublished package normally returns `404` from `npm view`; that response does not establish scope ownership or publish permission. If `0.0.1` already exists, stop: npm versions cannot be overwritten. If `npm whoami` returns `401`, sign in again before publishing.
+
+After inspecting the local tarball and documentation, publish from the repository root:
+
+```sh
+npm publish --access public --tag latest --registry https://registry.npmjs.org
+```
+
+`prepublishOnly` runs the unit tests, lint, and evaluator release check before this command publishes. Complete any authentication or two-factor prompt from npm. The initial publication of a scoped package needs `--access public`; see the [npm scope documentation](https://docs.npmjs.com/cli/v11/using-npm/scope).
+
+Confirm the published version, dist-tag and artifact metadata:
+
+```sh
+npm view @felixdotgo/aidlc-kit@0.0.1 version dist.tarball dist.integrity --json --registry https://registry.npmjs.org
+npm view @felixdotgo/aidlc-kit dist-tags --json --registry https://registry.npmjs.org
+```
+
+Expect version `0.0.1`, a tarball URL and integrity value, and `latest` pointing to `0.0.1`. Git tags, GitHub releases, commits, and pushes require their own delivery authorisation.

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@felixdotgo/aidlc-kit",
+  "version": "0.0.1",
+  "description": "Install a local, agent-adapted AI-DLC workflow into a project.",
+  "keywords": [
+    "ai-dlc",
+    "ai-agent",
+    "workflow",
+    "claude-code",
+    "codex",
+    "developer-tools"
+  ],
+  "homepage": "https://github.com/felixdotgo/aidlc-kit#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/felixdotgo/aidlc-kit.git"
+  },
+  "bugs": {
+    "url": "https://github.com/felixdotgo/aidlc-kit/issues"
+  },
+  "author": "felixdotgo <nguyenthanhdat.js@gmail.com>",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "aidlc-workflow": "dist/src/cli.js"
+  },
+  "files": [
+    "dist/src",
+    "dist/assets",
+    "dist/services",
+    "README.md",
+    "DEVELOPMENT.md",
+    "docs",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "node scripts/build-assets.mjs && tsc -p tsconfig.json",
+    "test": "npm run build && node --test dist/test/unit/*.test.js",
+    "lint": "tsc --noEmit -p tsconfig.json",
+    "release:check": "node dist/dev/evaluator/release-check.js .agents/project/release-eval.json --adapters codex",
+    "prepublishOnly": "npm test && npm run lint && npm run release:check"
+  },
+  "engines": {
+    "node": ">=20.17"
+  },
+  "dependencies": {
+    "@inquirer/prompts": "^8.5.2"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^5.8.0"
+  }
+}