feat: improve assurance clarity and adoption

Author: suyog19

CONTRIBUTING.md

@@ -1,4 +1,5 @@
 # Contributing
 
-Open an issue before implementation. Keep policy technology-neutral and encode obligations rather than generic engineering advice. Add tests for inheritance, classification, evidence, adapters, and migration impact. Run `pytest`, build/install the wheel, and exercise the CLI outside the checkout. Pull requests must explain why new machinery is necessary and identify native alternatives considered.
+Material policy, schema, workflow, adapter, or release changes must review and update `docs/capability-status.md`. If status does not change, state why in the pull request. Schema changes require compatibility/upgrade notes and tests.
 
+Open an issue before implementation. Keep policy technology-neutral and encode obligations rather than generic engineering advice. Add tests for inheritance, classification, evidence, adapters, and migration impact. Run `pytest`, build/install the wheel, and exercise the CLI outside the checkout. Pull requests must explain why new machinery is necessary and identify native alternatives considered.

README.md

@@ -1,5 +1,7 @@
 # Software Engineering Process
 
+See the maintained [capability status](docs/capability-status.md) for what is implemented, partial, experimental, designed, or deferred.
+
 A technology-neutral Software Engineering Policy and Assurance platform. It resolves **what must be true** for a change and delegates **how** to coding assistants, humans, CI, GitHub, and other native mechanisms.
 
 ```text

docs/adoption-modes.md

@@ -0,0 +1,14 @@
+# Progressive adoption modes
+
+Modes describe operational maturity, never delivery risk and never alternate meanings of locked controls.
+
+| Mode | Target users | Prerequisites | Guarantees | Limitations |
+|---|---|---|---|---|
+| Foundation | New/small repositories | Manifest, lock, generated bootstrap, validation workflow | Locked policy/version drift checks | No claim of authenticated end-to-end evidence |
+| Assured | Mature or solo repositories | Foundation + categorized validation, trusted CI/review workflow allowlists, GitHub adapter | Automated Lean evidence and authenticated review/readiness | No claim of Protected agent isolation |
+| Protected | Sensitive repositories | Assured + sandbox, network enforcement, audit sink | Protected execution fails closed and human production boundary remains | Native controls must be operated by repository owner |
+| Governed | Multi-maintainer/process-improvement programs | Protected + optional metrics enabled + maintained critical context | Aggregated outcome feedback and explicit truth ownership | Metrics cannot rank individuals |
+
+Run `engineering-process adoption-report`. A configured target above achieved prerequisites is diagnostic and makes `validate` fail. Transitions are incremental reviewed manifest/lock upgrades; optional metrics/adapters can be removed in a reviewed upgrade. Locked controls never weaken. A solo owner can manually authorize/promote production while independent review remains a separate fresh-context procedure.
+
+Examples: a new repository begins Foundation; a mature repository maps existing CI into Assured; a solo maintainer uses Assured/Protected with owner-controlled production; a multi-maintainer repository may reach Governed. Lean work in Assured uses trusted diff, automatic CI test evidence, one authenticated independent review, and readiness—no hand-authored routine test JSON.

docs/adoption.md

@@ -20,6 +20,23 @@ The initial checkout and runner are the bootstrap trust boundary. Evidence
 transport and v1 compatibility are defined in the [exact-revision evidence
 lifecycle](evidence-lifecycle.md).
 
+### Schema v2 and adapters
+
+Process 1.3.0 upgrades schema-v1 manifests to strict schema v2. Legacy
+`overrides.technology` moves to the explicit versioned `legacy/technology`
+extension; platform mechanics move from `overrides.native_enforcement` to
+`adapters.github`. Unknown v2 fields are rejected. Canonical policy now expresses
+semantic readiness, protected-branch, and production-boundary obligations while
+the versioned GitHub adapter selects status names, branches, environments, and
+runner labels. Stronger local controls remain valid; locked-control weakening is
+still rejected.
+
+Optional `adapters.github_copilot.scoped_instructions` generate compact
+path-scoped `.github/instructions/*.instructions.md` files from canonical process
+identity and declared local-context paths. They are hash-locked and non-canonical.
+Remove adapter configuration during a reviewed upgrade to remove only unchanged
+generated files; modified or repository-owned files are refused.
+
 ### Phase 2 evidence migration
 
 Process 1.1.0 obligation sets require `test-result/v2` and `independent-review/v2`.

docs/capability-status.md

@@ -0,0 +1,25 @@
+# Capability status
+
+Current process release: **1.3.0**.
+
+Status terms: **implemented** is executable and tested; **partial** works with stated prerequisites/limits; **experimental** is usable but compatibility may change; **designed** has an accepted contract but no complete implementation; **deferred** is intentionally postponed with tracked rationale. Material implementation and release changes must update this matrix.
+
+| Capability | Status | Limits / prerequisites |
+|---|---|---|
+| Locked policy inheritance and upgrades | implemented | Immutable Git revision and reviewed upgrade required. |
+| Trusted Git classification | implemented | Full Git history/base must be available. |
+| Exact-SHA evidence and producer trust | implemented | Standard/Protected require out-of-band platform provenance. |
+| Agent-execution security | partial | Policy and GitHub mapping implemented; adopters supply native sandbox/egress enforcement. |
+| End-to-end GitHub reference flow | implemented | Repository configures authorized workflow refs and review Environment. |
+| Outcome metrics | experimental | Optional repository aggregation; completeness depends on supplied events. |
+| Delegation assessment | experimental | Advisory only; does not grant authority. |
+| Dependency assurance | partial | Signals/obligations implemented; ecosystem-native commands supply registry/security facts. |
+| Context truth maintenance | implemented | Deterministic hooks only; no LLM assertion is accepted as proof. |
+| Progressive adoption modes | implemented | Modes describe achieved infrastructure, not weaker controls. |
+| Lean/Standard/Protected assurance profiles | implemented | Delivery assurance remains separate from adoption mode and delegation. |
+| Strict v2 manifest/extensions and GitHub adapter | implemented | v1 remains migration-compatible; v2 required for strict separation. |
+| Optional scoped GitHub Copilot instructions | implemented | Generated, hash-locked, compact, non-canonical. |
+| Cross-repository coordination | deferred | Out of scope; see epic #7 non-goals and future measured need. |
+| Additional native assistant formats | designed | Add only from stable semantics; track follow-up after #23. |
+
+The historical [target architecture](design/common-software-engineering-process-design-v4.md) remains a design reference. It is not evidence that every described capability is delivered.

policy/core.yaml

@@ -1,6 +1,6 @@
 schema_version: 1
 process:
-  version: 1.2.0
+  version: 1.3.0
   source: suyog19/software-engineering-process
 controls:
   traceability:
@@ -73,16 +73,10 @@ capabilities:
   solution-sufficiency: {authority: minimum_sufficient_solution_and_feedback_triage}
   ci-automation: {authority: objective_checks_and_policy_enforcement}
 native_enforcement:
-  required_status_checks: [engineering-process]
-  protected_branches: true
+  readiness_gate_required: true
+  protected_branch_required: true
   production_environment:
     manual_human_promotion_required: true
     automation_may_promote: false
     distinct_human_reviewer_required: false
     stronger_multi_human_gate_permitted: true
-  agent_execution:
-    permissions: read-only-by-default
-    secrets: environment-scoped-and-withheld-from-forks
-    runner: ephemeral-sandbox
-    network: adapter-enforced-allowlist
-    workflow_approval: required-for-untrusted-forks

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "software-engineering-process"
-version = "1.2.0"
+version = "1.3.0"
 description = "Technology-neutral engineering policy and assurance platform"
 readme = "README.md"
 requires-python = ">=3.11"

schemas/github-adapter-v1.schema.json

@@ -0,0 +1 @@
+{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","additionalProperties":false,"properties":{"readiness_status":{"type":"string"},"protected_branch":{"type":"string"},"production_environment":{"type":"string"},"runner_labels":{"type":"array","items":{"type":"string"}}}}

schemas/repository-process.schema.json

@@ -5,7 +5,7 @@
   "required": ["schema_version", "process", "repository"],
   "additionalProperties": false,
   "properties": {
-    "schema_version": {"const": 1},
+    "schema_version": {"enum": [1, 2]},
     "process": {
       "type": "object", "additionalProperties": false,
       "required": ["source", "version", "revision", "profile"],
@@ -17,7 +17,7 @@
       }
     },
     "repository": {
-      "type": "object", "required": ["name"], "additionalProperties": true,
+      "type": "object", "required": ["name"], "additionalProperties": false,
       "properties": {
         "name": {"type": "string", "minLength": 1},
         "trusted_ci_workflows": {"type": "array", "items": {"type": "string", "minLength": 1}, "uniqueItems": true},
@@ -44,10 +44,10 @@
     "overrides": {
       "type": "object", "additionalProperties": false,
       "properties": {
-        "technology": {"type": "object"},
-        "validation": {"type": "object", "properties": {"commands": {"type": "array", "items": {"type": ["string", "object"]}}}},
-        "classification": {"type": "object", "properties": {"protected_path_hints": {"type": "array", "items": {"type": "string"}}, "dependency_path_hints": {"type": "array", "items": {"type": "string"}}, "additional_protected_characteristics": {"type": "array", "items": {"type": "string"}}}},
-        "ux": {"type": "object", "properties": {"additional_required_when": {"type": "array", "items": {"type": "string"}}}},
+        "extensions": {"type": "array", "items": {"type": "object", "additionalProperties": false, "required": ["namespace", "schema_version", "configuration"], "properties": {"namespace": {"type": "string"}, "schema_version": {"type": "integer"}, "configuration": {"type": "object"}}}},
+        "validation": {"type": "object", "additionalProperties": false, "properties": {"commands": {"type": "array", "items": {"type": ["string", "object"]}}}},
+        "classification": {"type": "object", "additionalProperties": false, "properties": {"protected_path_hints": {"type": "array", "items": {"type": "string"}}, "dependency_path_hints": {"type": "array", "items": {"type": "string"}}, "additional_protected_characteristics": {"type": "array", "items": {"type": "string"}}}},
+        "ux": {"type": "object", "additionalProperties": false, "properties": {"additional_required_when": {"type": "array", "items": {"type": "string"}}}},
         "controls": {"type": "object"},
         "native_enforcement": {"type": "object"}
         ,"agent_execution": {
@@ -62,6 +62,11 @@
           }
         }
       }
-    }
+    },
+    "adoption": {"type": "object", "additionalProperties": false, "properties": {"target_mode": {"enum": ["Foundation", "Assured", "Protected", "Governed"]}, "metrics_enabled": {"type": "boolean"}}},
+    "adapters": {"type": "object", "additionalProperties": false, "properties": {
+      "github": {"type": "object", "additionalProperties": false, "properties": {"readiness_status": {"type": "string"}, "protected_branch": {"type": "string"}, "production_environment": {"type": "string"}, "runner_labels": {"type": "array", "items": {"type": "string"}}}},
+      "github_copilot": {"type": "object", "additionalProperties": false, "properties": {"scoped_instructions": {"type": "array", "items": {"type": "object", "additionalProperties": false, "required": ["name", "apply_to", "context_paths"], "properties": {"name": {"type": "string", "pattern": "^[a-z0-9-]+$"}, "apply_to": {"type": "string", "pattern": "^[^\\r\\n\"]+$"}, "context_paths": {"type": "array", "items": {"type": "string"}}}}}}}
+    }}
   }
 }

src/engineering_process/__init__.py

@@ -1,3 +1,3 @@
 """Software Engineering Policy and Assurance platform."""
 
-__version__ = "1.2.0"
+__version__ = "1.3.0"