pace-engine 0.1.0__tar.gz

pace_engine-0.1.0/PKG-INFO

@@ -0,0 +1,35 @@
+Metadata-Version: 2.4
+Name: pace-engine
+Version: 0.1.0
+Summary: PACE - an engineering operating system: a versioned, installable engine that preserves and governs a project's knowledge so any AI understands it in seconds.
+Author: Cley Duarte
+Project-URL: Homepage, https://github.com/cleyduartees-dot/PACE
+Keywords: ai,knowledge,engineering,governance,memory,context
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# PACE
+
+An engineering operating system: a versioned, installable engine that preserves, organizes, governs and evolves the architectural knowledge of software projects, in collaboration between people and AI.
+
+PACE is not a library embedded inside a product. It is installed once and governs any number of independent projects, each carrying only its own `.pace/` memory — never a copy of PACE itself.
+
+## Status
+
+Founded 2026-07-06. This repository currently contains only this founding commit. The minimal day-1 skeleton (kernel, services, engines, ontology, protocols, governance, policies, standards, contracts, cli, history, docs) is the next step, not yet built.
+
+## Founding principle
+
+- **PACE** — the engine. Code only, versioned, installable. No knowledge of any specific organization or project.
+- **Organización** — an adopting company's own governance memory (who holds authority, its own policies, its registry of projects), same recursive shape as a project instance, scoped one level up.
+- **Instancia (`.pace/`)** — a single project's own memory: mission, vision, roadmap, sprint, handoff, history, decisions.
+- **Proyecto** — the actual product codebase. Outside PACE's concern beyond hosting a `.pace/` folder at its root.
+
+## Roadmap (founding sequence)
+
+1. Crear el repositorio oficial PACE. — done
+2. Implementar el esqueleto mínimo.
+3. Implementar `pace init`.
+4. Adoptar el primer proyecto gobernado por PACE.
+5. Implementar `pace create`.
+6. Crear el primer proyecto nuevo nacido desde PACE.

pace_engine-0.1.0/README.md

@@ -0,0 +1,25 @@
+# PACE
+
+An engineering operating system: a versioned, installable engine that preserves, organizes, governs and evolves the architectural knowledge of software projects, in collaboration between people and AI.
+
+PACE is not a library embedded inside a product. It is installed once and governs any number of independent projects, each carrying only its own `.pace/` memory — never a copy of PACE itself.
+
+## Status
+
+Founded 2026-07-06. This repository currently contains only this founding commit. The minimal day-1 skeleton (kernel, services, engines, ontology, protocols, governance, policies, standards, contracts, cli, history, docs) is the next step, not yet built.
+
+## Founding principle
+
+- **PACE** — the engine. Code only, versioned, installable. No knowledge of any specific organization or project.
+- **Organización** — an adopting company's own governance memory (who holds authority, its own policies, its registry of projects), same recursive shape as a project instance, scoped one level up.
+- **Instancia (`.pace/`)** — a single project's own memory: mission, vision, roadmap, sprint, handoff, history, decisions.
+- **Proyecto** — the actual product codebase. Outside PACE's concern beyond hosting a `.pace/` folder at its root.
+
+## Roadmap (founding sequence)
+
+1. Crear el repositorio oficial PACE. — done
+2. Implementar el esqueleto mínimo.
+3. Implementar `pace init`.
+4. Adoptar el primer proyecto gobernado por PACE.
+5. Implementar `pace create`.
+6. Crear el primer proyecto nuevo nacido desde PACE.

pace_engine-0.1.0/pace/cli/pace.py

@@ -0,0 +1,253 @@
+"""PACE CLI - thin command layer delegating to the Kernel and Engines.
+
+Beyond argument handling, the only logic here is the guided intake: an
+interactive setup that seeds a project's memory from the owner's answers.
+Run as `python cli/pace.py <command> ...`, or install and run `pace ...`.
+"""
+
+import argparse
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+from pace.kernel.kernel import locate_instance, validate_instance
+from pace.services.pdl import read_pdl
+from pace.engines.project_creator import init_instance, create_project
+from pace.engines.handoff import generate_handoff
+from pace.engines.memory import remember, recall
+
+ACTIVE_SECTIONS = [
+    ("MISSION", "ACTIVE_MISSION"),
+    ("VISION", "ACTIVE_VISION"),
+    ("ROADMAP", "ACTIVE_ROADMAP"),
+    ("SPRINT", "ACTIVE_SPRINT"),
+]
+
+
+def cmd_doctor(args) -> int:
+    root = locate_instance(Path(args.path) if args.path else None)
+    if root is None:
+        print("no .pace/ instance found")
+        return 1
+    violations = validate_instance(root)
+    if violations:
+        print(f"INVALID - {len(violations)} violation(s):")
+        for v in violations:
+            print(f"  - {v}")
+        return 1
+    print(f"VALID - {root}")
+    return 0
+
+
+def cmd_context(args) -> int:
+    root = locate_instance(Path(args.path) if args.path else None)
+    if root is None:
+        print("no .pace/ instance found")
+        return 1
+
+    instance = read_pdl(root / "INSTANCE.pdl")
+    active = read_pdl(root / "ACTIVE_VERSIONS.pdl")
+
+    print(f"NAME {instance.get('NAME')}")
+    print(f"SLUG {instance.get('SLUG')}")
+    print(f"KIND {instance.get('KIND')}")
+    print(f"SCHEMA_VERSION {instance.get('SCHEMA_VERSION')}")
+    if instance.get("ORG_REF"):
+        print(f"ORG_REF {instance.get('ORG_REF')}")
+    print()
+
+    for label, key in ACTIVE_SECTIONS:
+        relative_path = active.get(key)
+        if not relative_path:
+            continue
+        full_path = root / relative_path
+        print(f"--- {label} ({relative_path}) ---")
+        if full_path.is_file():
+            print(full_path.read_text(encoding="utf-8").strip())
+        else:
+            print("(file not found)")
+        print()
+    return 0
+
+
+def _slugify(name: str) -> str:
+    slug = "".join(c if c.isalnum() else "-" for c in name.lower())
+    while "--" in slug:
+        slug = slug.replace("--", "-")
+    return slug.strip("-") or "project"
+
+
+def _prompt(text: str, default: str = "") -> str:
+    suffix = f" [{default}]" if default else ""
+    try:
+        value = input(f"{text}{suffix}\n> ").strip()
+    except EOFError:
+        value = ""
+    return value or default
+
+
+def run_guided_intake(kind, name, slug, org_ref):
+    """Interactive setup: ask a few questions and seed mission / vision /
+    roadmap / sprint. The AI (or the owner) answers; nothing is invented.
+    Returns the resolved identity plus an `extra` dict of seeded content."""
+    print("\nPACE guided setup - a few questions to seed your project's memory.")
+    print("Press Enter to accept a [default] or to skip a question.\n")
+
+    if not name:
+        name = _prompt("Project name") or "Unnamed project"
+    kind_in = _prompt("Kind (PROJECT / ORGANIZATION)", kind or "PROJECT").upper()
+    kind = "ORGANIZATION" if kind_in.startswith("O") else "PROJECT"
+    if kind == "PROJECT" and not org_ref:
+        org_ref = _prompt("Organization it belongs to (org ref)") or "org"
+    if not slug:
+        slug = _prompt("Slug", _slugify(name))
+
+    extra = {}
+    mission = _prompt("Why does this project exist? (mission)")
+    if mission:
+        extra["mission"] = mission
+    vision = _prompt("Where is it going? (vision)")
+    if vision:
+        extra["vision"] = vision
+    roadmap = _prompt("What is pending? (roadmap - main items)")
+    if roadmap:
+        extra["roadmap"] = roadmap
+    sprint = _prompt("What are you working on right now? (current sprint)")
+    if sprint:
+        extra["sprint"] = sprint
+    return kind, name, slug, org_ref, extra
+
+
+def cmd_init(args) -> int:
+    kind, name, slug, org_ref = args.kind, args.name, args.slug, args.org_ref
+    extra = {}
+    if args.guided:
+        kind, name, slug, org_ref, extra = run_guided_intake(kind, name, slug, org_ref)
+
+    if not name:
+        print("init failed: --name is required (or use --guided)")
+        return 1
+    if not slug:
+        slug = _slugify(name)
+
+    try:
+        root = init_instance(
+            Path(args.path), kind=kind, name=name, slug=slug, org_ref=org_ref, **extra
+        )
+    except (FileExistsError, ValueError) as error:
+        print(f"init failed: {error}")
+        return 1
+    print(f"created .pace/ at {root}")
+    violations = validate_instance(root)
+    if violations:
+        print("WARNING - the new instance is not structurally valid:")
+        for v in violations:
+            print(f"  - {v}")
+        return 1
+    return 0
+
+
+def cmd_create(args) -> int:
+    try:
+        root = create_project(
+            Path(args.path),
+            name=args.name,
+            slug=args.slug,
+            org_ref=args.org_ref,
+        )
+    except FileExistsError as error:
+        print(f"create failed: {error}")
+        return 1
+    print(f"created project at {root.parent}")
+    violations = validate_instance(root)
+    if violations:
+        print("WARNING - the new instance is not structurally valid:")
+        for v in violations:
+            print(f"  - {v}")
+        return 1
+    return 0
+
+
+def cmd_handoff(args) -> int:
+    root = locate_instance(Path(args.path) if args.path else None)
+    if root is None:
+        print("no .pace/ instance found")
+        return 1
+    out = generate_handoff(root)
+    print(f"handoff regenerated at {out}\n")
+    print(out.read_text(encoding="utf-8"))
+    return 0
+
+
+def cmd_remember(args) -> int:
+    root = locate_instance(Path(args.path) if args.path else None)
+    if root is None:
+        print("no .pace/ instance found")
+        return 1
+    out = remember(root, args.text)
+    print(f"remembered in {out}")
+    return 0
+
+
+def cmd_recall(args) -> int:
+    root = locate_instance(Path(args.path) if args.path else None)
+    if root is None:
+        print("no .pace/ instance found")
+        return 1
+    print(recall(root))
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="pace")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    doctor = subparsers.add_parser("doctor", help="validate a .pace/ instance structurally")
+    doctor.add_argument("path", nargs="?", default=None)
+    doctor.set_defaults(func=cmd_doctor)
+
+    context = subparsers.add_parser("context", help="print a .pace/ instance's current context")
+    context.add_argument("path", nargs="?", default=None)
+    context.set_defaults(func=cmd_context)
+
+    init = subparsers.add_parser("init", help="create a new .pace/ instance in an existing project")
+    init.add_argument("path")
+    init.add_argument("--kind", choices=["PROJECT", "ORGANIZATION"], default="PROJECT")
+    init.add_argument("--name", default=None)
+    init.add_argument("--slug", default=None)
+    init.add_argument("--org-ref", dest="org_ref", default=None)
+    init.add_argument("--guided", action="store_true",
+                      help="interactive guided setup that seeds mission/vision/roadmap/sprint")
+    init.set_defaults(func=cmd_init)
+
+    handoff = subparsers.add_parser("handoff", help="regenerate the AI-onboarding handoff for a .pace/ instance")
+    handoff.add_argument("path", nargs="?", default=None)
+    handoff.set_defaults(func=cmd_handoff)
+
+    remember = subparsers.add_parser("remember", help="append a continuity note to the project's working memory")
+    remember.add_argument("text")
+    remember.add_argument("path", nargs="?", default=None)
+    remember.set_defaults(func=cmd_remember)
+
+    recall = subparsers.add_parser("recall", help="print the project's working/continuity memory")
+    recall.add_argument("path", nargs="?", default=None)
+    recall.set_defaults(func=cmd_recall)
+
+    create = subparsers.add_parser("create", help="generate a brand-new project governed by PACE from scratch")
+    create.add_argument("path")
+    create.add_argument("--name", required=True)
+    create.add_argument("--slug", required=True)
+    create.add_argument("--org-ref", dest="org_ref", required=True)
+    create.set_defaults(func=cmd_create)
+
+    return parser
+
+
+def main(argv=None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

pace_engine-0.1.0/pace/contracts/INSTANCE_CONTRACT_0.1.0.pdl

@@ -0,0 +1,139 @@
+CONTRACT_VERSION 0.1.0
+
+STATUS DRAFT
+
+OWNER President Cley Duarte
+
+DEPENDS_ON
+
+ontology/PACE_ONTOLOGY_0.1.0.pdl
+protocols/PDL_SPECIFICATION.pdl (not yet written — referenced for future
+  format validation, not required for this contract to be a valid design
+  artifact today)
+
+PURPOSE
+
+Define the physical, checkable shape any .pace/ instance (a project or an
+organization hub — same KIND distinction, not two different contracts)
+must have to be valid. This is the representation layer for the entities,
+relations and assertions defined in PACE_ONTOLOGY_0.1.0.
+
+ROOT_MANIFEST
+
+.pace/INSTANCE.pdl
+
+  REPRESENTS the GOVERNED_UNIT entity itself and its direct identity
+  assertions and relations.
+
+  REQUIRED_FIELDS
+    KIND            PROJECT | ORGANIZATION
+    NAME            (HAS_NAME)
+    SLUG            (HAS_SLUG)
+    SCHEMA_VERSION  (HAS_SCHEMA_VERSION — which Contract version this
+                     instance claims to satisfy)
+    PACE_VERSION    (HAS_PACE_VERSION — which PACE engine version
+                     created or last managed this instance. Traceability
+                     only, permanently: the Kernel never decides what it
+                     can open based on this field, only on SCHEMA_VERSION
+                     — the same way a browser interprets HTML by its
+                     declared version, not by which browser authored it)
+    ORG_REF         (BELONGS_TO target — required if KIND=PROJECT,
+                     absent if KIND=ORGANIZATION)
+    CREATED_AT      (HAS_CREATED_AT)
+
+.pace/ACTIVE_VERSIONS.pdl
+
+  REPRESENTS the IS_CURRENTLY_ACTIVE relation, one entry per versioned
+  assertion sequence.
+
+  REQUIRED_FIELDS
+    ACTIVE_MISSION
+    ACTIVE_VISION
+    ACTIVE_ROADMAP
+    ACTIVE_SPRINT
+
+SECTIONS
+
+mission/, vision/, roadmap/, sprint/
+  REPRESENTS HAS_MISSION / HAS_VISION / HAS_ROADMAP / HAS_CURRENT_SPRINT
+  FORMAT PDL
+  MUTABILITY PROTECTED — superseded, never edited in place; every prior
+    version file is kept
+  REQUIRED_AT_V0.1 folder must exist; content optional
+
+history/
+  REPRESENTS HISTORY_ENTRY
+  FORMAT PDL
+  MUTABILITY PROTECTED — append-only
+  REQUIRED_AT_V0.1 must exist, with at least one founding entry
+
+releases/
+  REPRESENTS RELEASE
+  FORMAT PDL
+  MUTABILITY PROTECTED — append-only
+  REQUIRED_AT_V0.1 folder must exist; content optional
+
+decisions/
+  REPRESENTS DECISION
+  FORMAT PDL (by explicit decision — consistency over the old system's
+    mixed Markdown/PDL convention for this kind of record)
+  MUTABILITY PROTECTED — append-only
+  REQUIRED_AT_V0.1 folder must exist; content optional
+
+requests/
+  REPRESENTS REQUEST
+  FORMAT PDL
+  MUTABILITY core fields (WHO, DATE, RAW_TEXT) PROTECTED, immutable once
+    logged. STATUS and PROMOTED_TO are the one explicit exception —
+    updatable as the request's lifecycle advances.
+  REQUIRED_AT_V0.1 folder must exist; content optional
+
+handoff/
+  REPRESENTS no new entity, relation or assertion — a pure representation
+    layer: a materialized view over mission/vision/roadmap/sprint and
+    ACTIVE_VERSIONS, built for AI-onboarding consumption.
+  FORMAT PDL
+  MUTABILITY REGENERABLE — fully disposable, rebuilt by the Bootstrap /
+    Handoff engine (not yet built)
+  REQUIRED_AT_V0.1 folder must exist, empty until that engine ships
+
+memory/generated/
+  REPRESENTS computed reports (audits, continuity scores) — a regenerable
+    view, not an entity of its own
+  FORMAT JSON
+  MUTABILITY REGENERABLE — free to overwrite or discard
+  REQUIRED_AT_V0.1 folder must exist; content optional
+
+memory/persistent/
+  REPRESENTS HAS_CONTINUITY_NOTE
+  FORMAT PDL or JSON
+  MUTABILITY PROTECTED — refined in place, never silently discarded
+  REQUIRED_AT_V0.1 folder must exist; content optional
+
+NOT_REPRESENTED_HERE
+
+ACTOR entities are not defined per project instance. They live at the
+organization's own governed-unit instance and are referenced by ID from
+any assertion's ASSERTED_BY / APPROVED_BY field — this avoids duplicating
+"who is the President" inside every project instance.
+
+The DEPENDS_ON relation, as used for the PACE repository's own 12-component
+build graph, is not represented inside a project instance. It belongs to
+PACE's own repository, not to any .pace/ instance.
+
+HARD_RULES
+
+1  Every REQUIRED_AT_V0.1 folder must exist structurally, even empty,
+   from the moment pace init runs. Empty is valid; missing is not.
+
+2  No code, script or executable file of any kind may exist anywhere
+   inside .pace/, in any section, ever.
+
+3  PROTECTED sections are never edited in place. Any change to the
+   content of an existing file is a contract violation — only new files
+   or new versions are allowed.
+
+4  REGENERABLE sections (handoff/, memory/generated/) may be freely
+   rewritten or deleted at any time without violating this contract.
+
+END

pace_engine-0.1.0/pace/engines/handoff.py

@@ -0,0 +1,113 @@
+"""Handoff engine - regenerates the AI-onboarding view of a .pace/ instance.
+
+Produces .pace/handoff/HANDOFF.md: the single file an AI reads first. It
+names who governs the project (whom to consult), how to work here, and the
+current mission / vision / roadmap / sprint, plus pointers to the deeper
+memory. The handoff/ section is REGENERABLE: this rebuilds it from the
+authoritative sources, never the other way around.
+"""
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+from pace.services.pdl import read_pdl
+
+ACTIVE_SECTIONS = [
+    ("Mission", "ACTIVE_MISSION"),
+    ("Vision", "ACTIVE_VISION"),
+    ("Roadmap", "ACTIVE_ROADMAP"),
+    ("Current sprint", "ACTIVE_SPRINT"),
+]
+
+
+def _read_section(root: Path, relative_path):
+    if not relative_path:
+        return "(not set)"
+    full = root / relative_path
+    if not full.is_file():
+        return "(file not found)"
+    return full.read_text(encoding="utf-8").strip()
+
+
+def _count_pdl(root: Path, section: str) -> int:
+    d = root / section
+    if not d.is_dir():
+        return 0
+    return sum(1 for p in d.iterdir() if p.is_file() and p.suffix == ".pdl")
+
+
+def _root_authority(root: Path):
+    actors_dir = Path(root) / "actors"
+    if not actors_dir.is_dir():
+        return None
+    for p in sorted(actors_dir.glob("*.pdl")):
+        data = read_pdl(p)
+        if str(data.get("IS_ROOT_AUTHORITY", "")).strip().lower() == "true":
+            label = f"{data.get('ROLE', '')} {data.get('NAME', '')}".strip()
+            return label or data.get("NAME")
+    return None
+
+
+def generate_handoff(root: Path) -> Path:
+    """Rebuild .pace/handoff/HANDOFF.md from the instance. Returns its path."""
+    root = Path(root)
+    instance = read_pdl(root / "INSTANCE.pdl")
+    active = read_pdl(root / "ACTIVE_VERSIONS.pdl")
+    name = instance.get("NAME", "this project")
+    kind = instance.get("KIND", "PROJECT")
+    authority = _root_authority(root)
+
+    out = []
+    out.append(f"# PACE Handoff - {name}")
+    out.append("")
+    out.append("You are an AI joining this project. Read this first: it is the")
+    out.append("project's own memory, so you do not have to ask what we are doing")
+    out.append("or why. This file is regenerated by PACE - do not edit it by hand.")
+    out.append("")
+    out.append("## How to work here")
+    out.append("")
+    if authority:
+        out.append(f"- The ROOT_AUTHORITY of this project is **{authority}**.")
+        out.append("  You ADVISE and AUDIT; they decide. Propose to them, never")
+        out.append("  override. Confirm before anything becomes official.")
+    else:
+        out.append("- You ADVISE and AUDIT; the project owner (ROOT_AUTHORITY) decides.")
+        out.append("  Propose, never override. Confirm with the owner first.")
+    out.append("- Every permanent correction is logged as a request and, once")
+    out.append("  approved, becomes a rule you must follow. Do not re-ask what an")
+    out.append("  approved rule already settles.")
+    out.append("")
+    out.append("## Identity")
+    out.append("")
+    out.append(f"- Name: {name}")
+    out.append(f"- Kind: {kind}")
+    if instance.get("ORG_REF"):
+        out.append(f"- Belongs to: {instance.get('ORG_REF')}")
+    if authority:
+        out.append(f"- Root authority: {authority}")
+    out.append("")
+
+    for label, key in ACTIVE_SECTIONS:
+        out.append(f"## {label}")
+        out.append("")
+        out.append("```")
+        out.append(_read_section(root, active.get(key)))
+        out.append("```")
+        out.append("")
+
+    out.append("## Where the rest of the memory lives")
+    out.append("")
+    out.append(f"- Decisions: .pace/decisions/  ({_count_pdl(root, 'decisions')} recorded)")
+    out.append(f"- History:   .pace/history/    ({_count_pdl(root, 'history')} entries)")
+    out.append(f"- Requests:  .pace/requests/   ({_count_pdl(root, 'requests')} logged in intake)")
+    out.append("")
+    out.append("Read those for the WHY behind decisions and the reasoning that is")
+    out.append("not in the code - including paths that were tried and discarded.")
+    out.append("")
+
+    handoff_dir = root / "handoff"
+    handoff_dir.mkdir(parents=True, exist_ok=True)
+    path = handoff_dir / "HANDOFF.md"
+    path.write_text("\n".join(out) + "\n", encoding="utf-8")
+    return path

pace_engine-0.1.0/pace/engines/memory.py

@@ -0,0 +1,43 @@
+"""Working-memory engine - the continuity notes an AI keeps so it does not
+lose the thread within a long chat or across chats (the anti-"dementia"
+layer). `remember` appends a note; `recall` prints the accumulated memory.
+
+Lives in .pace/memory/persistent/CONTINUITY.md - refined in place, never
+silently discarded (HAS_CONTINUITY_NOTE). Agreements that become permanent
+graduate from here into decisions/ or history/; this file is the running
+working memory, not the system of record.
+"""
+
+from datetime import datetime, timezone
+from pathlib import Path
+
+MEMORY_FILE = "memory/persistent/CONTINUITY.md"
+
+_HEADER = (
+    "# Continuity memory\n\n"
+    "Running notes so an AI keeps the thread - objective, decisions, open\n"
+    "threads, latest state. Newest last. Read this every turn; do not lose\n"
+    "what was already agreed.\n\n"
+)
+
+
+def _memory_path(root: Path) -> Path:
+    return Path(root) / MEMORY_FILE
+
+
+def remember(root: Path, text: str) -> Path:
+    path = _memory_path(root)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    if not path.exists():
+        path.write_text(_HEADER, encoding="utf-8")
+    stamp = datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M")
+    with path.open("a", encoding="utf-8") as handle:
+        handle.write(f"- [{stamp}] {text}\n")
+    return path
+
+
+def recall(root: Path) -> str:
+    path = _memory_path(root)
+    if not path.is_file():
+        return '(no continuity memory yet - add notes with: pace remember "...")'
+    return path.read_text(encoding="utf-8").strip()

pace_engine-0.1.0/pace/engines/project_creator.py

@@ -0,0 +1,138 @@
+"""Project Creator engine — init and create modes.
+
+init_instance() attaches a valid, structurally minimal .pace/ instance to
+a project directory that already exists (its own code lives elsewhere,
+untouched).
+
+create_project() generates a brand-new project from scratch: a fresh
+directory, a git repository, a minimal README, and a .pace/ instance —
+nothing stack-specific (no framework, no language scaffolding). That is
+a separate, later capability (templates/, not yet built), not part of
+this minimal create mode.
+"""
+
+import subprocess
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+from pace.services.contract_loader import load_instance_contract
+from pace.services.version import PACE_VERSION
+
+CONTRACT_PATH = Path(__file__).resolve().parent.parent / "contracts" / "INSTANCE_CONTRACT_0.1.0.pdl"
+CONTRACT_VERSION = "0.1.0"
+
+PLACEHOLDER = "Not yet defined."
+
+
+def _write_pdl(path: Path, fields: dict) -> None:
+    lines = [f"{key} {value}".rstrip() for key, value in fields.items()]
+    lines.append("END")
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text("\n".join(lines) + "\n", encoding="utf-8")
+
+
+def init_instance(
+    target_dir: Path,
+    kind: str,
+    name: str,
+    slug: str,
+    org_ref: str = None,
+    mission: str = PLACEHOLDER,
+    vision: str = PLACEHOLDER,
+    roadmap: str = PLACEHOLDER,
+    sprint: str = PLACEHOLDER,
+) -> Path:
+    """Create a minimal, structurally valid .pace/ instance inside
+    `target_dir`. Raises if one already exists there."""
+    target_dir = Path(target_dir)
+    root = target_dir / ".pace"
+    if root.exists():
+        raise FileExistsError(f".pace/ already exists at {root}")
+
+    if kind == "PROJECT" and not org_ref:
+        raise ValueError("KIND=PROJECT requires org_ref")
+
+    contract = load_instance_contract(CONTRACT_PATH)
+
+    for section in sorted(contract["sections"]):
+        (root / section).mkdir(parents=True, exist_ok=True)
+
+    created_at = datetime.now(timezone.utc).isoformat()
+
+    instance_fields = {
+        "KIND": kind,
+        "NAME": name,
+        "SLUG": slug,
+        "SCHEMA_VERSION": CONTRACT_VERSION,
+        "PACE_VERSION": PACE_VERSION,
+        "CREATED_AT": created_at,
+    }
+    if org_ref:
+        instance_fields["ORG_REF"] = org_ref
+    _write_pdl(root / "INSTANCE.pdl", instance_fields)
+
+    _write_pdl(root / "mission" / "MISSION_1.0.0.pdl", {
+        "MISSION_VERSION": "1.0.0", "STATUS": "APPROVED", "MISSION": mission,
+    })
+    _write_pdl(root / "vision" / "VISION_1.0.0.pdl", {
+        "VISION_VERSION": "1.0.0", "STATUS": "APPROVED", "VISION": vision,
+    })
+    _write_pdl(root / "roadmap" / "ROADMAP_1.0.0.pdl", {
+        "ROADMAP_VERSION": "1.0.0", "STATUS": "APPROVED", "ROADMAP": roadmap,
+    })
+    _write_pdl(root / "sprint" / "SPRINT_1.pdl", {
+        "SPRINT_VERSION": "1", "STATUS": "ACTIVE", "SPRINT": sprint,
+    })
+
+    _write_pdl(root / "ACTIVE_VERSIONS.pdl", {
+        "ACTIVE_MISSION": "mission/MISSION_1.0.0.pdl",
+        "ACTIVE_VISION": "vision/VISION_1.0.0.pdl",
+        "ACTIVE_ROADMAP": "roadmap/ROADMAP_1.0.0.pdl",
+        "ACTIVE_SPRINT": "sprint/SPRINT_1.pdl",
+    })
+
+    _write_pdl(root / "history" / "HISTORY-0001-FOUNDING.pdl", {
+        "HISTORY_VERSION": "1.0.0",
+        "TYPE": "Founding",
+        "STATUS": "APPROVED",
+        "TITLE": f"{name} founded as a PACE-governed instance.",
+    })
+
+    return root
+
+
+def create_project(
+    target_dir: Path,
+    name: str,
+    slug: str,
+    org_ref: str,
+    mission: str = PLACEHOLDER,
+    vision: str = PLACEHOLDER,
+    roadmap: str = PLACEHOLDER,
+    sprint: str = PLACEHOLDER,
+) -> Path:
+    """Generate a brand-new project from scratch: creates `target_dir`
+    (must not already exist or must be empty), initializes a git
+    repository, writes a minimal README, and attaches a .pace/ instance.
+    Stack-specific scaffolding is deliberately out of scope."""
+    target_dir = Path(target_dir)
+    if target_dir.exists() and any(target_dir.iterdir()):
+        raise FileExistsError(f"{target_dir} already exists and is not empty")
+    target_dir.mkdir(parents=True, exist_ok=True)
+
+    subprocess.run(
+        ["git", "init"], cwd=target_dir, check=True,
+        capture_output=True, text=True,
+    )
+
+    (target_dir / "README.md").write_text(
+        f"# {name}\n\nGoverned by PACE. See .pace/ for its mission, vision, roadmap and history.\n",
+        encoding="utf-8",
+    )
+
+    return init_instance(
+        target_dir, kind="PROJECT", name=name, slug=slug, org_ref=org_ref,
+        mission=mission, vision=vision, roadmap=roadmap, sprint=sprint,
+    )

pace_engine-0.1.0/pace/kernel/kernel.py

@@ -0,0 +1,105 @@
+"""PACE Kernel — locates a .pace/ instance and validates it structurally
+against contracts/INSTANCE_CONTRACT_0.1.0.pdl, loaded at runtime from the
+actual file, not a hand transcription of its rules.
+
+Deliberately minimal: this is structural validation only (does the
+required shape exist, is SCHEMA_VERSION supported). Deeper, semantic
+validation belongs to the future Doctor engine, not the Kernel.
+"""
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+from pace.services.fs import find_upward
+from pace.services.pdl import read_pdl
+from pace.services.contract_loader import load_instance_contract
+from pace.services.validate import (
+    require_fields,
+    require_dirs,
+    require_non_empty_dir,
+    forbid_file_suffixes,
+)
+
+CONTRACT_PATH = Path(__file__).resolve().parent.parent / "contracts" / "INSTANCE_CONTRACT_0.1.0.pdl"
+
+# The schema dialects THIS Kernel build knows how to interpret — the way
+# a browser understands a set of HTML versions, not "the one current
+# version, everything else is outdated". Growing this set over time (as
+# PACE adds Contract versions) means the Kernel learns to read more
+# dialects; it does not mean older ones stop being valid. Whether a
+# mismatch means "this instance needs pace migrate" or "this Kernel
+# needs updating" depends on which side is actually behind — the Kernel
+# cannot assume it's always the instance's fault.
+SUPPORTED_SCHEMA_VERSIONS = {"0.1.0"}
+
+# HARD_RULE 2 ("no code, script or executable file") is prose, not a
+# machine-enumerable list — this is the Kernel's own codified reading of
+# that rule, not something extracted from the contract text.
+FORBIDDEN_SUFFIXES = {".py", ".ts", ".js", ".sh", ".exe", ".ps1", ".bat"}
+
+
+def locate_instance(start: Path = None):
+    """Find the nearest .pace/ directory walking upward from `start`."""
+    return find_upward(".pace", start)
+
+
+def validate_instance(root: Path) -> list:
+    """Structural validation only. Returns a list of violations; an
+    empty list means the instance is structurally valid."""
+    violations = []
+    contract = load_instance_contract(CONTRACT_PATH)
+
+    instance_file = root / "INSTANCE.pdl"
+    if not instance_file.is_file():
+        violations.append("missing INSTANCE.pdl")
+    else:
+        instance = read_pdl(instance_file)
+        # ORG_REF is excluded here: the contract marks it conditionally
+        # required (only when KIND=PROJECT), not unconditionally like
+        # the other fields — enforced explicitly just below instead.
+        required = [
+            field for field in contract["root_manifest"].get(".pace/INSTANCE.pdl", [])
+            if field != "ORG_REF"
+        ]
+        violations += require_fields(instance, required, "INSTANCE.pdl")
+        if instance.get("KIND") == "PROJECT" and not instance.get("ORG_REF"):
+            violations.append("INSTANCE.pdl KIND=PROJECT requires ORG_REF")
+        schema_version = instance.get("SCHEMA_VERSION")
+        if schema_version and schema_version not in SUPPORTED_SCHEMA_VERSIONS:
+            violations.append(
+                f"SCHEMA_VERSION {schema_version} is not understood by "
+                f"this PACE engine (understands: {sorted(SUPPORTED_SCHEMA_VERSIONS)}) "
+                "— either this instance needs pace migrate, or this "
+                "Kernel needs updating; pace migrate is not yet built"
+            )
+
+    active_versions_file = root / "ACTIVE_VERSIONS.pdl"
+    if not active_versions_file.is_file():
+        violations.append("missing ACTIVE_VERSIONS.pdl")
+    else:
+        active_versions = read_pdl(active_versions_file)
+        required = contract["root_manifest"].get(".pace/ACTIVE_VERSIONS.pdl", [])
+        violations += require_fields(active_versions, required, "ACTIVE_VERSIONS.pdl")
+
+    violations += require_dirs(root, sorted(contract["sections"]))
+    violations += require_non_empty_dir(root, "history")
+    violations += forbid_file_suffixes(root, FORBIDDEN_SUFFIXES)
+
+    return violations
+
+
+if __name__ == "__main__":
+    target = Path(sys.argv[1]) if len(sys.argv) > 1 else None
+    root = locate_instance(target)
+    if root is None:
+        print("no .pace/ instance found")
+        raise SystemExit(1)
+    print(f"instance located at {root}")
+    violations = validate_instance(root)
+    if violations:
+        print(f"INVALID - {len(violations)} violation(s):")
+        for v in violations:
+            print(f"  - {v}")
+        raise SystemExit(1)
+    print("VALID")

pace_engine-0.1.0/pace/services/contract_loader.py

@@ -0,0 +1,56 @@
+"""Loads contracts/INSTANCE_CONTRACT_*.pdl at runtime, instead of the
+Kernel hardcoding a hand transcription of its rules.
+
+Purpose-built for the Instance Contract's known document shape, not a
+fully general PDL engine — see protocols/PDL_SPECIFICATION_0.2.0.pdl.
+"""
+
+from pathlib import Path
+
+from pace.services.pdl_nested import split_top_level_sections, indented_field_names
+
+TOP_LEVEL_SECTIONS = [
+    "DEPENDS_ON", "PURPOSE", "ROOT_MANIFEST", "SECTIONS",
+    "NOT_REPRESENTED_HERE", "HARD_RULES",
+]
+
+ROOT_MANIFEST_FILES = [".pace/INSTANCE.pdl", ".pace/ACTIVE_VERSIONS.pdl"]
+
+
+def parse_root_manifest(root_manifest_text: str) -> dict:
+    files = split_top_level_sections(root_manifest_text, ROOT_MANIFEST_FILES)
+    return {
+        name: indented_field_names(body, "REQUIRED_FIELDS", base_indent=4)
+        for name, body in files.items()
+    }
+
+
+def parse_sections(sections_text: str) -> dict:
+    """A SECTIONS entry header is a line at indentation 0, one or more
+    comma-separated paths (e.g. 'mission/, vision/, roadmap/, sprint/'
+    or a single 'history/'). Every section in Contract 0.1.0 requires
+    its folder to exist, so this only needs to collect the paths."""
+    sections = {}
+    for line in sections_text.splitlines():
+        if not line.strip():
+            continue
+        indent = len(line) - len(line.lstrip(" "))
+        if indent == 0:
+            for raw_path in line.strip().split(","):
+                path = raw_path.strip().rstrip("/")
+                if path:
+                    sections[path] = {"required": True}
+    return sections
+
+
+def load_instance_contract(path: Path) -> dict:
+    text = Path(path).read_text(encoding="utf-8")
+    first_line = text.splitlines()[0]
+    contract_version = first_line.split(" ", 1)[1].strip() if " " in first_line else ""
+
+    top = split_top_level_sections(text, TOP_LEVEL_SECTIONS)
+    return {
+        "contract_version": contract_version,
+        "root_manifest": parse_root_manifest(top.get("ROOT_MANIFEST", "")),
+        "sections": parse_sections(top.get("SECTIONS", "")),
+    }

pace_engine-0.1.0/pace/services/fs.py

@@ -0,0 +1,15 @@
+"""Generic filesystem helpers shared by the Kernel and, later, Engines."""
+
+from pathlib import Path
+
+
+def find_upward(name: str, start: Path = None):
+    """Walk upward from `start` (default: cwd) looking for a directory
+    called `name` — the way Git locates `.git/` from anywhere inside a
+    repository. Returns the matching Path, or None if not found."""
+    current = Path(start or Path.cwd()).resolve()
+    for directory in [current, *current.parents]:
+        candidate = directory / name
+        if candidate.is_dir():
+            return candidate
+    return None

pace_engine-0.1.0/pace/services/pdl.py

@@ -0,0 +1,27 @@
+"""Minimal PDL parser for flat key-value documents.
+
+Implements the grammar in protocols/PDL_SPECIFICATION_0.1.0.pdl: one
+KEY VALUE pair per line, blank lines ignored, terminated by END.
+"""
+
+from pathlib import Path
+
+
+def parse_pdl(text: str) -> dict:
+    fields = {}
+    for raw_line in text.splitlines():
+        line = raw_line.strip()
+        if not line:
+            continue
+        if line == "END":
+            break
+        if " " in line:
+            key, value = line.split(" ", 1)
+        else:
+            key, value = line, ""
+        fields[key] = value.strip()
+    return fields
+
+
+def read_pdl(path: Path) -> dict:
+    return parse_pdl(Path(path).read_text(encoding="utf-8"))

pace_engine-0.1.0/pace/services/pdl_nested.py

@@ -0,0 +1,64 @@
+"""Nested-section extraction for PDL documents that mix structural
+fields with hand-wrapped prose (governance/ontology/contracts documents),
+on top of pdl.py's flat grammar.
+
+See protocols/PDL_SPECIFICATION_0.2.0.pdl for why this deliberately does
+not auto-detect section headers: a document that uses indentation both
+for structure and for visual line-wrap alignment cannot be told apart
+generically without guessing. Instead, the caller supplies the small,
+fixed vocabulary of top-level section names it expects — the same
+technique the old system's BOOTSTRAP_CONTEXT.pdl already used via its
+own READ_ORDER list.
+"""
+
+
+def split_top_level_sections(text: str, known_sections) -> dict:
+    """Split a document into named top-level blocks. A line is treated
+    as the start of a new section only if, once stripped, it exactly
+    matches one of `known_sections`. Everything up to the next known
+    section name (or END) becomes that section's raw body text."""
+    known = set(known_sections)
+    sections = {}
+    current_name = None
+    current_lines = []
+
+    def flush():
+        if current_name is not None:
+            sections[current_name] = "\n".join(current_lines).strip("\n")
+
+    for line in text.splitlines():
+        stripped = line.strip()
+        if stripped in known:
+            flush()
+            current_name = stripped
+            current_lines = []
+        elif stripped == "END":
+            break
+        elif current_name is not None:
+            current_lines.append(line)
+    flush()
+    return sections
+
+
+def indented_field_names(text: str, header: str, base_indent: int) -> list:
+    """Within `text`, find the block introduced by a line equal to
+    `header`, then collect the first token of every subsequent line
+    indented at exactly `base_indent`. Lines indented deeper than
+    `base_indent` are continuations of the previous field's wrapped
+    value, not new fields, and are ignored here."""
+    names = []
+    in_block = False
+    for line in text.splitlines():
+        stripped = line.strip()
+        if not stripped:
+            continue
+        indent = len(line) - len(line.lstrip(" "))
+        if not in_block:
+            if stripped == header:
+                in_block = True
+            continue
+        if indent < base_indent:
+            break
+        if indent == base_indent:
+            names.append(stripped.split()[0])
+    return names

pace_engine-0.1.0/pace/services/validate.py

@@ -0,0 +1,36 @@
+"""Small, reusable validation helpers — generic enough for the Kernel
+today and for a future Doctor/Validator engine, so validation logic
+doesn't live inline inside any one caller."""
+
+from pathlib import Path
+
+
+def require_fields(data: dict, fields, context: str) -> list:
+    violations = []
+    for field in fields:
+        if not data.get(field):
+            violations.append(f"{context} missing required field {field}")
+    return violations
+
+
+def require_dirs(root: Path, paths, label: str = "missing required section") -> list:
+    violations = []
+    for path in paths:
+        if not (root / path).is_dir():
+            violations.append(f"{label} {path}/")
+    return violations
+
+
+def require_non_empty_dir(root: Path, path: str) -> list:
+    directory = root / path
+    if directory.is_dir() and not any(directory.iterdir()):
+        return [f"{path}/ exists but has no founding entry"]
+    return []
+
+
+def forbid_file_suffixes(root: Path, suffixes) -> list:
+    violations = []
+    for path in root.rglob("*"):
+        if path.is_file() and path.suffix in suffixes:
+            violations.append(f"forbidden code/script file inside .pace/: {path.relative_to(root)}")
+    return violations

pace_engine-0.1.0/pace/services/version.py

@@ -0,0 +1,7 @@
+"""PACE's own engine version — the single source of truth referenced by
+Engines (when writing a new instance) and the Kernel (when reasoning
+about instance compatibility). Independent of SCHEMA_VERSION: the engine
+can evolve without the Instance Contract changing, and vice versa.
+"""
+
+PACE_VERSION = "0.1.0"

pace_engine-0.1.0/pace_engine.egg-info/PKG-INFO

@@ -0,0 +1,35 @@
+Metadata-Version: 2.4
+Name: pace-engine
+Version: 0.1.0
+Summary: PACE - an engineering operating system: a versioned, installable engine that preserves and governs a project's knowledge so any AI understands it in seconds.
+Author: Cley Duarte
+Project-URL: Homepage, https://github.com/cleyduartees-dot/PACE
+Keywords: ai,knowledge,engineering,governance,memory,context
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# PACE
+
+An engineering operating system: a versioned, installable engine that preserves, organizes, governs and evolves the architectural knowledge of software projects, in collaboration between people and AI.
+
+PACE is not a library embedded inside a product. It is installed once and governs any number of independent projects, each carrying only its own `.pace/` memory — never a copy of PACE itself.
+
+## Status
+
+Founded 2026-07-06. This repository currently contains only this founding commit. The minimal day-1 skeleton (kernel, services, engines, ontology, protocols, governance, policies, standards, contracts, cli, history, docs) is the next step, not yet built.
+
+## Founding principle
+
+- **PACE** — the engine. Code only, versioned, installable. No knowledge of any specific organization or project.
+- **Organización** — an adopting company's own governance memory (who holds authority, its own policies, its registry of projects), same recursive shape as a project instance, scoped one level up.
+- **Instancia (`.pace/`)** — a single project's own memory: mission, vision, roadmap, sprint, handoff, history, decisions.
+- **Proyecto** — the actual product codebase. Outside PACE's concern beyond hosting a `.pace/` folder at its root.
+
+## Roadmap (founding sequence)
+
+1. Crear el repositorio oficial PACE. — done
+2. Implementar el esqueleto mínimo.
+3. Implementar `pace init`.
+4. Adoptar el primer proyecto gobernado por PACE.
+5. Implementar `pace create`.
+6. Crear el primer proyecto nuevo nacido desde PACE.

pace_engine-0.1.0/pace_engine.egg-info/SOURCES.txt

@@ -0,0 +1,25 @@
+README.md
+pyproject.toml
+pace/__init__.py
+pace/cli/__init__.py
+pace/cli/pace.py
+pace/contracts/INSTANCE_CONTRACT_0.1.0.pdl
+pace/contracts/__init__.py
+pace/engines/__init__.py
+pace/engines/handoff.py
+pace/engines/memory.py
+pace/engines/project_creator.py
+pace/kernel/__init__.py
+pace/kernel/kernel.py
+pace/services/__init__.py
+pace/services/contract_loader.py
+pace/services/fs.py
+pace/services/pdl.py
+pace/services/pdl_nested.py
+pace/services/validate.py
+pace/services/version.py
+pace_engine.egg-info/PKG-INFO
+pace_engine.egg-info/SOURCES.txt
+pace_engine.egg-info/dependency_links.txt
+pace_engine.egg-info/entry_points.txt
+pace_engine.egg-info/top_level.txt

pace_engine-0.1.0/pace_engine.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

pace_engine-0.1.0/pace_engine.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pace = pace.cli.pace:main

pace_engine-0.1.0/pace_engine.egg-info/top_level.txt

@@ -0,0 +1 @@
+pace

pace_engine-0.1.0/pyproject.toml

@@ -0,0 +1,24 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pace-engine"
+version = "0.1.0"
+description = "PACE - an engineering operating system: a versioned, installable engine that preserves and governs a project's knowledge so any AI understands it in seconds."
+readme = "README.md"
+requires-python = ">=3.10"
+authors = [{ name = "Cley Duarte" }]
+keywords = ["ai", "knowledge", "engineering", "governance", "memory", "context"]
+
+[project.urls]
+Homepage = "https://github.com/cleyduartees-dot/PACE"
+
+[project.scripts]
+pace = "pace.cli.pace:main"
+
+[tool.setuptools]
+packages = ["pace", "pace.cli", "pace.kernel", "pace.services", "pace.engines", "pace.contracts"]
+
+[tool.setuptools.package-data]
+"pace.contracts" = ["*.pdl"]

pace_engine-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+