PUBLIC_MAINTENANCE_MODEL.json

{
  "version": "0.2.0",
  "reviewed_at": "2026-03-29",
  "primary_maintainer": "egor-n1",
  "supported_channels": [
    "GitHub issues for public bugs, docs gaps, integration questions, and contract change proposals.",
    "Pull requests for bounded public-surface edits to docs, schemas, examples, and machine-readable release artifacts.",
    "Private security reporting through SECURITY.md for trust-sensitive disclosures."
  ],
  "change_classes": [
    {
      "id": "docs-and-guides",
      "summary": "Documentation and orientation changes should keep front-door and reviewer paths coherent.",
      "strongest_surfaces": [
        "README.md",
        "QUICKSTART.md",
        "docs/reviewer-guide.md",
        "docs/public-contract-index.md"
      ],
      "verify_commands": [
        "npm run check:docs",
        "npm run check:surface",
        "npm run check:maintenance-model"
      ]
    },
    {
      "id": "schemas-and-openapi",
      "summary": "Schema or OpenAPI changes require aligned examples and explicit verification evidence.",
      "strongest_surfaces": [
        "schemas/capsule-schema.json",
        "schemas/validator-api-envelopes.schema.json",
        "openapi/validate.openapi.json",
        "docs/api-envelopes.md"
      ],
      "verify_commands": [
        "npm run check:api-schemas",
        "npm run check:catalog",
        "npm run check:maintenance-model"
      ]
    },
    {
      "id": "examples-and-negative-paths",
      "summary": "Example changes should preserve public-safe fixtures, negative-path coverage, and route-level alignment.",
      "strongest_surfaces": [
        "docs/examples.md",
        "PUBLIC_EXAMPLE_COVERAGE.json",
        "PUBLIC_FAILURE_MODEL.json",
        "docs/route-reference.md"
      ],
      "verify_commands": [
        "npm run check:examples",
        "npm run check:api-examples",
        "npm run check:example-coverage",
        "npm run check:maintenance-model"
      ]
    },
    {
      "id": "release-and-provenance-surfaces",
      "summary": "Release-facing changes must keep provenance, catalog, release metadata, and release review synchronized.",
      "strongest_surfaces": [
        "SOURCE_MANIFEST.json",
        "PUBLIC_CONTRACT_CATALOG.json",
        "PUBLIC_RELEASE_METADATA.json",
        "PUBLIC_RELEASE_REVIEW.md",
        "PUBLIC_CHANGE_CONTROL_MODEL.json",
        "PUBLIC_UPDATE_COHERENCE_MAP.json",
        "PUBLIC_LIMITATIONS_REGISTER.json",
        "PUBLIC_EVIDENCE_TIMELINE.json",
        "PUBLIC_REVIEW_SCORECARD.json",
        "PUBLIC_VERIFICATION_MATRIX.json"
      ],
      "verify_commands": [
        "npm run audit:public-surface",
        "npm run check:catalog",
        "npm run check:release",
        "npm run check:maintenance-model",
        "npm run check:change-control"
      ]
    },
    {
      "id": "community-and-intake-surfaces",
      "summary": "Contributor-facing changes must preserve issue intake, security routing, maintainer posture, and release discipline.",
      "strongest_surfaces": [
        "MAINTAINERS.md",
        "CONTRIBUTING.md",
        "docs/community-health.md",
        "docs/github-operations.md",
        ".github/labels.json",
        ".github/milestones.json",
        "docs/maintainer-operations.md",
        "docs/repo-validation-workflow.md"
      ],
      "verify_commands": [
        "npm run check:community-health",
        "npm run check:github-operations",
        "npm run check:maintenance-model"
      ]
    }
  ],
  "required_evidence": [
    "npm run verify:repo",
    "updated release-facing artifacts when the public surface changes",
    "upstream validator rechecks for example changes where applicable",
    "updated PUBLIC_CHANGE_CONTROL_MODEL.json when public change posture changed",
    "updated PUBLIC_UPDATE_COHERENCE_MAP.json when public sync groups changed",
    "updated PUBLIC_LIMITATIONS_REGISTER.json when deferred scope or public non-promises changed",
    "updated PUBLIC_EVIDENCE_TIMELINE.json when public hardening milestones or reviewer-facing maintenance history changed",
    "updated PUBLIC_REVIEW_SCORECARD.json when reviewer-facing maturity criteria or strongest public evidence changed",
    "updated PUBLIC_VERIFICATION_MATRIX.json when repo-local check coverage or protected public surfaces changed",
    "updated PUBLIC_AUDIENCE_PATHS.json when role-specific entry paths or public audience expectations changed",
    "updated PUBLIC_EVIDENCE_STRENGTH_MAP.json when stronger-source hierarchy changed across public surfaces",
    "updated PUBLIC_ADOPTION_READINESS.json when audience readiness, prerequisites, or deferred adoption posture changed",
    "updated PUBLIC_FRESHNESS_MODEL.json when freshness triggers or stale signals changed",
    "updated PUBLIC_ECOSYSTEM_VALUE_MAP.json when external value posture or beneficiary-facing utility changed",
    "updated PUBLIC_DECISION_LOG.json when public design rationale, projection intent, or trust-sensitive public decisions changed",
    "updated PUBLIC_EVIDENCE_GAPS_REGISTER.json when a public evidence gap, manual-review boundary, or maturity caveat changed materially",
    "updated .github/labels.json and .github/milestones.json when the maintained GitHub issue surface changed materially",
    "follow docs/repo-validation-workflow.md for bounded repo-only changes before the final full-stack pass"
  ],
  "operating_rules": [
    "Keep the public boundary intentional and do not widen scope by accident.",
    "Prefer small, reviewable changes over oversized public dumps.",
    "Treat main as the stable public branch and dream as the public exploration branch for larger still-public work.",
    "Do not treat dream as a private vault or as a bypass around public-boundary, provenance, or verification rules.",
    "Keep SOURCE_MANIFEST.json and PUBLIC_CONTRACT_CATALOG.json aligned with new or changed public artifacts.",
    "Require explicit verification evidence when schemas, examples, OpenAPI, or release surfaces change.",
    "Route trust-sensitive disclosures through SECURITY.md instead of public issue intake.",
    "Keep PUBLIC_UPDATE_COHERENCE_MAP.json aligned with release, reviewer, contract, and teaching surfaces when co-moving groups change.",
    "Keep PUBLIC_LIMITATIONS_REGISTER.json aligned with boundary docs, scope docs, reviewer paths, and release evidence when public limits change.",
    "Keep PUBLIC_EVIDENCE_TIMELINE.json aligned with CHANGELOG.md, reviewer docs, and release evidence when the bounded public hardening history changes.",
    "Keep PUBLIC_REVIEW_SCORECARD.json aligned with reviewer docs, release evidence, limitations, and the strongest criteria evidence it summarizes.",
    "Keep PUBLIC_VERIFICATION_MATRIX.json aligned with the real check stack, release evidence, and reviewer-facing verification docs.",
    "Keep PUBLIC_AUDIENCE_PATHS.json aligned with onboarding, reviewer, contributor, integration, and maintainer-facing docs.",
    "Keep PUBLIC_EVIDENCE_STRENGTH_MAP.json aligned with trust-model, compatibility, reviewer, and release-evidence surfaces.",
    "Keep PUBLIC_ADOPTION_READINESS.json aligned with audience paths, limitations, release evidence, and maintainer-facing docs when bounded public readiness changes.",
    "Keep PUBLIC_FRESHNESS_MODEL.json aligned with release evidence, reviewer shortcuts, audience paths, and adoption summaries when freshness posture changes.",
    "Keep PUBLIC_ECOSYSTEM_VALUE_MAP.json aligned with reviewer docs, capability summaries, adoption posture, and release evidence when external utility claims change.",
    "Keep PUBLIC_DECISION_LOG.json aligned with boundary posture, trust-model docs, assurance posture, and release evidence when public design rationale changes.",
    "Keep PUBLIC_EVIDENCE_GAPS_REGISTER.json aligned with release evidence, adoption posture, freshness, ecosystem-value posture, and limitations when public proof gaps or manual-review boundaries change.",
    "Keep .github/labels.json, .github/milestones.json, docs/github-operations.md, and issue-template labels aligned when the maintained GitHub issue surface changes.",
    "Keep docs/repo-validation-workflow.md aligned with CONTRIBUTING.md, docs/community-health.md, docs/verification.md, and the actual repo-local check stack."
  ],
  "non_claims": [
    "This file does not promise a guaranteed response-time SLA for public issues or pull requests.",
    "This file does not expose private internal workflow details from the upstream N1Hub runtime.",
    "This file does not treat the public dream branch as a private maintainer surface."
  ],
  "review_commands": [
    "npm run check:maintenance-model",
    "npm run verify:repo"
  ]
}