agentic-dev-loop 0.2.0__py3-none-any.whl

agentic_dev_loop/__init__.py

@@ -0,0 +1 @@
+"""Opinionated LangGraph engine for OpenHands agent pipelines."""

agentic_dev_loop/actions.py

@@ -0,0 +1,189 @@
+"""Built-in pipeline actions. Node-shaped: (state, params) -> state update.
+
+`commit` policy (ported unchanged from yosk): agents never commit mid-run;
+the pipeline commits exactly once, and only when the worktree was clean at
+run start — a dirty-at-start run is committed by the human, so the
+auto-commit can never swallow pre-existing unrelated changes (run 004: the
+dev agent's b4acb62a swept up an unrelated .gitignore edit).
+"""
+
+import os
+import shutil
+import subprocess
+import sys
+import time
+from pathlib import Path
+
+from .proc import child_env, is_pid_token
+
+
+def _git(args: list[str], cwd: Path) -> subprocess.CompletedProcess:
+    """Best-effort git invocation — callers inspect returncode/stdout rather
+    than raising, so a git problem never crashes a verified run. ``git`` is
+    resolved via ``shutil.which`` and run argv-style with a scrubbed child
+    environment (BR-5)."""
+    git = shutil.which("git")
+    if git is None:
+        return subprocess.CompletedProcess(["git", *args], 127, "", "")
+    return subprocess.run([git, *args], cwd=cwd, capture_output=True,
+                          text=True, check=False, shell=False,
+                          env=child_env())
+
+
+def git_worktree_clean(path: Path) -> bool:
+    """True only when `path` is a git repo with no uncommitted changes.
+    Outside a repo there is no clean baseline — False (fail-safe, keeps the
+    commit node disabled)."""
+    result = _git(["status", "--porcelain"], cwd=path)
+    return result.returncode == 0 and not result.stdout.strip()
+
+
+def _parse_cwd_output(out: str) -> str | None:
+    """The cwd path from `lsof -a -p PID -d cwd -Fn` output, or None when the
+    payload doesn't carry one. Two formats occur in the wild: macOS prints
+    `p<PID>` / `fcwd` / `n<path>` (the path is the `n` line immediately after
+    `fcwd`); Linux omits the fd line and prints `p<PID>` / `n<path>` (the
+    path is the first `n` line)."""
+    lines = out.splitlines()
+    for i, line in enumerate(lines):
+        if line == "fcwd" and i + 1 < len(lines):
+            nxt = lines[i + 1]
+            if nxt.startswith("n"):
+                return nxt[1:]
+        if line.startswith("n"):
+            return line[1:]
+    return None
+
+
+def _pid_cwd(pid: str) -> str | None:
+    """The working directory of `pid`, or None on any failure (lsof missing,
+    the process gone, or an unreadable cwd). Positive-only attribution: a pid
+    whose cwd can't be determined is spared by the caller, never killed.
+    Only a validated pid token reaches ``lsof`` (BR-5.2)."""
+    if not is_pid_token(pid):
+        return None
+    lsof = shutil.which("lsof")
+    if lsof is None:
+        return None
+    try:
+        out = subprocess.run(
+            [lsof, "-a", "-p", pid, "-d", "cwd", "-Fn"],
+            capture_output=True, text=True, check=False, shell=False,
+            env=child_env()).stdout
+    except FileNotFoundError:
+        return None
+    return _parse_cwd_output(out)
+
+
+def _listening_pids(port: int, match: str | None = None,
+                    cwd: Path | str | None = None) -> list[str]:
+    """PIDs of processes listening on `port`, optionally only those whose
+    command line contains `match` and whose working directory resolves to
+    `cwd`. The current process is always excluded — a pipeline must never
+    sweep its own listener (e.g. the live viz server), only orphaned
+    listeners left behind by earlier runs or agent subprocesses.
+
+    `cwd` is positive-only: a pid whose cwd can't be determined is spared,
+    so a multi-instance setup (two agentic-dev-loop runs from different
+    workspaces) never kills the other run's server.
+
+    Every token from ``lsof`` output is validated numeric before it can reach
+    ``ps``/``kill`` (BR-5.2); binaries resolve via ``shutil.which`` and run
+    argv-style with a scrubbed environment (BR-5.1, BR-5.3, BR-5.4)."""
+    lsof = shutil.which("lsof")
+    if lsof is None:
+        return []
+    out = subprocess.run(
+        [lsof, "-nP", "-ti", f"tcp:{port}", "-sTCP:LISTEN"],
+        capture_output=True, text=True, check=False, shell=False,
+        env=child_env()).stdout
+    self_pid = str(os.getpid())
+    ps = shutil.which("ps")
+    pids = []
+    for token in out.split():
+        if not is_pid_token(token) or token == self_pid:
+            continue
+        if match is not None:
+            if ps is None:
+                continue
+            cmd = subprocess.run(
+                [ps, "-p", token, "-o", "command="],
+                capture_output=True, text=True, check=False, shell=False,
+                env=child_env()).stdout
+            if match not in cmd:
+                continue
+        if cwd is not None:
+            pid_cwd = _pid_cwd(token)
+            if pid_cwd is None or Path(pid_cwd).resolve() != Path(cwd).resolve():
+                continue
+        pids.append(token)
+    return pids
+
+
+def kill_listeners_on_port(port: int, match: str | None = None,
+                           term_timeout: float = 3.0,
+                           cwd: Path | str | None = None) -> None:
+    """Kill processes listening on `port`, optionally only those whose command
+    line contains `match` and whose working directory resolves to `cwd`. A
+    stage that was cut short can orphan its server; the next attempt's server
+    would fail to bind and probes would hit the stale process serving a
+    previous attempt's build.
+
+    SIGTERM first, then SIGKILL whatever still holds the port after
+    `term_timeout` — a server that ignores TERM must not hold the port
+    indefinitely. Port freedom is judged by re-running lsof, so zombies
+    (dead, unreaped children) never look like survivors."""
+    if shutil.which("lsof") is None:
+        print(f"WARNING: lsof not found — cannot sweep orphaned listeners on "
+              f"port {port}.", file=sys.stderr, flush=True)
+        return
+    kill = shutil.which("kill")
+    pids = _listening_pids(port, match, cwd)
+    for pid in pids:
+        if kill is not None:
+            subprocess.run([kill, pid], capture_output=True, check=False,
+                           shell=False, env=child_env())
+    survivors = pids
+    deadline = time.monotonic() + term_timeout
+    while survivors and time.monotonic() < deadline:
+        survivors = _listening_pids(port, match, cwd)
+        if survivors:
+            time.sleep(0.05)
+    for pid in survivors:
+        if kill is not None:
+            subprocess.run([kill, "-9", pid], capture_output=True, check=False,
+                           shell=False, env=child_env())
+
+
+def commit(state: dict, params: dict) -> dict:
+    """The pipeline's only commit point. Skipped loudly when the worktree was
+    dirty at run start, so the auto-commit can never swallow pre-existing
+    unrelated changes; a dirty-at-start run is committed by the human.
+
+    `params["message"]` is required — a template rendered with `{subject}`.
+    Runs in the process's cwd (the consumer repo the pipeline was launched
+    from)."""
+    subject = state["subject"]
+    if not state.get("commit_allowed", False):
+        print(f"[{subject}] Skipping auto-commit — worktree was dirty at run "
+              f"start; commit the constructed work manually.", flush=True)
+        return {}
+    if "message" not in params:
+        raise ValueError("commit action requires params.message "
+                         "(a template rendered with {subject})")
+    cwd = Path.cwd()
+    _git(["add", "-A"], cwd=cwd)
+    if not _git(["status", "--porcelain"], cwd=cwd).stdout.strip():
+        print(f"[{subject}] Nothing to commit.", flush=True)
+        return {}
+    message = params["message"].format(subject=subject)
+    result = _git(["commit", "-m", message], cwd=cwd)
+    if result.returncode != 0:
+        # The work is built and verified — a git error is a loud warning,
+        # not a pipeline failure.
+        print(f"WARNING: [{subject}] auto-commit failed — commit manually.\n"
+              f"{result.stderr.strip()}", file=sys.stderr, flush=True)
+        return {}
+    short = _git(["rev-parse", "--short", "HEAD"], cwd=cwd).stdout.strip()
+    print(f"[{subject}] Committed constructed work as {short}.", flush=True)
+    return {}

agentic_dev_loop/agents.py

@@ -0,0 +1,49 @@
+"""Agent file loading + SDK factory mechanics.
+
+The SDK's built-in tools are registered at import (its registry is global);
+consumer tools are registered by extensions via `Registry.add_tool`."""
+
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from openhands.sdk import LLM
+from openhands.tools.file_editor import FileEditorTool  # noqa: F401 — registers "file_editor"
+from openhands.tools.task_tracker import TaskTrackerTool  # noqa: F401 — registers "task_tracker"
+from openhands.tools.terminal import TerminalTool  # noqa: F401 — registers "terminal"
+
+if TYPE_CHECKING:
+    from openhands.sdk.agent.agent import Agent
+
+
+def load_agent(agents_dir: Path | str, name: str, llm: LLM) -> "Agent":
+    """Load `<agents_dir>/<name>.agent.md` and build the Agent via the SDK
+    factory (frontmatter tool names resolved against the registry, unknown →
+    ValueError; the markdown body is delivered as the system prompt suffix).
+
+    Tool surface (BR-1): the frontmatter `tools:` list is the exact
+    capability allowlist — every name must resolve to a registered SDK tool.
+    `FinishTool` (done signal) and `ThinkTool` (reasoning scaffold) are added
+    by the SDK as default infra, never part of the allowlist and never
+    removable via `tools:`. There is no regex or default-tools knob.
+
+    Two pipeline policies on top of the SDK's native AgentDefinition loader:
+    the file must exist (fail fast — the SDK's dir loader would silently
+    skip it) and its frontmatter name must match its filename. A file with
+    no frontmatter or no name gets the SDK's stem fallback ("<name>.agent"),
+    which can never match the stem — so both degenerate cases fail the name
+    check."""
+    from openhands.sdk.subagent.registry import agent_definition_to_factory
+    from openhands.sdk.subagent.schema import AgentDefinition
+
+    path = Path(agents_dir) / f"{name}.agent.md"
+    if not path.is_file():
+        raise FileNotFoundError(f"Agent file not found: {path}")
+
+    agent_def = AgentDefinition.load(path)
+
+    stem = path.name.removesuffix(".agent.md")
+    if agent_def.name != stem:
+        raise ValueError(
+            f"Agent file {path} name {agent_def.name!r} does not match "
+            f"filename {stem!r}")
+    return agent_definition_to_factory(agent_def)(llm)

agentic_dev_loop/cli.py

@@ -0,0 +1,82 @@
+"""Two-phase CLI: phase 1 finds the pipeline YAML; phase 2 builds the full
+parser — core flags plus every document loader's contributed args (the
+built-in `plan` loader plus whatever the pipeline's `extensions:` register)
+— and runs the pipeline. A loader's flag therefore exists only when its
+extension is listed in that pipeline's YAML."""
+
+import argparse
+import importlib.metadata
+import sys
+from pathlib import Path
+
+from .config import load_config
+from .graph import run_pipeline
+from .registry import default_registry, load_extensions
+
+
+def _version() -> str:
+    """The installed distribution version — the single source of truth."""
+    try:
+        return importlib.metadata.version("agentic-dev-loop")
+    except importlib.metadata.PackageNotFoundError:
+        print("agentic-dev-loop is not installed — version unavailable; "
+              "run `pip install -e .`", file=sys.stderr)
+        raise SystemExit(1)
+
+
+def _add_version_flag(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--version", action="version",
+                        version=f"agentic-dev-loop {_version()}")
+
+
+def _core_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="agentic-dev-loop",
+        description="Run an OpenHands agent pipeline defined in YAML. "
+                    "Document-loader flags contributed by the pipeline's "
+                    "extensions appear once PIPELINE is known — see "
+                    "`agentic-dev-loop PIPELINE --help`.")
+    parser.add_argument("pipeline", type=Path,
+                        help="path to the pipeline YAML")
+    parser.add_argument("--resume", metavar="THREAD_ID", default=None,
+                        help="resume a checkpointed run by thread id")
+    parser.add_argument("--max-attempts", type=int, default=None,
+                        help="override the pipeline's max_attempts")
+    parser.add_argument("--no-viz", action="store_true",
+                        help="suppress the live graph view (served by "
+                             "default)")
+    parser.add_argument("--viz-port", type=int, default=8321,
+                        help="preferred port for the live graph view "
+                             "(default: 8321; falls back to a free port when "
+                             "busy)")
+    _add_version_flag(parser)
+    return parser
+
+
+def build_parser(cfg_path) -> argparse.ArgumentParser:
+    """The full parser for one pipeline: core flags + loader-contributed."""
+    cfg = load_config(cfg_path)
+    registry = default_registry()
+    load_extensions(cfg.extensions, registry)
+    parser = _core_parser()
+    for loader in registry.document_loaders:
+        loader.add_cli_args(parser)
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    probe = argparse.ArgumentParser(add_help=False)
+    probe.add_argument("pipeline", type=Path, nargs="?")
+    _add_version_flag(probe)
+    known, _ = probe.parse_known_args(argv)
+    if known.pipeline is None:
+        # No pipeline → the extension surface is unknowable; the core parser
+        # handles --help and the missing-positional error itself (both exit).
+        _core_parser().parse_args(argv)
+        return 2  # unreachable — parse_args exits first
+    args = build_parser(known.pipeline).parse_args(argv)
+    success, _attempts = run_pipeline(args.pipeline, args)
+    if not success:
+        print("agentic-dev-loop: pipeline failed — exiting with code 1",
+              file=sys.stderr)
+    return 0 if success else 1

agentic_dev_loop/config.py

@@ -0,0 +1,156 @@
+"""Pipeline YAML schema and loader. Strict: unknown keys fail at every level."""
+
+from pathlib import Path
+from typing import Any
+
+import yaml
+from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
+
+TERMINALS = frozenset({"success", "failure"})
+
+
+class VerdictSpec(BaseModel):
+    model_config = ConfigDict(extra="forbid", populate_by_name=True)
+
+    pass_: str = Field(alias="pass")
+    fail: str = Field(alias="fail")
+
+
+class Route(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    goto: str
+    retry: bool = False  # True consumes an attempt; exhaustion routes to failure
+
+
+RouteTarget = str | Route
+
+
+def route_target(route: RouteTarget | None) -> str | None:
+    if route is None:
+        return None
+    return route.goto if isinstance(route, Route) else route
+
+
+class StepConfig(BaseModel):
+    """One pipeline step. Its type IS the key it carries: exactly one of
+    `agent`, `action`, or `command` — empty values do not count, anything
+    else fails to load. See the `kind` property (the single discriminator
+    graph-building dispatches on)."""
+    model_config = ConfigDict(extra="forbid")
+
+    name: str
+    agent: str | None = None
+    action: str | None = None
+    command: str | None = None  # mechanical step: exit code is the verdict
+    params: dict[str, Any] = {}
+    produces: list[str] = []  # hygiene-tracked, no verdict parsing
+    artifact: str | None = None  # hygiene-tracked AND verdict-parsed
+    verdicts: VerdictSpec | None = None
+    max_iterations: int | None = None
+    timeout: float | None = Field(default=None, gt=0)  # seconds, command steps only
+    on_pass: RouteTarget | None = None
+    on_fail: RouteTarget | None = None
+
+    @property
+    def kind(self) -> str:
+        """The step's type: 'agent', 'command', or 'action'. Which of the
+        three keys is set is the ONLY signal; validation has already
+        guaranteed exactly one is set and non-empty by the time any instance
+        exists."""
+        if self.agent is not None:
+            return "agent"
+        if self.command is not None:
+            return "command"
+        return "action"
+
+    @field_validator("produces", mode="before")
+    @classmethod
+    def _coerce_produces(cls, v: Any) -> Any:
+        return [v] if isinstance(v, str) else v
+
+    @model_validator(mode="after")
+    def _check_shape(self) -> "StepConfig":
+        for key in ("agent", "action", "command"):
+            value = getattr(self, key)
+            if value is not None and not value.strip():
+                raise ValueError(
+                    f"step {self.name!r}: {key!r} must be a non-empty string"
+                )
+        if sum(k is not None for k in (self.agent, self.action, self.command)) != 1:
+            raise ValueError(
+                f"step {self.name!r}: exactly one of 'agent', 'action', or "
+                "'command' is required"
+            )
+        if self.command is not None:
+            for field, empty in (("artifact", None), ("verdicts", None),
+                                 ("produces", []), ("params", {}),
+                                 ("max_iterations", None)):
+                if getattr(self, field) != empty:
+                    raise ValueError(
+                        f"step {self.name!r}: 'command' steps cannot set {field!r}"
+                    )
+        if (self.artifact is None) != (self.verdicts is None):
+            raise ValueError(
+                f"step {self.name!r}: 'artifact' and 'verdicts' must appear together"
+            )
+        if self.artifact is not None and self.produces:
+            raise ValueError(
+                f"step {self.name!r}: 'produces' and 'artifact' are mutually exclusive"
+            )
+        if self.timeout is not None and self.command is None:
+            raise ValueError(
+                f"step {self.name!r}: 'timeout' requires 'command'"
+            )
+        return self
+
+
+class LlmConfig(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    model: str
+    base_url: str | None = None
+    api_key_env: str
+    timeout: float | None = None  # omitted → opinionated no-timeout default
+
+
+class PipelineConfig(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    name: str
+    extensions: list[str] = []
+    additional_files: list[str] = []
+    env_allowlist: list[str] = []
+    llm: LlmConfig
+    state_dir: str = ".pr"
+    max_attempts: int = 3
+    agents_dir: str
+    steps: list[StepConfig] = Field(min_length=1)
+
+    @model_validator(mode="after")
+    def _check_graph(self) -> "PipelineConfig":
+        names = [s.name for s in self.steps]
+        dupes = sorted({n for n in names if names.count(n) > 1})
+        if dupes:
+            raise ValueError(f"duplicate step names: {dupes}")
+        for n in names:
+            if n in TERMINALS:
+                raise ValueError(f"step name {n!r} collides with a reserved terminal")
+        valid = set(names) | TERMINALS
+        for step in self.steps:
+            for route in (step.on_pass, step.on_fail):
+                target = route_target(route)
+                if target is not None and target not in valid:
+                    raise ValueError(
+                        f"step {step.name!r}: unknown route target {target!r}"
+                    )
+        return self
+
+
+def load_config(path: Path) -> PipelineConfig:
+    data = yaml.safe_load(Path(path).read_text())
+    if not isinstance(data, dict):
+        raise ValueError(
+            f"pipeline config must be a mapping, got {type(data).__name__}: {path}"
+        )
+    return PipelineConfig.model_validate(data)

agentic_dev_loop/extensions/aidlc.py

@@ -0,0 +1,152 @@
+"""AI-DLC document-loader extension. Loading IS choosing: name
+`agentic_dev_loop.extensions.aidlc:AidlcExtension` in the pipeline's
+`extensions:` list and the pipeline gains `--ai-dlc-unit` (any
+unambiguous unit spelling: U4 / 4 / 004 / U004 / full slug) plus bare-run
+autodetect of the current unit from `aidlc-docs/aidlc-state.md`.
+
+Resolvers are verbatim ports of yosk's `resolve_unit_docs` /
+`get_current_unit`, with `docs_dir` parameterised (was the module-level
+AIDLC_DOCS_DIR) and the coding-standards merge dropped (the pipeline's
+`additional_files:` now owns shared files).
+"""
+
+import argparse
+import re
+from pathlib import Path
+
+_DOC_SUFFIXES = (".md", ".yaml", ".yml", ".txt")
+_UNIT_DIR_NUMBER = re.compile(r"unit[-_](\d+)")
+
+
+def _leading_number(text: str) -> int | None:
+    """Leading digits of a unit id (``"004-preset-management"`` -> 4), or
+    None for ids that do not start with a number."""
+    match = re.match(r"(\d+)", text)
+    return int(match.group(1)) if match else None
+
+
+def _dir_unit_number(dir_name: str) -> int | None:
+    """Numeric prefix of a unit dir name (``"unit-004-preset-management"``
+    -> 4, ``"unit-14"`` -> 14)."""
+    match = _UNIT_DIR_NUMBER.match(dir_name.lower())
+    return int(match.group(1)) if match else None
+
+
+def resolve_unit_docs(docs_dir: Path | str, unit_id: str) -> dict[str, str]:
+    docs: dict[str, str] = {}
+    docs_dir = Path(docs_dir)
+    unit_id = unit_id.strip()
+    if unit_id[:1] in ("U", "u"):
+        unit_id = unit_id[1:]
+
+    unit_patterns = [f"unit-{unit_id}", f"unit_{unit_id}"]
+    number = _leading_number(unit_id)
+    construction_dir = docs_dir / "construction"
+    candidates: list[Path] = []
+    if construction_dir.is_dir():
+        for entry in sorted(construction_dir.iterdir()):
+            if not entry.is_dir():
+                continue
+            name = entry.name.lower()
+            if name == unit_patterns[0].lower() or name == unit_patterns[1].lower():
+                candidates.append(entry)
+            elif number is not None and _dir_unit_number(entry.name) == number:
+                candidates.append(entry)
+
+    candidates = sorted(set(candidates), key=lambda p: p.name.lower())
+    if len(candidates) > 1:
+        raise RuntimeError(
+            f"Ambiguous unit id '{unit_id}': multiple unit directories match "
+            f"({', '.join(p.name for p in candidates)}). Pass the full unit "
+            "slug to disambiguate.")
+
+    unit_dir = candidates[0] if candidates else None
+    if unit_dir is None:
+        look_for = ", ".join(unit_patterns)
+        if number is not None:
+            look_for += f", or any unit dir numbered {number}"
+        raise FileNotFoundError(
+            f"No docs directory found for unit {unit_id} under {construction_dir} "
+            f"(looked for {look_for})")
+
+    for file in sorted(unit_dir.rglob("*")):
+        if file.is_file() and file.suffix in _DOC_SUFFIXES:
+            key = str(file.relative_to(unit_dir))
+            docs[key] = file.read_text()
+
+    # At this point docs holds only unit-dir files — an empty load means the
+    # pipeline would build context from inception docs alone (the 2026-07-19
+    # U3 silent-degradation bug). Fail fast instead.
+    if not any(not k.startswith("inception/") for k in docs):
+        raise RuntimeError(
+            f"Unit dir {unit_dir} matched but yielded no docs — "
+            "refusing to build context from inception docs alone")
+
+    # Namespaced keys so an inception doc can never silently overwrite a
+    # unit doc with the same filename.
+    inception = docs_dir / "inception" / "application-design"
+    if inception.is_dir():
+        for file in sorted(inception.iterdir()):
+            if file.is_file() and file.suffix in (".md", ".txt"):
+                docs[f"inception/{file.name}"] = file.read_text()
+
+    # The unit's code-generation plans are the build spec — absent is fine,
+    # present is how the spec reaches agents.
+    plans_dir = docs_dir / "construction" / "plans"
+    if plans_dir.is_dir():
+        for file in sorted(plans_dir.glob(f"unit-{unit_id}-*-code-generation-plan.md")):
+            docs[f"plans/{file.name}"] = file.read_text()
+
+    return docs
+
+
+def get_current_unit(docs_dir: Path | str) -> str:
+    """Read the current unit from the aidlc-state.md Current Stage line."""
+    state_file = Path(docs_dir) / "aidlc-state.md"
+    if not state_file.is_file():
+        raise FileNotFoundError(f"aidlc-state file not found: {state_file}")
+    # Anchor to the Current Stage line — the file accumulates history, so an
+    # unanchored search could silently pick up an earlier "Unit N" mention.
+    match = re.search(r"Current Stage[^\n]*Unit (\d+)", state_file.read_text())
+    if not match:
+        raise RuntimeError(
+            f"Could not determine current unit from {state_file} "
+            "(no 'Unit N' in the Current Stage line)")
+    return f"U{match.group(1)}"
+
+
+def _normalize_unit(unit: str) -> str:
+    unit = unit.strip()
+    if unit[:1] in ("U", "u"):
+        unit = unit[1:]
+    return f"U{unit}"
+
+
+class AidlcDocumentLoader:
+    """`--ai-dlc-unit` (any unambiguous spelling), or bare-run
+    autodetect from aidlc-state.md."""
+
+    name = "ai-dlc"
+    defaultable = True
+
+    def __init__(self, docs_dir: Path | str = "aidlc-docs"):
+        self.docs_dir = Path(docs_dir)
+
+    def add_cli_args(self, parser: argparse.ArgumentParser) -> None:
+        parser.add_argument("--ai-dlc-unit", metavar="U<N>", default=None,
+                        help="AI-DLC unit ID: any unambiguous spelling "
+                             "(U4, 4, 004, U004) or the full unit slug "
+                             "(U004-preset-management); defaults to the "
+                             "current unit in aidlc-docs/aidlc-state.md")
+
+    def resolve(self, args: argparse.Namespace) -> tuple[dict[str, str], str]:
+        unit = (_normalize_unit(args.ai_dlc_unit) if args.ai_dlc_unit
+                else get_current_unit(self.docs_dir))
+        return resolve_unit_docs(self.docs_dir, unit), f"unit {unit}"
+
+
+class AidlcExtension:
+    name = "ai-dlc"
+
+    def register(self, registry) -> None:
+        registry.add_document_loader(AidlcDocumentLoader())