@precepts/standards 0.1.0

package/LICENSE

@@ -0,0 +1,30 @@
+Attribution-ShareAlike 4.0 International (CC BY-SA 4.0)
+
+Copyright (c) 2026 Precepts Contributors
+
+This license applies to all standards content and schema files in this repository.
+
+You are free to:
+
+  Share - copy and redistribute the material in any medium or format for
+  any purpose, including commercially.
+
+  Adapt - remix, transform, and build upon the material for any purpose,
+  including commercially.
+
+Under the following terms:
+
+  Attribution - You must give appropriate credit, provide a link to the
+  license, and indicate if changes were made. You may do so in any
+  reasonable manner, but not in any way that suggests the licensor
+  endorses you or your use.
+
+  ShareAlike - If you remix, transform, or build upon the material, you
+  must distribute your contributions under the same license as the
+  original.
+
+  No additional restrictions - You may not apply legal terms or
+  technological measures that legally restrict others from doing anything
+  the license permits.
+
+Full license text: https://creativecommons.org/licenses/by-sa/4.0/legalcode

package/README.md

@@ -0,0 +1,115 @@
+# Precepts Standards
+
+Built for humans. Ready for agents.
+
+The canonical source of multi-discipline standards for the [Precepts](https://precepts.dev) platform. Standards are published as machine-readable Markdown with YAML frontmatter, consumable by both humans and AI agents.
+
+## Install
+
+```bash
+npm install @precepts/standards
+```
+
+## Usage
+
+Standards are plain Markdown files with structured YAML frontmatter. Consume them however you need:
+
+```javascript
+import { readFileSync } from 'fs';
+import matter from 'gray-matter';
+
+// Read a standard
+const raw = readFileSync(
+  'node_modules/@precepts/standards/standards/integration/standards/api/resource-design.md',
+  'utf-8'
+);
+const { data, content } = matter(raw);
+
+console.log(data.identifier); // "INTG-STD-008"
+console.log(data.status);     // "MANDATORY"
+console.log(data.domain);     // "INTEGRATION"
+```
+
+## Disciplines
+
+| Discipline | Prefix | Directory |
+|---|---|---|
+| Integration | `INTG` | `standards/integration/` |
+| Product Management | `PRD` | `standards/product/` |
+| UX | `UX` | `standards/ux/` |
+| Project Management | `PRJ` | `standards/project-management/` |
+
+## Integration Standards (Batch 1)
+
+| Identifier | Name | Status |
+|---|---|---|
+| INTG-STD-004 | Naming Conventions | MANDATORY |
+| INTG-STD-005 | Character Encoding | MANDATORY |
+| INTG-STD-006 | Backward and Forward Compatibility | MANDATORY |
+| INTG-STD-008 | API Resource Design | MANDATORY |
+| INTG-STD-009 | API Error Handling | MANDATORY |
+| INTG-STD-015 | Event Envelope (CloudEvents) | MANDATORY |
+| INTG-STD-029 | Observability | MANDATORY |
+| INTG-STD-033 | Resilience Patterns | MANDATORY |
+| INTG-STD-034 | Retry Policy | MANDATORY |
+| INTG-STD-035 | Timeout | MANDATORY |
+
+## Standards Schema
+
+Each standard has YAML frontmatter validated against `schema/standards.schema.json`:
+
+```yaml
+---
+identifier: INTG-STD-008
+name: API Resource Design
+version: 1.0.0
+status: MANDATORY
+domain: INTEGRATION
+documentType: standard
+category: protocol
+---
+```
+
+**Required fields:** `identifier`, `name`, `version`, `status`, `domain`, `documentType`
+
+**Identifier pattern:** `[INTG|PRD|PRJ|UX|SEC]-[STD|GDL|GOV|BP]-NNN`
+
+**Status values:** `DRAFT`, `MANDATORY`, `RECOMMENDED`, `DEPRECATED`
+
+## Content Conventions
+
+- `## Rules` for prescriptive instructions (not "Requirements")
+- RFC 2119 keywords (**MUST**, **SHOULD**, **MAY**) bolded throughout
+- Rule numbering: `### R-N: Title` as H3 headings
+- Concept-level examples (pseudocode), not technology-specific
+- 200-300 lines per standard
+
+## Validation
+
+```bash
+npm run validate          # check frontmatter + required sections
+npm run validate:strict   # warnings become errors
+```
+
+## Ecosystem
+
+This package is consumed by:
+
+- **[precepts-dev/platform](https://github.com/precepts-dev/platform)** - Docusaurus site, MCP server, validator
+- **precepts-dev/engine** - Commercial compliance scanning engine (private)
+- **Your tools** - build anything on top of these standards
+
+## Contributing
+
+Standards proposals and revisions are welcome. Each standard follows the template in `schema/document-standard-template.md`.
+
+1. Fork this repo
+2. Create a new standard or modify an existing one
+3. Run `npm run validate` to check your changes
+4. Open a PR
+
+## License
+
+CC BY-SA 4.0 - see [LICENSE](LICENSE) for details.
+
+All standards are freely usable by individuals, companies, and AI tools, with attribution and share-alike.

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@precepts/standards",
+  "version": "0.1.0",
+  "description": "Multi-discipline standards for software teams - machine-readable, AI-native, human-friendly",
+  "license": "CC-BY-SA-4.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/precepts-dev/standards.git"
+  },
+  "homepage": "https://precepts.dev",
+  "keywords": [
+    "standards",
+    "integration",
+    "product-management",
+    "ux",
+    "project-management",
+    "ai-native",
+    "mcp",
+    "llm"
+  ],
+  "files": [
+    "standards/",
+    "schema/",
+    "LICENSE"
+  ],
+  "main": "standards/",
+  "exports": {
+    "./standards": "./standards/",
+    "./schema": "./schema/",
+    "./schema/standards.schema.json": "./schema/standards.schema.json"
+  },
+  "scripts": {
+    "validate": "npx tsx tools/validate.ts --docs-root ./standards",
+    "validate:strict": "npx tsx tools/validate.ts --docs-root ./standards --strict"
+  },
+  "devDependencies": {
+    "gray-matter": "^4.0.3",
+    "tsx": "^4.19.0"
+  }
+}

package/schema/document-standard-template.md

@@ -0,0 +1,139 @@
+---
+# ┌──────────────────────────────────────────────────────────────────┐
+# │  PRECEPTS - Universal Standard/Guideline Template               │
+# │                                                                  │
+# │  Instructions:                                                   │
+# │  1. Copy this file as a starting point for your new document     │
+# │  2. Replace placeholder values (marked with <angle brackets>)    │
+# │  3. Pick ONE value from pipe-delimited options (a | b | c)       │
+# │  4. Delete inline comments once you've filled in the fields      │
+# │  5. Include all REQUIRED body sections; omit optional ones       │
+# │     that don't apply to your domain                              │
+# └──────────────────────────────────────────────────────────────────┘
+
+# ── Identity (required) ──────────────────────────────────────────
+identifier: "<PREFIX>-<TYPE>-<NNN>"
+  # Prefix: INTG | PRD | PRJ | UX | SEC
+  # Type:   STD (standard) | GDL (guideline) | GOV (governance) | BP (best practice)
+  # Number: zero-padded 3-digit (e.g., 001)
+  # Examples: INTG-STD-001, UX-GDL-003, PRJ-GOV-001
+
+name: "<Document Title>"
+version: "1.0.0"  # semver: patch = typo, minor = new fields/status change, major = breaking
+status: "DRAFT"   # DRAFT | MANDATORY | RECOMMENDED | DEPRECATED
+
+# ── Classification (required) ────────────────────────────────────
+domain: "<DOMAIN>"
+  # Pick one: INTEGRATION | PRODUCT-MANAGEMENT | PROJECT-MANAGEMENT | UX | SECURITY
+
+documentType: "<TYPE>"
+  # Pick one: standard | guideline | governance | best-practice
+
+category: "<CATEGORY>"
+  # Pick one or more (comma-separated in a list):
+  #   Universal:    governance, security, reliability, naming, versioning, observability
+  #   Integration:  format, protocol, data-modeling, error-handling
+  #   Product:      process, methodology, decision-framework
+  #   PM:           process, ceremony, methodology
+  #   UX:           accessibility, design-system, interaction, content
+
+# ── Applicability (recommended) ──────────────────────────────────
+appliesTo: []
+  # Domain-scoped values - pick from YOUR domain's vocabulary:
+  #   Integration:  api, events, a2a, files, mcp, webhooks, grpc, graphql, batch, streaming
+  #   Product:      prd, roadmap, user-story, okr, epic, spike
+  #   PM:           ceremony, estimation, risk, reporting, artifact, workflow
+  #   UX:           web, ios, android, design-tokens, component-library, content
+
+# ── Ownership ────────────────────────────────────────────────────
+lastUpdated: "YYYY-MM-DD"
+owner: "<Governing Body>"
+  # Examples: Integration Architecture Board, Product Council, UX Design Authority
+
+# ── Compliance References ────────────────────────────────────────
+standardsCompliance:
+  iso: []    # e.g., ["ISO-8601", "ISO-9241"]
+  rfc: []    # e.g., ["RFC-3339", "RFC-9557"]
+  w3c: []    # e.g., ["WCAG-2.2", "WAI-ARIA-1.2"]
+  other: []  # e.g., ["PMBOK-7", "SAFe-6.0", "OWASP-Top-10"]
+
+# ── Taxonomy ─────────────────────────────────────────────────────
+taxonomy:
+  capability: ""       # e.g., "data-format", "authentication", "estimation"
+  subCapability: ""    # e.g., "date-time", "oauth2", "story-points"
+  layer: ""
+    # Domain-scoped values:
+    #   Integration:  contract | transport | semantic | infrastructure
+    #   Product:      strategy | process | artifact | metric
+    #   PM:           governance | ceremony | artifact | metric
+    #   UX:           visual | interaction | content | information-architecture
+
+# ── Enforcement ──────────────────────────────────────────────────
+enforcement:
+  method: ""
+    # Pick one: automated | review-based | stage-gate | hybrid
+  # For automated enforcement (primarily Integration):
+  validationRules: {}
+  rejectionCriteria: []
+  supportedFormats: []
+  authoritativeModel: ""
+  # For human-review enforcement (primarily PM/Product/UX):
+  reviewChecklist: []
+
+# ── Relationships ────────────────────────────────────────────────
+dependsOn: []      # Identifiers this document depends on, e.g., ["INTG-STD-001"]
+supersedes: ""     # Identifier this document replaces, e.g., "INTG-STD-001"
+
+---
+
+# <Document Title>
+
+<!-- The identifier, version, status, domain, and documentType are rendered
+     automatically from frontmatter as a metadata bar above the content.
+     Do NOT duplicate the identifier in the body. -->
+
+## Purpose
+
+<!-- REQUIRED - All domains. Why does this standard/guideline exist? What problem does it solve? -->
+
+## Rules
+
+<!-- REQUIRED - All domains. Use RFC 2119 language (MUST, SHOULD, MAY) to state prescriptive instructions about what is allowed or prohibited. -->
+
+## Examples
+
+<!-- REQUIRED - All domains. Show concrete valid/invalid examples. Use code blocks, tables, or diagrams. -->
+
+## Allowed Representations
+
+<!-- OPTIONAL - Primarily Integration. Define acceptable serialization formats, encodings, or structural variants. -->
+
+## Validation Rules
+
+<!-- OPTIONAL - Primarily Integration, Security. Machine-checkable rules: regex patterns, schema constraints, linting rules. -->
+
+## Enforcement Rules
+
+<!-- OPTIONAL - Primarily Integration, Security. What must be rejected? At what boundary? -->
+
+## Roles & Responsibilities
+
+<!-- OPTIONAL - Primarily PM, Product. Define who does what (RACI or similar). -->
+
+## Accessibility
+
+<!-- OPTIONAL - Primarily UX. WCAG criteria, ARIA requirements, assistive technology behavior. -->
+
+## References
+
+<!-- REQUIRED - All domains. Links to external specifications, tools, and related resources. -->
+
+## Rationale
+
+<!-- REQUIRED - All domains. Why were these specific choices made? What alternatives were considered? -->
+
+## Version History
+
+| Version | Date       | Change             |
+| ------- | ---------- | ------------------ |
+| 1.0.0   | YYYY-MM-DD | Initial definition |

package/schema/standards.schema.json

@@ -0,0 +1,154 @@
+{
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "title": "Precepts Standard Metadata",
+    "description": "Schema for validating frontmatter in Precepts standards, guidelines, and governance documents.",
+    "type": "object",
+    "required": [
+        "identifier",
+        "name",
+        "version",
+        "status",
+        "domain",
+        "documentType"
+    ],
+    "properties": {
+        "identifier": {
+            "type": "string",
+            "pattern": "^(INTG|PRD|PRJ|UX|SEC)-(STD|GDL|GOV|BP)-\\d{3}$",
+            "description": "Unique document identifier: <PREFIX>-<TYPE>-<NNN>"
+        },
+        "name": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Human-readable document title"
+        },
+        "version": {
+            "type": "string",
+            "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$",
+            "description": "Semantic version (major.minor.patch)"
+        },
+        "status": {
+            "type": "string",
+            "enum": ["DRAFT", "MANDATORY", "RECOMMENDED", "DEPRECATED"],
+            "description": "Lifecycle status of the document"
+        },
+        "domain": {
+            "type": "string",
+            "enum": ["INTEGRATION", "PRODUCT-MANAGEMENT", "PROJECT-MANAGEMENT", "UX", "SECURITY"],
+            "description": "Discipline this document belongs to"
+        },
+        "documentType": {
+            "type": "string",
+            "enum": ["standard", "guideline", "governance", "best-practice"],
+            "description": "Type of document - controls which body sections are required"
+        },
+        "category": {
+            "type": "string",
+            "description": "Primary category (e.g., format, process, accessibility, governance)"
+        },
+        "appliesTo": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "Domain-scoped applicability targets (e.g., api, ceremony, web)"
+        },
+        "lastUpdated": {
+            "type": "string",
+            "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$",
+            "description": "Last modification date (YYYY-MM-DD)"
+        },
+        "owner": {
+            "type": "string",
+            "description": "Governing body or team responsible for this document"
+        },
+        "standardsCompliance": {
+            "type": "object",
+            "properties": {
+                "iso": {
+                    "type": "array",
+                    "items": { "type": "string" }
+                },
+                "rfc": {
+                    "type": "array",
+                    "items": { "type": "string" }
+                },
+                "w3c": {
+                    "type": "array",
+                    "items": { "type": "string" }
+                },
+                "other": {
+                    "type": "array",
+                    "items": { "type": "string" }
+                }
+            },
+            "additionalProperties": false
+        },
+        "taxonomy": {
+            "type": "object",
+            "required": ["capability", "layer"],
+            "properties": {
+                "capability": {
+                    "type": "string",
+                    "description": "Primary capability area (e.g., data-format, authentication, estimation)"
+                },
+                "subCapability": {
+                    "type": "string",
+                    "description": "Sub-capability (e.g., date-time, oauth2, story-points)"
+                },
+                "layer": {
+                    "type": "string",
+                    "description": "Domain-scoped layer (e.g., contract, process, visual, governance)"
+                }
+            },
+            "additionalProperties": false
+        },
+        "enforcement": {
+            "type": "object",
+            "properties": {
+                "method": {
+                    "type": "string",
+                    "enum": ["automated", "review-based", "stage-gate", "hybrid"],
+                    "description": "How compliance is verified"
+                },
+                "validationRules": {
+                    "type": "object",
+                    "description": "Machine-checkable validation rules (primarily for automated enforcement)"
+                },
+                "rejectionCriteria": {
+                    "type": "array",
+                    "items": { "type": "string" },
+                    "description": "Conditions that cause rejection"
+                },
+                "supportedFormats": {
+                    "type": "array",
+                    "items": { "type": "string" },
+                    "description": "Accepted format identifiers"
+                },
+                "authoritativeModel": {
+                    "type": "string",
+                    "description": "Canonical model or source of truth"
+                },
+                "reviewChecklist": {
+                    "type": "array",
+                    "items": { "type": "string" },
+                    "description": "Human-review checklist items (primarily for review-based enforcement)"
+                }
+            },
+            "additionalProperties": true
+        },
+        "dependsOn": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "Identifiers of standards this document depends on"
+        },
+        "supersedes": {
+            "type": "string",
+            "description": "Identifier of the document this one replaces"
+        },
+        "classifications": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "Sub-classifications within the standard (e.g., ABSOLUTE, SCHEDULED)"
+        }
+    },
+    "additionalProperties": true
+}

package/standards/integration/governance/_category_.json

@@ -0,0 +1 @@
+{"label": "Governance", "position": 2}

package/standards/integration/governance/integration-styles.md

@@ -0,0 +1,56 @@
+---
+identifier: "INTG-GOV-001"
+name: "Integration Styles"
+version: "1.0.0"
+status: "DRAFT"
+
+domain: "INTEGRATION"
+documentType: "governance"
+category: "governance"
+appliesTo: ["api", "events", "a2a", "files", "mcp"]
+
+lastUpdated: "2026-02-17"
+owner: "Integration Architecture Board"
+
+standardsCompliance:
+  iso: []
+  rfc: []
+  w3c: []
+  other: []
+
+taxonomy:
+  capability: "integration-patterns"
+  subCapability: ""
+  layer: "infrastructure"
+
+enforcement:
+  method: "review-based"
+  reviewChecklist: []
+
+dependsOn: []
+supersedes: ""
+---
+
+# Integration Styles
+
+## Purpose
+
+## Conceptual Model
+
+## Rules
+
+## Examples
+
+## Allowed Representations
+
+## Enforcement Rules
+
+## References
+
+## Rationale
+
+## Version History
+
+| Version | Date       | Change             |
+| ------- | ---------- | ------------------ |
+| 1.0.0   | 2026-02-17 | Initial definition |

package/standards/integration/index.md

@@ -0,0 +1,9 @@
+---
+sidebar_position: 1
+---
+
+# Integration Standards
+
+This section contains integration standards, guidelines, and governance documents for the Precepts platform.
+
+Standards in this discipline cover API design, event-driven architecture, data formats, resilience patterns, observability, versioning, and cross-cutting concerns. All standards are backed by ISO, IEEE, RFC and other industry specifications.

package/standards/integration/standards/_category_.json

@@ -0,0 +1 @@
+{"label": "Standards", "position": 1}

package/standards/integration/standards/api/_category_.json

@@ -0,0 +1 @@
+{"label": "API", "position": 3}