@rosetears/aili-pi 0.1.0

package/skills/agents-md-initialization/references/agents_md.py

@@ -0,0 +1,215 @@
+#!/usr/bin/env python3
+"""Create, update, and validate project AGENTS.md files from the bundled AILI template."""
+
+from __future__ import annotations
+
+import argparse
+import datetime as dt
+import re
+import shutil
+import sys
+from pathlib import Path
+
+
+VERSION_RE = re.compile(r"<!--\s*AILI_AGENTS_TEMPLATE_VERSION:\s*(\d+)\s*-->")
+SOURCE_MARKER = "<!-- AILI_AGENTS_TEMPLATE_SOURCE: templates/AGENTS.md -->"
+MODE_MARKER = "<!-- AILI_AGENTS_TEMPLATE_MODE: generated-project-local-file -->"
+BLOCK_RE = re.compile(
+    r"<!-- AILI_MANAGED_BLOCK_BEGIN: (?P<name>[a-z0-9-]+) -->.*?"
+    r"<!-- AILI_MANAGED_BLOCK_END: (?P=name) -->",
+    re.DOTALL,
+)
+PLACEHOLDER_RE = re.compile(r"\bTODO\b|<!--\s*Fill\b|<!--\s*Add rules\b", re.IGNORECASE)
+
+REQUIRED_SECTIONS = [
+    "# AGENTS.md",
+    "## Project Overview",
+    "## Setup Commands",
+    "## Architecture and Project Structure",
+    "## Project-Specific Rules",
+    "## Project-Specific Testing and Artifact Placement",
+    "## Local Overrides",
+]
+
+
+def bundle_root() -> Path:
+    return Path(__file__).resolve().parent
+
+
+def template_path() -> Path:
+    return bundle_root() / "agents-template.md"
+
+
+def agents_path(project: Path) -> Path:
+    return project.resolve() / "AGENTS.md"
+
+
+def read_text(path: Path) -> str:
+    return path.read_text(encoding="utf-8")
+
+
+def write_text(path: Path, text: str) -> None:
+    path.write_text(text, encoding="utf-8", newline="\n")
+
+
+def backup(path: Path) -> Path:
+    stamp = dt.datetime.now().strftime("%Y%m%d%H%M%S")
+    backup_path = path.with_name(f"{path.name}.backup.{stamp}")
+    shutil.copy2(path, backup_path)
+    return backup_path
+
+
+def managed_blocks(text: str) -> dict[str, str]:
+    return {match.group("name"): match.group(0) for match in BLOCK_RE.finditer(text)}
+
+
+def template_version(text: str) -> str | None:
+    match = VERSION_RE.search(text)
+    return match.group(1) if match else None
+
+
+def replace_managed_blocks(target_text: str, template_text: str) -> tuple[str, list[str]]:
+    target_blocks = managed_blocks(target_text)
+    template_blocks = managed_blocks(template_text)
+    missing = [name for name in template_blocks if name not in target_blocks]
+    if missing:
+        names = ", ".join(missing)
+        raise SystemExit(f"AGENTS.md is missing managed block(s): {names}")
+
+    updated = target_text
+    replaced: list[str] = []
+    for name, template_block in template_blocks.items():
+        current_block = target_blocks[name]
+        if current_block != template_block:
+            updated = updated.replace(current_block, template_block)
+            replaced.append(name)
+    return updated, replaced
+
+
+def command_init(args: argparse.Namespace) -> int:
+    project = Path(args.project)
+    destination = agents_path(project)
+    template = read_text(template_path())
+
+    if destination.exists():
+        if args.strategy == "abort":
+            print(f"AGENTS.md already exists: {destination}", file=sys.stderr)
+            print("Use update, or rerun init with --strategy backup-overwrite.", file=sys.stderr)
+            return 2
+        backup_path = backup(destination)
+        print(f"Backed up existing AGENTS.md to {backup_path}")
+
+    write_text(destination, template)
+    print(f"Created {destination} from {template_path()}")
+    return 0
+
+
+def command_update(args: argparse.Namespace) -> int:
+    project = Path(args.project)
+    destination = agents_path(project)
+    if not destination.exists():
+        print(f"AGENTS.md does not exist: {destination}", file=sys.stderr)
+        print("Run init first.", file=sys.stderr)
+        return 2
+
+    current = read_text(destination)
+    template = read_text(template_path())
+    updated, replaced = replace_managed_blocks(current, template)
+    if updated != current:
+        backup_path = backup(destination)
+        write_text(destination, updated)
+        print(f"Backed up AGENTS.md to {backup_path}")
+        print("Updated managed block(s): " + ", ".join(replaced))
+    else:
+        print("AGENTS.md managed blocks are already current.")
+    return 0
+
+
+def command_check(args: argparse.Namespace) -> int:
+    project = Path(args.project)
+    destination = agents_path(project)
+    errors: list[str] = []
+
+    if not destination.exists():
+        print(f"FAIL: AGENTS.md does not exist: {destination}", file=sys.stderr)
+        return 1
+
+    text = read_text(destination)
+    template = read_text(template_path())
+    template_blocks = managed_blocks(template)
+    target_blocks = managed_blocks(text)
+    current_version = template_version(text)
+    expected_version = template_version(template)
+
+    if current_version is None:
+        errors.append("missing AILI_AGENTS_TEMPLATE_VERSION marker")
+    elif expected_version is None:
+        errors.append("template missing AILI_AGENTS_TEMPLATE_VERSION marker")
+    elif current_version != expected_version:
+        errors.append(f"template version mismatch: AGENTS.md has {current_version}, template has {expected_version}")
+    if SOURCE_MARKER not in text:
+        errors.append("missing AILI_AGENTS_TEMPLATE_SOURCE marker")
+    if MODE_MARKER not in text:
+        errors.append("missing AILI_AGENTS_TEMPLATE_MODE marker")
+
+    for section in REQUIRED_SECTIONS:
+        if section not in text:
+            errors.append(f"missing required section: {section}")
+
+    for name, block in template_blocks.items():
+        if name not in target_blocks:
+            errors.append(f"missing managed block: {name}")
+        elif target_blocks[name] != block:
+            errors.append(f"managed block differs from template: {name}")
+    for name in sorted(target_blocks.keys() - template_blocks.keys()):
+        errors.append(f"stale managed block not present in template: {name}")
+
+    if not args.allow_placeholders and PLACEHOLDER_RE.search(text):
+        errors.append("unfilled placeholder remains; replace TODO/fill comments with project facts or 'unknown'")
+
+    if errors:
+        for error in errors:
+            print(f"FAIL: {error}", file=sys.stderr)
+        return 1
+
+    print(f"PASS: {destination} follows {template_path()}")
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description=__doc__)
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    init_parser = subparsers.add_parser("init", help="create AGENTS.md from the bundled AGENTS.md template")
+    init_parser.add_argument("--project", default=".", help="project root directory")
+    init_parser.add_argument(
+        "--strategy",
+        choices=["abort", "backup-overwrite"],
+        default="abort",
+        help="what to do when AGENTS.md already exists",
+    )
+    init_parser.set_defaults(func=command_init)
+
+    update_parser = subparsers.add_parser("update", help="update template-managed blocks only")
+    update_parser.add_argument("--project", default=".", help="project root directory")
+    update_parser.set_defaults(func=command_update)
+
+    check_parser = subparsers.add_parser("check", help="validate AGENTS.md template markers and managed blocks")
+    check_parser.add_argument("--project", default=".", help="project root directory")
+    check_parser.add_argument(
+        "--allow-placeholders",
+        action="store_true",
+        help="allow TODO/fill placeholders; intended for template or freshly initialized draft checks only",
+    )
+    check_parser.set_defaults(func=command_check)
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skills/ai-regression-scout/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: ai-regression-scout
+description: AI regression scouting routing. Use when agents, prompts, skills, model/tool routing, harness fixtures, or generated-output expectations change and need regression scenarios; do not use for ordinary product-code regressions.
+---
+
+# AI Regression Scout
+
+Use this skill to define one bounded AI-workflow regression-scouting need. ROSE may assign it to one fresh `ai-regression-scout` context after the delegation gate; this skill does not dispatch or invoke another process skill.
+
+## Trigger
+
+- Agent prompt, skill, routing rule, model/tool policy, fixture, or output contract changed.
+- ROSE needs over-trigger, under-trigger, ownership, permission, or completion-claim regression scenarios.
+- A formal harness change needs smoke cases before acceptance.
+
+## Near Misses
+
+- Product-code regression, prompt implementation, or false-success review are different primary intents; return the exact mismatch to ROSE.
+
+## Required Routing
+
+- Canonical owner: ROSE/`aili-delivery-flow`.
+- Optional agent: one fresh, terminal `ai-regression-scout` assignment after a new benefit decision.
+- Default evidence mode: read-only; return fixture/check recommendations and stop without editing, retrying, or owning the final verdict.

package/skills/aili-delivery-flow/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: aili-delivery-flow
+description: Run the AILI delivery lifecycle from natural-language IDEATE, DEFINE, BUILD, and SHIP intent or the equivalent slash shortcuts; use for idea shaping, spec/test definition, bounded BUILD package queues, review-repair closeout, or adapter routing without exposing internal stage commands.
+---
+
+# AILI Delivery Flow
+
+This is the canonical lifecycle/router authority for IDEATE, DEFINE, BUILD, and SHIP. Equivalent natural-language intent and command shortcuts enter the same state, gates, progress, stop conditions, and verification owner. Natural language is a first-class lifecycle entry, not a request to make the user type a slash command.
+
+## References
+
+- Lifecycle states and hard gates: `references/lifecycle.md`
+- Backend adapters: `references/backend-routing.md`
+- Artifact outputs: `references/artifact-contracts.md`
+- Question handling: `references/questionnaire-policy.md`
+- Test document rules: `references/test-document-policy.md`
+- Direct versus delegated work: `references/direct-vs-delegated-work.md`
+- Build package rules: `references/implementation-packages.md`
+- Neutral BUILD execution and loop budgets: `references/build-execution-loop.md`
+- Ship review and repair: `references/review-repair-loop.md`
+- Protocol templates: `references/protocols/`
+
+## Workflow
+
+### Semantic router
+
+For each current user intent, ROSE selects:
+
+1. lifecycle intent expressed by natural language or a slash shortcut, with neither form receiving extra authority;
+2. ordinary or formal/material handling;
+3. one primary process/domain/artifact loop;
+4. zero or one auxiliary capability only for a named gap the primary loop cannot cover directly;
+5. one terminal outcome: `complete`, `need-user`, `need-evidence`, `material-delta`, `blocked`, or `Unverified`.
+
+Explicit user intent wins, followed by the narrowest artifact/domain owner, then the lifecycle loop. A skill match is a route into this state, not a second workflow. Skills must not invoke another process skill, recurse, change phase, create another ledger/approval system, or automatically add planning, research, TDD, review, test, security, coverage, or convergence work.
+
+Treat unambiguous natural-language requests as first-class lifecycle entries; do not ask the user to restate a slash command. Classify by the requested outcome rather than one keyword. Examples include:
+
+- IDEATE: “先帮我想几种方案，暂时不要实现” or “explore options before we build”.
+- DEFINE: “把这个需求定义成可实施方案和测试计划，先不要实现” or “write the implementation-ready contract”.
+- BUILD: “按已经接受的方案和测试计划开始实现” or “implement the accepted change”.
+- SHIP: “把已实现的改动收尾并准备交付” or “close out the implemented change”.
+
+Explanation, comparison, translation, or status questions about these mode names remain ordinary near misses. When outcome, target, or current gate is genuinely ambiguous, ask one focused mode/target question rather than requiring command syntax.
+
+### Proactive delegation scan
+
+At the start of each non-trivial intent and whenever changed evidence creates a new work split, evaluate the `subagent.dispatch` capability triggers in `references/direct-vs-delegated-work.md`. If a current adapter supplies that capability and a trigger is met, dispatch before doing the same work directly. If multiple independent units are ready, launch them together rather than serializing them. Default concurrency is at most two, but it is not a hard cap; ROSE chooses a larger bounded fan-out only from the number of independent non-overlapping units, concrete wall-clock/context benefit, available specialist roles, and an explicit join plan. Every dispatch context remains fresh, single-use, non-nesting, permission-bounded, and subject to independent benefit evidence.
+
+Near misses stay direct: lifecycle words used for explanation/status, code that merely has tests, multi-file work without a planning need, and completion wording without a concrete review or evidence gap do not activate extra skills. An existing official Graphify graph may supply one scoped architecture-orientation result; exact-current symbols, source, call paths, tests, and impact stay with CodeGraph or current files, and no lifecycle phase installs, registers, or runs Graphify automatically.
+
+### Mode decision table
+
+| User intent | Mode/loop | Required gate | Stop boundary |
+|---|---|---|---|
+| Explore options without implementation | IDEATE | current request and relevant evidence | options/unknowns produced or material formal trigger found |
+| Create or materially revise a durable change contract | DEFINE | one resolved change identity | coherent artifacts plus final `test-plan.md` acceptance, or exact blocker |
+| Explicitly implement a resolved accepted formal change | BUILD | current acceptance, target, package, permission, and claim-verification path | accepted queue implemented and smallest completion check selected, or blocker/material delta |
+| Explicitly close out implemented work | SHIP | fresh SHIP intent and current implementation evidence | exact closeout claim supported or blocked |
+| Bounded work with no formal/material trigger | ordinary | clear scope and local rules | requested outcome and smallest claim-matched evidence |
+
+### Execution and approval classes
+
+- Safe local execution: perform requested in-scope reads, edits, deterministic diagnostics, and non-destructive claim-matched checks without asking for each step.
+- Material decision: ask one focused question only when the answer changes scope, architecture, public contract, dependency, permission, acceptance, verification strategy, product behavior, or target identity.
+- Risky operation: obtain the existing exact approval for destructive, external access/write/directory, dependency/lockfile, schema/migration, auth/permission/secret/security, Git/release, or A33 ADD/REMOVE operations.
+
+Every question names the decision or operation, target, why now, risk/trade-off, options, recommendation or uncertainty, and denial effect. One answer/approval never authorizes another operation, target, or risk class.
+
+### Directed hydration
+
+Read only evidence needed for the current mode, dependency, event, and claim:
+
+| Entry | Required current evidence | Conditional evidence |
+|---|---|---|
+| new DEFINE | change identity and dependencies for the next artifact | interview/context only for a material question or term |
+| DEFINE continuation | changed artifact and direct dependents | progress/drift only for resume, deviation, or conflict |
+| BUILD start/resume | accepted final-test-plan gate, current tasks/package and owning contract sections, target/Git/rules, affected verification | unrelated DEFINE/history only on conflict or material discovery |
+| SHIP | implemented diff/tree, current BUILD evidence, explicit target | only affected/stale risk, integration, packaging, or release evidence |
+| ordinary continuation | current request and directly relevant files | formal artifacts only when formal work is resumed or changed |
+
+Re-read every written file once before using it as durable evidence. A relevant user correction, write, hook, content/config/dependency/toolchain/target change, or conflict invalidates only dependent evidence. Phase/time/file presence/`continue` never triggers blanket hydration.
+
+### Mode rules
+
+1. **IDEATE:** run the proactive delegation scan, then explore and compare; do not edit production code. Direct chat is the fallback only when no Task trigger is met or delegation is concretely blocked. A material formal outcome routes to DEFINE, while ordinary brainstorming remains chat/optional approved idea placement.
+2. **DEFINE:** resolve one change identity; follow current backend dependency order; write only applicable artifacts. `requirements-grilling` owns `interview.md`; `test-document-generator` owns `test-plan.md`. Use the smallest decision-changing question/evidence lookup by default. An explicitly user-invoked Frontier Batch Mode may submit one bounded packet containing the complete current dependency-ready frontier of material product/requirements decisions only after identity, placement, permission, approval, and exact-operation questions are resolved separately; never infer batch mode from blocker count. Final `test-plan.md` acceptance remains the sole lifecycle-level pre-BUILD user gate, separate from material, validation, permission, and exact operation gates.
+3. **BUILD:** require explicit implementation intent and current formal readiness. Derive a dependency-ordered queue from the accepted contract, implement complete scoped packages, and record lightweight savepoints without package approvals or automatic tests/reviews. `BUILD_MATERIAL_DISCOVERY` stops affected work before a change to scope, architecture, dependency, public contract, permission, acceptance, or verification strategy and returns it to DEFINE. Acceptance alone executes nothing.
+4. **SHIP:** require fresh explicit closeout intent plus current implementation evidence. Reuse still-covering BUILD evidence; refresh only affected rows. Run the proactive delegation scan; direct inspection is the fallback when no Task trigger is met or delegation is concretely blocked. Review/repair/packaging/release capabilities run only for the exact closeout gap.
+
+### Verification owner
+
+The active ordinary-task/lifecycle owner chooses the smallest fresh check supporting the exact claim. Specialized skills may suggest risk-specific evidence but cannot impose per-slice full suites, automatic stress tests, review matrices, repeated rechecks, duplicate approvals, or additional completion authority. Broaden only when the affected integration, packaging, browser, permission, installer, security, or release claim requires it. BUILD permits at most one targeted repair/recheck and does not transition automatically to SHIP.
+
+## Continuation and compound intent
+
+- `continue`, `继续`, `go ahead`, and `继续做` resume exactly one active authorized envelope only when target, phase, current gates, and remaining budget are unambiguous. Preserve counters and stop state; never broaden authorization, change phase/target, refresh acceptance, or reset budget. Otherwise ask one decision-shaped question and perform no affected mutation.
+- A continuation carrying a material delta returns to DEFINE and never resumes execution. A no-write/chat-only clause overrides formal writeback, continue+delta, and acceptance+BUILD for that turn and yields only a blocked/`Unverified` preview with zero persistence/execution/mutation/acceptance/budget consumption.
+- Same-turn acceptance+BUILD persists/classifies acceptance in its owning artifact, rereads affected files once, then validates BUILD gates before execution.
+- Combined BUILD+SHIP intent authorizes only current-phase BUILD. Later SHIP requires fresh evidence and new explicit intent.
+- Package savepoints contain `scope`, `files_changed`, `unresolved_items`, `evidence_state`, and `next_package`; they trigger no automatic test, review, commit, or package approval.
+- Commit, push, merge, and release each require exact action-specific approval. CI failure reports the failed target/commit/tree/check and returns control to the user without automatic repair, commit, push, merge, or release.
+
+## Generated OpenSpec adapter boundary
+
+AILI guarantees only its four routes. Current generated `.opencode` `/opsx-*`, apply/continue/archive, and `openspec-*` adapters remain directly callable outside AILI. Do not route or recommend users to them, hand-edit/wrap/suppress/prevent them, alter their generator for control, or treat direct output as AILI evidence. Later AILI work must establish its own current contract, acceptance, and verification; integration/control is Phase II.
+
+## Boundaries
+
+- Only four top-level delivery commands are valid: `/ideate`, `/define`, `/build`, `/ship`.
+- `/local-review` is a standalone non-delivery local audit command owned by `local-review-gate`; do not route it through this delivery lifecycle skill as a fifth lifecycle mode.
+- Research, questionnaire, test-plan, implementation, debugging, review, repair, and harness evolution are internal stages, not user command entrypoints.
+- Anti-entrypoint blacklist: do not expose or invent top-level `/research`, `/questionnaire`, `/test-plan`, `/implement`, `/debug`, `/review`, `/repair`, `/harness`, or backend-specific lifecycle commands.
+- Do not register `/loop`, `/schedule`, `/goal`, `/proactive`, `/cycle`, `/watch`, `/objective`, or any other public lifecycle alias. Treat those words only as semantic classifier input. AILI does not own, imitate, bind, modify, or control native `/goal`; its successful behavior is Stage II / N/A. Automation scope blocks under the lifecycle reference.
+- Backend-specific task systems store artifacts; they do not weaken lifecycle gates.
+- Explicit acceptance of final `test-plan.md` is the sole mandatory lifecycle-level pre-BUILD user gate. Material-decision, coherence, strict-validation, permission, destructive/high-risk, external-operation, and named-risk gates remain separate and cannot be relabeled lifecycle acceptance.
+- A33 routing starts only from the user-selected Git startup host. AILI does not rank, move, broadly scan for, or auto-select hosts; every lane targets one declared repository, target rules may only narrow, same-level conflicts block, and artifacts stay in the owning target. A30 external-read routing is historical only.
+- A33 text here and in the references is admission/approval policy only. It creates no worktree operation authority: PREPARE has zero add/remove effect, and every real or `driver_fixture` ADD and later non-force REMOVE needs its own fresh exact key/class-bound approval and separate applicable risk gate.
+
+## Verification
+
+- Confirm the selected mode/ordinary loop and backend when applicable.
+- Name the artifact(s) created or updated.
+- For BUILD and SHIP, include traceability-backed fresh verification evidence or mark remaining items `Open Question` / `Unverified`.
+- For any blocked gate, return the missing approval, artifact, or evidence as the next action.

package/skills/aili-delivery-flow/references/artifact-contracts.md

@@ -0,0 +1,138 @@
+# Artifact Contracts
+
+Use the skill-internal `references/protocols/` templates as the first version of delivery artifacts.
+
+## Shared artifact envelope
+
+[KNOWN] All lifecycle artifacts use the same neutral reference fields when they are passed between lanes. A protocol may add fields, but it must not redefine these fields or create a second authority for the artifact:
+
+- `artifact_id`: stable identifier within the active change or task;
+- `artifact_kind`: formal contract, sidecar, progress, drift, review, handoff, evidence, or closeout;
+- `path`: canonical repository-local path or an explicitly approved non-OpenSpec placement;
+- `authority_class`: canonical source, generated/installed adapter, upstream reference, historical evidence, or out of scope;
+- `owner`: capability and lane allowed to write the artifact;
+- `lifecycle_phase`: IDEATE, DEFINE, BUILD, SHIP, or ordinary;
+- `source_requirements`: requirement, decision, risk, or task identifiers represented by the artifact;
+- `status` and `freshness`: current state and the evidence time/scope used to establish it;
+- `evidence_anchors`, `blocked`, and `unverified`: proof references and unresolved limits.
+
+[KNOWN] An artifact reference is navigation and ownership metadata. It does not replace the artifact's owning source, user approval, current Git/filesystem evidence, or fresh verification.
+
+## Shared delta classification
+
+[KNOWN] Every accepted correction, requirement, artifact change, finding, or implementation feedback item receives exactly one classification:
+
+- `covered`: already represented by the accepted contract and verification;
+- `material-question`: a decision-changing ambiguity that must be answered before affected work continues;
+- `material-delta`: changes scope, contract, task, acceptance, risk, or implemented behavior and returns to DEFINE writeback/revalidation;
+- `ordinary-steering`: in-scope execution guidance that does not change the accepted contract;
+- `Unverified`: evidence is insufficient to classify safely.
+
+[KNOWN] The record carries `delta_id`, `classification`, `evidence`, `affected_artifacts`, `writeback_required`, `acceptance_stale`, and `next_action`. It references existing artifacts rather than creating a delta ledger or competing formal authority.
+
+## Shared convergence link
+
+[KNOWN] Each convergence claim uses one link with `requirement_or_decision`, `task_or_package`, `file_or_artifact`, `fresh_verification`, `review_or_security_disposition`, `freshness`, and `status`. Status is `linked`, `missing`, `stale`, `conflicting`, `blocked`, or `Unverified`. A checked task, generated summary, CodeGraph result, or Graphify result is not a substitute for the link.
+
+## Package savepoint and completion-evidence contracts
+
+[KNOWN] Each implementation-package progress-ledger savepoint records `package`, `scope`, `files_changed`, `unresolved_items`, `evidence_state`, and `next_package` after the package's complete accepted behavior is implemented. It triggers no automatic test, review, commit, package approval, independent convergence, or readiness verdict. Generic lifecycle sources derive package identities from the active contract; Package 1–12 is history specific to `complete-aili-workflow-orchestration`.
+
+[KNOWN] After the accepted queue is implemented, ROSE directly inspects the changed scope/affected links and selects the smallest fresh check supporting the completion claim. Success records `IMPLEMENTED_TARGETED_VERIFIED` and stops BUILD. A full task matrix, convergence review, or review/test/security capability is selected only for a concrete gap or affected SHIP claim; none is mandatory because a package or phase exists. Package 12 is only the historical name for this umbrella's completion inspection.
+
+[KNOWN] When a canonical task matrix is actually selected, every current `tasks.md` checklist row appears exactly once with exactly these nine fields: `task_id`; `accepted requirement/decision/risk`; `expected behavior`; `implementation files/artifacts`; `fresh tests/inspection/review evidence`; `status`; `findings`; `disposition`; `freshness`. Status is exactly `Done | Partial | Missing | Blocked | N/A`. `Done` and resolved source-backed `N/A` pass; every other status or unsupported/unresolved state blocks the affected claim. The detailed evidence and mismatch rules remain owned by `agents/convergence-reviewer.md`; optional matrix evidence is not a broad BUILD or release gate.
+
+## Conditional review arbitration artifact
+
+[KNOWN] `openspec/changes/<change-id>/review-arbitration.md` exists only for disputed, blocking, cross-session, or materially inconsistent findings. It preserves finding identity, claims, evidence, counter-evidence, proposed dispositions, ROSE disposition/rationale, decision owner, status, required recheck, freshness, and residual `Unverified` items. It is not a vote ledger, confidence aggregation, routine review report, or artifact created in advance of a real qualifying dispute.
+
+## Shared loop envelope
+
+[KNOWN] This file is the canonical repository protocol path for neutral loop-envelope references. Delivery continuity requirement `CONT-005` remains the sole normative owner of budget representation and invariants. Every profile references one envelope with `loop_kind`, `trigger`, `trigger_evidence`, `objective`, `accepted_contract`, `change_id`, `success_evidence`, one nested `budgets` object, `human_gate`, `operation_gate`, `allowed_actions`, `writeback_targets`, `stop_reason`, and `outcome`. Protocol-only interval/event definitions additionally reference the canonical `ROUTE-007` identity object and may add only `external_trigger_source`, `event_classifier`, or `cancellation`.
+
+[KNOWN] The neutral terminal outcomes are `complete`, `need-user`, `need-evidence`, `material-delta`, `blocked`, `Unverified`, `cancelled`, and `budget-exhausted`. Profiles and packages must reference this envelope; they must not create flat budget fields, a second envelope, a session registry, or a background runtime.
+
+| Mode | Primary artifacts | Minimum fields |
+|---|---|---|
+| IDEATE | `references/protocols/idea-brief.md`, optional research evidence pack, optional lightweight idea capsule, optional backend-neutral `ideas/workflow-inbox.md` | goal, options, assumptions, unknowns, next decision, candidate idea notes when preserved, promotion target when selected |
+| DEFINE | spec draft, alignment questionnaire/interview, acceptance test plan, backend-specific `context.md` for formal changes | scope, requirements, questions, requirements/decisions/risks traceability matrix, test cases, approval state, confirmed decisions, rejected options, BUILD readiness |
+| BUILD | implementation package, subagent packet/result when delegated, progress-ledger savepoints, one minimal completion inspection/check, backend-neutral `progress.txt` ledger with backend-specific placement, `drift-log.md` for spec-backed drift notes, legacy `implementation-notes.html` as read-only migration evidence when present | requirement/decision/risk source, task/package, target files/artifacts, acceptance criteria, forbidden scope, expected/actual evidence, canonical `CONT-005` envelope and nested budgets, changed-scope diff and affected links, smallest targeted completion evidence, branch/status dirty-path classification, progress/checkpoint entries, ROSE decision, `Open Question` / `Unverified` items |
+| SHIP | review report, compact evidence pack when evidence is noisy, required repository-local Markdown closeout report | closeout document path, BUILD gate status, release-blocker audit target/status, spec coverage check result, review findings, finding classifications, repair result, fresh evidence, branch/worktree hygiene status and cleanup approvals needed, existing feature impact, release-readiness risks, `Open Question` / `Unverified` items, next steps |
+
+## Output Contract
+
+Every mode response includes only applicable fields:
+
+- selected mode and backend;
+- artifacts created, updated, or required;
+- gates satisfied, blocked, or unverified;
+- next action.
+
+## SHIP Closeout Document
+
+Every SHIP run must create or update a detailed, human-reviewable Markdown closeout document. The CLI response may stay concise, but it must include the document path, write/update status, verdict, spec coverage check status, branch/worktree hygiene status, blocking/important/`Open Question`/`Unverified` summary, and approved next action.
+
+- OpenSpec-backed SHIP writes `openspec/changes/<change-id>/ship-closeout.md`.
+- Non-OpenSpec SHIP must ask for a repository-local closeout document path before the final verdict if no approved path exists.
+- The document content should be written in Chinese unless the active contract explicitly requests another language.
+- Do not replace the document with chat-only output; if the document cannot be written, mark the SHIP result blocked or `Unverified` and explain why.
+
+## DEFINE Artifact Set
+
+For OpenSpec-backed changes, DEFINE creates or updates only artifacts required by current dependencies under `openspec/changes/<change-id>/`:
+
+```text
+proposal.md
+design.md
+tasks.md
+specs/**/spec.md
+interview.md
+test-plan.md
+context.md
+```
+
+- The listed files are the possible formal set, not a requirement to reread or rewrite all files on each turn.
+- `proposal.md`, `design.md`, `tasks.md`, and `specs/**/spec.md` follow the OpenSpec backend.
+- `interview.md` is generated or updated through `requirements-grilling`.
+- `test-plan.md` is generated or updated through `test-document-generator`.
+- `context.md` records maintained user intent, confirmed decisions, rejected options, unresolved questions, and drift-check anchors for the formal change.
+- Non-OpenSpec artifacts require one placement decision before writing, then the selected locations become part of the active change context.
+
+## Context, Inbox, and Progress Ledgers
+
+- IDEATE may preserve candidate ideas in a lightweight idea capsule or append them to `ideas/workflow-inbox.md` without creating a formal proposal by default; DEFINE promotes only selected ideas into a backend-specific change contract.
+- Formal changes use one backend-specific `context.md`; OpenSpec uses `openspec/changes/<change-id>/context.md`, while non-OpenSpec backends use adapter/placement rules.
+- BUILD uses a backend-neutral `progress.txt` contract; OpenSpec uses `openspec/changes/<change-id>/progress.txt`, while non-OpenSpec BUILD asks once for a repository-local placement before writing. Each implementation-package savepoint includes `scope`, `files_changed`, `unresolved_items`, `evidence_state`, and `next_package` and causes no automatic test, commit, or approval.
+- BUILD continuation references exactly one active canonical `CONT-005` envelope in current context/progress state. It does not create another identity, marker contract, flat budget model, or authorization source.
+- Only ROSE writes/appends `progress.txt`. Workers return compact evidence reports for ROSE to reconcile.
+- `progress.txt` entries include objective, worker dispatches, evidence references, current progress, user feedback/corrections, checkpoint ledger, changed/inspected files, verification/review/security status, blockers, ROSE decision, and next action.
+- For approved spec-backed implementation, maintain `drift-log.md` beside the change artifacts only for spec deviations, model drift/self-corrections, temporary decisions, trade-offs, open questions, unverified assumptions, and required DEFINE write-back. It is not a user-feedback log, progress ledger, review report, or formal contract substitute.
+- Legacy `implementation-notes.html` may be read during hydration or convergence as migration evidence, but new drift/self-correction entries go to `drift-log.md` unless the current active contract explicitly requires the legacy HTML format.
+- Apply `lifecycle.md`'s directed read set: no formal hydration for ordinary chat; next dependency plus direct dependents for DEFINE; accepted gate/current package/owning contract/target/affected verification for BUILD; implemented tree/current BUILD evidence/affected closeout owners for SHIP. Re-read each written file once before durable use and invalidate only dependents after a relevant event.
+- Idea capsules/inbox entries are IDEATE candidates and may guide selection; they are not a formal contract. Legacy `implementation-notes.html`, stale chat summaries, old logs, task checkboxes, handoff, and memory are navigation/migration context only and cannot establish acceptance, permission, completion, or fresh evidence.
+- Context pressure or compression thresholds may prompt an ordinary checkpoint but never authorize compression, handoff, persistence, or lifecycle movement. Continuity is provider-neutral and has no DCP dependency.
+- [KNOWN] `context.md`, `progress.txt`, `drift-log.md`, and legacy `implementation-notes.html` do not replace `rose-memory`, task-scoped `handoffs/` history, explicitly selected legacy `handoff.md`, `interview.md`, `test-plan.md`, backend tasks, formal specs/tasks, or final reports.
+- Exclude secrets, raw logs, full transcripts, full file contents, private data, and long dumps from inbox/context/progress/notes artifacts and evaluator input.
+
+## Memory, receipt, and handoff continuity
+
+- Legacy/pre-runtime `rose-memory` is additive project-local context. Safe scoped reusable explicit user requirements/preferences/corrections/decisions/acceptance criteria default-write through the existing CLI only, with literal `--db memory/memory.db` from the canonical project root and existing fields only. Ambiguous permission or sensitive content blocks or is safely redacted before invocation; alternate/manual/symlink database paths and schema/storage changes block. Backend file mode, backend symlink handling, and retention remain `Unverified`.
+- Ordinary one-turn/report-only work with no memory use and no formal long-running/resume/context-loss need writes no start/end receipt. Those named continuity events or actual current-task memory use require the applicable scoped checkpoint/completion receipt. A receipt is never contract, permission, Git truth, verification, or completion authority.
+- Formal resume reads only the active package/decision and referenced progress, bounded drift, scoped memory, or fresh verification that can change the next action, then revalidates the canonical startup host. It separately revalidates every declared A33 attachment's exact keys, current target root/Git/HEAD/dirty/file/rule state, owning-repository artifact destinations, and applicable `WT-001` identity evidence. Cross-repository common-dir equality is never required; packet, handoff, memory, and checkpoint text are navigation only.
+- [KNOWN] Versioned handoff history is created only on an explicit user or accepted lifecycle trigger. OpenSpec uses `openspec/changes/<change-id>/handoffs/`; ordinary work uses one previously confirmed repository-local `<task-root>/handoffs/` and asks one placement/identity question rather than scanning when that root is unknown.
+- [KNOWN] CREATE uses immutable finalized UTC-named snapshots plus an atomically replaced regular `LATEST.md` containing exact relative path, snapshot ID, SHA-256, and finalized time. LIST reads filenames and bounded frontmatter only. RESUME prefers one user-supplied exact snapshot, otherwise validates the current task's pointer, and never falls back by fuzzy title or another task history.
+- [KNOWN] Handoff stays model-oriented, lightweight, conditional, reference-first, redacted, and non-authoritative. It never auto-creates, auto-prunes, promotes durable memory, imports/moves/rewrites/deletes legacy `<task-root>/handoff.md`, or grants contract, permission, Git, verification, completion, publication, or destructive authority.
+- [KNOWN] Successful CREATE output ends with exactly one localized fenced `text` prompt naming the exact immutable snapshot and requiring current-state revalidation. For A33 the snapshot conditionally records owning-repository artifact destinations plus preserved rollback worktree/evidence references; RESUME revalidates every target/rule/identity separately, and each ADD or non-force REMOVE still needs a new exact approval.
+
+## Future extension point: `artifact-integrity`
+
+`artifact-integrity` is a documentation-only, non-binding name reserved for possible future protocol work. Phase I defines no provider, manifest, schema, digest, nonce, receipt, revision, configuration, storage, runtime behavior, approval semantic, warning, status field, or gate. Its absence has no effect on DEFINE, BUILD, review, SHIP, or any summary.
+
+## BUILD Readiness
+
+DEFINE output must report one of:
+
+- `READY`: all decision-shaping research is closed, artifacts are coherent/strictly valid, material decisions are resolved, and the final test plan is explicitly accepted.
+- `BLOCKED`: a required artifact, material answer, research conclusion, final test-plan acceptance, or evidence item is missing.
+
+A named non-material runtime residual may remain `Unverified` under its separate fail-closed operation gate, but neither a waiver nor accepted-`Unverified` wording is a BUILD-readiness alternative.

package/skills/aili-delivery-flow/references/backend-routing.md

@@ -0,0 +1,40 @@
+# Backend Routing
+
+Backend adapters organize artifacts. They do not define permission to advance modes.
+
+| Backend | Use when | Required handling |
+|---|---|---|
+| OpenSpec | Stage-I formal/material work, or an explicitly resumed change | Resolve one change by accepted scope; read current status/instructions only for the next dependency; write and re-read each applicable artifact once; route `interview.md` to `requirements-grilling` and `test-plan.md` to `test-document-generator`; run strict validation when the formal contract requires it. |
+| Custom files | Repository docs, issues, or bespoke task packets define scope | Cite source files and convert work into artifact contracts before BUILD. |
+| Auto detection | The user did not name a backend | Prefer existing explicit artifacts; ask when multiple plausible backends conflict. |
+
+## Rules
+
+- IDEATE may create recommendations for a backend but does not require one.
+- IDEATE may capture backend-neutral candidate ideas in a lightweight idea capsule or `ideas/workflow-inbox.md`; this does not create a formal change by default.
+- DEFINE may create or update backend artifacts and must record open questions; selected IDEATE ideas are promoted here rather than during pure IDEATE.
+- OpenSpec DEFINE uses deterministic artifact placement under `openspec/changes/<change-id>/`, including `proposal.md`, `design.md`, `tasks.md`, `specs/**/spec.md`, `interview.md`, `test-plan.md`, and `context.md`.
+- Formal Stage-I activation creates or reuses one OpenSpec change exactly once. Same accepted scope reuses; distinct established scope may create; multiple plausible changes or evasive identity answers trigger one focused question and zero writes. Never guess identity or ask whether to write each artifact.
+- File presence is not readiness. Re-read a written artifact once and refresh status/instructions only when its dependency changed; require strict validation, coherent material decisions, and explicit final test-plan acceptance before formal BUILD.
+- DEFINE closes only source gaps both unresolved and capable of changing a material decision. Select the one applicable class—local owner evidence, official/current version evidence, or explicitly requested/material prior art—rather than running all classes. A remaining material gap blocks acceptance; named non-material runtime residuals remain under separate fail-closed gates.
+- Non-OpenSpec DEFINE asks once where to place interview and test-plan artifacts, passes those locations to `requirements-grilling` and `test-document-generator`, and records the decision in the active change context instead of asking repeatedly.
+- Non-OpenSpec context/progress/drift-log artifacts require a repository-local placement decision or backend adapter mapping before writing; do not default them to the repository root.
+- BUILD requires approved backend scope plus either an explicit implementation package or enough ready artifact evidence to synthesize a queue from the active accepted contract. Generic routing must not assume this umbrella's Package 1–12 history or a fixed task count.
+- Use `lifecycle.md`'s directed read set. Normal chat performs no formal hydration; DEFINE reads the next dependency; BUILD reads acceptance/current package/owning contract/target/affected verification; SHIP reads the implemented tree/current BUILD evidence/affected closeout owners. Re-read written files once and invalidate dependents only. Idea/inbox, handoff, memory, old logs, stale chat, task checkboxes, and DCP/compression state are not authority.
+- The user selects the A33 host by starting OpenCode in that Git repository; a non-Git startup root blocks. AILI does not rank, move, broadly scan for, or auto-select hosts. OpenSpec BUILD resolves exactly one declared target repository from current backend/`WT-001` context and never treats another repository as a better host. Each lane targets one declared repository/cwd, target rules are re-read at the operation/dispatch boundary, may narrow but never broaden, same-level conflicts block, and artifacts remain in the owning target.
+- Before an A33 attachment is eligible, require exact destination `<session-root>/.worktrees/<repo_key>/<worktree_key>`, exact `/.worktrees/` ignore with no re-inclusion/tracked destination, grammar-valid non-reserved keys, collision-free trusted path/topology, separate current host/source/target identity evidence, and explicit branch/base-ref plus `branch_mode:existing|create` and source `reflog_policy:enabled|disabled`. Never suffix, guess, force, use `-B`, create orphan state, guess a remote, or infer a ref.
+- A33 backend records are references, not operation authority. PREPARE has zero add/remove effect. Each real or `driver_fixture` ADD and later non-force REMOVE needs a distinct fresh exact key/class-bound approval; ADD also needs accepted trusted-code risk, while observed REMOVE uses `trusted_code_risk:not_applicable` only under its separate deletion-inventory/risk gate. Missing, stale, reused, mismatched, wrong-class, or risk-invalid approval has zero effect.
+- Cross-repository backend resolution references one current `WT-001` context at `protocols/worktree-context.md`. Backend artifacts carry only its reference and cannot duplicate or rebind host/source/target Git, key, approval, dirty-state, path, command/cwd, or containment facts. A30/A31 external-read routing and probes are historical only and cannot prove A33 behavior.
+- Backend selection never chooses another process skill. Run the proactive delegation scan and use `subagent.dispatch` for an explicit user request or a concrete specialist/noisy-context/independent-unit gap; direct work is the no-trigger/blocked fallback. At most one auxiliary capability is selected. The current OpenCode adapter mapping is: Default Task concurrency is at most two but is not a hard cap. Larger bounded fan-out requires independent non-overlapping units, concrete benefit, suitable owners, and an explicit join plan.
+- OpenSpec BUILD with exactly one ready change and pending tasks synthesizes a neutral package queue from current `tasks.md`, specs, design, dependencies, and `test-plan.md`, maps requirement/decision/risk sources to package/file/artifact/verification evidence, records progress-ledger savepoints containing `scope`, `files_changed`, `unresolved_items`, `evidence_state`, and `next_package`, then uses one direct changed-scope diff/affected-link inspection and the smallest sufficient completion check. Savepoints trigger no automatic test, commit, or package approval.
+- BUILD may hydrate accepted artifacts, confirm exact implementation locality/contracts, and perform bounded diagnosis only. Open-ended or mature-prior-art research blocks. A discovery changing scope, architecture, dependency, public contract, permissions, acceptance, or verification strategy emits `BUILD_MATERIAL_DISCOVERY`, stops before changed work, and returns to DEFINE writeback/revalidation/reacceptance.
+- Continuation references exactly one active canonical `CONT-005` envelope through current context/progress state. It preserves target, phase, accepted authorization, current gates, consumed budgets, accounting/overshoot state, and stop reason; it creates no second session identity or marker contract.
+- Approved spec-backed BUILD records current progress, user feedback/corrections, checkpoint ledger, traceability evidence, verification/review/security state, blockers, ROSE decisions, and next action in `progress.txt`.
+- Approved spec-backed BUILD maintains `drift-log.md` only for spec deviations, model drift/self-corrections, temporary decisions, trade-offs, open questions, unverified assumptions, and required DEFINE write-back; append to legacy `implementation-notes.html` only when the active contract explicitly requires legacy HTML.
+- Keep sidecars such as `progress.txt`, `drift-log.md`, legacy `implementation-notes.html`, and scoped state markers as AILI-managed files for the MVP. Only create or fork a custom OpenSpec schema later if these sidecars need first-class OpenSpec generation or validation.
+- Only ROSE writes progress ledger entries. Workers must return compact reports and evidence references instead of editing `progress.txt`.
+- BUILD success records `IMPLEMENTED_TARGETED_VERIFIED` and stops. SHIP requires fresh explicit intent, reuses still-covering BUILD evidence, and refreshes only stale or affected claim rows. Unchanged transport does not stale evidence; a changed merge triggers only affected integration checks. CI failure returns to the user with no automatic repair, commit, push, merge, or release. Commit, push, merge, and release retain separate exact approvals.
+
+## Generated/direct OpenSpec surfaces
+
+Classify OpenSpec-facing surfaces before edits as canonical AILI source, generated/installed adapter, or upstream runtime/tool. Current `.opencode/commands/opsx-*` and `.opencode/skills/openspec-*` are unchanged direct routes outside AILI guarantees. Do not route or recommend users to them, hand-edit/wrap/suppress/prevent them, alter a generator to control them, or treat their output as AILI evidence. AILI-owned generated output changes only through an explicitly in-scope canonical source/generator. Upstream runtime changes are out of scope.