aw-spec-cli 0.1.5 → 0.1.6

package/assets/.aw-spec/scripts/python/aw-rev-constitution.py

@@ -1,312 +0,0 @@
-#!/usr/bin/env python3
-"""aw-rev-constitution.py — deterministic substrate for the Brownfield GOVERN-BACKWARD
-phase.
-
-A legacy codebase has no GOVERNANCE tier — no split constitution, no rule packs —
-yet specify/design/implement/gates are all driven by one. Govern-backward
-reverse-engineers that tier from what the code itself evidences, so forward
-development of the SAME codebase runs governed exactly like greenfield (Change
-Requests through the CR delta loop).
-
-CALLER (2026-07-29 onward): the standalone `/aw-spec-orch rev-constitution` workflow
-is RETIRED — do not expect that command to exist. The phase now lives in:
-  * `/aw-spec-orch onboard` — up front, over the WHOLE repo, before any slice is
-    adopted. It is the ONLY caller of this core (workflow `scripts:` ref, both
-    shells). At onboard time nothing is adopted yet, so `list-adopted` legitimately
-    returns slice_count 0 and draws its context from the OKF bundle instead.
-  * `/aw-spec-orch adopt` — per slice, reconciling each provisional principle
-    against that slice's real spec.md/design.md evidence. Adopt does NOT call this
-    core; it reconciles in its own steps.
-
-This core survived the retirement unchanged because it is the MODEL-FREE half: it
-enumerates whatever slices ARE adopted and scaffolds the
-`docs/domainspecs/brf-<domain>/` pack directory; the calling workflow's authoring
-agents fill the rule files + the split constitution. Governance stance is AS-BUILT
-(the constitution reflects what the code does, not an aspiration — a separate
-modernization/migration workflow drains the debt later).
-
-Two subcommands, each printing a single JSON object as the LAST stdout line (so
-the orchestrator's execute_script can bind it); human-readable summaries go to
-STDERR so they never corrupt the JSON contract:
-
-  list-adopted [--root <dir>] [--specs <dir>] [--bundle <dir>]
-      -> the union of adopted artifacts to reverse-engineer FROM. Returns
-         {slices[], slice_count, reverse_count, spec_context[], design_context[],
-          all_context[], project_context[], project_name, overview, platform,
-          backlog, root}. *_context arrays are workspace-relative paths ready for a
-          build_context `context_from:`. The technology (design) side carries the
-          designs + OKF overview + platform note + migration backlog + the per-slice
-          source-maps (the code-coordinate bridge) so the TECHNICAL half is derived from
-          what the code evidences AND cites real code files/types, not the template —
-          including the shared-infra gaps (platform Open Questions) and the as-built debt
-          sink to route unmet template ideals to. Stays domain-agnostic by the author's
-          prompt (cite code paths, ignore the source-map's domain spec-ids / entity names).
-
-  pack-setup --name <domain> [--fallback <name>] [--root <dir>]
-      -> slugify + `brf-` prefix the domain, create docs/domainspecs/<slug>/ (guard:
-         refuses to clobber a pack that already holds .md files). Returns
-         {domain_slug, pack_dir, comandrulemap, domain_constitution_source,
-          pack_present}. pack_present is the STRING "true"/"false" (so verify_context
-          require_value/condition can gate the anti-clobber guard).
-
-Usage: aw-rev-constitution.py <list-adopted|pack-setup> [options]
-"""
-
-import argparse
-import json
-import os
-import re
-import sys
-
-
-def _root(arg_root):
-    """Repo/component root: explicit --root, else CWD (the orchestrator runs each
-    execute_script with CWD = the component root, where .aw-spec / specs / docs live)."""
-    return os.path.abspath(arg_root) if arg_root else os.getcwd()
-
-
-def _rel(path, root):
-    """Workspace-relative POSIX path (build_context resolves against CWD = root)."""
-    return os.path.relpath(path, root).replace(os.sep, "/")
-
-
-def _emit(obj):
-    """JSON contract: the object as the LAST stdout line."""
-    print(json.dumps(obj))
-
-
-def _uniq(seq):
-    """Order-preserving de-dup (context arrays are concatenated from overlapping
-    sources — the OKF overview belongs to several of them)."""
-    seen, out = set(), []
-    for x in seq:
-        if x and x not in seen:
-            seen.add(x)
-            out.append(x)
-    return out
-
-
-def _project_name(overview_abs):
-    """The project's display name — the WHOLE project the governance tier governs,
-    NOT the outer tooling folder. Inventory writes the OKF overview's Purpose as
-    '## Purpose ... **<ProjectName>** is a ...', so the first bold token in that
-    section is the solution/product name (e.g. 'Medicinal.Healthcare'). Empty when no
-    overview exists — pack-setup then falls back to the repo basename as before."""
-    if not overview_abs or not os.path.isfile(overview_abs):
-        return ""
-    try:
-        with open(overview_abs, "r", encoding="utf-8", errors="replace") as fh:
-            text = fh.read(8192)
-    except OSError:
-        return ""
-    m = re.search(r"##\s*Purpose\s*(.+?)(?:\n##\s|\Z)", text, re.IGNORECASE | re.DOTALL)
-    scope = m.group(1) if m else text
-    b = re.search(r"\*\*([^*\n]+?)\*\*", scope)
-    return b.group(1).strip() if b else ""
-
-
-# ─────────────────────────────── list-adopted ──────────────────────────────
-def cmd_list_adopted(args):
-    root = _root(args.root)
-    specs_dir = os.path.join(root, args.specs)
-    bundle_dir = os.path.join(root, args.bundle)
-
-    slices = []
-    spec_context = []
-    design_context = []
-    source_maps = []
-    reverse_count = 0
-
-    if os.path.isdir(specs_dir):
-        for name in sorted(os.listdir(specs_dir)):
-            sdir = os.path.join(specs_dir, name)
-            if not os.path.isdir(sdir):
-                continue
-            spec = os.path.join(sdir, "spec.md")
-            design = os.path.join(sdir, "design.md")
-            # A slice is adoptable-governance input only when BOTH docs exist.
-            if not (os.path.isfile(spec) and os.path.isfile(design)):
-                continue
-            smap = os.path.join(sdir, "source-map.md")
-            is_reverse = False
-            try:
-                with open(spec, "r", encoding="utf-8", errors="replace") as fh:
-                    head = fh.read(4096)
-                if re.search(r"reverse-engineered", head, re.IGNORECASE):
-                    is_reverse = True
-            except OSError:
-                pass
-            if is_reverse:
-                reverse_count += 1
-            slices.append({
-                "name": name,
-                "spec": _rel(spec, root),
-                "design": _rel(design, root),
-                "source_map": _rel(smap, root) if os.path.isfile(smap) else "",
-                "origin": "reverse-engineered" if is_reverse else "unknown",
-            })
-            spec_context.append(_rel(spec, root))
-            design_context.append(_rel(design, root))
-            if os.path.isfile(smap):
-                source_maps.append(_rel(smap, root))
-
-    # The OKF architecture overview names the actual tech stack (technology half input).
-    overview = ""
-    overview_abs = ""
-    for cand in ("architecture/overview.md", "architecture/architecture.md"):
-        p = os.path.join(bundle_dir, cand)
-        if os.path.isfile(p):
-            overview = _rel(p, root)
-            overview_abs = p
-            break
-
-    # TECHNICAL evidence beyond the overview, both domain-free: the shared-platform note
-    # (cross-cutting persistence / tenancy / concurrency reality — incl. its Open Questions,
-    # e.g. tenancy may be inactive) and the migration backlog (the as-built DEBT SINK the
-    # technical author routes any unmet template ideal / stub to, instead of asserting it).
-    # These feed the DESIGN side so the technical half is EVIDENCE-FIRST, not template-first.
-    platform_ref = ""
-    p = os.path.join(bundle_dir, "architecture/platform.md")
-    if os.path.isfile(p):
-        platform_ref = _rel(p, root)
-    backlog_ref = ""
-    p = os.path.join(bundle_dir, "migration-backlog.md")
-    if os.path.isfile(p):
-        backlog_ref = _rel(p, root)
-
-    # Project-level OKF framing — the PROJECT AS A WHOLE, not just one adopted slice:
-    # the overview (mission + aggregate map + external refs + stack), the aggregate
-    # index (bounded-context map), and the shared-platform note. These are what let the
-    # DOMAIN author write a project charter instead of a single-aggregate spec. The
-    # technical half deliberately does NOT get the aggregate index or specs (stays
-    # domain-free); it DOES get platform.md + the backlog as technical evidence (below).
-    project_context = [overview] if overview else []
-    for cand in ("aggregates/index.md", "architecture/platform.md", "index.md"):
-        p = os.path.join(bundle_dir, cand)
-        if os.path.isfile(p):
-            project_context.append(_rel(p, root))
-    project_context = _uniq(project_context)
-
-    # The display name of the whole project the governance tier governs (from the OKF
-    # overview), so the pack/constitution are named + titled after the PROJECT — not the
-    # outer tooling folder the CWD-basename fallback would pick.
-    project_name = _project_name(overview_abs)
-
-    # spec side = domain input (specs + source-maps + PROJECT framing); design side =
-    # technology input (designs + OKF stack overview + shared-platform note + as-built
-    # backlog + the per-slice source-maps — the code-coordinate bridge, so the TECHNICAL
-    # half anchors each principle to a real code file/type, not just a design section;
-    # kept domain-agnostic by the author's prompt discipline, not by starving it of the
-    # code map — rich enough to DERIVE the principle set from evidence and route unmet
-    # ideals to debt); all = the pack author's full picture.
-    spec_side = _uniq(spec_context + source_maps + project_context)
-    design_side = _uniq(
-        design_context
-        + source_maps
-        + ([overview] if overview else [])
-        + ([platform_ref] if platform_ref else [])
-        + ([backlog_ref] if backlog_ref else [])
-    )
-    all_context = _uniq(spec_context + design_context + source_maps + project_context)
-
-    result = {
-        "slices": slices,
-        "slice_count": len(slices),
-        "reverse_count": reverse_count,
-        "spec_context": spec_side,
-        "design_context": design_side,
-        "all_context": all_context,
-        "project_context": project_context,
-        "project_name": project_name,
-        "overview": overview,
-        "platform": platform_ref,
-        "backlog": backlog_ref,
-        "root": root,
-    }
-
-    names = ", ".join(s["name"] for s in slices) or "(none)"
-    print(
-        f"[govern-backward] adopted slices: {len(slices)} "
-        f"({reverse_count} reverse-engineered) — {names}\n"
-        f"                   project: {project_name or '(unknown — no OKF overview)'}  "
-        f"overview: {overview or '(none — no OKF bundle)'}\n"
-        f"                   technical evidence: platform={platform_ref or '(none)'}  "
-        f"backlog={backlog_ref or '(none)'}",
-        file=sys.stderr,
-    )
-    _emit(result)
-    return 0
-
-
-# ─────────────────────────────── pack-setup ────────────────────────────────
-def _slugify(name):
-    s = (name or "").strip().lower()
-    s = re.sub(r"[^a-z0-9]+", "-", s)
-    s = re.sub(r"-{2,}", "-", s).strip("-")
-    return s
-
-
-def cmd_pack_setup(args):
-    root = _root(args.root)
-    raw = args.name if (args.name and args.name.strip()) else args.fallback
-    if not raw or not raw.strip():
-        # Last-resort fallback: the component/repo directory name.
-        raw = os.path.basename(root.rstrip(os.sep)) or "domain"
-    slug = _slugify(raw)
-    if not slug:
-        slug = "domain"
-    # Strip any leading brf- the operator already typed, then re-apply once.
-    slug = re.sub(r"^brf-+", "", slug)
-    domain_slug = "brf-" + slug
-
-    pack_dir = os.path.join(root, "docs", "domainspecs", domain_slug)
-    # Anti-clobber guard: a pack that already holds curated .md files is not ours
-    # to overwrite (mirrors inventory's bundle_guard). pack_present drives the gate.
-    present = False
-    if os.path.isdir(pack_dir):
-        present = any(f.endswith(".md") for f in os.listdir(pack_dir))
-    if not present:
-        os.makedirs(pack_dir, exist_ok=True)
-
-    result = {
-        "domain_slug": domain_slug,
-        "pack_dir": _rel(pack_dir, root),
-        "comandrulemap": _rel(os.path.join(pack_dir, "comandrulemap.md"), root),
-        "domain_constitution_source": f"docs/{domain_slug}-constitution.md",
-        "pack_present": "true" if present else "false",
-        "root": root,
-    }
-    print(
-        f"[govern-backward] domain pack: docs/domainspecs/{domain_slug}/ "
-        f"({'EXISTS — guarded' if present else 'created'})",
-        file=sys.stderr,
-    )
-    _emit(result)
-    return 0
-
-
-def main(argv):
-    ap = argparse.ArgumentParser(prog="aw-rev-constitution.py", add_help=True)
-    sub = ap.add_subparsers(dest="cmd")
-
-    la = sub.add_parser("list-adopted", help="enumerate adopted slices to reverse-engineer from")
-    la.add_argument("--root", default="")
-    la.add_argument("--specs", default="specs")
-    la.add_argument("--bundle", default="knowledge")
-    la.set_defaults(func=cmd_list_adopted)
-
-    ps = sub.add_parser("pack-setup", help="create the docs/domainspecs/brf-<domain>/ pack dir")
-    ps.add_argument("--name", default="")
-    ps.add_argument("--fallback", default="")
-    ps.add_argument("--root", default="")
-    ps.set_defaults(func=cmd_pack_setup)
-
-    args = ap.parse_args(argv)
-    if not getattr(args, "func", None):
-        ap.print_help(sys.stderr)
-        return 2
-    return args.func(args)
-
-
-if __name__ == "__main__":
-    sys.exit(main(sys.argv[1:]))