{
  "id": "page:library-composition-open-source-data-validation",
  "_kind": "Page",
  "_file": "wiki/library/composition-open-source-data-validation.md",
  "_cluster": "wiki",
  "attributes": {
    "nodeKind": "Page",
    "title": "Composition: Open Source Data-Validation Framework (TDD + BDD + Kanban + XP + Continuous Deployment) (Library)",
    "displayName": "Composition: Open Source Data-Validation Framework (TDD + BDD + Kanban + XP + Continuous Deployment) (Library)",
    "slug": "library/composition-open-source-data-validation",
    "articlePath": "wiki/library/composition-open-source-data-validation.md",
    "article": "\n# Composition: Open Source Data-Validation Framework (TDD + BDD + Kanban + XP + Continuous Deployment)\n\nImplements methodology backlog **Example 7** (community-driven, greenfield data-validation\nlibrary). See `../backlog.md` (~line 2291): \"Open Source Library — Data Validation Framework\"\n(previously **📝 Not Implemented**). Completes all seven backlog compositions.\n\n## Why this composition\n\nA public, community-driven validation library has to reconcile five concerns at once: community\ndemand, executable acceptance, test-first correctness, contributor flow, and safe releases.\n\n| Methodology | What it contributes | Seam artifact |\n|-------------|---------------------|---------------|\n| **BDD (Specification by Example)** | Gherkin acceptance scenarios per validation behavior (valid + invalid + explicit error message), one `.feature` per rule | the **scenario set** |\n| **TDD** | Each rule implemented red-green-refactor directly from its scenarios; every test annotated with its `scenarioId` | the **rule -> scenario -> test map** |\n| **Kanban** | Community contribution flow: Backlog -> In Progress -> Review -> Done, labels (`bug`/`feature`/`documentation`/`good-first-issue`), **no WIP limit** (contributor availability is bursty) | the **board + flow metrics** |\n| **XP** | Collective ownership, coding standards (lint/format), simple design, continuous integration, small releases | the **CI-green merge candidate** |\n| **Continuous Deployment** | Stage-promoted pipeline to a public package registry, dry-run first | the **verified pipeline** |\n\nThe seam this composition exists to encode: **community signals -> RFC -> BDD scenarios ->\nTDD/XP implementation on a Kanban board -> executed suite -> CD pipeline -> versioned release ->\ncommunity announcement.**\n\n## Inline Continuous Deployment (no `continuous-deployment/` dir)\n\nThere is **no** `library/methodologies/continuous-deployment/` directory. Per the batch-3\n**strangler-fig inline-ingredient precedent** (`../composition-legacy-modernization/` models the\nStrangler Fig cutover inline via `clm.cutover.*` rather than importing a nonexistent dir), the\nContinuous Deployment ingredient is modeled **inline** here: a frozen ordered `PIPELINE_STAGES`\nlist borrowing the **stage-promotion** semantics of\n[`../../specializations/release-engineering/release-lifecycle.js`](../../specializations/release-engineering/release-lifecycle.js)\n(frozen ordered stages, entry-gated promotion, executed per-stage verification). The module\n**never references a nonexistent `continuous-deployment` path and never falls back.**\n\nFrozen stages (a `pipelineStagesOverride` must be a strict **prefix-ordered subset**; an unknown\nstage **throws**):\n\n```\nci -> build -> publish-dry-run -> docs-deploy-dry-run\n```\n\n`publish-dry-run` packs the tarball and resolves the version **without** a real publish — the\nreal publish is the separate policy-gated `cod.package-publish` executor, never a pipeline stage.\nInternal stage promotions are orchestrator-driven; the only human policy gates are the three\nbelow.\n\n## Phase chain (P0..P9)\n\n```\nP0 kip recall (methodology-composition)\nP1 cod.requirements-intake -> cod.rfc-authoring                         (community RFC)\nP2 ctx.parallel: cod.bdd-scenario-authoring per rule                    -> GATE cod.bdd-scenarios\nP3 ctx.parallel: cod.contribution-triage + cod.tdd-implement-rule       (Kanban + TDD/XP)\n   -> cod.ci-check (aggregate) -> parallel cod.contribution-review\nP4 cod.test-suite-execution (executes both suites)                      -> GATE cod.executed-suite\nP5 iterate PIPELINE_STAGES -> cod.cd-pipeline-stage; cod.semver-analysis-> GATE cod.cd-readiness\nP6 [bump==major] routedBreakpoint breaking-change-release (reject=>stop)\n   -> routedBreakpoint package-publish-approval -> cod.package-publish   (guarded)\nP7 cod.changelog-generation                                            (changelog + living docs)\nP8 cod.release-announcement-draft -> routedBreakpoint community-announcement-send\n   -> cod.announcement-send                                             (guarded)\nP9 cod.retrospective -> kip assert (composition-seam + open-source-release facts)\n```\n\n## Policy-gated actions\n\n| Action / `breakpointId` | Expert | When raised | Executor guard |\n|-------------------------|--------|-------------|----------------|\n| `breaking-change-release` | `project-maintainer` | **only** when `semver.bump === 'major'` | rejection blocks the publish path entirely (explicit stop) |\n| `package-publish-approval` | `project-maintainer` | after cd-readiness gate passed and (`bump !== 'major'` or breaking-change approved) | `cod.package-publish` runs ONLY inside `if (approved === true)` |\n| `community-announcement-send` | `community-manager` | after a successful publish | `cod.announcement-send` runs ONLY inside `if (approved === true)` |\n\nAll three are raised via `routedBreakpoint` with `breakpointId = actionId`, tags\n`['policy-gated', 'cod', <phase-tag>]`, strategy `single`, and **no** `autoApproveAfterN` — the\nprocess never auto-approves a policy gate. Provenance\n`{ approved, autoApproved, breakpointId, expert, response }` is always recorded (`autoApproved`\nreflects `response?.autoApproved === true` set by an external rule — a fail-closed surfacing).\nReady for `adapters/policy` YAML gating on the `policy-gated` tag.\n\n## Executed-evidence gate contract\n\nThree adversarial seam gates (via `adversarialGate`) **re-execute** their artifacts — they never\nread-only review:\n\n| Gate `gateId` | Seam | Critics re-execute |\n|---------------|------|--------------------|\n| `cod.bdd-scenarios` | requirements -> BDD | parse/dry-run every `.feature`; every rule needs >=1 valid + >=1 invalid scenario |\n| `cod.executed-suite` | BDD/TDD/XP -> CD | re-run BOTH suites; every rule maps to an EXECUTED passing test; a skipped/todo mapping is a FAIL |\n| `cod.cd-readiness` | CD pipeline -> release | run a full pipeline dry-run + re-derive the semver bump from the actual API diff |\n\nEach gate's critics are independent agents fanned out in parallel by the combinator (none is the\nproducing agent, none sees another's verdict); evidence is mandatory (a `passed:true` with empty\nevidence is coerced to a protocol failure); a bounded fix loop (`maxFixAttempts`, built-in fixer)\nruns between rounds; exhaustion escalates via the combinator-owned `<gateId>.gate-escalation`\nbreakpoint to `owner`. Any failed gate returns `success: false` and stops the chain before the\nnext phase.\n\n## Inputs\n\n```\n{\n  libraryName: string (required),\n  libraryDescription: string (required),\n  validationRules?: [{ ruleId, title, description, priority?, votes?, parallelSafe?, dependsOn? }],\n  communitySignals?: string,        // at least one of validationRules / communitySignals required\n  contributions?: [{ contributionId, kind: 'feature'|'bug'|'documentation', ruleRef?, summary, parallelSafe?, dependsOn? }],\n  currentVersion?: string (default '0.0.0'),\n  registry?: string (default 'npm'),\n  pipelineStagesOverride?: string[]|null (default null — strict prefix-ordered subset; unknown stage THROWS),\n  maxFixAttempts?: number (default 2),\n  kipEnabled?: boolean (default true),\n  kipDir?: string (default '.a5c/kip'),\n  kipModel?: string (default 'sonnet')\n}\n```\n\n## Outputs\n\n```\n{\n  success: boolean,               // true iff every gate passed AND (bump!='major' || breaking approved)\n                                  //   AND publish approved AND published === true\n  rfc: { rfcPath, prioritizedRules, accepted },\n  scenarios: [{ ruleId, featurePath, scenarioCount }],\n  bddGate: { passed, attempts, escalated, issues, evidence },\n  board: { columns, cards: [{ contributionId, column, labels }], flowMetrics },\n  implementations: [{ ruleId, summary, filesChanged, scenarioTestMap }],\n  reviews: [{ contributionId, approved, reviewer, findings }],\n  suiteGate: { passed, attempts, escalated, issues, evidence },\n  cdPipeline: { stages: [{ stage, gate, verified, dryRun, evidenceRef }], readinessGate },\n  semver: { bump, breaking, apiDiffPath, rationale },\n  breakingChange: { raised, approved, autoApproved, breakpointId, expert, response } | null,\n  publish: { approved, autoApproved, breakpointId, expert, published, version, registry, artifacts, response },\n  release: { changelogPath, docsPath, version, livingDocs },\n  announcement: { approved, autoApproved, breakpointId, expert, sent, channels, response } | null,\n  retro: { wentWell, couldImprove, actions },\n  kipFactsAsserted: number,\n  artifacts: array,\n  metadata: { processId, runId, breakpointsHit, pipeline: { stages, dryRun: true } }\n}\n```\n\n## Parallelism\n\n- **P2**: `ctx.parallel.all` authors BDD scenarios concurrently, one thunk per prioritized rule.\n- **P3**: a single `ctx.parallel.all` fans out contribution triage **and** the `parallelSafe`\n  rule implementations concurrently; dependent rules are then awaited in `dependsOn` order\n  (`orderByDependencies`, cycle **throws**) — never speculatively co-scheduled. Contribution\n  reviews run in parallel afterward (they depend on triaged contributions).\n- **P5**: pipeline stages are **sequential** — promotion requires the prior stage\n  `verified === true` (deliberately not parallel).\n\n## Usage\n\n```js\nconst result = await orchestrate('methodologies/composition-open-source-data-validation', {\n  libraryName: 'valides',\n  libraryDescription: 'A schema-first data validation framework for JavaScript',\n  communitySignals: 'Users want async validators and clearer error messages (#12, #34).',\n  currentVersion: '1.2.0',\n  contributions: [\n    { contributionId: 'PR-101', kind: 'feature', ruleRef: 'rule-async', summary: 'Async validator support' },\n  ],\n});\n```\n\n## Composed modules\n\n- [`../tdd.js`](../tdd.js) — red-green-refactor loop (a **file**, exporting only `process`; its\n  task constants are not exported, so this composition defines its own `cod.*` tasks mirroring\n  those phase semantics rather than importing constants)\n- [`../bdd-specification-by-example/`](../bdd-specification-by-example/) — discovery-workshop /\n  gherkin-formulation / execute-tests semantics\n- [`../kanban/`](../kanban/) — pull-system / flow-metrics semantics\n- [`../extreme-programming/`](../extreme-programming/) — continuous-integration / refactoring\n  semantics and the XP constraints\n- Continuous Deployment: **inline** (no `continuous-deployment/` dir), borrowing\n  [`../../specializations/release-engineering/release-lifecycle.js`](../../specializations/release-engineering/release-lifecycle.js)\n  stage-promotion semantics\n\nCombinators come from\n[`../../specializations/common-utilities/routed-gate-combinators.js`](../../specializations/common-utilities/routed-gate-combinators.js)\n(`routedBreakpoint`, `adversarialGate`, `kipRecall`, `kipAssert`).\n\n## Design rules honored\n\n- **No shell subtasks**: every `cod.*` task is `kind: 'agent'`; suite/lint/pipeline execution is\n  performed BY agents who paste executed output as evidence.\n- **No fallbacks**: invalid inputs throw; an unknown pipeline-stage override throws; a rule\n  dependency cycle throws; a malformed `currentVersion` throws; a failed gate, a rejected\n  breaking-change, and a rejected/failed publish each return an explicit `success: false` shape.\n- **Guarded executors**: `cod.package-publish` and `cod.announcement-send` run ONLY inside an\n  `approved === true` branch; the breaking-change gate is a hard precondition on publish when the\n  bump is major.\n- **Sparse breakpoints**: exactly the three policy gates plus combinator-owned gate escalations;\n  RFC acceptance and internal stage promotions are orchestrator decisions.\n- **kip symmetry**: recall at start, assert at end (`methodology-composition` kind), emitting the\n  required `open-source-release` facts.\n```\n",
    "documents": [
      "specialization:composition-open-source-data-validation"
    ]
  },
  "outgoingEdges": [
    {
      "from": "page:library-composition-open-source-data-validation",
      "to": "specialization:composition-open-source-data-validation",
      "kind": "documents"
    }
  ],
  "incomingEdges": [
    {
      "from": "page:index",
      "to": "page:library-composition-open-source-data-validation",
      "kind": "contains_page"
    }
  ]
}