v0.x This is the released v0.x line — the version that ships in release tarballs and is dogfooded in this repository. The v1.0 rebuild is documented separately in the v1.x preview.

processkit v1.0 RFC Analysis

Analysis of the guiding RFC for the processkit v1.0 redesign.

Source: processkit-v1.0-rfc-draft.md

Analyzed: 2026-07-04

Status for this project: guiding briefing. Where this RFC conflicts with concept-mapping-2026-05-16.md or concept-mapping-briefing-analysis.md , this RFC wins.

Executive Read

The RFC turns the earlier concept-mapping work into an implementation and release proposal. It is no longer just an ontology discussion. It asks upstream processkit maintainers to host a full v1.0 greenfield rebuild on a parallel v1.0 branch while main continues v0.x maintenance.

The product target from the base context remains intact: processkit is still provider-neutral process memory, skills, and MCP tooling for agentic software projects. The RFC changes the model and build plan used to reach that target.

The RFC’s operational direction is:

  • full greenfield ontology rebuild
  • 89 concepts in T/P/D/C classes
  • Jinja + YAML schema composition
  • committed build-time _generated/ schemas
  • new regenerate_schemas MCP endpoint
  • interface-aware polymorphic queries
  • strict/tolerant per-kind validation during migration
  • 9-12 month rebuild on a v1.0 branch
  • alpha, beta, rc, final pre-release progression
  • 81-criterion cutover gate before v1.0.0

Authority And Evidence

The RFC cites:

  • DEC-DeepTide: rebuild authorization
  • DEC-BraveAtlas: 81-criterion cutover gate
  • DISC-BriskWillow: 20-round ontology discussion
  • upstream issues #74 and #75 as pk-doctor reliability evidence

Those DEC/DISC entities are not indexed in this new repository, so they were not locally verifiable through processkit MCP.

I also checked the private projectious-work/internal repository as an external evidence source:

  • origin/main 44704b451d4baa53d04eb0e53c1bc01a41f6627e (2026-05-16T20:18:07+02:00)
  • origin/policy-primitive-trigger-reeval-2026-06-29 8197000d5951ae5e5303e6f2ca868d9f7b4e9ad9 (2026-06-29T07:05:29Z)

That repository verifies DISC-BriskWillow at context/discussions/ DISC-20260515_1955-BriskWillow-is-hierarchy-a-primitive-are-higher.md. The discussion is active, supersedes the earlier DISC-OpenPanda record, and carries forward the hierarchy / abstraction-level question. It also says the proposed decision was leaning toward editorial three-level framing without new primitives or schema migration, with hierarchy remaining composable through existing parent / Scope / Role / Binding shapes.

The same internal repository did not contain DEC-DeepTide or DEC-BraveAtlas by filename, ID token, or all-history search on the available branches. The June branch only adds tmp/policy-primitive-trigger-reeval-2026-06-29.md, which corroborates that DISC-BriskWillow is a live non-Policy primitive-admission question but does not provide the missing RFC decision records.

Treat the RFC as the authority because the user explicitly selected it as the guiding document. Treat DEC-DeepTide and DEC-BraveAtlas as unresolved external provenance to be imported, recreated, or replaced by new local decision records before irreversible implementation cutover.

What Supersedes The Earlier Concept Mapping

The earlier analysis treated Round 14/15 as the likely baseline and noted open questions. The RFC closes or changes several of those points.

The RFC now says:

  • final ontology count is 89 concepts, not 81/82
  • Location is a new primitive
  • Skill is a primitive, not a composition
  • TeamMember is a composition, not Actor{kind=team-member}
  • Service is S(Capability)/C, not a primitive
  • Position is Binding{kind=role-slot} with nullable subject
  • Location has five discriminator variants
  • Capability{kind=disposition} settles the disposition question
  • build-time Jinja + YAML composition is the preferred mechanism
  • _generated/ output is committed
  • processkit v1.0 should be built upstream on a v1.0 branch, not only in this derived repo

Any earlier note saying “confirm this later” should be read as resolved when the RFC makes a concrete settlement.

Ontology Direction

The current v0.x 13-primitive ontology is rejected as insufficient. The RFC says it cannot cleanly model AI-first SAFe execution at 100x5000 scale without both:

  • missing first-class concepts, and
  • grammar concepts leaking into the entity layer

The intended v1.0 ontology uses four concept classes:

  • T: foundational terminology or meta-mechanic, no own lifecycle
  • P: atomic primitive with schema, lifecycle, and persistence
  • D: discriminator variant of a primitive
  • C: composition of primitives and terminology fragments

Final RFC counts:

  • T: 19
  • P: 22
  • D: 24
  • C: 24
  • total: 89

Key Primitive Settlements

The RFC explicitly calls out these settlements:

  • Proposition is a new primitive. It is the parent for Belief, Risk, WorldFact, WSJF-estimate, and related epistemic content.
  • Location is a new primitive, with discriminator variants for geographic region, site, coordinate, logical region, and timezone.
  • Skill is a primitive with its own schema and lifecycle, distinct from Capability.
  • Capability remains a primitive; Service is composed from Capability.
  • TeamMember becomes a composition of Actor plus calendar, capabilities, persona, skill list, and journal.
  • Position is a Binding variant with nullable subject.
  • Hierarchy remains named for mental anchoring but is implemented as Binding{kind=parent-child}.

These are guiding decisions for processkit v1.0 unless later input supersedes the RFC.

Implementation Mechanics

The RFC rejects runtime $ref as the main solution and chooses build-time generation:

  • schema sources live under schemas/src/
  • Jinja templates render into flat _generated/*.yaml
  • runtime tools consume _generated/
  • _generated/ is committed to git
  • composition uses extends: parent.yaml
  • templates use {% include %} for T fragments
  • merge behavior uses __merge: replace|concat|name-merge

This is more specific than the earlier “Option 8 first, Option 3 later” guidance. The RFC chooses the build-time path directly.

Required MCP endpoint:

regenerate_schemas(kinds: list | None) -> {rebuilt, unchanged, errors}

The same endpoint handles full and partial rebuilds. aibox apply triggers full rebuilds by default, with opt-out for fast iteration.

Validation And Indexing

Validation is phase-gated:

  • migrated kinds: strict validation
  • kinds still migrating: tolerant validation, warn but pass
  • per-kind validation mode must be observable through MCP

Indexing extends the existing FTS5 surface rather than replacing it. Schemas declare interfaces:

interfaces: [Record, Versioned]

The required new query capability is:

query_by_interface(Record, ...)

This is load-bearing. The RFC identifies it as the fix for agent routing failures where agents have to choose between WorkItem, DecisionRecord, Artifact, LogEntry, and similar concrete kinds.

Branch And Release Model

The RFC proposes an upstream v1.0 feature branch:

  • main continues v0.x.y maintenance
  • v1.0 receives all greenfield rebuild work
  • alpha, beta, rc, and final tags are cut from v1.0
  • final cutover merges v1.0 into main and tags v1.0.0
  • derived projects opt in by pinning aibox.toml to alpha/beta/rc tags

Backport policy:

  • security fixes flow both ways
  • dependency bumps flow at maintainer discretion
  • feature work does not backport either way

This keeps the 9-12 month divergence bounded.

Cutover Gate

The RFC adopts an 81-criterion acceptance gate:

  • 75 strict criteria
  • 6 soft criteria
  • 8 phases

Phases:

  • P0: pre-conditions
  • O1: ontology completeness
  • T2: tooling parity
  • C3: corpus migration
  • S4: skills and agents
  • A5: first-ART validation
  • G6: cutover decision point
  • R7: post-cutover stabilization

The most important proof phase is A5: model a real ART end to end and run one full PI cycle in the new ontology.

The RFC highlights these specific acceptance constraints:

  • regenerate_schemas(kinds: list | None) MCP endpoint is required
  • search must include FTS5 plus interface grouping
  • canned query set must be signed off before rc
  • all MCP tools need valid Python type signatures and matching draft-2020-12 JSON Schemas
  • pk-doctor must pass a golden adversarial fixture

Upstream Asks

The RFC asks upstream maintainers for:

  1. host the v1.0 feature branch upstream
  2. endorse merge-to-main and v1.0.0 release model
  3. accept the backport policy
  4. name an upstream owner/contact
  5. adopt DEC-BraveAtlas or counter-propose a release gate

It explicitly does not ask upstream for engineering capacity.

Timeline

Indicative timeline:

  • months 1-2: composition tooling and first alpha
  • months 3-4: parent promotion and migration scripts
  • months 5-6: specification compositions plus Channel, Queue, Resource, Container; beta begins
  • months 7-9: skills, MCP tools, doctor, indexer; beta to rc
  • months 10-12: cutover and first ART on v1.0
  • post-cutover: at least 14 days stabilization

The gate, not the calendar, decides release progress.

Risks

The RFC’s main risks:

  • upstream rejects branch model
  • single derived-project decider bottlenecks sign-off
  • pk-doctor bugs hide failures
  • corpus migration loses data
  • agents drift into non-canonical interpretations
  • long-lived main / v1.0 divergence becomes hard to merge

The RFC mitigates these through the RFC itself, DEC-BraveAtlas tracking, adversarial doctor fixtures, migration loss ceilings, agent scenario tests, and strict backport policy.

Implications For This Repository

For processkit v1.0, this RFC should become the primary planning baseline:

  • do not build from the old v0.27.1 schema set
  • do not follow the earlier 81/82-concept Round 14/15 interpretation
  • use the RFC’s 89-concept shape as current guidance
  • plan schema tooling before broad schema migration
  • make interface-aware indexing a first-class requirement
  • design validation modes before migrating live corpora
  • treat pk-doctor rewrite/hardening as part of v1.0, not afterthought
  • prepare for upstream-branch workflow or a fork fallback

The first concrete work products should be:

  1. local copy of the RFC analysis and conflict rules
  2. ontology inventory derived from the 89-concept RFC
  3. phase-zero work plan for composition tooling
  4. local representation of the 81-criterion gate
  5. decision record for processkit v1.0 adopting this RFC as guidance

The fifth item should be recorded through processkit DecisionRecord MCP only after explicit acceptance, or when the user asks us to start planning work items.

Conflict Rule

If processkit-v1.0-rfc-draft.md conflicts with concept-mapping-2026-05-16.md, the RFC wins.

If the RFC conflicts with old processkit v0.27.1 implementation, the RFC wins for processkit v1.0 design, while v0.27.1 remains migration-source evidence.

If later user-provided input conflicts with the RFC, analyze that input explicitly and decide whether it supersedes this RFC.