Skip to content

Add initial operating standards structure#2

Draft
iperev wants to merge 11 commits into
mainfrom
feature/initial-operating-standards
Draft

Add initial operating standards structure#2
iperev wants to merge 11 commits into
mainfrom
feature/initial-operating-standards

Conversation

@iperev

@iperev iperev commented Jul 8, 2026

Copy link
Copy Markdown
Contributor

Summary

Adds the initial Agent Operating Standards kernel and refines the pull request description standard into an agent-first contract.

The core runtime rule is explicit: external agents load repository bindings, select the standards catalog entry, load the global agent operating kernel when adopted, then use the selected standard.yaml as the token-efficient task instruction when agent_entrypoint is present. standard.md remains the proof, rationale, and dispute surface.

Context

Agents need durable, versioned owner surfaces for artifact creation and review. Without a catalog, claim taxonomy, repository binding, machine entrypoint, kernel invariants, and artifact-specific standards, agents infer authority from filenames, templates, generated Markdown, pull request bodies, or chat context.

The pull request description standard is the first artifact standard hardened under this model. It defines the universal PR body invariant as Summary plus Context, then adds optional sections only when decision-tree triggers are true.

Impact

  • Gives agent harnesses a stable machine-readable path for creating standards-compliant artifacts.
  • Adds a reusable kernel for cross-standard invariants instead of repeating those rules in every artifact standard.
  • Reduces PR description boilerplate by forbidding routine visible Validation sections.
  • Preserves proof and rationale in standards surfaces instead of rendering them into every generated artifact.
  • Clarifies that executable skills and harness behavior are not owned by this standards repository unless a standard admits their package shape.

Changes

  • Adds meta.agent-operating-kernel.v1 for repository-wide agent operating invariants.
  • Adds standard.yaml as the machine-readable agent entrypoint for standard packages.
  • Adds meta.standard-package.v1 to separate proof/prose, agent contract, schema, semantic rules, templates, and examples.
  • Adds meta.semantic-rules.v1 plus validation for unique semantic rule ids.
  • Adds docs/AGENT_CONSUMPTION.md to define external-agent load order and the final instruction surface.
  • Adds artifact.rendered-view.v1 to bound Markdown, HTML, and rendered projections as non-canonical unless freshness is proven.
  • Adds roadmap and pull request description artifact standards.
  • Refines pull request description v1 around mandatory Summary and Context, structured review_scope, change_profiles, readiness_state, and triggered optional sections.
  • Removes stale roadmap wording from the earlier rejected PR-description model that forced validation, risk, and non-claims for every PR.
  • Extends validation for PR description schema conditionals, kernel invariant ledgers, semantic-rule mirrors, template projection parity, and YAML/JSON syntax.
  • Keeps executable harness adapters out of this standards repository; the harness capability is handled separately.

Links

  • docs/AGENT_CONSUMPTION.md
  • standards.catalog.yaml
  • standards/meta/agent-operating-kernel/v1/standard.md
  • standards/meta/agent-operating-kernel/v1/standard.yaml
  • standards/meta/standard-package/v1/standard.md
  • standards/meta/semantic-rules/v1/standard.md
  • standards/artifacts/rendered-view/v1/standard.md
  • standards/artifacts/roadmap/v1/standard.md
  • standards/artifacts/pull-request-description/v1/standard.md
  • standards/artifacts/pull-request-description/v1/standard.yaml
  • standards/artifacts/pull-request-description/v1/schema.json
  • standards/artifacts/pull-request-description/v1/semantic-rules.yaml

Evidence

  • npm run validate: passed.
  • git diff --check HEAD~1..HEAD: passed for the latest commit.
  • tracked-file scan for stale PRD wording, Cyrillic, and [codex]: no matches.
  • JSON Schema ad hoc check for meta.agent-operating-kernel.v1 template and minimal example: passed earlier in this PR.
  • JSON Schema ad hoc check for meta.agent-operating-kernel.v1/standard.yaml against meta.standard-package.v1/schema.json: passed earlier in this PR.
  • Chat-history audit located the main Codex JSONL transcript and found no remaining critical omissions after the roadmap wording fix.
  • Earlier PR-description positive and negative schema cases were checked locally; they are not yet preserved as a repository fixture suite.

Risk / Rollback

Risk: The first machine-entrypoint and kernel layer may need migration as issue, release, evidence, validator, renderer, and harness installation standards are admitted.

Rollback: Revert this PR branch to remove the standards kernel and machine-entrypoint layer.

Non-Claims

  • This PR does not define issue body, release notes, changelog, evidence report, or CI workflow standards.
  • This PR does not make downstream repositories compliant.
  • This PR does not make generated Markdown or HTML canonical.
  • This PR does not prove rendered-view freshness without a manifest and digest evidence.
  • This PR does not install or package executable harness skills.
  • This PR does not claim that routine PR descriptions should include visible command logs.
  • This PR does not make semantic review a required GitHub status check.

Review Focus

  • Check that meta.agent-operating-kernel.v1 owns only cross-standard operating invariants.
  • Check that standard.yaml is the routine agent instruction and standard.md remains the proof surface.
  • Check that PR description v1 makes only Summary and Context universally visible.
  • Check that Evidence is conditional and does not reintroduce routine visible validation boilerplate.
  • Check that schema, semantic rules, templates, and validator obligations stay aligned.
  • Check that rendered views cannot falsely claim freshness.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Development

Successfully merging this pull request may close these issues.

1 participant