aw-spec-cli 0.1.4 → 0.1.5

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

@@ -0,0 +1,312 @@
+#!/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:]))