archctx 0.1.2 → 0.1.4-beta.0

package/assets/practices/data.single-authoritative-model.yaml

@@ -0,0 +1,67 @@
+{
+  "schemaVersion": "archcontext.practice/v1",
+  "id": "data.single-authoritative-model",
+  "revision": 1,
+  "status": "active",
+  "title": "Data concepts need one authoritative model",
+  "summary": "When multiple data shapes represent the same business concept, identify one authoritative model and keep adapters at explicit boundaries.",
+  "category": "data",
+  "tags": ["data", "model", "authority"],
+  "appliesTo": {
+    "repositoryKinds": ["application", "service"],
+    "languages": [],
+    "frameworks": [],
+    "pathGlobs": ["src/**", "packages/**", "schemas/**", "migrations/**"],
+    "nodeKinds": ["resource", "module", "service"],
+    "negativePathGlobs": ["test/**", "**/*.fixture.*"]
+  },
+  "triggers": {
+    "candidateTerms": ["model", "dto", "mapper", "entity", "schema"],
+    "pressureSignals": ["dual-track-business-concept"],
+    "structuralPredicates": ["parallel-data-shape-observed", "mapper-symbol-added"]
+  },
+  "evidencePolicy": {
+    "minimumStrengthForRecommendation": "heuristic",
+    "minimumStrengthForCheckpoint": "observed",
+    "minimumStrengthForEnforcement": "observed",
+    "requiredKindsForEnforcement": ["symbol", "data-edge"],
+    "maxEnforcementWhenOnlyHeuristic": "advisory"
+  },
+  "guidance": {
+    "questions": ["Which representation owns writes?", "Where are adapters allowed?", "What temporary shapes are removed?"],
+    "preferred": ["Keep one internal representation.", "Map at ingress, egress, or persistence boundaries."],
+    "avoid": ["Business rules duplicated across DTO/entity pairs.", "New mapper chains with no target-state plan."]
+  },
+  "checks": [
+    {
+      "checkId": "single-authoritative-model",
+      "mode": "deterministic",
+      "parameters": {
+        "requireBoundaryAdapter": true
+      }
+    }
+  ],
+  "enforcement": {
+    "default": "advisory",
+    "promotableTo": "checkpoint",
+    "repoOptInRequired": true
+  },
+  "provenance": {
+    "sourceKind": "archcontext-native",
+    "sourceRefs": [
+      {
+        "sourceId": "archcontext.spec"
+      },
+      {
+        "sourceId": "archcontext.adr.0009"
+      }
+    ],
+    "curator": "archcontext-maintainers",
+    "reviewedAt": "2026-06-23"
+  },
+  "lifecycle": {
+    "introducedAt": "2026-06-23",
+    "reviewAfter": "2027-06-23",
+    "supersedes": []
+  }
+}

package/assets/practices/decision.record-significant-change.yaml

@@ -0,0 +1,69 @@
+{
+  "schemaVersion": "archcontext.practice/v1",
+  "id": "decision.record-significant-change",
+  "revision": 1,
+  "status": "active",
+  "title": "Significant architecture changes require a durable decision record",
+  "summary": "When a task changes a boundary, persistence model, runtime path, or compatibility contract, record the decision and its tradeoffs before treating the change as settled.",
+  "category": "decisions",
+  "tags": ["adr", "governance", "tradeoff"],
+  "appliesTo": {
+    "repositoryKinds": ["application", "service", "library"],
+    "languages": [],
+    "frameworks": [],
+    "pathGlobs": ["**/*"],
+    "nodeKinds": ["module", "service", "capability", "public-api"],
+    "negativePathGlobs": ["docs/verification/**", "README.md"]
+  },
+  "triggers": {
+    "candidateTerms": ["adr", "decision", "tradeoff", "boundary", "architecture"],
+    "pressureSignals": ["architecture-intervention", "boundary-change"],
+    "structuralPredicates": ["architecture-boundary-changed", "policy-or-contract-changed"]
+  },
+  "evidencePolicy": {
+    "minimumStrengthForRecommendation": "declared",
+    "minimumStrengthForCheckpoint": "observed",
+    "minimumStrengthForEnforcement": "observed",
+    "requiredKindsForEnforcement": ["architecture-model", "diff"],
+    "maxEnforcementWhenOnlyHeuristic": "advisory"
+  },
+  "guidance": {
+    "questions": ["What changed at the architecture boundary?", "Which alternatives were rejected?", "What rollback or review condition exists?"],
+    "preferred": ["Record the decision next to the architecture source of truth.", "Keep the record short, specific, and linked to the changed boundary."],
+    "avoid": ["Treating a large structural change as self-evident.", "Putting durable rationale only in a PR comment."]
+  },
+  "checks": [
+    {
+      "checkId": "observed-before-enforced",
+      "mode": "deterministic",
+      "parameters": {
+        "requireObservedEvidence": true
+      }
+    }
+  ],
+  "enforcement": {
+    "default": "advisory",
+    "promotableTo": "checkpoint",
+    "repoOptInRequired": true
+  },
+  "provenance": {
+    "sourceKind": "curated-open-source",
+    "sourceRefs": [
+      {
+        "sourceId": "madr",
+        "sourceRevision": "v4.0.0",
+        "licenseSpdx": "MIT OR CC0-1.0"
+      },
+      {
+        "sourceId": "archcontext.adr.0036"
+      }
+    ],
+    "curator": "archcontext-maintainers",
+    "reviewedAt": "2026-06-23"
+  },
+  "lifecycle": {
+    "introducedAt": "2026-06-23",
+    "reviewAfter": "2027-06-23",
+    "supersedes": []
+  }
+}

package/assets/practices/migration.target-and-removal-state.yaml

@@ -0,0 +1,82 @@
+{
+  "schemaVersion": "archcontext.practice/v1",
+  "id": "migration.target-and-removal-state",
+  "revision": 1,
+  "status": "active",
+  "title": "Migration work needs both target state and removal state",
+  "summary": "A migration is not complete until the desired target state and the removal path for temporary state are both explicit.",
+  "category": "migration",
+  "tags": ["migration", "target-state", "cleanup"],
+  "appliesTo": {
+    "repositoryKinds": ["application", "service", "library"],
+    "languages": [],
+    "frameworks": [],
+    "pathGlobs": ["**/*"],
+    "nodeKinds": ["module", "service", "resource"],
+    "negativePathGlobs": ["docs/**", "test/**"]
+  },
+  "triggers": {
+    "candidateTerms": ["migration", "target state", "cleanup", "remove old", "dual path"],
+    "pressureSignals": ["migration-without-target-state", "temporary-state-without-removal"],
+    "structuralPredicates": ["old-and-new-path-coexist", "migration-cleanup-missing"]
+  },
+  "evidencePolicy": {
+    "minimumStrengthForRecommendation": "declared",
+    "minimumStrengthForCheckpoint": "observed",
+    "minimumStrengthForEnforcement": "observed",
+    "requiredKindsForEnforcement": ["architecture-model", "diff"],
+    "maxEnforcementWhenOnlyHeuristic": "advisory"
+  },
+  "guidance": {
+    "questions": ["What is the final single-path state?", "Which temporary elements remain?", "What proof deletes or retires them?"],
+    "preferred": ["Track target state and kill list together.", "Attach review date and owner to temporary state."],
+    "avoid": ["Calling migration complete when dual paths still exist.", "Leaving deletion as implicit future work."]
+  },
+  "checks": [
+    {
+      "checkId": "migration-review-date",
+      "mode": "deterministic",
+      "parameters": {
+        "required": true
+      }
+    },
+    {
+      "checkId": "migration-removal-condition",
+      "mode": "deterministic",
+      "parameters": {
+        "required": true
+      }
+    }
+  ],
+  "enforcement": {
+    "default": "advisory",
+    "promotableTo": "complete",
+    "repoOptInRequired": true,
+    "fixtureGate": {
+      "positive": [{ "id": "fixture.migration.target-and-removal-state.positive", "path": "packages/core/practice-engine/test/practice-engine.test.ts", "description": "Migration evidence without review date or removal condition fails complete enforcement." }],
+      "nearNegative": [{ "id": "fixture.migration.target-and-removal-state.near-negative", "path": "evals/practices/benign-negative.jsonl", "description": "Plain migration wording without typed subjects remains non-gating." }],
+      "mixedChange": [{ "id": "fixture.migration.target-and-removal-state.mixed-change", "path": "packages/core/practice-engine/test/practice-engine.test.ts", "description": "Partial migration proof distinguishes missing removal from invalid review date." }],
+      "baseline": [{ "id": "fixture.migration.target-and-removal-state.baseline", "path": "packages/core/practice-engine/test/practice-engine.test.ts", "description": "Complete migration review and removal evidence passes deterministically." }]
+    }
+  },
+  "provenance": {
+    "sourceKind": "archcontext-native",
+    "sourceRefs": [
+      {
+        "sourceId": "archcontext.adr.0009"
+      },
+      {
+        "sourceId": "madr",
+        "sourceRevision": "v4.0.0",
+        "licenseSpdx": "MIT OR CC0-1.0"
+      }
+    ],
+    "curator": "archcontext-maintainers",
+    "reviewedAt": "2026-06-23"
+  },
+  "lifecycle": {
+    "introducedAt": "2026-06-23",
+    "reviewAfter": "2027-06-23",
+    "supersedes": []
+  }
+}

package/assets/practices/modularity.no-new-cycle.yaml

@@ -0,0 +1,71 @@
+{
+  "schemaVersion": "archcontext.practice/v1",
+  "id": "modularity.no-new-cycle",
+  "revision": 1,
+  "status": "active",
+  "title": "Do not introduce new dependency cycles",
+  "summary": "A change that creates a new dependency cycle should be stopped or split until the directional boundary is restored.",
+  "category": "modularity",
+  "tags": ["modularity", "dependency", "cycle"],
+  "appliesTo": {
+    "repositoryKinds": ["application", "service", "library"],
+    "languages": [],
+    "frameworks": [],
+    "pathGlobs": ["packages/**", "src/**"],
+    "nodeKinds": ["module", "service", "package"],
+    "negativePathGlobs": ["test/**", "**/*.fixture.*"]
+  },
+  "triggers": {
+    "candidateTerms": ["cycle", "circular", "dependency"],
+    "pressureSignals": ["dependency-cycle"],
+    "structuralPredicates": ["new-import-cycle-observed", "new-package-cycle-observed"]
+  },
+  "evidencePolicy": {
+    "minimumStrengthForRecommendation": "observed",
+    "minimumStrengthForCheckpoint": "observed",
+    "minimumStrengthForEnforcement": "observed",
+    "requiredKindsForEnforcement": ["import-edge", "diff"],
+    "maxEnforcementWhenOnlyHeuristic": "advisory"
+  },
+  "guidance": {
+    "questions": ["Which new edge closed the cycle?", "Can the dependency invert through an interface or existing boundary?", "Is the cycle historical or introduced by this diff?"],
+    "preferred": ["Break the newest edge first.", "Move shared contracts to the existing lower-level package."],
+    "avoid": ["Adding a helper import that crosses back upward.", "Treating historical cycles and new cycles as the same remediation."]
+  },
+  "checks": [
+    {
+      "checkId": "no-new-cycle",
+      "mode": "deterministic",
+      "parameters": {
+        "onlyNewViolations": true
+      }
+    }
+  ],
+  "enforcement": {
+    "default": "advisory",
+    "promotableTo": "complete",
+    "repoOptInRequired": true,
+    "fixtureGate": {
+      "positive": [{ "id": "fixture.modularity.no-new-cycle.positive", "path": "packages/core/practice-engine/test/practice-engine.test.ts", "description": "New cycle evidence blocks complete enforcement when opted in." }],
+      "nearNegative": [{ "id": "fixture.modularity.no-new-cycle.near-negative", "path": "evals/practices/benign-negative.jsonl", "description": "Cycle wording without observed import evidence remains advisory." }],
+      "mixedChange": [{ "id": "fixture.modularity.no-new-cycle.mixed-change", "path": "packages/core/practice-engine/test/practice-engine.test.ts", "description": "Mixed source and test changes keep cycle subjects scoped." }],
+      "baseline": [{ "id": "fixture.modularity.no-new-cycle.baseline", "path": "packages/core/practice-engine/test/practice-engine.test.ts", "description": "Historical cycles do not fail unless a new cycle edge appears." }]
+    }
+  },
+  "provenance": {
+    "sourceKind": "curated-open-source",
+    "sourceRefs": [
+      {
+        "sourceId": "archunit",
+        "licenseSpdx": "Apache-2.0"
+      }
+    ],
+    "curator": "archcontext-maintainers",
+    "reviewedAt": "2026-06-23"
+  },
+  "lifecycle": {
+    "introducedAt": "2026-06-23",
+    "reviewAfter": "2027-06-23",
+    "supersedes": []
+  }
+}

package/assets/practices/modularity.respect-dependency-direction.yaml

@@ -0,0 +1,74 @@
+{
+  "schemaVersion": "archcontext.practice/v1",
+  "id": "modularity.respect-dependency-direction",
+  "revision": 1,
+  "status": "active",
+  "title": "Dependency direction must follow declared layers",
+  "summary": "When a repository declares layers or package ownership, new imports must move in the allowed direction unless an explicit boundary contract exists.",
+  "category": "modularity",
+  "tags": ["modularity", "layers", "imports"],
+  "appliesTo": {
+    "repositoryKinds": ["application", "service", "library"],
+    "languages": [],
+    "frameworks": [],
+    "pathGlobs": ["packages/**", "src/**"],
+    "nodeKinds": ["module", "service", "package"],
+    "negativePathGlobs": ["test/**", "scripts/**"]
+  },
+  "triggers": {
+    "candidateTerms": ["layer", "boundary", "import", "dependency"],
+    "pressureSignals": ["boundary-crossing-import"],
+    "structuralPredicates": ["declared-layer-violation-observed", "cross-boundary-import-added"]
+  },
+  "evidencePolicy": {
+    "minimumStrengthForRecommendation": "declared",
+    "minimumStrengthForCheckpoint": "observed",
+    "minimumStrengthForEnforcement": "observed",
+    "requiredKindsForEnforcement": ["import-edge", "architecture-model"],
+    "maxEnforcementWhenOnlyHeuristic": "advisory"
+  },
+  "guidance": {
+    "questions": ["Which declared boundary is being crossed?", "Is the dependency direction part of a public contract?", "Can the call move behind a port?"],
+    "preferred": ["Use the existing package entrypoint or contract layer.", "Keep core and domain packages free of runtime or surface imports."],
+    "avoid": ["Relative imports across package boundaries.", "Adding a convenience import that weakens the layer graph."]
+  },
+  "checks": [
+    {
+      "checkId": "dependency-direction",
+      "mode": "deterministic",
+      "parameters": {
+        "requiresDeclaredProfile": true
+      }
+    }
+  ],
+  "enforcement": {
+    "default": "advisory",
+    "promotableTo": "complete",
+    "repoOptInRequired": true,
+    "fixtureGate": {
+      "positive": [{ "id": "fixture.modularity.respect-dependency-direction.positive", "path": "packages/core/practice-engine/test/practice-engine.test.ts", "description": "Typed boundary violation evidence blocks complete enforcement." }],
+      "nearNegative": [{ "id": "fixture.modularity.respect-dependency-direction.near-negative", "path": "packages/core/practice-engine/test/practice-engine.test.ts", "description": "Plain import edges do not prove declared layer violations." }],
+      "mixedChange": [{ "id": "fixture.modularity.respect-dependency-direction.mixed-change", "path": "packages/core/practice-engine/test/practice-engine.test.ts", "description": "Mixed historical and new direction violations isolate only the new subject." }],
+      "baseline": [{ "id": "fixture.modularity.respect-dependency-direction.baseline", "path": "packages/core/practice-engine/test/practice-engine.test.ts", "description": "Historical declared-layer violations pass when unchanged." }]
+    }
+  },
+  "provenance": {
+    "sourceKind": "curated-open-source",
+    "sourceRefs": [
+      {
+        "sourceId": "archunit",
+        "licenseSpdx": "Apache-2.0"
+      },
+      {
+        "sourceId": "archcontext.spec"
+      }
+    ],
+    "curator": "archcontext-maintainers",
+    "reviewedAt": "2026-06-23"
+  },
+  "lifecycle": {
+    "introducedAt": "2026-06-23",
+    "reviewAfter": "2027-06-23",
+    "supersedes": []
+  }
+}

package/assets/practices/observability.boundary-telemetry.yaml

@@ -0,0 +1,65 @@
+{
+  "schemaVersion": "archcontext.practice/v1",
+  "id": "observability.boundary-telemetry",
+  "revision": 1,
+  "status": "active",
+  "title": "New runtime boundaries need telemetry at the boundary",
+  "summary": "When a change adds a runtime boundary, queue, external call, or long-lived job, add telemetry that identifies the boundary and failure mode.",
+  "category": "observability",
+  "tags": ["observability", "telemetry", "runtime-boundary"],
+  "appliesTo": {
+    "repositoryKinds": ["application", "service"],
+    "languages": [],
+    "frameworks": [],
+    "pathGlobs": ["src/**", "packages/**", "services/**"],
+    "nodeKinds": ["service", "resource", "module"],
+    "negativePathGlobs": ["test/**", "docs/**"]
+  },
+  "triggers": {
+    "candidateTerms": ["queue", "worker", "external call", "telemetry", "trace", "metric", "log"],
+    "pressureSignals": ["runtime-boundary-without-observability"],
+    "structuralPredicates": ["runtime-boundary-added", "telemetry-evidence-missing"]
+  },
+  "evidencePolicy": {
+    "minimumStrengthForRecommendation": "declared",
+    "minimumStrengthForCheckpoint": "observed",
+    "minimumStrengthForEnforcement": "observed",
+    "requiredKindsForEnforcement": ["diff", "runtime-check"],
+    "maxEnforcementWhenOnlyHeuristic": "advisory"
+  },
+  "guidance": {
+    "questions": ["What boundary can fail independently?", "Which signal identifies latency and failure?", "Where is service identity attached?"],
+    "preferred": ["Emit low-cardinality signals at ingress and egress.", "Tie telemetry names to stable architecture IDs where possible."],
+    "avoid": ["Adding logs only inside happy-path business logic.", "Using raw request payloads as telemetry fields."]
+  },
+  "checks": [
+    {
+      "checkId": "boundary-telemetry-required",
+      "mode": "deterministic",
+      "parameters": {
+        "forRuntimeBoundary": true
+      }
+    }
+  ],
+  "enforcement": {
+    "default": "advisory",
+    "promotableTo": "checkpoint",
+    "repoOptInRequired": true
+  },
+  "provenance": {
+    "sourceKind": "curated-open-source",
+    "sourceRefs": [
+      {
+        "sourceId": "opentelemetry",
+        "licenseSpdx": "CC-BY-4.0"
+      }
+    ],
+    "curator": "archcontext-maintainers",
+    "reviewedAt": "2026-06-23"
+  },
+  "lifecycle": {
+    "introducedAt": "2026-06-23",
+    "reviewAfter": "2027-06-23",
+    "supersedes": []
+  }
+}

package/assets/practices/ownership.explicit-lifecycle-owner.yaml

@@ -0,0 +1,74 @@
+{
+  "schemaVersion": "archcontext.practice/v1",
+  "id": "ownership.explicit-lifecycle-owner",
+  "revision": 1,
+  "status": "active",
+  "title": "Governed architecture elements need one lifecycle owner",
+  "summary": "A component, integration, policy, compatibility path, or generated artifact that can block delivery must have one accountable lifecycle owner.",
+  "category": "ownership",
+  "tags": ["ownership", "lifecycle", "governance"],
+  "appliesTo": {
+    "repositoryKinds": ["application", "service", "library"],
+    "languages": [],
+    "frameworks": [],
+    "pathGlobs": ["**/*"],
+    "nodeKinds": ["module", "service", "resource", "public-api"],
+    "negativePathGlobs": ["test/**", "**/*.fixture.*"]
+  },
+  "triggers": {
+    "candidateTerms": ["owner", "ownership", "team", "lifecycle"],
+    "pressureSignals": ["multiple-lifecycle-owner", "missing-owner"],
+    "structuralPredicates": ["governed-element-created", "ownership-spread-observed"]
+  },
+  "evidencePolicy": {
+    "minimumStrengthForRecommendation": "declared",
+    "minimumStrengthForCheckpoint": "observed",
+    "minimumStrengthForEnforcement": "observed",
+    "requiredKindsForEnforcement": ["architecture-model", "diff"],
+    "maxEnforcementWhenOnlyHeuristic": "advisory"
+  },
+  "guidance": {
+    "questions": ["Who owns this element through removal or replacement?", "Where is that owner recorded?", "What condition ends the obligation?"],
+    "preferred": ["Record one owner in the model or policy.", "Use review dates for temporary ownership."],
+    "avoid": ["Shared ownership with no escalation path.", "Implicit ownership by whoever touched the file last."]
+  },
+  "checks": [
+    {
+      "checkId": "owner-required",
+      "mode": "deterministic",
+      "parameters": {
+        "scope": "governed-elements"
+      }
+    }
+  ],
+  "enforcement": {
+    "default": "advisory",
+    "promotableTo": "complete",
+    "repoOptInRequired": true,
+    "fixtureGate": {
+      "positive": [{ "id": "fixture.ownership.explicit-lifecycle-owner.positive", "path": "packages/core/practice-engine/test/practice-engine.test.ts", "description": "Governed subjects without lifecycle owners fail complete enforcement." }],
+      "nearNegative": [{ "id": "fixture.ownership.explicit-lifecycle-owner.near-negative", "path": "packages/core/practice-engine/test/practice-engine.test.ts", "description": "Plain symbols are not treated as governed owner subjects." }],
+      "mixedChange": [{ "id": "fixture.ownership.explicit-lifecycle-owner.mixed-change", "path": "packages/core/practice-engine/test/practice-engine.test.ts", "description": "Owned, missing, split and self-attested subjects are separated in one fixture." }],
+      "baseline": [{ "id": "fixture.ownership.explicit-lifecycle-owner.baseline", "path": "packages/core/practice-engine/test/practice-engine.test.ts", "description": "Owner registry readback anchors complete enforcement to declared model owners." }]
+    }
+  },
+  "provenance": {
+    "sourceKind": "curated-open-source",
+    "sourceRefs": [
+      {
+        "sourceId": "backstage",
+        "licenseSpdx": "Apache-2.0"
+      },
+      {
+        "sourceId": "archcontext.spec"
+      }
+    ],
+    "curator": "archcontext-maintainers",
+    "reviewedAt": "2026-06-23"
+  },
+  "lifecycle": {
+    "introducedAt": "2026-06-23",
+    "reviewAfter": "2027-06-23",
+    "supersedes": []
+  }
+}