@felixdotgo/aidlc-kit 0.0.1

package/DEVELOPMENT.md

@@ -0,0 +1,31 @@
+# Contributing to aidlc-kit
+
+This file is the short entry point for maintainers and contributors. Detailed guidance lives in [`docs/`](./docs/README.md) so that user setup, system operation, and repository development can evolve independently.
+
+## Local bootstrap
+
+Requirements: Node.js 20 or newer and npm.
+
+```sh
+npm install
+npm test
+npm run lint
+```
+
+## Contributor documentation
+
+- [Development guide](./docs/development.md) — dependencies, repository layout, implementation boundaries, and local commands.
+- [Testing and release](./docs/testing-and-release.md) — focused tests, package smoke test, evaluator, and release readiness.
+- [Architecture](./docs/architecture.md) — module ownership, data flow, and installed-runtime parity.
+- [Configuration reference](./docs/configuration.md) — profiles, rules, Codex/Claude permissions, and project-owned configuration.
+
+## Documentation policy
+
+- Keep `README.md` focused on package requirements and setup.
+- Add operational and system guidance to the relevant page in `docs/`.
+- Update command/configuration examples and their tests in the same change as a public contract.
+- Do not duplicate canonical agent instructions from `assets/aidlc/` in overview documentation.
+
+## Delivery boundary
+
+Running verification does not authorise publishing, tagging, committing, or pushing. Those actions require separate human approval.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,59 @@
+# aidlc-kit
+
+`@felixdotgo/aidlc-kit` installs a local AI-DLC workflow into an existing project. The workflow gives coding agents a shared task lifecycle, explicit human review gates, and project-owned state and rules.
+
+It is deliberately local-only: workflow assets are bundled with the package, `remoteUpdates` is `false`, and normal status checks never contact a registry.
+
+## Requirements
+
+- Node.js 20.17 or newer.
+- An existing project directory.
+- Codex or Claude Code.
+
+## Quick start
+
+Run these commands from your existing project's directory to preview the installation, then apply it:
+
+```sh
+npx --package @felixdotgo/aidlc-kit@0.0.1 aidlc-workflow init . --agent codex --dry-run
+npx --package @felixdotgo/aidlc-kit@0.0.1 aidlc-workflow init . --agent codex --yes
+```
+
+`npx` may ask permission to download the package on first use. These examples pin version `0.0.1`. After installation, the project's lifecycle scripts run locally without `npx` or a registry connection.
+
+Use the adapter that matches the coding tool:
+
+| Tool | `--agent` value | Installed entry point |
+| --- | --- | --- |
+| Codex | `codex` | `AGENTS.md` |
+| Claude Code | `claude` | `CLAUDE.md` and phase skills |
+
+Use `--all` to install both supported adapters. Codex installs workspace-write sandboxing with on-request approvals and a project execpolicy that permits only AI-DLC lifecycle scripts; trust the project before starting Codex so that it loads the project configuration. Claude Code installs a local permission allowlist for the same lifecycle-script command prefix without granting general Bash access. Use `--force --yes` only for an initial installation when replacing an unmanaged conflicting file is intentional.
+
+Confirm the installed project locally:
+
+```sh
+npx --package @felixdotgo/aidlc-kit@0.0.1 aidlc-workflow status .
+npx --package @felixdotgo/aidlc-kit@0.0.1 aidlc-workflow doctor . --strict
+```
+
+## Documentation
+
+The detailed documentation is organised by task and audience:
+
+- [Documentation index](./docs/README.md) — choose the right guide.
+- [Operating the workflow](./docs/operating-workflow.md) — lifecycle, state, gates, and blocked work.
+- [Configuration](./docs/configuration.md) — project configuration, profiles, rules, and adapters.
+- [Command reference](./docs/command-reference.md) — every package CLI command and safety constraint.
+- [Development](./docs/development.md) — local contributor setup, source layout, and implementation rules.
+- [Testing and release](./docs/testing-and-release.md) — verification, evaluator, package smoke test, and release readiness.
+- [Architecture](./docs/architecture.md) — package boundaries and the source-to-installed flow.
+- [AI-DLC Coordination service](./docs/coordination-service.md) — opt-in Docker/remote coordination, security, and polling contract.
+
+## Safety note
+
+Only a human may initiate or apply a workflow upgrade. `upgrade` rejects `--yes` and `--force`, requires an interactive terminal, and asks the human to type the target package version. See the [command reference](./docs/command-reference.md#upgrade) before changing an existing installation.
+
+## License
+
+MIT

package/dist/assets/.agents/aidlc/conventions.md

@@ -0,0 +1,68 @@
+# AI-DLC v1 Conventions
+
+## Canonical data
+
+Schema v4 is one authoritative store with multiple records: `.agents/data/state/aidlc-state.json` keeps active task state plus a compact archive catalog; immutable terminal records live under `.agents/data/state/archive/` and are verified by digest. `.agents/data/lessons/index.json` is a rebuildable cache, never a source of truth. `.agents/data/memory/agentic-memory.json` is a separate project-owned advisory registry, with explicit promotion/retirement audit data; it is never lifecycle state or a substitute for project rules. Use bounded `task list`, `task find`, and `task show <task-id>` commands; do not persist `BOARD.md` or another editable state projection. Intent, design, and workplan prose remain Markdown review artifacts under a stable task directory keyed by `task_id`.
+
+Never edit review artifacts to change state. Use `node .agents/aidlc/scripts/state.mjs`, then run `node .agents/aidlc/scripts/render.mjs <task-id>` when a refreshed workplan is needed.
+
+## Task lifecycle
+
+```text
+clarify/G0_confirm → plan/G1_review → build/G2_codereview → wrap/none → done/none
+                                      ↘ paused/handoff → reopened plan, closed, or superseded → fresh successor G0
+```
+
+Each transition requires the preceding approval evidence. Build additionally requires every decision to be `approved`, `changed`, or `dropped`. The latest passing G1 approval starts the current build boundary. Wrap requires current-build verification, current-build review, and current-build G2 approval; evidence from an older build boundary cannot advance a reopened task.
+
+Verification is evaluated independently for each affected area and each `test` or `lint` kind recorded after the current build boundary. At least one verification kind must exist per area, and the latest record of every kind present must pass. A lint pass cannot hide a test failure, or vice versa.
+
+`blocked_on_user` is reserved for a gate that is structurally ready and waiting for explicit human approval; wrap has no human gate, so it is rejected there. Every route that leaves a human gate wait, including `paused`, requires the audited form `task status <id> --status <active|paused> --mode audited --reason <reason> --source <source>`, which records a gate-bound diagnostic evidence entry, or a sourced closure/handoff command that leaves its own terminal trail. Entering `paused` from `active` requires the same audited form and records a `Paused while active` diagnostic; resuming `paused → active` needs no audit metadata. `task archive <id> --reason <reason> --source <source>` is the sourced completion alias of `task transition --to done`: it applies the same transition checks and records an `Archive to done` diagnostic. Exactly two compatibility paths exist and neither is a human approval: a migration-stamped legacy G2 wait (the `legacyG2Wait` marker is written only by schema migration and only exempts a still-ready wait from the repair bound; runtime commands consume and clear it) and the command-driven recovery of an invalid `wrap`/`none` wait back to `active`. A real blocker or exhausted repair bound uses `task handoff` with `--kind` exactly one of `repair_exhausted`, `review_exhausted`, `g2_failed`, `release_failed`, `structural_change`, or `other`. Every durable handoff exposes `create_successor`, `supersede`, and `close`; build-phase handoffs additionally expose `reopen_g1`. Reopening G1 resets every non-deferred build item to `todo`. `closed` and `superseded` are terminal non-success outcomes that preserve the phase where work stopped; only `done` is successful completion. A successor is created as a fresh G0 task, then linked atomically with `task supersede`; it never inherits approvals or evidence.
+
+Lifecycle commands that end or redirect work require an explicit reason and source:
+
+```sh
+node .agents/aidlc/scripts/state.mjs task handoff <id> --kind <kind> --reason <reason> --source <source>
+node .agents/aidlc/scripts/state.mjs task reopen <id> --to plan --reason <reason> --source <source>
+node .agents/aidlc/scripts/state.mjs task close <id> --reason <reason> --source <source>
+node .agents/aidlc/scripts/state.mjs task supersede <id> --successor <fresh-id> --reason <reason> --source <source>
+```
+
+Decision states:
+
+- `unresolved`: build is blocked.
+- `approved`: implement the proposed choice.
+- `changed`: implement the recorded resolution.
+- `dropped`: explicitly out of scope.
+
+## Evidence
+
+Evidence kinds are `approval`, `spec`, `test`, `lint`, `review`, and `diagnostic`; results are `pass`, `fail`, or `skip`. Approval evidence is created only by atomic `gate approve`; the generic `evidence add` command rejects `approval`. A skipped verification must state residual risk. Evidence is append-only during a task; corrections add a new record rather than rewriting history, and current-build boundaries use that append order rather than wall-clock ordering.
+
+## Command output contract
+
+Every `state.mjs` and `task-next.mjs` command prints one JSON envelope: `{ok: true, result, nextAction?}` on success (with `nextAction` present whenever the command is task-scoped) and a one-line `{ok: false, error: {message, hint?}}` on stderr for failures. A success envelope may additionally carry `warnings: [{code, message, hint?}]` when the mutation persisted but a derived step failed afterwards — `LESSON_INDEX_STALE` (lesson-index rebuild) or `RENDER_FAILED` (workplan render); the mutation is committed, exit stays `0`, and the caller follows the hint instead of treating the command as failed. The explicit repair commands (`lesson rebuild`, `render.mjs`) and `state migrate` still fail loudly. With `--require-stop`, `task-next.mjs` adds a machine-readable `continuation` object to the envelope (`{required, code: CONTINUATION_REQUIRED|STOP_ALLOWED, taskId, classification}` plus `command`, `reason`, `itemId`, and `remainingItems` while work remains) and prints `CONTINUATION_REQUIRED: {json}` as the first stderr line; execute `continuation.command` instead of replying. Exit codes are typed: `0` success, `1` an expected validation or gate error, `2` the `--require-stop` continuation guard (an expected pause, not a failure), `3` an unexpected crash. Commands embedded in `nextAction` carry an explicit `--root` so they run correctly from any working directory.
+
+## Human gate forms
+
+Gate presentation is executable, not model-authored. After a passing gate check, set `blocked_on_user`, render the phase artifact when required, then run `node .agents/aidlc/scripts/gate-view.mjs <task-id>` and relay its output verbatim. The default Markdown uses a portable `[!IMPORTANT]` blockquote with explicit task state, artifact links, decision/execution counts, evidence, and exactly one `ACTION REQUIRED` line. Use `--format plain` when the tool does not render Markdown and `--format json` for integrations. Renderer-specific color is enhancement only; approval semantics live in canonical state.
+
+G0, G1, and G2 never auto-pass. Gate approval and phase transition are atomic; after a non-terminal transition or item/evidence mutation, continue until the next human gate, real blocker, or completion. Item completion is never a turn-level handoff. The local CLI validates gate readiness and records `--source` as provenance, but without a host-attested channel it cannot prove who authored free-form text; adapters must invoke approval only in a later turn containing explicit user assent.
+
+## Context budget
+
+The default phase packet budget is 16,000 characters. 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; if they do not fit, packet generation fails instead of truncating them. Packet output reports characters, estimated tokens, and omitted rule files.
+
+## Repair bounds
+
+Repair bounds are machine-enforced from current-build evidence; the model does not have to count.
+
+- Verification: at most three failed verify records (`test`/`lint`) per affected area. The third failure flips `nextAction` to `blocked` and adds a `REPAIR_BOUND` error to the G2 gate check.
+- Review: at most two failed review records; the second failure does the same with `--kind review_exhausted`.
+- Security, migration, contract, or where-logic-lives changes reopen G1 immediately.
+- A bound hit produces a diagnosis and human escalation; it never silently passes. Follow the handoff command returned by `nextAction` instead of retrying.
+- Reopening G1 moves the build boundary, which resets both counters for the new cycle.
+
+## Language and scaffold
+
+Technical tokens, paths, commands, enum values, and structural headings remain English. Prose follows the task language. Stable emoji headings are: `📋 Problem`, `🗺️ Affected areas`, `💭 Assumptions`, `❓ Open questions`, `🎯 Scope` (with an inline `**🚫 Out:**` list inside it), `🧩 Solution per affected area`, `📌 Spec traceability`, `🔗 Cross-service contracts`, `⚠️ Risks / edge cases`, `🧩 Decisions`, and `🧩 Tasks`. The intent headings and the design headings are enforced verbatim by `gate-check.mjs` at G0 and G1.

package/dist/assets/.agents/aidlc/orchestrator.md

@@ -0,0 +1,73 @@
+# AI-DLC v1 Orchestrator
+
+This file is the compact kernel contract. Project customization lives under `.agents/project/` (optional — create it when needed; the installer does not scaffold it); discovery indexes live under `.agents/data/index/`; the authoritative lifecycle store uses a compact `.agents/data/state/aidlc-state.json` catalog plus digest-validated terminal records under `.agents/data/state/archive/`; task prose and workplans are review artifacts, not mutable state.
+
+## Turn routing
+
+1. Use `node .agents/aidlc/scripts/state.mjs task list` (or `task find --query <text>`) for bounded routing. Never read or dump the canonical store directly. Use `task show <task-id>` only after selecting one task.
+2. Resolve `node .agents/aidlc/scripts/state.mjs task next <task-id>` for an existing task; do not infer the next action from prose alone.
+3. Classify the request as `NEW`, `RESUME`, `SWITCH`, or `OFF-WORKFLOW`.
+   - A requested feature, bug fix, or project change is `NEW` unless canonical state already contains the matching unfinished task; a read-only explanation or inspection is `OFF-WORKFLOW`.
+   - Bootstrap `NEW` with the exact user-supplied canonical ID when present: run `state.mjs task create`, then execute the clarify phase. `task next` applies only after canonical state exists. When the user supplies no ID, derive a short kebab-case slug from the title (lowercase letters, digits, hyphens; it must match `^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$`, e.g. `fix-login-retry`) and reuse that exact ID for the whole lifecycle.
+   - For `SWITCH`, preserve the current task. If it has a durable handoff, ask the user to reopen G1, close it, or create a fresh G0 successor and then supersede it; never mark failed work `done` or inherit approvals into the successor.
+   - `task create` fails while another task is actionable (`nextAction` `run_phase`) and returns the actionable task(s) plus the exact `--switch-from <task-id>` acknowledgement. Pass that flag only with explicit user direction to switch; it records a resume-marker diagnostic on each acknowledged task and never pauses or mutates its lifecycle — the acknowledged task remains the authoritative resume target. This guard is local-CLI enforcement; the optional MCP state service does not enforce it.
+4. For a task, request only its current phase packet with `node .agents/aidlc/scripts/context.mjs <task-id> --phase <phase>`. Do not load every workflow file.
+5. Use `node .agents/aidlc/scripts/state.mjs` for lifecycle mutations when the active adapter policy is `scripted`. Gate approval always uses the atomic `gate approve` command when scripts are available. Native fallback must apply approval and transition as one logical transaction after the same checks.
+6. A non-terminal transition is not a stopping point. Continue in the same turn until the next human gate, a real blocker, or completion; do not emit a final handoff between phases.
+   After every lifecycle mutation, including item and evidence updates, parse the returned `nextAction`: execute `run_phase`, stop for `await_user`, `blocked`, or `terminal`, and treat only `complete` as successful completion. Completing an item or affected area is progress, not a stopping point; progress belongs in commentary, never a final response. `terminal` means closed/superseded without a success claim. Never convert this loop into automatic human approval.
+   Immediately before any final response for a task, run `node .agents/aidlc/scripts/task-next.mjs <task-id> --require-stop` and parse its `continuation` object. Exit code 2 (`continuation.code = CONTINUATION_REQUIRED`) is a hard local guard: execute `continuation.command` instead of replying, and never convert the guard output into a final response or summary. This cannot technically intercept a message already emitted by a model host; if a premature final response slipped out, recover in the very next turn by running `state.mjs task next <task-id>` and executing its returned command — never re-approve a gate to catch up.
+7. Use `node .agents/aidlc/scripts/render.mjs <task-id>` for the selected task review artifact. `--all` is explicit maintenance only. Never persist a second lifecycle-state projection such as `BOARD.md`.
+
+Read-only questions remain off-workflow and do not create state. Multiple tasks may exist, but a session builds one task at a time.
+
+## Gates
+
+- `G0_confirm`: the user confirms intent and scope.
+- `G1_review`: the user resolves every design decision and approves the plan.
+- `G2_codereview`: verification and adversarial review have run; the user reviews the code.
+
+Before presenting a gate, run `node .agents/aidlc/scripts/gate-check.mjs <task-id> --gate <gate>`, set the validated wait with `node .agents/aidlc/scripts/state.mjs task status <task-id> --status blocked_on_user`, render the task artifact when the phase requires it, then run `node .agents/aidlc/scripts/gate-view.mjs <task-id>` and relay that output verbatim. Structural errors must be fixed. If G2 cannot pass or a repair bound is exhausted, record diagnostic evidence and use `task handoff`; do not set `blocked_on_user` or suggest gate approval. Semantic fidelity remains an LLM/human responsibility. Never mark work complete without executable evidence.
+
+Transitions are enforced by the state machine. A gate may not be skipped, and unresolved decisions block build. G2 always requires human approval.
+
+## Quality contract
+
+- Inspect relevant files and specs before editing.
+- Make the smallest approved change and preserve unrelated user work.
+- Trace quantified rules, enumerations, and contracts to an exact source.
+- Run the narrowest meaningful verification for every affected area.
+- Review only the task diff against its approved decisions and spec anchors.
+- Repair bounds (three verify cycles per area, two review passes) are machine-enforced from evidence: the bound hit flips `nextAction` to `blocked` and closes G2 with a `REPAIR_BOUND` error. Follow the returned handoff command and escalate with evidence.
+- Structural changes discovered during build reopen G1.
+
+Economy models use the same bounded packet contract, gates, executable checks, and quality rules. Escalate to a stronger model or human for security, migrations, cross-service contracts, ambiguous specs, or exhausted repair bounds.
+
+## Delegation contract
+
+- At every phase entry and dependency boundary, the lead must triage whether independent, valuable work can proceed in parallel. Fan out only such work, and use at most the available collaboration slots minus the lead; keep dependent or low-value work local.
+- The lead is the single writer for lifecycle state, gate actions, and task review artifacts. Workers never approve or present gates, mutate lifecycle records, or make canonical artifact decisions; every human-gate and state-machine invariant remains in force.
+- Each worker assignment must name a bounded objective, owned paths or read-only scope, dependencies, expected verification, and required return output (summary, changed paths, evidence, and concerns). The lead integrates and verifies worker results before recording evidence or advancing the task.
+- Assign one writer per path. Partition work so concurrent changes cannot overlap; workers may inspect shared files, but must report a needed cross-owner change to the lead rather than edit it. The lead resolves conflicts and performs final integration.
+
+## Customization layers
+
+Precedence is deterministic:
+
+```text
+kernel → built-in topology profile → local profile → project config/rules → approved task decisions
+```
+
+Built-in profiles are `topology/generic`, `topology/single`, `topology/workspace`, and `topology/git-submodules`. Stack, delivery, issue-tracker, runtime, and domain rules belong in `.agents/config.json`, `.agents/project/profiles/`, or `.agents/project/rules/` (create these optional directories when first needed), not in this kernel.
+
+Configured commands use executable + argument arrays. Never turn configuration into an unreviewed shell string.
+
+## Upgrade boundary — mandatory
+
+Workflow upgrades are initiated and applied only by a human through documented `npm` or `npx` commands.
+
+- Never query npm or another registry for newer workflow versions.
+- Never run an `npm`/`npx` command whose purpose is installing, detecting, previewing, or upgrading this workflow. Project-configured build, test, and lint commands remain allowed.
+- Never suggest an upgrade merely because an installed version is old.
+- You may explain the command and review a dry-run report the user supplies.
+
+`status` and `doctor` inspect only local state. The workflow has no background check, postinstall update, remote profile lookup, or runtime asset download.

package/dist/assets/.agents/aidlc/phase-build.md

@@ -0,0 +1,23 @@
+# AI-DLC · Build (G2)
+
+Precondition: G1 approval evidence exists and every decision is resolved.
+
+Use the shared orchestration contract in `orchestrator.md`. The lead may assign a batch of independent canonical items to workers only after giving each one exclusive file/area ownership; shared/public surfaces, overlapping paths, lifecycle actions, gates, final integration, and task-wide review remain lead-owned. The lead integrates and inspects each result before marking items or recording any lifecycle evidence/state mutation.
+
+1. Read the build phase packet; re-open cited spec lines immediately before implementing dependent behavior.
+2. Read `templates/model-contract.md` and apply its COSTARS build emphasis to the implementation context.
+3. Loop over canonical task items, one item and one affected area at a time, or a safe batch of such independent items under the shared orchestration contract. Prefer an `in_progress` item, otherwise select the next `todo` item; inspect callers before shared/public changes and preserve unrelated work. For a batch, wait for all assigned results, integrate and narrowly verify each owned area, then have the lead record progress and mark each item `done` or explicitly `deferred` with `node .agents/aidlc/scripts/state.mjs task item <task-id> <item-id> --status done|deferred`. Parse every returned `nextAction` immediately and stop for a `blocked` or `terminal` action; otherwise, after the batch use only the final/current authoritative `nextAction` to continue. An item or area completion may be reported only as commentary/progress, never as a final response. Continue the loop while `nextAction.classification` is `run_phase`; when no actionable item remains, continue directly into aggregate verification, adversarial review, and G2 preparation.
+4. A new structural or spec conflict requires `node .agents/aidlc/scripts/state.mjs task handoff <task-id> --kind structural_change --reason <reason> --source <source>`; after explicit user direction, `task reopen <task-id> --to plan --reason <reason> --source <user-message>` invalidates the prior G1 approval. Do not spend repair cycles on an unapproved workaround.
+5. Run the narrowest configured test/lint per area. Record every result with `node .agents/aidlc/scripts/state.mjs evidence add <task-id> --kind test|lint --area <area> --result pass|fail|skip --source <command-or-tool> --detail <summary>`; a skip must state residual risk in `--detail`. The repair bound is machine-enforced: after three failed verify records in one area (current build), `nextAction` turns `blocked` and G2 is structurally closed — record the failed diagnostic and follow the returned handoff action instead of retrying.
+6. Perform an adversarial review of only the task diff against decisions and spec anchors, using every CRITICS section from `templates/model-contract.md`. Record findings and the outcome with `evidence add <task-id> --kind review --result pass|fail --source <reviewer> --detail <findings>`. The review bound is machine-enforced after two failed review records; the returned handoff action uses `--kind review_exhausted`.
+7. Handoff kinds are exactly: `repair_exhausted`, `review_exhausted`, `g2_failed`, `release_failed`, `structural_change`, `other`.
+8. Mark items and record per-area verify evidence, render the workplan, and run `node .agents/aidlc/scripts/gate-check.mjs <task-id> --gate G2_codereview`. Only after the check passes, set task status to `blocked_on_user` with `node .agents/aidlc/scripts/state.mjs task status <task-id> --status blocked_on_user`.
+9. Run `node .agents/aidlc/scripts/gate-view.mjs <task-id>`, relay it verbatim, and stop for human review. Presenting the gate ends this turn.
+
+## ONLY in a later turn, after the user explicitly approves G2
+
+Explicit approval is a user message that says yes to this gate. Then — and only then — run `node .agents/aidlc/scripts/state.mjs gate approve <task-id> --gate G2_codereview --source <the-user-approval-message>`, parse the returned `nextAction`, and execute its `run_phase` command before emitting any final response. Continue through `wrap` to `complete` unless delivery authority or a real blocker is missing; never invent approval. If the user instead requests fixes, record the rejection as review evidence (`--kind review --result fail`), cancel the wait with `task status <task-id> --status active --mode audited --reason <requested-changes> --source <the-user-message>`, and continue the build loop.
+
+Before any final response, execute `task-next.mjs <task-id> --require-stop`; a continuation-required result prohibits a final response.
+
+Post-condition: every task is done or explicitly deferred, verification/review evidence is honest, the diff matches approved decisions, and residual risks are visible.

package/dist/assets/.agents/aidlc/phase-clarify.md

@@ -0,0 +1,22 @@
+# AI-DLC · Clarify (G0)
+
+Goal: confirm intent before discovery cost.
+
+When independent, read-only index or ambiguity checks exist, use the shared orchestration contract in `orchestrator.md` to delegate bounded workstreams. The lead agent alone reconciles their findings, writes the intent brief, and performs every lifecycle or gate action.
+
+1. Read the compact repository/spec indexes if available; do not scan implementation code.
+2. Read `templates/model-contract.md` and apply its COSTARS clarify emphasis to the intent brief. Use CRITICS only for elevated risk, ambiguity, or model disagreement.
+3. Canonical task state already exists from turn routing (`task create` runs there, before this packet). Never create it a second time; a repeated create fails with `Task already exists`.
+4. Fill the intent template: problem, affected areas, assumptions, open questions with safe defaults, and decidable in/out scope.
+5. Run `node .agents/aidlc/scripts/gate-check.mjs <task-id> --gate G0_confirm` and fix every structural error. Only after it passes, set the gate wait with `node .agents/aidlc/scripts/state.mjs task status <task-id> --status blocked_on_user`, then render only this task with `node .agents/aidlc/scripts/render.mjs <task-id>`.
+6. Run `node .agents/aidlc/scripts/gate-view.mjs <task-id>`, relay the output verbatim, and stop. Presenting the gate ends this turn.
+
+## ONLY in a later turn, after the user explicitly approves G0
+
+Explicit approval is a user message that says yes to this gate (for example "ok", "approve", "duyệt"). Resolving questions or requesting changes is NOT approval. Then — and only then — run `node .agents/aidlc/scripts/state.mjs gate approve <task-id> --gate G0_confirm --source <the-user-approval-message>`, parse the returned `nextAction`, and execute its `run_phase` command before emitting any final response. Continue into `plan` until G1 or a real blocker; never invent approval. If the user instead requests changes, revise the intent while the task waits, or cancel the wait explicitly with `task status <task-id> --status active --mode audited --reason <what-changed> --source <the-user-message>`.
+
+Read-only questions remain off-workflow. The task language is set here and retained throughout the lifecycle.
+
+Post-condition: a teammate with no chat context can understand the problem and scope; every affected area has an indexed source or explicitly says `none indexed`.
+
+Before any final response, execute `task-next.mjs <task-id> --require-stop`; a continuation-required result prohibits a final response.

package/dist/assets/.agents/aidlc/phase-index.md

@@ -0,0 +1,14 @@
+# AI-DLC · Index
+
+Generate compact repository and specification manifests at `.agents/data/index/repo-map.md` and `.agents/data/index/specs-index.md` without assuming a particular stack or repository layout.
+
+Use the shared orchestration contract in `orchestrator.md` for independent discovery roots. Workers return bounded findings only; the lead reconciles them and is the sole writer of both canonical manifests.
+
+1. Resolve configured topology profiles and discovery roots.
+2. Detect areas from project markers and local profile rules. Built-in topologies are generic, single repository, workspace/monorepo, and git submodules.
+3. Index configured spec roots plus relevant README, docs, and API descriptions. Read only titles and short leading sections.
+4. Record each area, stack marker, narrow verification command, spec document, keywords, and one-line summary.
+5. Write only the two canonical manifests under `.agents/data/index/`; never create `.aidlc/index/` or write discovery indexes into `.agents/data/state/`.
+6. Keep manifests small and deterministic; report unknown stacks rather than guessing.
+
+Indexing is maintenance and never creates a task. Stack, Docker, screen-code, runtime, and domain discovery belong in local profiles/rules, not this phase contract.

package/dist/assets/.agents/aidlc/phase-plan.md

@@ -0,0 +1,21 @@
+# AI-DLC · Plan (G1)
+
+Precondition: canonical state contains passing G0 approval evidence.
+
+Use the shared orchestration contract in `orchestrator.md` to fan out only independent, bounded discovery streams. Workers return summaries and exact anchors; the lead reconciles conflicts, writes design/workplan content, and is the sole lifecycle and gate writer.
+
+1. Retrieve only matched specs and impacted symbols. Parallelize bounded discovery when available; return summaries and exact spec anchors, not file dumps.
+2. Read `templates/model-contract.md` and apply its COSTARS plan emphasis. Use CRITICS only for elevated risk, ambiguity, or model disagreement.
+3. Fill the design template with the solution per affected area, exact sources for quantified rules, contracts, risks, and reuse candidates.
+4. Add every real judgement call with `node .agents/aidlc/scripts/state.mjs decision set <task-id> <decision-id> --status unresolved --label <label> --resolution <proposed-default>`. Code/spec conflicts and ambiguous enumerations are always decisions.
+5. Add implementation items with `node .agents/aidlc/scripts/state.mjs task item <task-id> <item-id> --status todo --label <label>` and configure narrow verification commands; render the workplan review artifact with `node .agents/aidlc/scripts/render.mjs <task-id>`.
+6. Unresolved decisions block the G1 gate structurally. Present them to the user and apply each answer with `decision set <task-id> <decision-id> --status approved|changed|dropped --resolution <user-resolution>`. Do not treat a decision answer as gate approval.
+7. When every decision is resolved, run `node .agents/aidlc/scripts/gate-check.mjs <task-id> --gate G1_review` and fix every structural error. Only after it passes, set the gate wait with `node .agents/aidlc/scripts/state.mjs task status <task-id> --status blocked_on_user`, run `node .agents/aidlc/scripts/gate-view.mjs <task-id>`, relay it verbatim, and stop. G1 always requires explicit human approval.
+
+## ONLY in a later turn, after the user explicitly approves G1
+
+Explicit approval is a user message that says yes to this gate (for example "approve", "ok", "duyệt"). Resolving decisions is NOT approval — never run gate approve just because no decision remains unresolved. Then — and only then — run `node .agents/aidlc/scripts/state.mjs gate approve <task-id> --gate G1_review --source <the-user-approval-message>`, parse the returned `nextAction`, and execute its `run_phase` command before emitting any final response. Continue into `build` until G2 or a real blocker; never invent approval. If the user instead requests plan changes, revise the design/workplan, or cancel the wait explicitly with `task status <task-id> --status active --mode audited --reason <what-changed> --source <the-user-message>`.
+
+Post-condition: the plan names concrete affected areas/paths, traces every relied-upon value to a source, exposes conflicts, and needs no implementation judgement beyond mechanical details.
+
+Before any final response, execute `task-next.mjs <task-id> --require-stop`; a continuation-required result prohibits a final response.

package/dist/assets/.agents/aidlc/phase-wrap.md

@@ -0,0 +1,16 @@
+# AI-DLC · Wrap
+
+Precondition: the user approved G2 and canonical state contains passing G2 approval evidence.
+
+Wrap is success-only and has NO human gate (`gate: none`): never set `blocked_on_user` here — the CLI rejects it. `closed` and `superseded` tasks are terminal at the phase where they stopped and never enter wrap or imply release success.
+
+Use the shared orchestration contract in `orchestrator.md` for independent read-only delivery-policy, lesson, or residual-risk checks. The lead reconciles outputs and is the only agent that records lessons/delivery evidence, performs delivery actions, or transitions the task.
+
+1. Commit only when the user requested it. Follow the project's configured delivery policy; kernel does not assume submodules, branches, PR provider, or issue tracker.
+2. Review durable corrections. Record each with `node .agents/aidlc/scripts/state.mjs lesson record <task-id> <lesson-id> --summary <s> --prevention <p> --example <e> --source <source>`, including provenance; if none exist, run `node .agents/aidlc/scripts/state.mjs lesson none <task-id> --reason <reason> --source <source>`. Promote advisory project memory only with explicit user approval via `state.mjs memory promote`; retirement also requires an explicit audited approval. Prefer executable enforcement over prose. Memory and lesson-index commands are not task-scoped, so their output has no `nextAction` — continue the wrap steps in order.
+3. Record delivery evidence and residual risk. Rebuild/search lessons and manage advisory memory only through the installed lifecycle script; never hand-edit the derived index or memory registry.
+4. Complete the task with `node .agents/aidlc/scripts/state.mjs task transition <task-id> --mode audited --to done --reason <completion-summary> --source <source>` (or `task archive <task-id> --reason <completion-summary> --source <source>`); the lesson disposition from step 2 is required first. Schema v3 writes a digest-validated terminal record and compacts the active catalog. Refresh only this task's review artifact.
+
+Post-condition: reported commits/integrations match reality, the terminal task and lesson disposition are durable, and no local rule was silently admitted.
+
+Before any final response, execute `task-next.mjs <task-id> --require-stop`; a continuation-required result prohibits a final response.

package/dist/assets/.agents/aidlc/profiles/generic/profile.json

@@ -0,0 +1,9 @@
+{
+  "schemaVersion": 1,
+  "id": "topology/generic",
+  "topology": "generic",
+  "discovery": { "roots": ["."], "workspaceMarkers": [] },
+  "specs": { "roots": [] },
+  "commands": {},
+  "rules": { "include": [] }
+}

package/dist/assets/.agents/aidlc/profiles/git-submodules/profile.json

@@ -0,0 +1,9 @@
+{
+  "schemaVersion": 1,
+  "id": "topology/git-submodules",
+  "topology": "git-submodules",
+  "discovery": { "roots": ["."], "workspaceMarkers": [".gitmodules"] },
+  "specs": { "roots": [] },
+  "commands": {},
+  "rules": { "include": [] }
+}

package/dist/assets/.agents/aidlc/profiles/single/profile.json

@@ -0,0 +1,9 @@
+{
+  "schemaVersion": 1,
+  "id": "topology/single",
+  "topology": "single",
+  "discovery": { "roots": ["."], "workspaceMarkers": [] },
+  "specs": { "roots": [] },
+  "commands": {},
+  "rules": { "include": [] }
+}

package/dist/assets/.agents/aidlc/profiles/workspace/profile.json

@@ -0,0 +1,12 @@
+{
+  "schemaVersion": 1,
+  "id": "topology/workspace",
+  "topology": "workspace",
+  "discovery": {
+    "roots": ["."],
+    "workspaceMarkers": ["package.json", "pnpm-workspace.yaml", "lerna.json"]
+  },
+  "specs": { "roots": [] },
+  "commands": {},
+  "rules": { "include": [] }
+}

package/dist/assets/.agents/aidlc/rules/gate-check.md

@@ -0,0 +1,16 @@
+# Gate-check command (AI-DLC · project rule)
+
+> Project-specific executable for the gate self-check. The generic contract lives in `conventions.md`, section "Human gate forms".
+
+## Command
+
+```sh
+node .agents/aidlc/scripts/gate-check.mjs <task-id> --gate <gate>
+```
+
+The command is offline and dependency-free. Exit `0` means no structural error; exit `1` means at least one `ERROR`.
+
+## Caveats
+
+- Semantic correctness, prose language, spec interpretation and code quality remain LLM/human-reviewed.
+- AI agents may run this gate checker. It is unrelated to workflow upgrade, which agents must never run.

package/dist/assets/.agents/aidlc/rules/stack-runtime.md

@@ -0,0 +1,3 @@
+# Stack runtime — concrete commands (AI-DLC · project rule)
+
+> Optional project-specific stack lifecycle/exec commands. Keep them idempotent and check-first, never tear down a shared running stack, and configure narrow test/lint commands in `.agents/config.json` or local profiles.

package/dist/assets/.agents/aidlc/schemas/adapter.schema.json

@@ -0,0 +1,13 @@
+{
+  "title": "AI-DLC local declarative adapter",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "id", "displayName", "detect", "files"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$" },
+    "displayName": { "type": "string", "minLength": 1 },
+    "detect": { "type": "array", "items": { "type": "string" } },
+    "files": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": ["path", "content"], "properties": { "path": { "type": "string" }, "content": { "type": "string" }, "strategy": { "enum": ["replace", "managed-block"] } } } }
+  }
+}

package/dist/assets/.agents/aidlc/schemas/config.schema.json

@@ -0,0 +1,26 @@
+{
+  "title": "AI-DLC project configuration",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "extends", "specs", "commands", "rules", "risk", "context"],
+  "properties": {
+    "schemaVersion": { "enum": [1, 2, 3] },
+    "extends": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+    "specs": { "type": "object", "required": ["roots"], "properties": { "roots": { "type": "array", "items": { "type": "string" } } } },
+    "commands": { "type": "object", "additionalProperties": { "$ref": "#/$defs/command" } },
+    "rules": { "type": "object", "required": ["include"], "properties": { "include": { "type": "array", "items": { "type": "string" } } } },
+    "risk": { "type": "object", "required": ["default"], "properties": { "default": { "enum": ["low", "normal", "high", "regulated"] } } },
+    "context": { "type": "object", "required": ["maxChars"], "properties": { "maxChars": { "type": "integer", "minimum": 4000, "maximum": 128000 } } },
+    "agentState": { "type": "object", "additionalProperties": { "enum": ["native", "scripted"] } },
+    "tracker": { "type": "object", "additionalProperties": false, "required": ["enabled"], "properties": { "enabled": { "type": "boolean" }, "provider": { "enum": ["backlog"] }, "spaceUrl": { "type": "string", "format": "uri" }, "project": { "type": "string", "minLength": 1 }, "tokenEnv": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" }, "workflow": { "enum": ["waterfall", "scrum"] }, "mapping": { "type": "object", "properties": { "statuses": { "type": "object", "additionalProperties": { "type": "integer", "minimum": 1 } }, "gateFieldId": { "type": "integer", "minimum": 1 } } } } },
+    "mcp": { "type": "object", "additionalProperties": false, "required": ["enabled"], "properties": { "enabled": { "type": "boolean" }, "endpoint": { "type": "string", "format": "uri" }, "workspace": { "type": "string", "minLength": 1 }, "tokenEnv": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" }, "pollMs": { "type": "integer", "minimum": 1000, "maximum": 3600000 }, "providers": { "type": "array", "items": { "enum": ["jira", "trello", "github-issues"] }, "uniqueItems": true } } }
+  },
+  "$defs": {
+    "command": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["command", "args"],
+      "properties": { "command": { "type": "string", "minLength": 1 }, "args": { "type": "array", "items": { "type": "string" } } }
+    }
+  }
+}

package/dist/assets/.agents/aidlc/schemas/manifest.schema.json

@@ -0,0 +1,12 @@
+{
+  "title": "AI-DLC managed installation manifest",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "packageVersion", "workflow", "source", "remoteUpdates", "managedBy", "adapters", "files"],
+  "properties": {
+    "schemaVersion": { "const": 2 }, "packageVersion": { "type": "string" }, "workflow": { "const": "AI-DLC" },
+    "source": { "const": "local-package-assets" }, "remoteUpdates": { "const": false }, "managedBy": { "const": "aidlc-workflow" },
+    "adapters": { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$" } },
+    "files": { "type": "object", "additionalProperties": { "type": "object", "required": ["hash", "owner", "strategy"], "properties": { "hash": { "type": "string" }, "owner": { "type": "string" }, "strategy": { "enum": ["replace", "managed-block"] } } } }
+  }
+}

package/dist/assets/.agents/aidlc/schemas/profile.schema.json

@@ -0,0 +1,12 @@
+{
+  "title": "AI-DLC declarative profile",
+  "type": "object",
+  "required": ["schemaVersion", "id", "topology"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "id": { "type": "string" },
+    "extends": { "type": "array", "items": { "type": "string" } },
+    "topology": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._/-]{0,127}$" },
+    "discovery": { "type": "object" }, "specs": { "type": "object" }, "commands": { "type": "object" }, "rules": { "type": "object" }
+  }
+}