xdrs-core 0.38.3 → 0.39.0

package/.xdrs/_core/adrs/index.md

@@ -21,6 +21,7 @@ Foundational standards, principles, and guidelines.
 - [_core-adr-policy-013](principles/013-platform-scope-type.md) - **platform scope type** — Defines the `platform` scope type: live services or operational areas consumable directly
 - [_core-adr-policy-014](principles/014-standard-scope-type.md) - **standard scope type** — Defines the `standard` scope type: the default for business areas, products, and teams
 - [_core-adr-policy-015](principles/015-local-scope-type.md) - **_local scope type** — Defines the `_local` scope type: reserved for workspace-local decisions that must never be distributed
+- [_core-adr-policy-016](principles/016-policy-subjects.md) - **Policy Subjects** — Allowed subjects per type (ADR/BDR/EDR), descriptions, examples, and disambiguation tiebreakers
 
 ## Skills
 

package/.xdrs/_core/adrs/principles/001-xdrs-core.md

@@ -28,6 +28,8 @@ Policies can be of different kinds, depending on the nature of the decision:
 - ADR (Architectural Decision Record): Wider architectural and technical decisions. Examples: how big topics relate to each other, system contexts, overview without realy deciding on details, integration patterns, overarching topics, corporate wide practices, corporate systems, external and internal partners etc
 - EDR (Engineering Decision Record): captures engineering details about how to implement things. Examples: specific tools and libraries selection, framework usage, best practices on coding, testing, quality, project structure, pipelines etc
 
+ADR and EDR share the same six technical subject names (see [`_core-adr-policy-016`](016-policy-subjects.md)). The type disambiguates the abstraction level: ADR captures the architectural choice (what to adopt, which strategy, which topology); EDR captures the engineering implementation of that choice (how to configure, which conventions to follow, which tools to use). When the same concern spans both layers, authors MUST create two separate documents in the same-named subject across types. See `_core-adr-policy-016` for full subject descriptions, examples, and cross-type tiebreaker rules.
+
 #### General framework standards
 
 - The main document type in the collection of XDRS is the Policy document, which contains the core of a decision, contraints, rules and what SHOULD be followed. Other documents are normally related to this policy and MUST NOT go against its contents.
@@ -90,52 +92,7 @@ Policies can be of different kinds, depending on the nature of the decision:
     - `metadata` (optional): Arbitrary key-value map for additional scope metadata.
     - `follows` (optional): Core scope names whose Policies apply as mandatory conventions to this scope, beyond `_core`. Last-listed takes precedence on conflicts (e.g., `follows: myarea-core, shared-standards`).
     - `related-scopes` (optional): Scope names of parent, sibling, or child scopes. Use when structural links help verify policy correctness across related scopes.
-- **Subjects:** MUST be one of the following depending on the type of the Policy. Use the subject to indicate the main concern of the decision.
-  - **ADR subjects**
-    - `principles`: Cross-cutting architecture and policy foundations.
-      - Examples: architecture style, interoperability rules, long-term technology direction.
-    - `application`: System and service design decisions at application level.
-      - Examples: modularization strategy, service decomposition, app-level security flows.
-    - `data`: Data architecture and information modeling choices.
-      - Examples: canonical schemas, data ownership boundaries, retention strategies.
-    - `integration`: Decisions about communication between internal/external systems.
-      - Examples: sync vs async patterns, contract strategy, partner integration approach.
-    - `platform`: Platform-level runtime and enabling capabilities.
-      - Examples: cloud/runtime baseline, foundational services, platform tenancy approach.
-    - `controls`: Architecture controls for risk, security, and compliance at a high level.
-      - Examples: encryption baseline, auditability requirements, policy enforcement points.
-    - `operations`: Operational architecture decisions.
-      - Examples: incident model, resilience objectives, operational ownership boundaries.
-  - **BDR subjects**
-    - `principles`: Business principles and decision criteria that guide all business areas.
-      - Examples: customer fairness rules, policy precedence, strategic guardrails.
-    - `marketing`: Go-to-market, communication, and campaign policy decisions.
-      - Examples: campaign approval rules, channel usage standards, positioning constraints.
-    - `product`: Product behavior, lifecycle, and offering decisions.
-      - Examples: feature rollout policy, packaging/tiers, product requirement governance.
-    - `controls`: Business control framework decisions.
-      - Examples: approval segregation, mandatory checks, exception handling policy.
-    - `operations`: Day-to-day business process and procedure decisions.
-      - Examples: support workflows, onboarding/offboarding procedures, SLA operations.
-    - `organization`: Structure, roles, and responsibility model decisions.
-      - Examples: decision rights, team topology, accountability boundaries.
-    - `finance`: Financial and cost-control business decisions.
-      - Examples: budgeting process, pricing governance, investment approval rules.
-    - `sustainability`: Environmental and social responsibility policy decisions.
-      - Examples: sustainability KPIs, reporting cadence, procurement sustainability criteria.
-  - **EDR subjects**
-    - `principles`: Engineering principles and non-functional quality defaults.
-      - Examples: coding standards baseline, testing philosophy, secure-by-default engineering rules.
-    - `application`: Code-level implementation patterns and application conventions.
-      - Examples: framework patterns, layer organization, API implementation conventions.
-    - `infra`: Infrastructure implementation and runtime operations details.
-      - Examples: IaC patterns, environment provisioning, network/runtime hardening details.
-    - `observability`: Telemetry, monitoring, alerting, and diagnostics implementation.
-      - Examples: log/metric/tracing standards, alert routing policy, SLO measurement approach.
-    - `devops`: Delivery pipeline, release automation, and developer workflow decisions.
-      - Examples: CI/CD stages, branch strategy, release promotion gates.
-    - `governance`: Engineering governance, risk controls, and compliance mechanics.
-      - Examples: dependency governance, approval policies, mandatory quality checks.
+- **Subjects:** The subject folder MUST be chosen per [`_core-adr-policy-016`](016-policy-subjects.md), which defines allowed subjects, full descriptions, examples, and disambiguation tiebreakers.
 - MUST NOT use emojis
 - **Links:** Use relative paths for all links; MUST NOT use absolute paths starting with `/`.
 - **Indexes**
@@ -144,8 +101,8 @@ Policies can be of different kinds, depending on the nature of the decision:
   - Canonical index requirements:
     - Organize XDRS documents by subject for easier navigation
     - Add a short description of what this scope is about (responsibilities, general worries, teams involved, link to discussion process, etc)
-    - Add a list of other scope indexes that this scope might be related to (only add scopes that might be overridden). E.g: "business-x-mobileapp" scope could refer to "business-x" and "sensitive-data" scopes in its index list. XDRS in scopes listed last override XDRS in scopes listed first when addressing the same topic.
-    - Each XDRS element entry in the index MUST include a short description of its content. The description SHOULD use an imperative statement or the question it answers when possible (<15 words). Example: "Use this while planning a new feature", "What communication tone we use with our customers?", "PNPM vs Yarn comparison study"
+    - Add links to related scope indexes that this scope might override or be overridden by (scopes listed last override earlier ones on the same topic).
+    - Each XDRS element entry MUST include a short description. SHOULD use an imperative statement or the question it answers (<15 words). Example: "Use this while planning a new feature", "What communication tone we use with our customers?"
   - Outside the scopes, keep a root index in `[xdrs-root]/index.md` that links to each scope index (`[xdrs-root]/[scope]/index.md`). Add the text "XDRS scopes listed last override the ones listed first". The root index MUST NOT link directly to type indexes; readers navigate from the scope index to the type indexes. Use the link text pattern `View scope [scope_name]` for each scope link (e.g. `[View scope myteam] linking to (myteam/index.md)`).
   - MUST verify if indexes are up to date after making changes
 - **Scope index**
@@ -157,9 +114,9 @@ Policies can be of different kinds, depending on the nature of the decision:
   - Whenever the contents of a scope change (new Policies, skills, articles, research, or plans are added, updated, or removed), evaluate whether the scope index SHOULD be updated to reflect the newer contents.
 
 **Folder structure examples** (using the default `.xdrs/` root):
-- `.xdrs/business-x/edrs/devops/003-required-development-workflow.md`
-- `.xdrs/business-x/adrs/controls/010-security-and-secrets-management.md`
-- `.xdrs/_core/edrs/devops/001-multi-repo.md`
+- `.xdrs/business-x/edrs/platform/003-required-development-workflow.md`
+- `.xdrs/business-x/adrs/governance/010-security-and-secrets-management.md`
+- `.xdrs/_core/edrs/platform/001-multi-repo.md`
 
 ```text
 subject/
@@ -185,6 +142,7 @@ subject/
 - [_core-adr-policy-002 - Policy standards](002-policy-standards.md) - Standards for writing individual Policy documents
 - [_core-adr-policy-010 - Scope governance](010-scope-governance.md) - Scope-type definition convention, scope-local standards, and governance application model
 - [_core-adr-policy-011 - core scope type](011-core-scope-type.md) - Defines the `core` scope type and meta-governance scope conventions
+- [_core-adr-policy-016 - Policy Subjects](016-policy-subjects.md) - Allowed subjects per type, descriptions, examples, and disambiguation tiebreakers
 - [001-review skill](skills/001-review/SKILL.md) - Skill for reviewing code changes against Policies
 - [002-write-policy skill](skills/002-write-policy/SKILL.md) - Skill for creating a new Policy following this standard
 - [_core-adr-policy-003 - Skill standards](003-skill-standards.md)

package/.xdrs/_core/adrs/principles/002-policy-standards.md

@@ -28,7 +28,7 @@ Policy documents are the authoritative source of truth for their scope, type, an
 | `name` | Yes | 1-64 characters. Lowercase letters, numbers, hyphens, and leading underscores only. MUST NOT end with a hyphen. MUST NOT contain consecutive hyphens. MUST match the document identifier from the heading: `[scope]-[type]-policy-[number]-[short-title]`. |
 | `description` | Yes | 1-1024 characters. Describes what this decision is about and when to use it. SHOULD include keywords that help agents identify when to apply it. |
 | `apply-to` | Yes | Short description of contexts this decision is applicable to. Keep it under 40 words. Use `All scopes` when the decision applies broadly. Examples: `Only frontend code`, `JavaScript projects`, `All scopes`. |
-| `valid-from` | Yes | ISO date (`YYYY-MM-DD`) indicating from when this decision MUST be enforced. Before this date it SHOULD be used everywhere possible, but compliance is not enforced during reviews until after this date. Defaults to the date the Policy was created. When updating an existing Policy whose `valid-from` date has already passed, preserve the original date—do not update it to the current date. The historical date shows when the policy was originally enabled and is important for understanding policy evolution. |
+| `valid-from` | Yes | ISO date (`YYYY-MM-DD`) indicating from when this decision MUST be enforced. Before this date it SHOULD be used everywhere possible, but compliance is not enforced during reviews until after this date. Defaults to the date the Policy was created. When updating an existing Policy whose `valid-from` date has already passed, preserve the original date—it MUST NOT be updated to the current date. The historical date shows when the policy was originally enabled and is important for understanding policy evolution. |
 | `license` | No | SPDX license expression (e.g. `MIT`, `Apache-2.0`, `CC-BY-4.0`). Indicates the license under which the document content is shared. If omitted, the license is governed by the repository or package defaults. |
 | `metadata` | No | Arbitrary key-value map for additional properties not defined by this spec. |
 
@@ -62,6 +62,8 @@ Policy documents are the authoritative source of truth for their scope, type, an
   - Types in IDs: `adr-policy`, `bdr-policy`, `edr-policy`
   - Define the next number of a Policy by checking what is the highest number present in the type+scope. Don't fill numbering gaps, as they might be old deleted Policies and we MUST NOT reuse numbers of different documents/decisions. Numbering gaps are expected.
 - Policies MUST be concise and reference other Policies to avoid duplication.
+- Policies MUST NOT contain duplicated content: the same rule or information MUST NOT appear more than once in the document, whether stated identically or rephrased. Consolidate into a single authoritative statement and reference it where needed.
+- Policies MUST NOT contain conflicting content: all rules and statements within the same document MUST be consistent with each other.
 - The `### Details` section SHOULD state relevant boundaries or exceptions and what a reader SHOULD do or avoid in common cases. Use the frontmatter fields `apply-to` and `valid-from` as the first-pass filter for applicability, then keep nuanced boundaries in the decision text.
 - Use concise rules, examples, `Allowed` / `Disallowed` lists or checklists with required items to help the reader apply the decision correctly. Keep them short and decision-specific.
 - Policies MUST NOT include historical change notes or descriptions of what changed from a previous version. State only the current rule that MUST be followed. Historical context is available via git history or versioned packages.
@@ -69,6 +71,7 @@ Policy documents are the authoritative source of truth for their scope, type, an
 - When a policy covers elements that could be confused with each other, include explicit disambiguation statements clarifying the distinction before stating the rules for each.
 - A "why" explanation for a policy rule MAY only be included if it is brief, non-obvious, relevant to the reader, and not longer than the rule itself.
 - Rules MUST focus on what is required or forbidden. Explanations of why a rule exists belong in a Research document, not in the Policy itself. Link to the relevant research when the rationale is important for adoption.
+- Each policy rule and rule block MUST be unambiguous: it MUST be possible to clearly follow, check, and discuss it without requiring additional interpretation.
 - When the decision defines strong policies or rules that SHOULD be stated explicitly as stable rule blocks, or when other documents, skills, or agents need to cite those rules individually by identifier, the Policy MUST follow the extension [_core-adr-policy-008 - Policy structured standards](008-policy-structured-standards.md) instead of using plain bullet lists for those rules.
 - Conflict handling applies to Policy documents:
   - For cross-scope overrides, document the decision conflict in the Policy `## Conflicts` section of the Policy that overrides another scope.

package/.xdrs/_core/adrs/principles/012-reference-scope-type.md

@@ -35,7 +35,7 @@ Use `scope-type: reference` when the scope contains:
 - Business area procedure standards: how sales processes SHOULD be conducted, how customer data MUST be handled, how marketing communications MUST comply with applicable regulations.
 - Operational compliance guidelines: finance controls, accounting procedures, public communication standards, customer data management rules.
 
-Do not use `scope-type: reference` for scopes that represent a live service, an active team, or a production system. Use `scope-type: platform` for those.
+`scope-type: reference` MUST NOT be used for scopes that represent a live service, an active team, or a production system. Use `scope-type: platform` for those.
 
 #### 03-naming-convention
 

package/.xdrs/_core/adrs/principles/016-policy-subjects.md

@@ -0,0 +1,130 @@
+---
+name: _core-adr-policy-016-policy-subjects
+description: Defines the allowed subjects per XDRS type (ADR, BDR, EDR) with descriptions, examples, and disambiguation tiebreakers. Use when choosing a subject for any new policy or document.
+apply-to: All XDRS scopes and document types
+valid-from: 2026-07-09
+---
+
+# _core-adr-policy-016: Policy Subjects
+
+## Context and Problem Statement
+
+Policy documents are placed in a subject folder that reflects their primary concern. Without a well-defined and consistently applied subject taxonomy, documents are hard to find, placement decisions are inconsistent, and AI agents cannot reliably determine relevance.
+
+What subjects are allowed per type, and how should ambiguous placements be resolved?
+
+## Decision Outcome
+
+**A reduced, unambiguous subject taxonomy per type with explicit tiebreaker rules**
+
+Each type uses a small, well-separated set of subjects. ADR and EDR share identical subject names, creating a consistent zoom-in relationship: ADR captures architectural decisions at a higher abstraction level; EDR captures engineering implementation decisions for the same concerns. BDR uses a business-specific set.
+
+### Details
+
+#### 01-subject-must-be-from-allowed-list
+
+The subject folder for any XDRS document MUST be one of the subjects allowed for its type, as listed below. A document placed in any other subject name is invalid.
+
+| Subject | ADR | BDR | EDR |
+|---|---|---|---|
+| `principles` | ✓ | ✓ | ✓ |
+| `application` | ✓ | | ✓ |
+| `data` | ✓ | | ✓ |
+| `platform` | ✓ | | ✓ |
+| `operations` | ✓ | ✓ | ✓ |
+| `governance` | ✓ | ✓ | ✓ |
+| `product` | | ✓ | |
+| `finance` | | ✓ | |
+
+#### 02-principles-must-be-cross-cutting
+
+A document MUST only be placed in `principles` when its content affects potentially all other subjects in its type. A document that only concerns a single subject MUST be placed in that specific subject instead. Do not use `principles` as a catch-all when a more specific subject applies.
+
+#### 03-adr-and-edr-share-subject-names-at-different-abstraction-levels
+
+ADR and EDR intentionally share the same six subject names. The type disambiguates the abstraction level: ADR captures architectural choices about what to adopt or how systems relate at a high level; EDR captures engineering decisions about how to implement those choices in detail. When both an architectural and an engineering decision exist on the same topic, authors MUST create two separate documents. See tiebreaker 16 for the decision test.
+
+#### 04-subject-descriptions-for-adr
+
+Authors MUST place ADR documents in the subject that best matches the following definitions and examples.
+
+- `principles`: Cross-cutting architectural foundations affecting all other ADR subjects. Examples: architecture style adoption, domain-driven design rules, interoperability rules, long-term technology direction.
+- `application`: System and service design decisions. Covers application structure, integration and API patterns, service decomposition, migration patterns, and frontend architecture. Examples: modularization strategy, strangler fig migration, API versioning strategy, service contract approach, sync vs async communication, monolith decomposition, frontend rendering strategy (SSR vs CSR, SPA vs MPA), design system adoption, UI component library selection, mobile app architecture, AI/ML model selection and inference architecture.
+- `data`: Data architecture and information modeling choices. Examples: canonical data model, data ownership boundaries, data retention strategy (technical architecture only — regulatory retention obligations MUST go in BDR `governance`), data mesh vs centralized approach, event sourcing, polyglot persistence.
+- `platform`: Platform-level runtime and enabling capabilities — includes infrastructure topology, identity and authentication, cloud cost management, and managed external technical services adopted as infrastructure. Examples: cloud provider selection, multi-region topology, Kubernetes adoption, SSO/IAM architecture, mTLS, message broker selection, CDN strategy, FinOps and cloud cost allocation model, workflow orchestration tool selection (Airflow, Temporal), managed SaaS adoption (observability platforms, LLM API providers, data warehouse services), SIEM adoption as security monitoring infrastructure (a mandatory enforcement obligation to have a SIEM belongs in ADR `governance`).
+- `operations`: Operational architecture decisions about how systems behave and are owned in production. Examples: resilience and availability objectives, disaster recovery strategy, incident ownership model, SLA definitions, operational accountability boundaries.
+- `governance`: Architecture controls for security, compliance, and risk enforcement. Examples: encryption baseline, zero-trust architecture, threat modeling requirements, SOC2/ISO27001 compliance adoption, data classification and PII tiers, architecture review process, technology radar governance, architecture-level penetration testing requirements.
+
+#### 05-subject-descriptions-for-bdr
+
+Authors MUST place BDR documents in the subject that best matches the following definitions and examples.
+
+- `principles`: Cross-cutting business principles that affect all other BDR subjects. Examples: customer-first decision framework, policy precedence rules, strategic guardrails, brand values, patent and IP strategic stance (e.g., patent-first vs open-core), technology debt governance principle.
+- `product`: Product offering, go-to-market, marketing, and sales policy decisions. Covers product behavior and lifecycle, brand and communication standards, and sales process and revenue operations. Examples: feature rollout policy, product versioning and end-of-life, pricing tier structure, customer SLA commitments, product accessibility standards, beta program criteria, campaign approval process, social media policy, customer communication tone, brand naming, sales methodology, deal approval and discount authority matrix, CRM standards, sales commission structure, channel and partner sales policy, territory and quota policy.
+- `operations`: Day-to-day business processes, organizational structure, responsibility model, and workforce decisions. Covers business process execution, team and organizational decisions, and the employee and contractor lifecycle. Examples: support workflows, vendor selection process, decision rights and RACI, team topology, hiring and interview process, performance management framework, compensation and benefits policy, learning and development standards, remote and hybrid work policy, onboarding and offboarding procedures, workforce planning, internal communication standards, M&A integration process, outage customer communication process, on-call scheduling and compensation policy (on-call ownership model belongs in ADR `operations`).
+- `governance`: Legal, regulatory, compliance, risk management, and enterprise control decisions. Covers all mandatory policies imposed by law, regulation, or risk authority — including external regulatory obligations, internal control frameworks, enterprise risk governance, and ESG compliance requirements. Examples: GDPR and data privacy policy, risk appetite statement, KYC/AML procedures, business continuity policy, legal contract standards, employee data privacy, open-source licensing policy, vendor risk and due diligence standards, AI ethics and responsible AI policy, model risk management policy, regulatory compliance programs (SOX, HIPAA, Basel, MiFID, ISO 27001), internal audit requirements, fraud prevention policy, information security policy, ESG reporting requirements, carbon footprint targets, DEI compliance obligations, whistleblower policy, IP and patent compliance obligations, penetration testing regulatory obligation.
+- `finance`: Financial and cost-control business decisions. Examples: budgeting process, investment approval thresholds, partner revenue sharing model, procurement policy, pricing approval and margin rules.
+
+#### 06-subject-descriptions-for-edr
+
+Authors MUST place EDR documents in the subject that best matches the following definitions and examples.
+
+- `principles`: Cross-cutting engineering principles that affect all other EDR subjects. Examples: test-driven development philosophy, secure-by-default engineering rule, GitOps as default, immutable infrastructure principle.
+- `application`: Code-level implementation patterns and application conventions. Covers coding patterns, API implementation, testing approaches, in-code practices, and frontend and mobile implementation. Examples: framework selection, REST API conventions, error handling patterns, unit testing approach, caching strategy, feature flag implementation, security headers (CSP/HSTS) in code, structured log format, frontend framework selection, UI component library standards, a11y implementation patterns, i18n/l10n patterns, AI/ML inference integration patterns.
+- `data`: Data layer implementation and data management decisions. Examples: ORM selection and usage patterns, database migration tooling (Flyway, Liquibase), query optimization guidelines, ETL/ELT implementation, connection pooling standards, data masking in non-production environments.
+- `platform`: Infrastructure implementation, delivery pipeline, and developer environment decisions. Covers both production infrastructure and local developer tooling. Examples: IaC tool selection (Terraform, Pulumi), CI/CD pipeline stages, Docker image standards, Kubernetes manifest standards, git branching strategy, secrets management tooling (Vault, AWS Secrets Manager), cloud cost tagging standards, local developer environment and devcontainer setup.
+- `operations`: Production behavior and operational response decisions. Covers observability, monitoring, alerting, and runtime incident handling. Examples: log and metric collection standards, distributed tracing implementation, alert routing and escalation, SLO/SLI measurement, incident post-mortem process, rollback procedures, developer productivity and DORA metrics measurement.
+- `governance`: Engineering controls enforced as mandatory checks, gates, or approval policies. Examples: mandatory test coverage thresholds, dependency vulnerability scanning, security scanning in CI pipelines, license compliance checking, code review approval policies, breaking change approval process, deprecation enforcement.
+
+#### 07-tiebreaker-rules
+
+When a document could plausibly fit more than one subject, authors MUST apply these rules in order until one subject is clearly indicated.
+
+1. `platform` vs `operations` (ADR and EDR): `platform` covers infrastructure capabilities and the delivery pipeline — decisions made before production. `operations` covers production behavior and response — monitoring, rollback, and incident handling. Multi-region topology MUST go in `platform`; rollback procedures MUST go in `operations`. See tiebreaker 22 for delivery pipeline specifics.
+
+2. `application` vs `governance` (EDR): `application` covers how code is written — patterns, conventions, and in-code practices. `governance` covers mandatory controls enforced externally as a gate or automated scan. Security headers written into HTTP responses MUST go in `application`; a mandatory security scanning gate in CI MUST go in `governance`. Rate limiting middleware in code MUST go in `application`; a gateway-enforced rate limit threshold gate MUST go in `governance`. Container security hardening in Dockerfiles MUST go in `platform`; a mandatory container image vulnerability scan gate in CI MUST go in `governance`.
+
+3. `platform` vs `governance` (ADR): `platform` covers capabilities you adopt as part of the runtime. `governance` covers security or compliance controls you enforce. SSO/IAM infrastructure MUST go in `platform`; encryption baseline policy and data classification tiers MUST go in `governance`. See tiebreaker 17 for extended security infrastructure guidance.
+
+4. `application` vs `data` (EDR): `application` covers the implementation pattern in code. `data` covers storage, schema, and data management. A caching strategy MUST go in `application`; ORM configuration and database migration tooling MUST go in `data`.
+
+5. `product` vs `finance` (BDR): `product` covers what is offered and how it behaves. `finance` covers financial governance and cost control. Pricing tier structure MUST go in `product`; pricing approval rules and margin controls MUST go in `finance`.
+
+6. `product` vs `operations` (BDR): `product` covers the commitment made to customers. `operations` covers the process to deliver on that commitment. A customer SLA commitment MUST go in `product`; the operational workflow and escalation process to meet the SLA MUST go in `operations`.
+
+7. Security decisions across types: Security as a concern distributes across subjects by layer — there is no single `security` subject. Authors MUST place security decisions by domain: architecture security controls in ADR `governance`; identity and auth infrastructure in ADR `platform`; secure coding practices and in-code security in EDR `application`; automated security enforcement gates in EDR `governance`.
+
+8. Performance and capacity decisions: A performance design pattern MUST go in `application`. An enforced performance threshold or budget gate MUST go in `governance`. Performance infrastructure (CDN, autoscaling) MUST go in `platform`. Availability objectives and capacity planning (SLA targets, scaling strategy) MUST go in ADR `operations`.
+
+9. Change management: Process automation and delivery pipeline steps MUST go in `platform`. Human authorization and approval policies for changes MUST go in `governance`.
+
+10. `platform` abstraction level across ADR and EDR: ADR/platform covers the architectural choice — what to adopt, which topology, which strategy. EDR/platform covers the implementation conventions — tool configuration, pipeline stages, naming standards, and developer environment setup. A FinOps cost allocation strategy MUST go in ADR/platform; tagging naming conventions MUST go in EDR/platform. When a concern spans both layers, create two separate documents. See tiebreaker 16 for the general ADR-vs-EDR test.
+
+11. On-call rotation across BDR and ADR: The on-call ownership model and system accountability structure MUST go in ADR `operations`; on-call scheduling, rotation cadence, and compensation policy MUST go in BDR `operations`.
+
+10. AI/ML decisions: Model selection and inference architecture MUST go in ADR `application`; AI/ML inference implementation patterns MUST go in EDR `application`. Training pipeline infrastructure (GPUs, orchestration, experiment tracking) MUST go in `platform`. Dataset management, feature stores, model registries, and data labeling standards MUST go in `data`.
+
+11. AI ethics, responsible AI, and agentic governance: Business-level AI ethics and responsible AI policy MUST go in BDR `governance`. Mandatory architecture-level AI controls (AI risk assessment, model risk governance) MUST go in ADR `governance`. Automated AI compliance gates in CI/CD (bias scanning, model validation) MUST go in EDR `governance`. In-code guardrails, prompt safety patterns, and agentic workflow implementation MUST go in EDR `application`. Human-in-the-loop thresholds as runtime behavior MUST go in ADR `operations`.
+
+12. External technical vendor placement: Adopting a managed external technical service as a runtime capability (LLM API provider, observability SaaS, data warehouse) MUST go in ADR `platform`. Integrating with a third-party API as part of an application flow (payment gateway, identity provider, partner API) MUST go in ADR `application`. Risk assessment and due diligence for any external vendor MUST go in BDR `governance`. The business process for selecting and onboarding vendors MUST go in BDR `operations`.
+
+13. `operations` vs `governance` for workforce and sustainability decisions (BDR): `operations` covers discretionary workforce policies. `governance` covers legally or regulatorily mandated obligations. Remote work policy MUST go in `operations`; labor law compliance and ESG regulatory reporting MUST go in `governance`. Voluntary sustainability targets MUST go in `operations`; mandatory ESG disclosure or regulatory sustainability compliance MUST go in `governance`.
+
+14. `product` vs `operations` for customer-facing process decisions (BDR): `product` covers the policy for what is offered, how it is sold, and how it is communicated. `operations` covers the execution process to deliver on those policies. A sales commission structure MUST go in `product`; the operational workflow for onboarding a new customer MUST go in `operations`.
+
+15. Single policy spanning multiple subjects — mandatory split: When one concern spans two subjects, authors MUST NOT merge them. Create two separate documents — one per subject — linked bidirectionally in each References section. Examples: GDPR erasure → one BDR `governance` (legal obligation) + one BDR `operations` (deletion workflow); DR → one BDR `governance` (DR policy) + one BDR `operations` (drill procedure).
+
+16. ADR vs EDR for the same topic — abstraction-level test: If the decision answers *"what to adopt or how systems relate structurally"* → ADR. If it answers *"how to implement or configure that choice"* → EDR. When a concern spans both levels, create one ADR and one EDR in the same-named subject. Examples: error budget policy MUST go in ADR `operations`; SLO measurement implementation MUST go in EDR `operations`. Chaos engineering tool adoption MUST go in ADR `platform`; the chaos runbook standards MUST go in EDR `operations`.
+
+17. Security infrastructure in ADR — `platform` vs `governance`: If the security technology primarily *provides* a runtime capability other systems depend on (KMS, VPN, network segmentation, certificate authority, PAM tooling) → `platform`. If it primarily *mandates, restricts, or audits* behaviour as a compliance control (encryption baseline, mandatory access review, data classification enforcement) → `governance`. When the same security concern yields both a capability adoption and an enforcement obligation, apply tiebreaker 15.
+
+18. Runtime infrastructure always goes to `platform`: Any technology adopted as a runtime enabling capability — regardless of whether it also stores data (cache, message bus, search runtime, workflow engine, session store) — MUST go in `platform`. Place a technology in `data` only when it is selected for data storage, schema management, query patterns, or data lifecycle with no infrastructure runtime role. When both roles are present, apply tiebreaker 15. Examples: Redis as cache → ADR `platform`; ORM patterns → EDR `data`. Elasticsearch as search runtime → ADR `platform`; index schema standards → EDR `data`.
+
+19. BDR `finance` vs `governance` — obligation vs strategy: If the financial decision is driven by external legal, regulatory, or contractual obligation (IFRS 15, tax law, banking capital rules, mandatory insurance) → `governance`. If it is a discretionary organizational financial decision (budget process, investment thresholds, pricing approval, revenue sharing, ESOP design) → `finance`.
+
+22. Delivery pipeline vs production behavior — `platform` vs `operations`: Any decision governing what happens before or at deployment (build, test, package, deploy, canary rollout, blue-green switch) MUST go in `platform`. Any decision governing runtime behaviour after a successful deployment (monitoring, alerting, rollback trigger, incident response, SLO measurement) MUST go in `operations`. Sharpens tiebreaker 1: blue-green strategy → `platform`; rollback trigger and procedure → `operations`.
+
+## References
+
+- [_core-adr-policy-001 - XDRS core](001-xdrs-core.md) — Framework structure, scopes, types, and subject folder placement
+- [_core-adr-policy-002 - Policy standards](002-policy-standards.md) — How to write Policy documents

package/.xdrs/_core/adrs/principles/skills/002-write-policy/SKILL.md

@@ -37,10 +37,7 @@ Consult `001-xdrs-core` while making each choice in this phase. The summaries be
 **Scope** — use `_local` unless the user explicitly names another scope.
 - If the user names a scope other than `_local`, check the workspace root `.filedist.lock` file. If any file under `.xdrs/[scope]/` appears in `.filedist.lock`, the scope is external and new documents MUST NOT be created there. Inform the user and ask them to choose a non-external scope.
 
-**Subject** — pick one from the allowed list for the chosen type (from `001-xdrs-core`):
-- ADR: `principles`, `application`, `data`, `integration`, `platform`, `controls`, `operations`
-- BDR: `principles`, `marketing`, `product`, `controls`, `operations`, `organization`, `finance`, `sustainability`
-- EDR: `principles`, `application`, `infra`, `observability`, `devops`, `governance`
+**Subject** — MUST read `_core-adr-policy-016` ([016-policy-subjects.md](../../016-policy-subjects.md)) in full before choosing. That document defines all allowed subjects per type with full descriptions, examples, and disambiguation tiebreakers. Do not rely on summaries or prior knowledge of the subject list — always read the policy and select the subject that best matches the decision topic according to its definitions.
 
 When type, scope, or subject cannot be confidently inferred, ask the user a clarifying question before proceeding. Ask one question at a time and wait for the answer; follow up if the response introduces new ambiguity.
 

package/.xdrs/_core/adrs/principles/skills/003-write-skill/SKILL.md

@@ -38,10 +38,7 @@ Quick test:
 **Scope** — use `_local` unless the user explicitly names another scope.
 - If the user names a scope other than `_local`, check the workspace root `.filedist.lock` file. If any file under `.xdrs/[scope]/` appears in `.filedist.lock`, the scope is external and new documents MUST NOT be created there. Inform the user and ask them to choose a non-external scope.
 
-**Subject** — pick the most specific match for the chosen type (required list per type is in `_core-adr-policy-001`):
-- ADR subjects: `principles`, `application`, `data`, `integration`, `platform`, `controls`, `operations`
-- BDR subjects: `principles`, `marketing`, `product`, `controls`, `operations`, `organization`, `finance`, `sustainability`
-- EDR subjects: `principles`, `application`, `infra`, `observability`, `devops`, `governance`
+**Subject** — MUST read `_core-adr-policy-016` ([016-policy-subjects.md](../../016-policy-subjects.md)) in full before choosing. That document defines all allowed subjects per type with full descriptions, examples, and disambiguation tiebreakers. Do not rely on summaries or prior knowledge of the subject list — always read the policy and select the most specific subject that matches the skill's activity domain.
 
 **Skill number** — scan `.xdrs/[scope]/[type]/[subject]/skills/` for the highest existing number and increment by 1. Never reuse numbers from deleted skills.
 
@@ -146,16 +143,16 @@ If any check fails, revise before continuing.
 **Input**: "Create a skill to help debug CI pipelines"
 - Type: EDR (engineering workflow)
 - Scope: `_local`
-- Subject: `devops`
-- Number: scan `.xdrs/_local/edrs/devops/skills/` → next available
-- Output: `.xdrs/_local/edrs/devops/skills/001-debug-ci-pipeline/SKILL.md`
+- Subject: `platform`
+- Number: scan `.xdrs/_local/edrs/platform/skills/` → next available
+- Output: `.xdrs/_local/edrs/platform/skills/001-debug-ci-pipeline/SKILL.md`
 
 **Input**: "Create a skill to review API designs"
 - Type: ADR (architectural evaluation)
 - Scope: `_local`
-- Subject: `integration`
-- Number: scan `.xdrs/_local/adrs/integration/skills/` → next available
-- Output: `.xdrs/_local/adrs/integration/skills/001-review-api-design/SKILL.md`
+- Subject: `application`
+- Number: scan `.xdrs/_local/adrs/application/skills/` → next available
+- Output: `.xdrs/_local/adrs/application/skills/001-review-api-design/SKILL.md`
 
 ## Edge Cases
 

package/.xdrs/_core/adrs/principles/skills/006-write-plan/SKILL.md

@@ -142,7 +142,7 @@ Rules to apply while drafting:
 **Expected actions:**
 1. Read `007-plan-standards.md`.
 2. Topic: API v2 migration. Scope: `_local`.
-3. Type: `adrs` (architectural). Subject: `integration` or `application`.
+3. Type: `adrs` (architectural). Subject: `application`.
 4. Research related Policies about API design and integration patterns.
 5. Draft the plan with clear problem, solution, milestones, and expected end date.
 6. Save, register in canonical index, and lint.

package/.xdrs/_core/adrs/principles/skills/008-write-xdrs-doc/SKILL.md

@@ -44,3 +44,4 @@ Read the full content of the skill file for the inferred type, then follow all i
 - MUST read the full target SKILL.md before proceeding — do not rely on summaries or prior knowledge of the target skill.
 - MUST follow all phases of the target skill from Phase 1 onward; do not skip any phase.
 - MUST NOT create documents of a type not listed in the routing table above.
+- When routing to the Policy skill, MUST also read `_core-adr-policy-016` (`.xdrs/_core/adrs/principles/016-policy-subjects.md`) before choosing a subject — it contains the allowed subject list, descriptions, and disambiguation tiebreaker rules.

package/README.md

@@ -60,6 +60,16 @@ The compilation process of a raw Decision Record is to distribute it into those
 
 Different teams at different organizational levels make decisions that apply to different audiences. XDRS are organized by scope (e.g. `_core`, `business-x`, `business-y-mobileapp`) so that each team owns its own decision space. Scopes can extend or override policies from broader scopes, with explicit precedence rules: scopes listed later in an index override those listed earlier.
 
+### Scope types and `follows`
+
+Every scope declares a `scope-type` in its `index.md` frontmatter. The five built-in types are `core`, `reference`, `platform`, `standard`, and `_local`, each with different governance rules. Custom types (e.g. `business-area`) can be introduced by adding a `{type}-scope-type` policy to any `core`-type scope.
+
+`core` scopes play a special role: they carry **meta-policies** — authoring standards, scope-type definitions, and governance conventions that apply to all scopes in the workspace. `_core` is the built-in foundation; teams can add their own `core` scope (e.g. `myorg-core`) to extend it with organization-level standards.
+
+The `follows` field in a scope's `index.md` links it to one or more `core` scopes whose policies it must respect (beyond `_core`). This models organizational hierarchies: a team scope can follow a business-area `core` scope, which in turn follows `_core`.
+
+See [examples/typed-scope](examples/typed-scope) for a full working example covering all five scope types and a custom `business-area` type.
+
 ### Subject grouping
 
 Within each scope and type, decisions are grouped by subject (e.g. `application`, `data`, `platform` for ADRs; `product`, `finance` for BDRs). This keeps related decisions together, improves human navigation, and allows AI agents to narrow their search to the relevant subject folder before reading individual records.

package/lib/lint.js

@@ -11,9 +11,9 @@ const TYPE_TO_ID = {
 };
 
 const ALLOWED_SUBJECTS = {
-  adrs: new Set(['principles', 'application', 'data', 'integration', 'platform', 'controls', 'operations']),
-  bdrs: new Set(['principles', 'marketing', 'product', 'controls', 'operations', 'organization', 'finance', 'sustainability']),
-  edrs: new Set(['principles', 'application', 'infra', 'observability', 'devops', 'governance'])
+  adrs: new Set(['principles', 'application', 'data', 'platform', 'operations', 'governance']),
+  bdrs: new Set(['principles', 'product', 'marketing', 'operations', 'governance', 'finance', 'sustainability']),
+  edrs: new Set(['principles', 'application', 'data', 'platform', 'operations', 'governance'])
 };
 
 const TYPE_NAMES = new Set(Object.keys(TYPE_TO_ID));
@@ -1654,7 +1654,7 @@ function lintStructuredRuleBlocks(content, filePath, errors) {
     const ruleBodyNonCodeLines = lines.slice(bodyStart, bodyEnd).filter((_, idx) => !ignoredLines[bodyStart + idx]);
     const ruleBodyTextForEmphasis = ruleBodyNonCodeLines.join('\n');
 
-    if (!NORMATIVE_KEYWORDS_RE.test(ruleBodyText)) {
+    if (!NORMATIVE_KEYWORDS_RE.test(ruleBodyTextForEmphasis)) {
       errors.push(`Policy structured rule body must contain normative language (MUST/SHOULD/MAY) in "${number}-${title}": ${toDisplayPath(filePath)} [_core-adr-policy-008.03-rule-body-must-use-normative-language]`);
     }
 

package/lib/lint.test.js

@@ -2709,6 +2709,33 @@ test('reports structured rule block body missing normative language', () => {
   expect(result.errors.join('\n')).toContain('[_core-adr-policy-008.03-rule-body-must-use-normative-language]');
 });
 
+test('reports structured rule block body with normative language only inside a code block', () => {
+  const workspaceRoot = createWorkspace('structured-rule-normative-in-code-block', {
+    '.xdrs/index.md': rootIndex(),
+    '.xdrs/_local/adrs/index.md': localAdrIndex([
+      '- [001-main](principles/001-main.md) - Main decision'
+    ]),
+    '.xdrs/_local/adrs/principles/001-main.md': xdrDocument([
+      '### Details',
+      '',
+      '#### 01-my-rule',
+      '',
+      'Here is an example:',
+      '',
+      '```',
+      'You MUST do this.',
+      '```',
+      '',
+      'No normative language in prose.',
+    ].join('\n')),
+  });
+
+  const result = lintWorkspace(workspaceRoot);
+
+  expect(result.errors.join('\n')).toContain('structured rule body must contain normative language');
+  expect(result.errors.join('\n')).toContain('[_core-adr-policy-008.03-rule-body-must-use-normative-language]');
+});
+
 test('accepts valid structured rule blocks', () => {
   const workspaceRoot = createWorkspace('structured-rule-valid', {
     '.xdrs/index.md': rootIndex(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xdrs-core",
-  "version": "0.38.3",
+  "version": "0.39.0",
   "description": "A framework to structure, compile and distribute Architectural (ADR), Business (BDR), and Engineering (EDR) decision records contents so that AI agents and humans can reliably find and use them with hierarchical scopes and controlled rollout in the format of distributable versioned packages.",
   "repository": {
     "type": "git",