Analysis Archive

• 1: processkit v1.0 Base Context
• 2: Concept Mapping Briefing Analysis
• 3: processkit v1.0 RFC Analysis
• 4: OKF Compatibility Analysis
• 5: processkit v1.0 Start Assessment

1 - processkit v1.0 Base Context

Created: 2026-07-04

This historical base context was created for the processkit v1.0 redesign. It was built from the earlier projectious-work/processkit repository, cloned locally at:

• Source URL: https://github.com/projectious-work/processkit
• Analyzed commit: 6a9a175f95c42dd76e23488feca42e3d05526b98
• Local clone: /tmp/processkit-original

The goal is to preserve the proven v0.x product target while creating a clean basis for processkit v1.0 improvement briefings.

Current Guiding Briefing

The current guiding briefing is processkit-v1.0-rfc-draft.md, analyzed in the processkit v1.0 RFC analysis .

Conflict rule:

• preserve the stable product target captured in this base context
• use the v1.0 RFC for ontology, branch, release, schema-composition, validation, indexing, and cutover-gate direction
• treat concept-mapping-2026-05-16.md as historical input where it agrees with the RFC, not as current guidance where it conflicts

Current Repository Status

At the time of this analysis, the workspace was a fresh aibox/processkit-derived project scaffold, not yet a rebuilt processkit source tree.

• aibox.lock pins upstream processkit to v0.27.1.
• aibox.toml enables the processkit core/managed skill surface.
• The workspace currently has no src/, docs-site/, or implementation source tree.
• Indexed processkit entities for WorkItems, DecisionRecords, Discussions, and Artifacts are currently empty in this project.
• GitHub auth was available for repository status checks.

Session-start process checks were run before this document was created. The pending aibox.lock backfill migration MIG-LOCK-20260703T161218 was applied through migration-management. After that, active migrations were zero.

pk-doctor still reports setup drift that should be tracked separately:

• missing scripts/check-src-context-drift.sh
• missing TeamMember tier directories for cora and thrifty-otter
• missing Claude sub-agent export for cora
• stale MCP manifest / server-header / preauth metadata
• one applied migration that is now an archive candidate

These findings are not part of the base-context target itself, but they are important when this repository starts growing source and release machinery.

Stable Product Target

The first processkit version defines processkit as:

provider-neutral process memory, skills, and MCP tools for agentic software projects.

The stable target should not change:

1. processkit is a versioned content and runtime layer for AI-assisted projects.
2. It gives agents and humans structured project memory through repository files, schemas, skills, state machines, and MCP tools.
3. It is provider-neutral and harness-neutral. Claude, Codex, OpenCode, Hermes, Aider, and other harnesses are integration targets, not core dependencies.
4. It is a process layer, not a replacement for a harness, runtime manager, issue tracker, or model provider.
5. It must remain usable manually, through MCP-capable harnesses, or via an external installer such as aibox.
6. It must remain forkable. Organizations can maintain private forks and downstream projects can consume those forks without changing their own structure.

The original PRD states the primary goal clearly: make it easy for any team to add a structured, agent-readable process layer to any repository.

Shipped Deliverable Boundary

The old project made a hard distinction between the processkit repository’s dogfooding context and the content shipped to consumers. This distinction is foundational and should be preserved.

src/ in the original repository is a literal mirror of a fresh consumer project root:

• src/AGENTS.md becomes <project>/AGENTS.md.
• src/context/ becomes <project>/context/.
• src/.gitignore.example is the recommended ignore template.
• src/.processkit/ is catalog tooling and package metadata; it is not installed into consumers as live project context.

The repository-root context/ in the old project is dogfood project state. It contains processkit’s own WorkItems, Decisions, Artifacts, logs, migrations, team state, and release history. That content must not be blindly mirrored into src/context/.

The release boundary guard from the original project explicitly allows dogfood-only directories under root context/ while forbidding them from shipping under src/context/. In src/context/, shipped Artifacts are model specs and model profiles only; dogfood Decisions, WorkItems, Discussions, Notes, Logs, Migrations, and Templates do not ship.

Consumer Usage Model

Consumers can use processkit manually or through a manager.

Manual use:

1. Download a versioned processkit release tarball.
2. Copy the shipped context/, .processkit, and AGENTS.md into the consuming project.
3. Configure the harness to launch processkit-gateway, or launch individual per-skill MCP servers.

aibox-assisted use:

1. aibox.toml pins [processkit] source, version, and src_path.
2. aibox fetches the source release, installs selected package tiers, and records aibox.lock.
3. aibox may configure or supervise runtime files, but processkit remains the standalone source for schemas, skills, packages, and MCP runtime.

The old README names three MCP layouts:

• processkit-gateway: preferred provider-neutral entry point.
• Per-skill MCP servers: canonical granular compatibility surface.
• aggregate-mcp: legacy compatibility bridge.

The gateway is additive. It must not replace per-skill servers as the canonical validation and compatibility surface.

Package Tiers

The original package model has five tiers:

• minimal: foundation for solo developers and small side projects.
• managed: recommended default for small teams with backlog and process cadence.
• software: managed plus architecture, infrastructure, security, performance, database, and observability skills.
• research: managed plus data, ML, AI, and research-authoring skills.
• product: software plus design, framework, product, and broader end-to-end product-development skills.

Packages compose through spec.extends; consumers can add or remove specific skills through config overrides.

Entity and Contract Model

The stable entity model is Markdown files with YAML frontmatter:

• apiVersion
• kind
• metadata
• spec
• body content where appropriate

The v2 direction is intentionally breaking and explicit. The historical decisions rejected long-term v1/v2 compatibility shims. v1 contexts are migration sources; after migration, v2 schemas and index semantics are authoritative.

Important v2 contract points:

• Unknown kinds, stale primitive assumptions, and ad hoc event/type vocabulary should fail validation.
• Metric, Model, Process, Schedule, and StateMachine are legacy v1 migration-source kinds, not shipped v2 entity primitives.
• Process definitions are Artifacts plus process-instance WorkItems.
• Schedule semantics use Binding(type=time-window).
• Runtime state-machine YAML files are implementation contracts, not user-authored StateMachine entities.
• Hook inbox items are Notes with spec.inbox.
• Agent cards and security policies are Artifact-backed projections.
• Eval gates produce eval-spec Artifacts, paired Gates, policy/application Bindings, and calibration LogEntries.

MCP and Indexing Principles

The old project converged on these operational rules:

• Agents read entities through index-management, not raw filesystem scraping.
• Agents write entities through management MCP tools so schema validation, state-machine enforcement, index updates, and event logs happen consistently.
• index-management is the read-side foundation.
• id-management is the write-side ID foundation.
• Entity search uses SQLite FTS5, with optional sqlite-vec semantic search and hybrid search.
• Broad health checks and release checks should return structured JSON so agents can route findings instead of re-parsing prose.

The original release had 30 MCP server files under src/context/skills. Most are processkit management servers; one additional shipped server was devops/repo-management.

Provider and Model Neutrality

Provider neutrality is a core invariant, not a convenience.

The old decisions establish:

• processkit skills, commands, MCP tools, and doctor findings must not require or invoke aibox host commands from inside derived project containers.
• aibox and other managers may install, supervise, or provide runtime signals, but processkit remediation surfaces stay generic.
• Role and TeamMember model assignments bind to provider-neutral Artifact(kind=model-profile) artifacts by default.
• Concrete Artifact(kind=model-spec) artifacts may encode provider and model names because they describe real provider models.
• Runtime access gates expand profiles into concrete candidates.
• Direct Role/TeamMember bindings to concrete ModelSpec artifacts are explicit pins or compatibility cases.

This is the design line that lets a processkit project move between Codex, Claude Code, Gemini CLI, Aider, Cursor, Copilot, OpenCode, Hermes, and future harnesses without rewriting its process memory.

Team and Role Model

The old project introduced persistent TeamMembers, Roles, RoleSlots, and Bindings to support repeatable multi-agent collaboration:

• Roles define responsibilities.
• TeamMembers represent named humans or AI personas.
• Bindings connect actors, roles, model profiles, scopes, and other addressable surfaces.
• RoleSlots decouple identity and capacity planning from concrete people or model invocations.
• Sub-agent dispatch should route through route_task first and use the recommended TeamMember/model class when available.

The workspace had processkit TeamMember remnants from installation, but pk-doctor reported missing tier directories and one missing Claude sub-agent export. Treat that as setup hygiene, not as the future team model.

Release and Migration Model

The first processkit version treated releases as deliberate versioned content, not silent syncs.

Stable release expectations:

• src/PROVENANCE.toml maps shipped files to the tag where each last changed.
• scripts/processkit-diff.sh compares tagged versions and classifies added, removed, changed, and unchanged files.
• Installers write explicit Migration documents for upgrades.
• Users and agents review migrations before applying them.
• Migration flow is pending -> in-progress -> applied.
• Release tarballs are built reproducibly from src/.
• Release packaging runs a release-boundary guard, release audit, provenance freshness check, MCP preauth validation, and checksum generation.

The old release process guarded against a known failure mode: dogfood context had changed while src/context/ did not receive corresponding shippable changes. The new version should preserve a guard that makes that drift visible.

Documentation Surface

The first version had two user-facing documentation surfaces:

• root docs such as docs/harness-claude-code.md
• Docusaurus docs under docs-site/

The most important stable docs topics are:

• installation and harness setup
• package tiers and skill catalog
• API version policy
• migration model
• v2 contracts
• ID formats
• privacy tiers
• gateway and MCP layouts

At the time of capture, the workspace did not yet have the current Docusaurus development section. Treat that statement as historical.

Current Gap Summary

Compared with the original processkit repository, this project currently has:

• processkit runtime context installed under root context/
• aibox config and lock data
• devcontainer/runtime scaffolding
• this base-context document

It does not yet have:

• src/ deliverable tree
• src/context/ schemas, state machines, skills, model artifacts, roles, bindings, and TeamMember defaults
• package definitions under src/.processkit/packages
• release scripts and verification scripts
• docs-site user documentation
• changelog, contribution guide, or release packaging flow
• processkit v1.0-specific WorkItems, Decisions, or Artifacts describing the rebuild roadmap

Base-Context Readiness Audit

This first phase is complete enough for the next briefing document.

Open items are intentionally deferred until the incoming briefing is reviewed:

• creating processkit v1.0-specific WorkItems or DecisionRecords
• choosing which old skills or runtime code to import versus redesign
• rebuilding src/, docs-site/, release scripts, or MCP runtime code
• resolving unrelated installed-context hygiene findings from pk-doctor

Improvement Surface for Later Briefing

The next briefing can change how the new implementation is built, but it should do so against these preserved targets:

• keep processkit provider-neutral and host-orchestrator-neutral
• keep the shipped deliverable boundary explicit
• keep entity writes validated through MCP, not hand-edited context files
• keep migrations explicit and reviewable
• keep gateway additive rather than replacing per-skill canonical servers
• keep model routing provider-neutral through profiles
• keep docs and release checks first-class
• keep dogfood project context separate from consumer deliverables

Likely redesign areas for processkit v1.0:

• simplify the source layout without losing the consumer mirror invariant
• reduce prompt/runtime overhead of the skill and MCP surfaces
• make package selection and command projection easier to reason about
• strengthen release and migration tests from the start
• define processkit v1.0-specific WorkItems/Decisions after the incoming briefing document is reviewed
• decide whether to import, regenerate, or redesign each old skill family rather than copying the whole first-version catalog wholesale

Evidence Index

Primary evidence from the original repository:

• README.md: product promise, install model, MCP layouts, current status
• ART-20260409_1854-KindCrane-processkit-product-requirements-document: original approved PRD
• src/INDEX.md: shipped deliverable boundary and mirror invariant
• src/.processkit/packages/*.yaml: package tiers and composition
• docs/harness-claude-code.md: harness behavior and compliance payloads
• docs-site/docs/reference/apiversion-policy.md: apiVersion rules
• docs-site/docs/reference/migration.md: version migration model
• docs-site/docs/reference/v2-contracts.md: v2 entity/projection rules
• docs-site/docs/reference/id-formats.md: ID prefix and format policy
• docs-site/docs/reference/privacy.md: privacy tiers and private dirs
• src/context/skills/processkit/processkit-gateway/SKILL.md: gateway architecture
• src/context/skills/processkit/index-management/SKILL.md: read-side index foundation
• scripts/check-src-context-drift.sh: release boundary guard
• scripts/build-release-tarball.sh: release packaging flow
• scripts/smoke-test-servers.py: MCP smoke workflow

High-signal historical decisions:

• DEC-20260430_1416-SmoothTiger-adopt-breaking-v2-implementation-plan-for
• DEC-20260501_1739-ProudCrane-adopt-smoothtiger-informed-split-track-v2
• DEC-20260502_0743-CoolFjord-adopt-provider-neutral-processkit-gateway-daemon
• DEC-20260503_1829-LoyalComet-route-roles-and-team-members-through
• DEC-20260515_1232-GentleLantern-keep-processkit-host-orchestrator-neutral

2 - Concept Mapping Briefing Analysis

Source: concept-mapping-2026-05-16.md

Analyzed: 2026-07-04

Supersession note: processkit-v1.0-rfc-draft.md is now the guiding briefing for processkit v1.0. Where this analysis conflicts with the processkit v1.0 RFC analysis , the RFC analysis wins. Keep this file as historical interpretation of the earlier concept-mapping input, not as current implementation guidance.

The filename dates the briefing to 2026-05-16, but the document itself continues through Round 17 on 2026-05-20. Treat it as a mid-May design snapshot, roughly six to seven weeks old as of this analysis.

Executive Read

The document starts as a reconciliation exercise: preserve processkit’s closed primitive set and map missing concepts onto fields, sub-kinds, or Binding types. It does not stay there.

By the later rounds, the recommendation has shifted to a greenfield ontology for a new processkit version:

• keep the processkit target from the v0.x line
• replace the old “small closed primitive set plus many special cases” model with a richer orthogonal ontology
• promote several abstract parents to first-class atomic primitives
• model domain terms through discriminators and compositions
• support large agent-heavy organizations by making vocabulary explicit enough for agents to reason over

The most important sentence operationally is in Round 16: for a 10-human, many-agent company doing roughly 500-person work, the document recommends going full greenfield.

Relationship To Base Context

The briefing preserves these base-context invariants:

• processkit remains provider-neutral and harness-neutral
• project memory remains structured, versioned, and agent-readable
• repository-local process data remains the source of truth
• migrations remain explicit
• rich skills and MCP tooling remain part of the product
• old context/ dogfood history is evidence, not a payload to ship

It challenges these base-context assumptions:

• the current v0.x primitive set is no longer treated as the likely target
• current schemas are evidence, not constraints
• “no new primitives” is rejected by later rounds
• kind= discriminators alone are insufficient for the greenfield model
• composition support becomes load-bearing

The base context says “do not change the product target.” This briefing does not change the target. It changes the ontology and implementation strategy for reaching that target.

Evolution Inside The Document

The early section says:

• zero new primitives required
• keep the closed primitive set
• add fields, known_kinds, known_types, and Binding kinds
• use an editorial Content / Structure / Governance framing

The middle rounds add:

• a fourth level: Specification / Type / Meta
• a cross-cutting Relation stratum
• explicit Definition / Instance / Record thinking, then later simplify back to level-only organization
• a class column:
  • T: terminology only
  • P: primitive
  • D: discriminator on a parent primitive
  • C: composed schema

The late rounds settle on a greenfield-corrected cut:

• parent concepts such as Record, Specification, Container, Policy, Event, and Capability become atomic primitives
• children such as DecisionRecord and LogEntry become compositions under Record
• some grammar-level concepts are dropped as too low-level
• the greenfield model is judged sufficient for SAFe-style scaling

This means the final recommendation should be read from Rounds 13-17, not from the opening “zero new primitives” finding.

Final Ontology Shape

The final stable shape in the document has five levels:

• Specification / Type / Meta
• Content
• Structure
• Governance
• Relation

It classifies concepts by four implementation classes:

• T: concept only, no schema
• P: atomic primitive with its own YAML schema
• D: discriminator variant on a parent primitive
• C: composed schema assembled from primitive blocks

Round 14/15 reports:

• 35 foundational concepts
• 47 specifics
• 82 concepts total
• 21 primitives
• 19 discriminators
• 23 compositions
• 19 terminology concepts

The very last delta table also says Round 14 drops from 87 to 81 concepts after removing six grammar-leak concepts. This conflicts with the Round 14/15 total of 82 because Round 15 adds Uniqueness. For future work, treat the effective final count as 82 unless newer input clarifies otherwise.

The RFC is that newer input. The current processkit v1.0 target is 89 concepts: 19 T, 22 P, 24 D, and 24 C.

Candidate Atomic Primitives

The greenfield model’s important P candidates are:

Specification / Type / Meta:

• Specification

Content:

• Artifact
• Capability
• Command
• Discussion
• Message
• Note
• Proposition
• Queue
• Record
• Resource
• Token
• WorkItem

Structure:

• Actor
• Channel
• Container
• Role

Governance:

• Event
• Gate
• Policy

Relation:

• Binding

Some of these overlap with old processkit primitives. Others are new or promoted from concepts previously represented by fields, sub-kinds, or runtime behavior.

Major Reclassifications

The biggest conceptual shift is parent promotion:

• Record becomes primitive; DecisionRecord, LogEntry, Measurement, Outcome, and Archive become Record-derived forms.
• Container becomes primitive; Scope becomes a composition or specific container form.
• Specification becomes primitive; schema, process, role, gate, schedule, goal, service, channel, queue, and test specifications become composed specifications.
• Policy becomes primitive instead of being represented only through Artifact + Binding + Gate composition.
• Event becomes primitive and pairs with Command.
• Proposition becomes primitive and absorbs Belief, WorldFact, and Risk as discriminator variants.
• Capability becomes primitive and absorbs Skill, Authority, and Service as specific forms.
• Binding remains primitive, but Hierarchy, Position, Correlation, and Provenance become Binding variants.

These changes are incompatible with simply importing v0.27.1 schemas. They require a deliberate model redesign.

Load-Bearing Design Decisions

The document creates several decisions that should be confirmed before implementation:

1. Adopt full greenfield ontology rather than incremental v0.27.x evolution.
2. Treat Round 14/15 as the baseline cut, subject to newer inputs.
3. Use 5 levels: Specification / Content / Structure / Governance / Relation.
4. Use T/P/D/C classification to decide storage shape.
5. Promote Record, Specification, Container, Event, Policy, Capability, Proposition, Command, Message, Queue, Resource, Token, and Channel.
6. Demote old first-class children such as DecisionRecord and LogEntry to composed Record forms in the greenfield model.
7. Keep Binding as the relation primitive and express hierarchy, provenance, position, and correlation as Binding variants.
8. Use Proposition as the shared parent for belief, fact, and risk.
9. Demote Service to a Capability-specific composition, unless newer SOA-oriented input reverses that.
10. Keep spatial/location and BFO disposition out of the core model.

The RFC supersedes item 10: Location is now a primitive and Capability{kind=disposition} is explicitly included.

None of these should be silently encoded as implementation work without a current confirmation pass, because the briefing is dated.

Composition Strategy

The document rejects a false binary between duplicated flat schemas and runtime $ref.

Recommended path:

1. Start with Option 8: runtime-only composition. Schemas may duplicate initially, while tests and polymorphic query behavior enforce shared interfaces.
2. Evolve toward Option 3: build-time generation. Source uses composition; generated runtime schemas are flat YAML.
3. Keep Option 7 available: extends: annotation with a lightweight loader.

The RFC supersedes this staged path. processkit v1.0 should use build-time Jinja + YAML schema generation from the start, with committed _generated/*.yaml output.

Scaling Argument

The document tests the model against:

• 10 humans plus agents doing roughly 500-person work
• 100 humans plus agents doing roughly 5000-person work
• SAFe / ART / portfolio structures

Its conclusion:

• today’s model is too weak for this
• a reduced model improves agentic workflows but under-models cadence, channel, policy, and goal vocabulary
• the greenfield model reaches near-complete SAFe modelling capability
• further 10x scale does not require new concepts

The remaining scale problems are engineering and governance:

• composition tooling
• indexing and search
• federation
• throughput
• bulk operations
• interpretation drift
• agent training on canonical meanings

This strongly implies that processkit v1.0 should invest early in indexing, composition tests, and canonical ontology documentation.

Questions Resolved By The RFC

The document left these unresolved or only implicitly resolved. The RFC now settles them for processkit v1.0:

• Position is Binding{kind=role-slot} with nullable subject.
• Belief, WorldFact, Risk, and WSJF-estimate sit under Proposition.
• Service is S(Capability)/C, not a primitive.
• Hierarchy remains a named concept implemented as Binding{kind=parent-child}.
• Location is a primitive with five discriminator variants.
• Capability{kind=disposition} is included.
• The final concept count is 89, not 81 or 82.
• The RFC supersedes Round 14/15 where they conflict.

Implications For processkit v1.0 Build-Up

The new project should not start by copying the old src/context/ schemas wholesale. The better path is:

1. Preserve the product target and release discipline from the first version.
2. Treat old schemas, skills, and MCP servers as implementation evidence.
3. Define the greenfield ontology contract first.
4. Decide the first-phase primitive set and class assignment.
5. Create schema-generation or runtime-composition policy.
6. Build minimal tooling around the new primitives:
   • ID generation
   • schema validation
   • state transitions
   • entity index
   • relation queries
   • migrations
7. Port or rewrite skills after the new ontology is stable.
8. Use migration adapters to ingest old-processkit context where needed.

The first implementation milestone should be a thin vertical slice, not the whole ontology:

• one or two Specification forms
• Record
• WorkItem
• Binding
• Container or Scope
• Event / Command
• index and validation support

Then expand through compositions and discriminators.

Risks

• The document is internally inconsistent because it records an evolving discussion, not a single final spec.
• It references companion Notes and Decisions that are not present in this new repository.
• It was produced before later project learning, so its final recommendation may be superseded.
• Going full greenfield creates a migration burden from processkit v0.x.
• Composition tooling can become a project inside the project.
• Agents may benefit from rich vocabulary, but humans may find the ontology too abstract without good docs and examples.

What The RFC Resolves

The later RFC answers the briefing’s implementation questions:

• The intended baseline is the RFC’s 89-concept T/P/D/C ontology.
• v1.0 is a greenfield rebuild with migration/import bridges from v0.x.
• The composition mechanism is build-time Jinja + YAML generation.
• SAFe / many-agent scaling remains the main ontology pressure.
• The first deliverable is a phase-gated alpha built around ontology completeness and tooling parity.

Working Interpretation

Until newer input says otherwise, use this as the working direction:

processkit v1.0 should preserve processkit’s product promise but rebuild the core model around the RFC’s greenfield 89-concept ontology. The old project is evidence and migration source, not a schema constraint. Implementation should follow the RFC’s build-time schema generation, interface-aware indexing, and 81-criterion gate.

3 - processkit v1.0 RFC Analysis

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.

4 - OKF Compatibility Analysis

Source:

• Google Cloud announcement, “Introducing the Open Knowledge Format”, published 2026-06-12
• GoogleCloudPlatform/knowledge-catalog okf/SPEC.md, v0.1 draft, inspected at d44368c15e38e7c92481c5992e4f9b5b421a801d

Analyzed: 2026-07-04

Recommendation

processkit v1.0 should support OKF as an import/export and publication profile, but should not make OKF the canonical internal format.

In practical terms:

• Yes: emit conformant OKF bundles from selected processkit knowledge.
• Yes: ingest OKF bundles into processkit as external knowledge sources.
• Yes: preserve OKF-compatible affordances in v1.0 schema design where they do not weaken processkit semantics.
• No: do not require the whole repository or canonical context/ tree to be an OKF bundle.
• No: do not replace processkit entity IDs, typed relations, lifecycle states, validation modes, event logs, or interface-aware queries with OKF’s permissive markdown conventions.

This gives us interoperability without losing the benefits that make processkit more than an LLM wiki.

What OKF Is

OKF v0.1 is a deliberately small knowledge-bundle format:

• a directory tree of UTF-8 markdown files
• YAML frontmatter at the top of every concept document
• type as the only required frontmatter key
• optional title, description, resource, tags, and timestamp
• file path, minus .md, as the concept ID
• normal markdown links as graph edges
• optional index.md files for progressive disclosure
• optional log.md files for chronological history
• permissive consumers that tolerate missing optional fields, unknown types, unknown keys, broken links, and missing indexes

The announcement frames OKF as a vendor-neutral, agent- and human-friendly standard for exchanging metadata, context, and curated knowledge. It explicitly says OKF is a format, not a platform or service.

Fit With processkit Goals

OKF strongly aligns with several processkit goals:

• plain files over service lock-in
• git-native review, diffs, history, and distribution
• human-readable and agent-readable knowledge
• provider-neutral consumption
• markdown plus YAML frontmatter
• progressive disclosure through indexes
• graph navigation through links

This means OKF is strategically relevant. It is close enough to processkit’s existing shape that ignoring it would create unnecessary interoperability debt.

Limits And Mismatches

OKF is intentionally less strict than processkit needs to be.

Key mismatches:

• OKF has no fixed taxonomy; processkit v1.0 is explicitly building a typed ontology with T/P/D/C classes.
• OKF treats type values as unregistered strings; processkit needs schema-backed kinds, discriminators, and interfaces.
• OKF concepts are identified by bundle-relative paths; processkit uses stable entity IDs and may move storage paths as an implementation detail.
• OKF links are untyped and their relationship meaning lives in prose; processkit needs typed Bindings, explicit relations, lifecycle transitions, and queryable graph semantics.
• OKF requires permissive consumption of broken links and unknown fields; processkit needs strict validation for migrated kinds and controlled tolerant validation during migration.
• OKF log.md is prose history; processkit LogEntry entities are structured, append-only process evidence.
• OKF reserves lowercase index.md and log.md; processkit has richer index, schema, migration, and event-log machinery that should not be collapsed into those two files.

There is also a reference-implementation/spec mismatch: the v0.1 spec says only type is required for conformance, while the checked-in reference agent’s OKFDocument.validate() currently requires type, title, description, and timestamp. For processkit, the spec should be treated as normative and the reference implementation as an example producer profile, not as the compatibility contract.

Compatibility Model

The right compatibility model is a projection layer:

processkit canonical entities
  -> OKF exporter
  -> conformant OKF bundle

OKF bundle
  -> OKF importer
  -> external-source Artifacts / Notes / indexed knowledge

The canonical v1.0 system should keep:

• generated schemas and validation modes
• entity IDs
• lifecycle state machines
• typed relations and Bindings
• interface-aware queries
• event logs
• MCP tools as the write path

The OKF layer should provide:

• read-only exports for external consumers
• lossy-but-useful imports of external OKF knowledge
• optional round-trip preservation of unknown OKF frontmatter
• generated index.md files for exported bundles
• generated log.md files only as human-facing summaries, not as the source of truth for process events

Proposed v1.0 Requirements

Add an “OKF compatibility” acceptance slice to the v1.0 plan:

1. Define a processkit OKF exporter profile.
2. Map each exported processkit kind to an OKF type.
3. Include title, description, timestamp, and tags wherever available, even though only type is required by OKF.
4. Preserve processkit IDs in an extension key such as processkit_id.
5. Preserve processkit kind/interface metadata in extension keys such as processkit_kind and processkit_interfaces.
6. Encode typed relations in extension frontmatter, while also emitting normal markdown links for generic OKF consumers.
7. Generate conformant index.md files for progressive disclosure.
8. Treat log.md as an optional generated changelog summary.
9. Provide an OKF validator mode that checks v0.1 conformance.
10. Provide an OKF importer that marks imported knowledge as external and does not pretend it has full processkit lifecycle semantics.

Decision Guidance

Adopt OKF compatibility if it remains a boundary format.

Do not adopt OKF as the internal canonical model unless the OKF specification evolves to cover typed relations, lifecycle semantics, stable non-path IDs, validation profiles, and structured event history. That would be a different standard from OKF v0.1.

The safest wording for the v1.0 roadmap is:

processkit v1.0 SHOULD be able to produce and consume OKF v0.1 bundles, while retaining processkit’s stricter canonical schema, lifecycle, relation, and MCP semantics internally.

5 - processkit v1.0 Start Assessment

Analyzed: 2026-07-04

Sources considered:

• processkit-v1.0-rfc-draft.md
• processkit v1.0 RFC Analysis
• Concept Mapping Briefing Analysis
• OKF Compatibility Analysis
• Google OKF announcement and v0.1 specification
• External survey of adjacent agent, memory, metadata, and coding-agent projects

Judgement

The v1.0 plan is good enough to start, but not as an unconstrained 9-12 month greenfield rebuild.

Start a v1.0 branch now, but run it as a narrow alpha first:

• prove a small vertical slice before implementing the full ontology
• keep processkit’s canonical semantics stricter than OKF
• position processkit as process memory and governance, not as another agent runtime
• integrate with external runtimes instead of rebuilding them
• add OKF import/export as a boundary compatibility feature

The plan’s direction is strong. Its main risk is scope, not concept.

Why Start

The market is converging toward exactly the problems processkit is trying to solve:

• persistent agent context
• local and git-native knowledge
• markdown / frontmatter agent memory
• MCP tool interoperability
• durable work state
• human review and approval gates
• multi-agent role specialization
• observability, lineage, and auditability

The RFC’s core differentiators remain valid:

• schema-backed process entities
• lifecycle-aware WorkItems, Decisions, Discussions, Notes, Artifacts, Bindings, Gates, Skills, and Logs
• MCP write paths rather than ad hoc file edits
• typed relations instead of prose-only links
• provider-neutral model and role routing
• interface-aware search and query
• structured event history

No surveyed external project fully covers this combination.

Why Constrain The Start

The RFC’s 89-concept ontology is too large to treat as proven before implementation. It should be validated by usage.

The first alpha should answer:

• Does the new ontology reduce agent confusion in real work?
• Does query_by_interface improve routing and retrieval?
• Can existing v0.x history migrate without losing process evidence?
• Can agents create and transition entities reliably through MCP tools?
• Can humans still inspect and review the files directly?
• Can OKF export/import work without weakening internal semantics?

If those are not proven early, a larger rebuild will produce more schema surface without enough operational proof.

Concepts To Learn From

These external concepts should influence v1.0 without replacing processkit’s identity.

OKF: Boundary Format

Learn:

• minimal markdown + YAML interchange
• permissive consumers
• path-readable bundles
• generated index.md for progressive disclosure
• plain markdown links for generic graph consumers

Apply:

• OKF exporter and importer
• extension frontmatter preserving processkit IDs and kinds
• OKF validator mode
• generated OKF bundles for publication and exchange

Do not copy:

• path IDs as canonical IDs
• untyped relations as the only graph model
• prose log.md as authoritative event history

Basic Memory / LLM Wiki: Local-First Memory

Learn:

• agents work well with simple, readable markdown memory
• backlinks and lightweight entity extraction are useful
• user-owned files build trust
• MCP access to memory lowers integration friction

Apply:

• keep canonical files inspectable by humans
• improve indexes, backlinks, and local search ergonomics
• expose memory operations through MCP with clear tool metadata
• make agent write paths safe but still low-friction

Do not copy:

• free-form notes as the only data model
• weak lifecycle semantics

LangGraph / ADK / Microsoft Agent Framework: Runtime Boundaries

Learn:

• durable execution, pause/resume, and human-in-the-loop workflows are now table stakes
• agent runtimes increasingly support state, tools, telemetry, and multi-agent orchestration
• framework-specific orchestration changes quickly

Apply:

• make processkit easy for those runtimes to use
• define stable MCP tools for work, decisions, gates, and logs
• model approvals and interrupts as first-class process state
• provide runtime-neutral integration examples

Do not copy:

• agent loop orchestration
• provider-specific runtime assumptions

OpenAI Agents SDK: Handoffs, Guardrails, Tracing

Learn:

• handoffs need explicit target identity and task shape
• guardrails should be auditable process artifacts
• traces are valuable when debugging agent behavior

Apply:

• connect TeamMember / Role routing to handoff metadata
• model guardrails as Gates and policy Bindings
• map traces or summaries into structured LogEntries or Artifacts

Do not copy:

• SDK-specific session state as canonical project memory

Letta / Mem0: Memory Layering

Learn:

• long-term memory needs summarization, retrieval, and consolidation
• different memory layers serve different retrieval needs
• graph memory can improve multi-hop questions

Apply:

• separate fleeting notes, permanent artifacts, decisions, logs, and team-member memory
• add explicit promotion and consolidation workflows
• support graph-aware retrieval over typed entities and Bindings

Do not copy:

• opaque memory stores as the only source of truth
• personalization-first memory as the center of the project model

DataHub / OpenMetadata / Unity Catalog: Metadata Governance

Learn:

• catalogs win by combining metadata, lineage, ownership, search, quality, and governance
• typed metadata supports automation better than prose alone
• enterprise users expect lineage and ownership to be queryable

Apply:

• make ownership, source, provenance, and lifecycle queryable
• add lineage-style relations where process artifacts derive from one another
• expose health and quality checks through pk-doctor
• keep metadata extensible without losing validation

Do not copy:

• data-catalog scope as the core product
• centralized service dependency

OpenLineage: Faceted Extensibility

Learn:

• a small core model plus extension facets can scale across domains
• lineage events benefit from consistent naming and extensible metadata

Apply:

• consider facet-like schema extension points for v1.0 entities
• keep core fields stable while allowing typed extension payloads
• use event metadata to preserve provenance and causal relationships

Do not copy:

• run/job/dataset as processkit’s universal core model

OpenHands / SWE-agent / Copilot Agent / Aider: Coding-Agent Fit

Learn:

• coding agents need repository maps, task context, plans, tests, and review loops
• asynchronous agents need durable project state outside chat
• issue-to-PR agents benefit from clear acceptance criteria

Apply:

• make processkit the context substrate for coding agents
• export concise task briefs with related decisions and artifacts
• model acceptance criteria and verification as queryable fields
• preserve branch, PR, test, and review evidence in structured logs

Do not copy:

• code-editing agent behavior
• benchmark chasing as the project goal

Immediate Plan Improvements

Before full implementation, amend the v1.0 plan with these additions:

1. Add an OKF compatibility acceptance slice.
2. Add a one-project alpha proving a small ontology subset.
3. Define processkit’s runtime boundary explicitly.
4. Add a “not building” list: agent runtime, vector database, data catalog, OKF-only wiki.
5. Add provenance and lineage requirements.
6. Add handoff / approval / guardrail mapping to Roles, Gates, and Logs.
7. Add graph/backlink ergonomics for human and agent navigation.
8. Add migration proof for existing v0.x entities.
9. Add examples for LangGraph, ADK, OpenAI Agents SDK, and Microsoft Agent Framework as consumers.

Start Condition

Start once the first alpha slice is defined as a vertical proof:

• 10-15 highest-value concepts only
• generated schemas
• MCP create/read/transition path
• interface query
• OKF export
• migration of a small existing corpus
• one real process cycle driven through the new model

That is enough to learn quickly while preserving the RFC’s direction.