Support safe existing repository adoption

Author: suyog19

README.md

@@ -28,7 +28,7 @@ engineering-process --root ../my-web-app init \
   --profile frontend --repository-name suyog19/my-web-app
 ```
 
-Or supply an immutable released revision explicitly with `--revision <40-hex-sha>`. Initialization creates the manifest and lock, compact `AGENTS.md`/`CLAUDE.md`, portable Skills, and a validation workflow. Add repository differences—validation commands, protected path hints, UX triggers—to `.engineering/process.yaml`, then re-render/re-lock using a reviewed process upgrade.
+Or supply an immutable released revision explicitly with `--revision <40-hex-sha>`. Initialization creates the manifest and lock, compact `AGENTS.md`/`CLAUDE.md`, portable Skills, and a validation workflow. Existing assistant context is never silently overwritten; follow the [mature repository migration](docs/adoption.md#mature-repository-migration) and use the explicit `--adopt-existing-context` flow. Add repository differences—validation commands, protected path hints, UX triggers—to `.engineering/process.yaml`, then re-render/re-lock using a reviewed process upgrade.
 
 ## Change flow
 

docs/adoption.md

@@ -9,5 +9,34 @@
 
 Repository-local technology is deliberately opaque to policy. Put commands under `overrides.validation.commands`; add sensitive paths/characteristics and domain triggers when they strengthen classification. Never copy the canonical policy into the manifest.
 
-For upgrades, run `engineering-process upgrade --version X --revision SHA --dry-run`, review inherited/profile/generated-file changes and conflicts, then apply from the reviewed target process checkout. A central update never mutates an active repository automatically.
+## Mature repository migration
 
+Initialization is non-destructive. If `AGENTS.md`, `CLAUDE.md`, or the process validation workflow is repository-owned, normal `init` stops before creating `.engineering/process.yaml`. Do not use `--force` to bypass this boundary.
+
+Use this reviewed workflow:
+
+1. Inventory existing assistant, architecture, branch/release, validation, security, product/UX, and deployment guidance. Identify copied generic policy versus genuine repository-specific context.
+2. Keep canonical requirements in this process. Keep local mechanics and stronger constraints in repository-owned documents. Existing `overrides` remain the only mechanism for validation commands, classification additions, UX triggers, controls, and native enforcement.
+3. Commit or otherwise preserve a baseline so the migration can be reviewed.
+4. Run `engineering-process --root <repo> init --profile frontend --adopt-existing-context`. The command moves existing `AGENTS.md` and/or `CLAUDE.md` verbatim into `docs/engineering/local-context/`, declares them in `local_context`, and writes compact generated bootstraps. It refuses to replace a repository-owned workflow.
+5. Split or rename the preserved documents as useful, then update `local_context`. Each entry has a category, repository-relative path, and optional contextual `load_when` instruction:
+
+   ```yaml
+   local_context:
+     - category: operating_contract
+       path: docs/engineering/operating-contract.md
+       load_when: load before branch, issue, or release workflow changes
+     - category: architecture
+       path: docs/architecture/
+       load_when: load for changes affecting component boundaries
+     - category: ux_product_design
+       path: docs/ux/ux-gates.md
+       load_when: load for user-visible changes
+   ```
+
+6. Review the full diff. Confirm branch responsibilities, issue-first workflow, agent roles, architecture/deployment rules, Senior UX Designer responsibilities, UX Gates A-D, and local implementation/review conventions remain referenced and readable.
+7. Run `engineering-process validate`. Missing paths, invalid context structure, stale generated bootstraps, modified generated files, and locked-control override attempts fail validation.
+
+Local-context documents add detail and mechanics; they do not override the Effective Obligation Set. Progressive `load_when` hints keep the bootstraps compact and avoid loading every document for every change.
+
+For upgrades, run `engineering-process upgrade --version X --revision SHA --dry-run`, review inherited/profile/generated-file changes, preserved local-context paths, and conflicts, then apply from the reviewed target process checkout. Upgrade verifies generated-file hashes before replacement and refuses modified or repository-owned targets. It never rewrites files referenced by `local_context`. A central update never mutates an active repository automatically.

schemas/repository-process.schema.json

@@ -20,6 +20,18 @@
       "type": "object", "required": ["name"], "additionalProperties": true,
       "properties": {"name": {"type": "string", "minLength": 1}}
     },
+    "local_context": {
+      "type": "array",
+      "items": {
+        "type": "object", "additionalProperties": false,
+        "required": ["category", "path"],
+        "properties": {
+          "category": {"enum": ["operating_contract", "architecture", "ux_product_design", "deployment_release", "validation_testing", "security_domain", "other"]},
+          "path": {"type": "string", "minLength": 1, "pattern": "^(?!/|[A-Za-z]:|.*(?:^|/)\\.\\.(?:/|$)).+"},
+          "load_when": {"type": "string", "minLength": 1}
+        }
+      }
+    },
     "overrides": {
       "type": "object", "additionalProperties": false,
       "properties": {
@@ -33,4 +45,3 @@
     }
   }
 }
-

src/engineering_process/cli.py

@@ -45,7 +45,7 @@ def parser() -> argparse.ArgumentParser:
     p = argparse.ArgumentParser(prog="engineering-process", description="Engineering policy and assurance CLI")
     p.add_argument("--root", default=".", help="participating repository root")
     sub = p.add_subparsers(dest="command", required=True)
-    init = sub.add_parser("init"); init.add_argument("--profile", required=True, choices=["generic", "frontend", "backend"]); init.add_argument("--repository-name"); init.add_argument("--revision"); init.add_argument("--force", action="store_true")
+    init = sub.add_parser("init"); init.add_argument("--profile", required=True, choices=["generic", "frontend", "backend"]); init.add_argument("--repository-name"); init.add_argument("--revision"); init.add_argument("--force", action="store_true"); init.add_argument("--adopt-existing-context", action="store_true")
     sub.add_parser("validate")
     for name in ("classify", "evaluate", "explain"):
         c = sub.add_parser(name); c.add_argument("--path", action="append"); c.add_argument("--declared"); c.add_argument("--semantic"); c.add_argument("--rationale"); c.add_argument("--sha")
@@ -63,7 +63,7 @@ def run(args: argparse.Namespace) -> dict:
     root = Path(args.root).resolve()
     if args.command == "init":
         revision = args.revision or current_revision(data_root())
-        return initialize(root, args.profile, args.repository_name or root.name, revision, args.force)
+        return initialize(root, args.profile, args.repository_name or root.name, revision, args.force, args.adopt_existing_context)
     manifest = _manifest(root)
     if args.command == "validate": return validate_repository(root)
     if args.command in {"classify", "evaluate", "explain"}:

src/engineering_process/render.py

@@ -3,13 +3,22 @@
 import json
 from pathlib import Path
 
-from .io import digest_bytes
+from .errors import ProcessError
+from .io import digest_file
+
+
+GENERATED_MARKER = "<!-- GENERATED BY software-engineering-process; DO NOT EDIT. -->"
 
 
 def bootstrap(manifest: dict, assistant: str) -> str:
     p = manifest["process"]
     title = "Codex" if assistant == "codex" else "Claude Code" if assistant == "claude" else "Engineering participant"
-    return f"""<!-- GENERATED; DO NOT EDIT. -->
+    local_context = manifest.get("local_context", [])
+    context_lines = "\n".join(
+        f"- `{item['path']}` ({item['category']}): {item.get('load_when', 'load when relevant to the change')}"
+        for item in local_context
+    ) or "- None declared."
+    return f"""{GENERATED_MARKER}
 # {title} engineering bootstrap
 
 Process: `{p['source']}` `{p['version']}` @ `{p['revision']}`  
@@ -18,6 +27,9 @@ def bootstrap(manifest: dict, assistant: str) -> str:
 Before changing code, run `engineering-process classify` and `engineering-process evaluate`.
 Follow the resolved Effective Obligation Set; load only its selected Skills.
 
+Repository-owned local context (adds mechanics/detail; never overrides canonical policy):
+{context_lines}
+
 Non-negotiable boundaries:
 - Keep issue/change traceability and work only within approved scope.
 - Never expose or commit secrets or private data.
@@ -31,11 +43,20 @@ def bootstrap(manifest: dict, assistant: str) -> str:
 """
 
 
-def render_files(root: Path, manifest: dict) -> dict[str, str]:
+def is_generated_bootstrap(path: Path) -> bool:
+    return path.is_file() and path.read_text(encoding="utf-8").startswith(GENERATED_MARKER)
+
+
+def render_files(root: Path, manifest: dict, allow_create: bool = True) -> dict[str, str]:
     files = {"AGENTS.md": bootstrap(manifest, "codex"), "CLAUDE.md": bootstrap(manifest, "claude")}
     for name, text in files.items():
-        (root / name).write_text(text, encoding="utf-8")
-    return {name: digest_bytes(text.encode()) for name, text in files.items()}
+        path = root / name
+        if path.exists() and not is_generated_bootstrap(path):
+            raise ProcessError(f"refusing to overwrite repository-owned context: {name}; use init --adopt-existing-context")
+        if not path.exists() and not allow_create:
+            raise ProcessError(f"generated adapter is missing: {name}")
+        path.write_text(text, encoding="utf-8")
+    return {name: digest_file(root / name) for name in files}
 
 
 def metrics(root: Path, selected_skills: list[str] | None = None) -> dict:
@@ -46,4 +67,3 @@ def metrics(root: Path, selected_skills: list[str] | None = None) -> dict:
             result[name] = {"bytes": len(text.encode()), "words": len(text.split()), "approx_tokens": round(len(text) / 4)}
     result["activated_skills"] = len(selected_skills or [])
     return result
-