From 550bf07af2d5aefb610b0d59783b18d821073b41 Mon Sep 17 00:00:00 2001 From: projectious Date: Fri, 7 Aug 2026 12:24:07 +0200 Subject: [PATCH 1/6] docs(spec): define processkit v1 from first principles --- CHANGELOG.md | 6 + README.md | 4 + scripts/validate-v1-spec.py | 155 ++++++++++++++++++ spec/doc/v1/00-from-scratch-assessment.md | 142 ++++++++++++++++ spec/doc/v1/01-product-definition.md | 105 ++++++++++++ spec/doc/v1/02-conceptual-model.md | 116 +++++++++++++ .../v1/03-project-storage-and-ownership.md | 100 +++++++++++ .../v1/04-content-packages-and-extensions.md | 83 ++++++++++ spec/doc/v1/05-application-and-lifecycle.md | 93 +++++++++++ .../v1/06-agent-protocol-and-query-surface.md | 95 +++++++++++ .../07-configuration-output-and-evidence.md | 95 +++++++++++ spec/doc/v1/08-security-and-trust.md | 81 +++++++++ spec/doc/v1/09-architecture-and-language.md | 95 +++++++++++ spec/doc/v1/10-verification-strategy.md | 79 +++++++++ .../11-compatibility-migration-and-release.md | 117 +++++++++++++ .../doc/v1/12-documentation-and-acceptance.md | 78 +++++++++ spec/doc/v1/13-standard-entity-types.md | 148 +++++++++++++++++ spec/doc/v1/14-performance-and-operations.md | 74 +++++++++ spec/doc/v1/15-review-decisions.md | 104 ++++++++++++ spec/doc/v1/README.md | 54 ++++++ spec/doc/v1/roadmap.yaml | 84 ++++++++++ spec/schemas/v1/roadmap.schema.json | 78 +++++++++ .../v1/roadmap/invalid-broken-dependency.yaml | 14 ++ spec/tests/v1/roadmap/invalid-cycle.yaml | 19 +++ .../v1/roadmap/invalid-duplicate-id.yaml | 19 +++ .../v1/roadmap/invalid-shipped-evidence.yaml | 14 ++ spec/tests/v1/roadmap/invalid-status.yaml | 14 ++ 27 files changed, 2066 insertions(+) create mode 100755 scripts/validate-v1-spec.py create mode 100644 spec/doc/v1/00-from-scratch-assessment.md create mode 100644 spec/doc/v1/01-product-definition.md create mode 100644 spec/doc/v1/02-conceptual-model.md create mode 100644 spec/doc/v1/03-project-storage-and-ownership.md create mode 100644 spec/doc/v1/04-content-packages-and-extensions.md create mode 100644 spec/doc/v1/05-application-and-lifecycle.md create mode 100644 spec/doc/v1/06-agent-protocol-and-query-surface.md create mode 100644 spec/doc/v1/07-configuration-output-and-evidence.md create mode 100644 spec/doc/v1/08-security-and-trust.md create mode 100644 spec/doc/v1/09-architecture-and-language.md create mode 100644 spec/doc/v1/10-verification-strategy.md create mode 100644 spec/doc/v1/11-compatibility-migration-and-release.md create mode 100644 spec/doc/v1/12-documentation-and-acceptance.md create mode 100644 spec/doc/v1/13-standard-entity-types.md create mode 100644 spec/doc/v1/14-performance-and-operations.md create mode 100644 spec/doc/v1/15-review-decisions.md create mode 100644 spec/doc/v1/README.md create mode 100644 spec/doc/v1/roadmap.yaml create mode 100644 spec/schemas/v1/roadmap.schema.json create mode 100644 spec/tests/v1/roadmap/invalid-broken-dependency.yaml create mode 100644 spec/tests/v1/roadmap/invalid-cycle.yaml create mode 100644 spec/tests/v1/roadmap/invalid-duplicate-id.yaml create mode 100644 spec/tests/v1/roadmap/invalid-shipped-evidence.yaml create mode 100644 spec/tests/v1/roadmap/invalid-status.yaml diff --git a/CHANGELOG.md b/CHANGELOG.md index b3a4a08d..91922803 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,12 @@ Versions follow [Semantic Versioning](https://semver.org/). ## Unreleased +### Added + +- Add a from-scratch processkit v1.x product specification, implementation + language assessment, normative requirement set, executable roadmap schema, + and phased roadmap for review. + ## [v1.0.0-alpha.5] - 2026-07-31 v1.0.0-alpha.5 completes the extracted issue #135 follow-up tracks for trusted diff --git a/README.md b/README.md index 89e3efc1..0d8a6fd7 100644 --- a/README.md +++ b/README.md @@ -31,6 +31,10 @@ > > The current v1 release is `v1.0.0-alpha.5`. Its published native executable > supports Linux ARM64 GNU only. +> +> A [from-scratch replacement v1 product specification](spec/doc/v1/README.md) +> is proposed for review. Until accepted and implemented, it describes planned +> behavior and does not replace the alpha.5 contracts documented below. --- diff --git a/scripts/validate-v1-spec.py b/scripts/validate-v1-spec.py new file mode 100755 index 00000000..d9b003a7 --- /dev/null +++ b/scripts/validate-v1-spec.py @@ -0,0 +1,155 @@ +#!/usr/bin/env -S uv run --script +# /// script +# requires-python = ">=3.12" +# dependencies = [ +# "jsonschema>=4.0", +# "pyyaml>=6.0", +# ] +# /// + +"""Validate the processkit v1 specification's executable contracts.""" + +from __future__ import annotations + +import json +import re +from pathlib import Path + +import jsonschema +import yaml + + +ROOT = Path(__file__).resolve().parents[1] +SCHEMA_PATH = ROOT / "spec/schemas/v1/roadmap.schema.json" +ROADMAP_PATH = ROOT / "spec/doc/v1/roadmap.yaml" +DOC_ROOT = ROOT / "spec/doc/v1" +REQUIREMENT_RE = re.compile(r"\b(PK-[A-Z]+-[0-9]{3})\b") +MARKDOWN_LINK_RE = re.compile(r"\[[^]]+\]\(([^)]+)\)") +INVALID_ROADMAP_ROOT = ROOT / "spec/tests/v1/roadmap" + + +def validate_roadmap( + roadmap: dict[str, object], + validator: jsonschema.Draft202012Validator, + *, + check_note_paths: bool, +) -> None: + validator.validate(roadmap) + + groups = roadmap["groups"] + group_ids = [group["id"] for group in groups] + duplicate_groups = sorted( + group_id + for group_id in set(group_ids) + if group_ids.count(group_id) > 1 + ) + if duplicate_groups: + raise ValueError(f"duplicate roadmap group IDs: {duplicate_groups}") + + items = [item for group in groups for item in group["items"]] + item_ids = [item["id"] for item in items] + duplicates = sorted( + item_id for item_id in set(item_ids) if item_ids.count(item_id) > 1 + ) + if duplicates: + raise ValueError(f"duplicate roadmap IDs: {duplicates}") + + known = set(item_ids) + broken = sorted( + (item["id"], dependency) + for item in items + for dependency in item["dependencies"] + if dependency not in known + ) + if broken: + raise ValueError(f"unknown roadmap dependencies: {broken}") + + dependencies = { + item["id"]: set(item["dependencies"]) + for item in items + } + pending = set(known) + while pending: + ready = { + item_id + for item_id in pending + if not (dependencies[item_id] & pending) + } + if not ready: + raise ValueError( + f"cyclic roadmap dependencies: {sorted(pending)}" + ) + pending -= ready + + if check_note_paths: + for item in items: + if item["status"] == "shipped": + note = ROOT / item["devNote"] + if not note.is_file(): + raise ValueError( + f"{item['id']} references absent development note: " + f"{note}" + ) + + +def main() -> None: + schema = json.loads(SCHEMA_PATH.read_text(encoding="utf-8")) + roadmap = yaml.safe_load(ROADMAP_PATH.read_text(encoding="utf-8")) + + jsonschema.Draft202012Validator.check_schema(schema) + validator = jsonschema.Draft202012Validator( + schema, + format_checker=jsonschema.Draft202012Validator.FORMAT_CHECKER, + ) + validate_roadmap(roadmap, validator, check_note_paths=True) + + for invalid_path in sorted(INVALID_ROADMAP_ROOT.glob("invalid-*.yaml")): + invalid = yaml.safe_load(invalid_path.read_text(encoding="utf-8")) + try: + validate_roadmap(invalid, validator, check_note_paths=False) + except (jsonschema.ValidationError, ValueError): + continue + raise ValueError( + f"expected roadmap validation to fail: {invalid_path}" + ) + + requirement_sources: dict[str, list[str]] = {} + for document in sorted(DOC_ROOT.glob("*.md")): + text = document.read_text(encoding="utf-8") + for requirement_id in REQUIREMENT_RE.findall(text): + requirement_sources.setdefault(requirement_id, []).append( + document.name + ) + + for target in MARKDOWN_LINK_RE.findall(text): + if "://" in target or target.startswith("#"): + continue + path_part = target.split("#", 1)[0] + linked_path = (document.parent / path_part).resolve() + if path_part and not linked_path.exists(): + raise ValueError( + f"broken local link in {document.name}: {target}" + ) + + duplicates = { + requirement_id: sources + for requirement_id, sources in requirement_sources.items() + if len(sources) > 1 + } + if duplicates: + raise ValueError(f"duplicate normative requirement IDs: {duplicates}") + + if len(requirement_sources) < 100: + raise ValueError( + "unexpectedly small normative requirement inventory: " + f"{len(requirement_sources)}" + ) + + print( + "processkit v1 specification contracts are valid " + f"({len(requirement_sources)} normative requirements)" + ) + + +if __name__ == "__main__": + main() diff --git a/spec/doc/v1/00-from-scratch-assessment.md b/spec/doc/v1/00-from-scratch-assessment.md new file mode 100644 index 00000000..942577ce --- /dev/null +++ b/spec/doc/v1/00-from-scratch-assessment.md @@ -0,0 +1,142 @@ +# From-scratch product and implementation assessment + +## Method + +This assessment begins with the product outcomes in this specification. It +does not assume that existing v0 behavior, the earlier v1 RFC, the 89-concept +ontology, released alpha artifacts, the Rust installer, or Python MCP servers +are the correct solution. + +Existing material was reviewed only to answer: + +- which user problems have demonstrated value; +- which failure modes and compatibility obligations are real; +- which architecture choices created duplicated authority or release cost; +- which experiments provide reusable evidence; and +- what existing adopters would need from an explicit migration. + +## Durable product findings + +The strongest validated product idea is not a particular ontology or +installer. It is a Git-native, human-readable process layer with validated +agent operations and durable evidence. WorkItems, decisions, discussions, +events, skills, and repository-local policy have repeatedly supported real +coordination. MCP is the appropriate provider-neutral agent boundary. + +These findings survive a clean redesign: + +1. Canonical project memory should remain in inspectable repository files. +2. Normal mutations need validated tools and lifecycle enforcement. +3. Derived indexes are valuable but must never become canonical state. +4. Installed content needs explicit ownership and safe three-way updates. +5. Harness projections should derive from one provider-neutral catalog. +6. A project must be usable without aibox or a hosted processkit service. +7. Cross-repository coordination requires explicit handoffs and ownership, + not a global shared writable context. + +## Root causes of drift + +### No single normative product baseline + +Product claims are distributed across an RFC, planning pages, architecture +notes, issue-status pages, release scripts, schemas, skills, MCP servers, +installer contracts, and observed dogfood behavior. Several development pages +explicitly describe themselves as historical while remaining the nearest +thing to a product specification. This makes conformance circular: current +code can be interpreted as the intended contract when prose is incomplete. + +### Ontology-first scope + +The former v1 effort made an 89-concept T/P/D/C ontology and first-ART coverage +central success measures. That work contains useful modeling research, but it +committed product scope before proving that each kernel concept required +cross-domain lifecycle enforcement. Vocabulary breadth increased schema, +migration, documentation, query, and agent-training obligations at once. + +The replacement uses a kernel test: a core concept must have cross-domain +lifecycle semantics that packages cannot safely express. Other vocabulary is +an extension, not a v1 release blocker. + +### Split behavioral authority + +The experimental architecture divided lifecycle installation and filesystem +mutation into Rust while leaving entity behavior, MCP, schema handling, +indexing, and skills in Python. This produced two model systems, two error +surfaces, two dependency and release toolchains, and machine contracts between +components whose ownership boundary followed implementation history rather +than product semantics. + +The replacement has one Python application core shared by CLI and MCP. Native +components remain possible only behind a measured, narrow contract. + +### Release machinery ahead of product closure + +The former branch invested substantially in native artifact signing, +installer requests, platform bootstrap, prerelease promotion, and recovery +while foundational entity, package, extension, and runtime semantics were +still evolving. Supply-chain and recovery work remains mandatory, but it +should prove an accepted product contract rather than stabilize an accidental +one. + +### Producer, dogfood, generated, and project state ambiguity + +The repository has needed repeated drift controls between producer content, +installed `context/`, generated schemas, MCP manifests, harness configuration, +and derived-project customizations. The replacement makes ownership class and +source-of-truth status part of package and installation contracts rather than +inferring them from directory conventions. + +## Language assessment + +The following weighting reflects this specification, not a generic language +comparison. + +| Criterion | Weight | Python | Go | Rust | +|---|---:|---:|---:|---:| +| Contract iteration and content tooling | 20 | 5 | 4 | 3 | +| MCP and agent ecosystem fit | 15 | 5 | 4 | 3 | +| Filesystem correctness and testability | 15 | 4 | 5 | 5 | +| Cross-platform application installation | 10 | 4 | 5 | 5 | +| Contributor and extension accessibility | 15 | 5 | 4 | 3 | +| Runtime performance and concurrency | 5 | 3 | 5 | 5 | +| One-language architectural coherence | 10 | 5 | 5 | 5 | +| Dependency and release simplicity | 10 | 4 | 5 | 3 | +| **Weighted result out of 500** | **100** | **455** | **450** | **380** | + +The numerical difference between Python and Go is intentionally small. Go is +the better choice for a native executable product; Python is the better choice +for the processkit product as specified because rapid contract iteration, +MCP integration, structured-content tooling, and contributor accessibility +slightly outweigh native distribution. `uv tool install` weakens the main Go +distribution advantage sufficiently to make Python the recommended choice. + +Rust offers excellent local safety but does not provide enough additional +product value to offset implementation and cross-ecosystem cost. The previous +work remains valuable as test cases for transactions, archives, trust, and +recovery, not as a language commitment. + +## Reuse, replace, and retire + +| Existing evidence | Treatment | +|---|---| +| Git-backed canonical entities | Preserve the product principle; re-specify formats. | +| MCP gateway and domain tools | Reuse behavior only where new conformance fixtures approve it. | +| SQLite/FTS indexing | Retain as the default derived adapter; rewrite behind a port. | +| Rust installer | Mine adversarial fixtures and transaction cases; replace implementation. | +| Python per-skill servers | Consolidate semantics into one application core; adapters may remain thin. | +| 89-concept ontology | Retain as optional package research; do not make it the kernel or GA gate. | +| v0 and v1-alpha corpora | Preserve as migration fixtures and compatibility evidence. | +| Signed release and recovery tests | Adapt to Python artifacts and the new ownership contract. | +| Existing public documentation | Archive by version; rewrite v1 docs from accepted behavior. | + +## Recommendation + +Accept this specification as a new baseline, reconcile the existing v1 branch +through a separate non-destructive branch plan, and implement the phases in +`roadmap.yaml` using Python 3.12+, uv, one shared application core, strict +public schemas, Git-native canonical state, and derived local indexes. + +Do not begin by porting Rust modules to Python. Begin with conformance fixtures +for the kernel, repository transaction, ownership, machine-result, and MCP +contracts. Existing code may then be retained only when it passes those +fixtures without redefining them. diff --git a/spec/doc/v1/01-product-definition.md b/spec/doc/v1/01-product-definition.md new file mode 100644 index 00000000..12152eba --- /dev/null +++ b/spec/doc/v1/01-product-definition.md @@ -0,0 +1,105 @@ +# Product definition + +## Purpose + +processkit is a local-first, provider-neutral process and project-memory +substrate for humans and AI agents working in software repositories. It turns +important project state into typed, inspectable, versioned records and exposes +safe operations over that state through a CLI and MCP. + +The product answers four questions without replaying chat history: + +1. What work, decisions, evidence, and risks exist? +2. What state are they in, and which transitions are valid? +3. Why did the state change, who or what changed it, and what evidence exists? +4. Which process capability should an agent use next? + +## Users + +- A project owner installs and upgrades a coherent process capability set. +- A human contributor reads and reviews canonical state in Git. +- An AI agent queries and mutates project state through validated tools. +- A process author creates reusable skills, schemas, state machines, and + process definitions. +- A harness or orchestrator integrates through stable MCP and machine + contracts without becoming a processkit dependency. +- A portfolio coordinator links work and evidence across repositories without + treating any single repository as a global mutable database. + +## Goals + +- **PK-PROD-001:** canonical project process state MUST remain human-readable, + Git-compatible, and usable without a hosted processkit service. +- **PK-PROD-002:** normal agent writes MUST pass through validated operations + that enforce schemas, lifecycle rules, ownership, and event recording. +- **PK-PROD-003:** the same public process semantics MUST be available to every + supported harness through provider-neutral contracts. +- **PK-PROD-004:** installation, upgrade, verification, and removal MUST + preserve project-owned changes or stop with an explicit conflict. +- **PK-PROD-005:** shipped content and runtime behavior MUST be versioned, + locally testable, and independently verifiable from release artifacts. +- **PK-PROD-006:** processkit MUST support one repository as one concern while + allowing explicit references and handoffs between independently owned + repositories. +- **PK-PROD-007:** project state MUST remain authoritative when indexes, + caches, generated references, or harness projections are absent. + +## Non-goals + +- **PK-PROD-010:** processkit MUST NOT run language models, own an agent loop, + schedule autonomous teams, or replace a harness or orchestrator. +- **PK-PROD-011:** processkit MUST NOT replace Git hosting, issue trackers, + code review, CI systems, chat, secrets managers, or artifact stores. +- **PK-PROD-012:** processkit MUST NOT require a central database, cloud + account, projectious.work service, aibox, or a specific AI provider. +- **PK-PROD-013:** processkit MUST NOT encode a single scaling framework, + organizational method, or model vendor as its universal ontology. +- **PK-PROD-014:** processkit MUST NOT make every Markdown file an entity or + claim that unstructured documentation has lifecycle semantics. +- **PK-PROD-015:** processkit v1 MUST NOT provide portfolio-wide distributed + transactions or pretend cross-repository operations are atomic. + +## Product boundary + +processkit owns: + +- contracts for process entities, relations, transitions, and events; +- reusable process content and its packaging metadata; +- local installation and reconciliation of processkit-owned files; +- validated CLI and MCP operations; +- derived local indexes and generated harness projections; +- compatibility, migration, verification, and diagnostic behavior. + +The consuming repository owns: + +- its entities and their meaning within the declared contracts; +- local policies, extensions, accepted overrides, and private content; +- Git history, review, retention, backup, and publication; +- authorization to mutate the repository; +- credentials and external-system integrations. + +The harness or orchestrator owns model execution, prompts outside shipped +skills, conversation state, task scheduling, agent isolation, cost control, +and cross-agent coordination. + +## Required user journeys + +- **PK-PROD-020:** a new user MUST be able to install a pinned release into a + disposable Git repository, verify it, start MCP, and create/read/transition + a WorkItem without aibox. +- **PK-PROD-021:** an existing project MUST be able to preview an update, + inspect every planned file action and conflict, apply it atomically within + documented limits, and verify the result. +- **PK-PROD-022:** an agent MUST be able to discover an applicable skill, + query the relevant entities, perform an allowed mutation, and observe the + resulting event without raw filesystem discovery. +- **PK-PROD-023:** a maintainer MUST be able to rebuild all derived indexes + and projections from canonical files. +- **PK-PROD-024:** a project with local extensions MUST be able to distinguish + upstream-owned, locally modified, project-owned, and generated paths. +- **PK-PROD-025:** a failed or interrupted mutation MUST leave either the + previous valid state or explicit recovery evidence; it MUST NOT claim + transactionality beyond what was achieved. +- **PK-PROD-026:** a project MUST be able to export a sanitized, bounded + handoff bundle and record an external reference without surrendering local + ownership or exposing private context by default. diff --git a/spec/doc/v1/02-conceptual-model.md b/spec/doc/v1/02-conceptual-model.md new file mode 100644 index 00000000..896c588d --- /dev/null +++ b/spec/doc/v1/02-conceptual-model.md @@ -0,0 +1,116 @@ +# Conceptual model + +## Design rule + +The core model is deliberately small. A concept belongs in the v1 kernel only +when processkit must validate its lifecycle or relationships consistently +across unrelated projects. Domain taxonomies belong in packages or project +extensions. + +The earlier 89-concept T/P/D/C model is useful research, but breadth is not a +v1 success criterion. The clean v1 model optimizes for coherent invariants, +composability, and migration rather than maximum vocabulary coverage. + +## Kernel concepts + +| Concept | Purpose | +|---|---| +| Entity | Persisted typed project record with identity and version. | +| EntityType | Schema, lifecycle, storage, and interface declaration. | +| StateMachine | Allowed states, transitions, guards, and terminal states. | +| Relation | Typed edge between addressable subjects. | +| Event | Append-only fact describing an observed process change. | +| Policy | Project-owned rule controlling authority or validation. | +| Package | Versioned set of content and compatibility declarations. | +| Capability | Discoverable operation or knowledge surface. | +| ProcessDefinition | Reusable ordered or branching workflow contract. | +| ProcessRun | Project-owned execution state and evidence for a definition. | + +## Standard entity types + +- **PK-MODEL-000:** the managed profile MUST include these standard + EntityTypes: + +- WorkItem; +- DecisionRecord; +- Discussion; +- Note; +- Artifact; +- Actor; +- Role; +- TeamMember; +- Binding; +- Scope; +- Gate; +- Migration; +- LogEntry; and +- ProcessRun. + +- **PK-MODEL-008:** profiles MAY omit EntityTypes they do not expose, but + installed schemas and tools MUST agree exactly. + +## Common envelope + +- **PK-MODEL-001:** every entity MUST declare a contract version, entity type, + stable ID, creation time, and typed specification. +- **PK-MODEL-002:** mutable entities SHOULD declare an update time and MUST + declare lifecycle state when their EntityType has a state machine. +- **PK-MODEL-003:** unknown fields MUST fail strict validation unless the + owning schema explicitly declares an extension map. +- **PK-MODEL-004:** extension fields MUST be namespaced and MUST NOT redefine + kernel or EntityType fields. +- **PK-MODEL-005:** IDs MUST be unique within a repository context and remain + stable across path changes. +- **PK-MODEL-006:** references MUST use typed IDs or declared external + references; filenames and Markdown links alone are not durable identity. +- **PK-MODEL-007:** a schema MUST distinguish absent, null, empty, and default + values whenever they have different semantics. + +## Lifecycle and mutation + +- **PK-MODEL-010:** every state transition MUST name its source, destination, + applicable guards, authority requirement, and emitted event. +- **PK-MODEL-011:** terminal-state mutation MUST be prohibited unless the + EntityType defines an explicit correction or supersession operation. +- **PK-MODEL-012:** historical decisions and events MUST be superseded or + corrected through traceable records, not silently rewritten. +- **PK-MODEL-013:** mutating operations MUST validate the complete resulting + entity before replacing canonical state. +- **PK-MODEL-014:** successful mutations MUST emit their required domain event + in the same operation boundary. +- **PK-MODEL-015:** failed validation or authorization MUST leave canonical + files and derived indexes unchanged. + +## Relations and interfaces + +- **PK-MODEL-020:** relations MUST declare type, subject, target, and optional + scope or validity bounds. +- **PK-MODEL-021:** relation types MUST define direction, cardinality, + endpoint constraints, inverse behavior, and deletion semantics. +- **PK-MODEL-022:** interfaces MAY group EntityTypes by capability, such as + `Record`, `Assignable`, or `Versioned`, but MUST NOT hide incompatible + lifecycle semantics. +- **PK-MODEL-023:** querying by interface MUST return the concrete EntityType + and contract version of every result. +- **PK-MODEL-024:** cross-repository references MUST carry repository identity, + object identity, and observed revision where reproducibility matters. +- **PK-MODEL-025:** unresolved external references MUST remain visible and + MUST NOT be treated as validated local relations. + +## Events + +- **PK-MODEL-030:** LogEntry is the canonical append-only event record. +- **PK-MODEL-031:** an event MUST identify event type, time, actor or system + authority, subject, outcome, and structured details appropriate to its type. +- **PK-MODEL-032:** event vocabulary and detail schemas MUST be versioned. +- **PK-MODEL-033:** operational logs MUST NOT be inserted into the domain + event stream merely because they are available. +- **PK-MODEL-034:** corrections append new evidence and preserve original + content or its cryptographic digest according to retention policy. + +## Extensibility test + +- **PK-MODEL-026:** a proposed new kernel concept MUST demonstrate at least two + unrelated product domains, lifecycle semantics that packages cannot express + safely, and a migration path. Otherwise it belongs in a package or project + namespace. diff --git a/spec/doc/v1/03-project-storage-and-ownership.md b/spec/doc/v1/03-project-storage-and-ownership.md new file mode 100644 index 00000000..9e34ee77 --- /dev/null +++ b/spec/doc/v1/03-project-storage-and-ownership.md @@ -0,0 +1,100 @@ +# Project storage and ownership + +## Canonical layout + +- **PK-STORE-000:** the default installed root is `context/`. A project MAY + configure another contained root before installation. The selected root is + recorded in processkit state and cannot change implicitly. + +```text +context/ + entities//... + schemas/... + state-machines/... + processes/... + skills/... + packages/... + policy/... + generated/... + .processkit/... +``` + +Exact sharding beneath an EntityType is declared by its storage contract. +Index databases, journals, locks, ownership manifests, and installed-release +metadata live below `.processkit/` and are not domain entities. + +## Sources of truth + +- **PK-STORE-001:** canonical entities, accepted project policy, and local + extensions MUST be ordinary files suitable for Git review. +- **PK-STORE-002:** SQLite databases, search indexes, caches, rendered indexes, + and harness projections MUST be rebuildable derived state. +- **PK-STORE-003:** generated schemas MAY be committed for review, but their + generator inputs and generation metadata MUST identify the authoritative + source and support a drift check. +- **PK-STORE-004:** release payload content and consuming-project state MUST + have distinct ownership; dogfood project entities MUST NOT enter a release. +- **PK-STORE-005:** processkit MUST NOT require users to commit caches, locks + used only for concurrency, or machine-specific paths. + +## File contract + +- **PK-STORE-010:** text contracts MUST use UTF-8, LF on serialization, and a + deterministic documented serialization policy. +- **PK-STORE-011:** entity bodies MAY use Markdown, but structural semantics + MUST remain in validated frontmatter or another declared structured region. +- **PK-STORE-012:** parsers MUST support the complete declared YAML subset and + MUST NOT locate frontmatter with ambiguous delimiter heuristics. +- **PK-STORE-013:** paths derived from IDs or user input MUST be normalized, + checked for containment, and rejected on traversal, symlink escape, special + files, or normalization collision. +- **PK-STORE-014:** writes MUST use temporary files in the destination + filesystem, flush as required by the durability profile, and replace + atomically where the platform supports it. +- **PK-STORE-015:** multi-file operations MUST use a journal and publish their + achieved guarantees; processkit MUST NOT label a sequence atomic when a + crash can expose an intermediate state. + +## Ownership classes + +Every managed path is classified as one of: + +- `release-owned`: exact bytes supplied by a pinned package; +- `mergeable`: upstream baseline with supported project customization; +- `project-owned`: created and controlled by the consuming project; +- `generated`: reproducible from declared inputs; or +- `runtime`: local cache, lock, journal, or index. + +- **PK-STORE-020:** installation manifests MUST record path, ownership class, + source package, source digest, installed digest, and applicable merge rule. +- **PK-STORE-021:** update MUST use recorded base, incoming release, and local + content for three-way reconciliation of mergeable files. +- **PK-STORE-022:** an unresolved semantic or textual conflict MUST stop before + canonical mutation and appear in both human and machine plans. +- **PK-STORE-023:** uninstall MUST remove only paths whose ownership and + unchanged state processkit can prove; modified or project-owned paths remain. +- **PK-STORE-024:** processkit MUST NOT silently overwrite an unknown existing + path, adopt it as owned, or delete an untracked path. + +## Concurrency and recovery + +- **PK-STORE-030:** mutating commands MUST acquire a root-scoped operation lock + with owner, process, start time, and safe stale-lock diagnostics. +- **PK-STORE-031:** concurrent reads MAY proceed from canonical files; index + readers MUST detect generation changes or use a consistent snapshot. +- **PK-STORE-032:** interruption MUST preserve a recovery journal until the + operation is completed, rolled back, or explicitly abandoned. +- **PK-STORE-033:** recovery MUST revalidate source hashes and current paths; + it MUST NOT replay stale operations onto changed content. +- **PK-STORE-034:** `verify` and `doctor` MUST distinguish invalid canonical + state, stale derived state, interrupted mutation, and benign local changes. +- **PK-STORE-035:** processkit MAY inspect Git root, tracked state, ignore + rules, and cleanliness for safety evidence but MUST NOT commit, merge, + rebase, push, fetch, switch branches, or modify Git configuration as an + implicit side effect of a lifecycle or entity operation. +- **PK-STORE-036:** a command requiring a clean worktree MUST report the exact + relevant dirty paths and allow no blanket assumption that unrelated changes + belong to processkit. +- **PK-STORE-037:** generated ignore-file updates are planned, bounded to a + marked processkit block, idempotent, and preserve surrounding project-owned + content. diff --git a/spec/doc/v1/04-content-packages-and-extensions.md b/spec/doc/v1/04-content-packages-and-extensions.md new file mode 100644 index 00000000..2a31f175 --- /dev/null +++ b/spec/doc/v1/04-content-packages-and-extensions.md @@ -0,0 +1,83 @@ +# Content, packages, and extensions + +## Content types + +processkit distributes process capability as independently inspectable files: + +- EntityType schemas and state machines; +- skills containing instructions, tools, configuration, and references; +- ProcessDefinitions; +- templates and maintained examples; +- policies and validation rules; +- harness-neutral capability metadata; +- harness projections generated from that metadata; and +- documentation tied to the owning content. + +## Package manifest + +- **PK-PKG-001:** every package MUST have a versioned manifest declaring name, + version, processkit compatibility, contents, dependencies, conflicts, + ownership classes, capabilities, and digests. +- **PK-PKG-002:** package dependency resolution MUST be deterministic for a + pinned release and MUST fail on cycles, absent dependencies, incompatible + ranges, duplicate ownership, or ambiguous capability providers. +- **PK-PKG-003:** profiles MUST be named selections of packages; they MUST NOT + duplicate package contents or alter package semantics implicitly. +- **PK-PKG-004:** the initial profiles are `minimal`, `managed`, `product`, + `research`, and `software`; each MUST publish an exact resolved manifest. +- **PK-PKG-005:** package and profile selection MUST be previewable without + filesystem mutation. + +## Skills + +- **PK-PKG-010:** a skill MUST declare stable identity, version, purpose, + triggers, inputs, outputs, owned capabilities, dependencies, side effects, + safety constraints, and progressive-disclosure resources. +- **PK-PKG-011:** skill instructions MUST be provider-neutral; provider or + harness adapters MAY project them into native discovery formats without + changing their semantics. +- **PK-PKG-012:** a skill that exposes MCP tools MUST declare those tools in a + machine-readable capability manifest whose schemas match runtime discovery. +- **PK-PKG-013:** skills MUST declare whether operations are read-only, + project-mutating, externally mutating, privileged, or destructive. +- **PK-PKG-014:** extension skills MUST NOT impersonate a reserved processkit + identity or override a core capability without explicit policy. + +## Processes + +- **PK-PKG-020:** a ProcessDefinition MUST declare ordered or branching steps, + entry conditions, completion conditions, required capabilities, evidence, + failure behavior, and resumability. +- **PK-PKG-021:** ProcessDefinitions describe coordination semantics; they MUST + NOT embed arbitrary executable code. +- **PK-PKG-022:** starting a durable process MUST create a ProcessRun or a + declared set of linked WorkItems so execution state is inspectable. +- **PK-PKG-023:** process overrides MUST identify the upstream definition and + compatibility range they replace. + +## Extension model + +- **PK-PKG-030:** projects MAY add namespaced EntityTypes, relation types, + skills, processes, policies, and packages under project-owned paths. +- **PK-PKG-031:** extensions MUST validate against published extension + metaschemas and MUST declare their namespace owner. +- **PK-PKG-032:** extension loading order MUST be deterministic and explicit; + directory traversal order MUST NOT affect behavior. +- **PK-PKG-033:** processkit MUST offer conformance commands that validate an + extension without installing it into a real project. +- **PK-PKG-034:** extension failures MUST be isolated and attributed; one + invalid optional extension MUST NOT silently disable unrelated core checks. +- **PK-PKG-035:** executable plugins are outside the default v1 extension + model. If introduced later, they require a separate trust, sandbox, signing, + and compatibility contract. + +## Harness projections + +- **PK-PKG-040:** one canonical capability catalog MUST generate supported + harness configuration and command/skill projections. +- **PK-PKG-041:** projection generation MUST preserve user-owned configuration + or stop with a conflict; generated files MUST carry provenance. +- **PK-PKG-042:** harness absence MUST NOT prevent package installation, + verification, CLI use, or manual MCP configuration. +- **PK-PKG-043:** adding a harness adapter MUST NOT change core entity or + process semantics. diff --git a/spec/doc/v1/05-application-and-lifecycle.md b/spec/doc/v1/05-application-and-lifecycle.md new file mode 100644 index 00000000..5405e07a --- /dev/null +++ b/spec/doc/v1/05-application-and-lifecycle.md @@ -0,0 +1,93 @@ +# Application and lifecycle + +## Distribution + +The reference implementation is installed as a Python application with +`uv tool install processkit==` or an equivalent isolated Python +application installer. Releases publish a wheel, source distribution, source +archive, checksums, SBOM, and signature or attestation material. + +- **PK-CLI-000:** the installed CLI is `processkit`; `pk` MAY be supplied as a + documented alias. All commands accept `--root` and operate on exactly one + project root. + +## Command surface + +| Command | Purpose | +|---|---| +| `processkit version` | Report product, source, runtime, and contract versions. | +| `processkit help` | Show stable command help. | +| `processkit init` | Create a new installation plan for an uninitialized root. | +| `processkit plan` | Preview install, update, profile, adapter, or removal changes. | +| `processkit apply --plan PLAN` | Apply an exact reviewed plan. | +| `processkit verify` | Verify ownership, contracts, projections, and derived state. | +| `processkit doctor [--reconcile]` | Diagnose and optionally apply bounded safe repairs. | +| `processkit migrate` | Plan or apply an explicit contract/data migration. | +| `processkit reindex` | Rebuild disposable indexes from canonical files. | +| `processkit generate` | Regenerate declared schemas, indexes, docs, or projections. | +| `processkit mcp serve` | Serve the configured MCP capability set. | +| `processkit mcp proxy` | Adapt stdio to an explicitly configured local MCP endpoint. | +| `processkit package validate` | Validate a package or extension in isolation. | + +- **PK-CLI-009:** EntityType- and skill-specific convenience commands MAY be + added after their MCP operations are stable. They use the same application + services rather than reimplementing semantics. + +## Lifecycle requirements + +- **PK-CLI-001:** lifecycle plans MUST bind root identity, operation, release, + profile, adapters, current ownership state, input digests, and expiration. +- **PK-CLI-002:** apply MUST refuse a plan when any bound input or relevant + target path changed after planning. +- **PK-CLI-003:** destructive changes require an explicit plan and confirmation; + non-interactive confirmation requires both `--non-interactive` and `--yes`. +- **PK-CLI-004:** `init`, `plan`, `verify`, and doctor without `--reconcile` + MUST be read-only with respect to canonical project state. +- **PK-CLI-005:** `doctor --reconcile` MAY repair only registered, + deterministic, idempotent, locally contained derived or processkit-owned + state. +- **PK-CLI-006:** doctor MUST NOT rewrite project entities, accept policy, + install runtimes, fetch releases, or resolve semantic conflicts. +- **PK-CLI-007:** migration MUST separate analysis, plan, application, and + verification and MUST preserve a recovery record. +- **PK-CLI-008:** all mutating commands MUST support interruption and report + whether rollback completed, recovery is required, or no mutation occurred. + +## Exit categories + +| Code | Category | +|---:|---| +| 0 | Success or completed diagnostic with no blocking finding. | +| 2 | Invalid invocation or malformed input. | +| 3 | Contract, policy, or compatibility refusal. | +| 4 | Conflict or stale plan. | +| 5 | Dependency or environment unavailable. | +| 6 | Operation failed with canonical state preserved. | +| 7 | Recovery or manual inspection required. | +| 130 | Interrupted by SIGINT where supported. | + +- **PK-CLI-010:** exit meanings MUST remain stable within v1.x. +- **PK-CLI-011:** commands MUST NOT use success for skipped required work, + unresolved conflicts, or unavailable checks that determine correctness. +- **PK-CLI-012:** cancellation and termination handling MUST be tested on every + supported operating system, with platform differences documented. + +## Supported environments + +- **PK-CLI-020:** v1 supports CPython 3.12 and later minor versions explicitly + listed in release metadata. +- **PK-CLI-021:** v1 targets current supported Linux, macOS, and Windows on + x86-64 and ARM64 where CPython and uv support are available; each release + MUST state its actually tested matrix. +- **PK-CLI-022:** default operation MUST be local and offline after application + and package installation; network access requires an explicit command or + authorized configuration. +- **PK-CLI-023:** no command may assume a shell, GNU userland, writable home + directory, or ambient Git credentials. +- **PK-CLI-024:** root selection resolves an explicit `--root`, then + `PROCESSKIT_ROOT`, then the nearest ancestor containing `processkit.toml` or + processkit installed-state metadata; otherwise it uses the current directory + only for `init` and fails for commands requiring an installation. +- **PK-CLI-025:** root discovery MUST NOT search configured root lists, cross a + filesystem boundary implicitly, select a descendant, or choose between + multiple repositories by basename. diff --git a/spec/doc/v1/06-agent-protocol-and-query-surface.md b/spec/doc/v1/06-agent-protocol-and-query-surface.md new file mode 100644 index 00000000..53bfeadc --- /dev/null +++ b/spec/doc/v1/06-agent-protocol-and-query-surface.md @@ -0,0 +1,95 @@ +# Agent protocol and query surface + +## MCP role + +MCP is processkit's primary agent-facing protocol. The CLI and MCP adapters +invoke the same application services and enforce identical validation, +authority, mutation, event, and recovery semantics. + +The default runtime is a single local process exposing a configured capability +catalog. Per-domain servers can be supported for isolation or debugging, but +do not define competing behavior. + +## Discovery + +- **PK-MCP-001:** runtime discovery MUST expose tool name, version, description, + input schema, output schema, side-effect class, owning capability, and + deprecation state. +- **PK-MCP-002:** discovered schemas MUST match the schemas used for runtime + validation and generated reference documentation. +- **PK-MCP-003:** tool names MUST be stable and collision-free; aliases MUST + declare their canonical replacement and removal horizon. +- **PK-MCP-004:** a configured capability absent at runtime is a startup or + verification failure, not a silently omitted tool. +- **PK-MCP-005:** list/read/search tools MUST be clearly distinguishable from + project-mutating and externally mutating tools. + +## Core read surface + +The managed profile provides operations equivalent to: + +```text +get_entity(id | path) +list_entities(type?, state?, scope?, limit?, cursor?) +search_entities(text, filters?, limit?, cursor?) +query_by_interface(interface, filters?, limit?, cursor?) +traverse_relations(subject, relation?, direction?, depth?) +events_for_subject(subject, after?, limit?, cursor?) +find_skill(task_description) +route_task(task_description, constraints?) +get_effective_configuration() +``` + +- **PK-MCP-010:** reads MUST come from canonical files or a verified index + generation and MUST report index staleness when freshness cannot be proven. +- **PK-MCP-011:** pagination order and cursors MUST be deterministic for a + stable generation. +- **PK-MCP-012:** search ranking MAY evolve compatibly, but filters, result + identity, and completeness claims MUST be explicit. +- **PK-MCP-013:** a query MUST not expose private entity bodies or sensitive + fields beyond the caller's configured local policy. + +## Mutation surface + +EntityTypes own typed create, update, transition, link, supersede, and archive +operations as applicable. + +- **PK-MCP-020:** mutating tools MUST accept structured requests and return a + versioned result containing outcome, affected IDs, emitted event IDs, + warnings, and recovery state. +- **PK-MCP-021:** tools MUST re-read and validate relevant state immediately + before commit; read-time observations are not mutation preconditions unless + bound by revision or digest. +- **PK-MCP-022:** optimistic concurrency MUST be available through an expected + revision or content digest. +- **PK-MCP-023:** partial multi-entity success MUST be prohibited unless the + operation contract explicitly defines partial outcomes and compensation. +- **PK-MCP-024:** idempotency keys SHOULD be supported for operations likely to + be retried by orchestrators. +- **PK-MCP-025:** authorization is local policy plus host-process authority; + MCP connectivity alone MUST NOT grant permission to bypass policy. + +## Runtime and transports + +- **PK-MCP-030:** stdio MUST be supported for local harness integration. +- **PK-MCP-031:** streamable HTTP MAY be supported only on loopback by default; + non-loopback binding requires explicit authorization and an authentication + and transport-security profile. +- **PK-MCP-032:** requests MUST have size and concurrency limits, cancellation, + timeouts, and bounded error payloads. +- **PK-MCP-033:** the server MUST isolate request context and correlation data; + concurrent responses MUST not leak data or diagnostics between requests. +- **PK-MCP-034:** graceful shutdown MUST stop accepting work, complete or + cancel active operations according to contract, flush evidence, and release + locks. + +## Cross-repository coordination + +- **PK-MCP-040:** processkit MAY expose export/import and external-reference + operations, but each call remains scoped to one explicitly selected root. +- **PK-MCP-041:** a cross-repository handoff MUST identify source repository, + source revision, owning entity, requested outcome, and sanitized evidence. +- **PK-MCP-042:** receiving a handoff MUST create local project-owned state; + it MUST NOT mutate the source repository or claim distributed completion. +- **PK-MCP-043:** portfolio orchestration remains a consumer of processkit + contracts and is outside the processkit agent runtime. diff --git a/spec/doc/v1/07-configuration-output-and-evidence.md b/spec/doc/v1/07-configuration-output-and-evidence.md new file mode 100644 index 00000000..6967877c --- /dev/null +++ b/spec/doc/v1/07-configuration-output-and-evidence.md @@ -0,0 +1,95 @@ +# Configuration, output, and evidence + +## Configuration hierarchy + +Configuration resolves from lower to higher precedence: + +```text +compiled defaults +→ system configuration +→ user configuration +→ project policy +→ environment variables +→ command-line or MCP invocation +``` + +- **PK-CONFIG-000:** the application MAY omit a system layer on platforms + without an appropriate location but MUST NOT reorder layers. + +- **PK-CONFIG-001:** configuration files MUST use a closed, versioned schema. +- **PK-CONFIG-002:** environment variables use the `PROCESSKIT_` prefix. +- **PK-CONFIG-003:** relative paths resolve against the file declaring them or + another explicitly documented anchor, never an accidental working directory. +- **PK-CONFIG-004:** project policy MUST NOT select executables, add + credentials, weaken user/system security, enable network listeners, or + redirect state outside allowed roots without higher-authority approval. +- **PK-CONFIG-005:** processkit MUST expose deterministic redacted effective + configuration with winning and overridden sources and rejected settings. +- **PK-CONFIG-006:** invocation overrides are ephemeral unless a dedicated + write command explicitly changes project-owned configuration. +- **PK-CONFIG-007:** project configuration is `/processkit.toml` by + default; project policy and mutable operational state MUST NOT share one + file. +- **PK-CONFIG-008:** system and user files use the operating system's published + application configuration locations and are reported by `doctor` and the + effective-configuration result even when absent. +- **PK-CONFIG-009:** environment and invocation layers MUST NOT change the + selected root after root discovery has loaded project policy; root selection + is resolved before other project configuration. + +## Result envelope + +Every machine result uses a closed versioned envelope containing: + +```text +apiVersion, command, outcome, result, diagnostics, correlationId +``` + +`outcome` distinguishes `succeeded`, `refused`, `failed`, `cancelled`, +`timed_out`, `partial`, and `recovery_required` where applicable. + +- **PK-OUTPUT-001:** JSON stdout MUST contain exactly one declared result + object and no logs, progress, banners, or child output. +- **PK-OUTPUT-002:** requested human results go to stdout and diagnostics to + stderr; non-interactive output is plain and colorless by default. +- **PK-OUTPUT-003:** result schemas, examples, and negative fixtures MUST cover + every command and outcome category. +- **PK-OUTPUT-004:** unknown fields and unsupported result API versions MUST + fail strict consumers. +- **PK-OUTPUT-005:** `version` output MUST report product version, source + commit, build/package provenance, Python runtime, platform, and supported + entity, package, plan, event, and machine-result contract versions. + +## Operational logging + +- **PK-LOG-001:** logs are structured semantic events rendered to configured + sinks after redaction. +- **PK-LOG-002:** events SHOULD include time, level, name, component, operation, + correlation ID, outcome, duration, and attributed dependency. +- **PK-LOG-003:** default level is `warning`; verbosity changes operational + detail, not result semantics. +- **PK-LOG-004:** file and network sinks require authorized configuration and + declare rotation, retention, failure, and privacy behavior. +- **PK-LOG-005:** sink failure MUST be surfaced without corrupting requested + output or canonical domain evidence. + +## Domain evidence + +- **PK-EVIDENCE-001:** entity events, migration journals, ownership manifests, + release records, and accepted gate results are durable evidence, not logs. +- **PK-EVIDENCE-002:** evidence retention and deletion follow project policy; + rotating logs MUST NOT erase authoritative evidence. +- **PK-EVIDENCE-003:** evidence must distinguish observed facts, user claims, + inferred conclusions, skipped checks, and unavailable dependencies. +- **PK-EVIDENCE-004:** export requires an explicit selection and redaction + policy; private context is excluded by default. + +## Redaction + +- **PK-REDACT-001:** secrets, secret-shaped values, personal data, sensitive + paths, and project-declared protected fields MUST be redacted before any + renderer, buffer, log sink, response, telemetry, or test artifact. +- **PK-REDACT-002:** redaction MUST cover structured values, free text, chunks, + exception chains, and concurrent streams. +- **PK-REDACT-003:** raw modes require explicit invocation and MUST still block + known secrets; their residual risk is documented. diff --git a/spec/doc/v1/08-security-and-trust.md b/spec/doc/v1/08-security-and-trust.md new file mode 100644 index 00000000..05af42a6 --- /dev/null +++ b/spec/doc/v1/08-security-and-trust.md @@ -0,0 +1,81 @@ +# Security and trust + +## Assets and boundaries + +Protected assets include project entities, unpublished discussions and notes, +credentials referenced by integrations, Git history, release packages, +ownership manifests, migration evidence, harness configuration, and generated +agent instructions. + +Trust boundaries exist between: + +- release publisher and installer; +- processkit-owned and project-owned content; +- project policy and user/system authority; +- MCP clients and the local runtime; +- canonical files and untrusted indexes or caches; +- package instructions and executable tools; +- one repository and external repositories or services. + +## Release trust + +- **PK-SEC-001:** installers MUST verify package integrity and authenticated + release provenance before mutation when signature material is supplied. +- **PK-SEC-002:** trust anchors MUST be configured independently of the + untrusted release being verified. +- **PK-SEC-003:** a checksum downloaded from the same unauthenticated location + as an artifact proves integrity in transit only, not publisher identity. +- **PK-SEC-004:** package manifests MUST bind every installed file digest, + ownership class, contract version, and dependency. +- **PK-SEC-005:** downgrade, prerelease adoption, and trust-anchor replacement + require explicit policy and confirmation. + +## Input and filesystem safety + +- **PK-SEC-010:** parsers MUST bound document size, nesting, collection counts, + string lengths, archive expansion, and decompression ratio. +- **PK-SEC-011:** archives MUST reject absolute paths, traversal, duplicate + normalized paths, symlink/hardlink escape, devices, sockets, and unsupported + metadata before extraction. +- **PK-SEC-012:** filesystem checks MUST be race-aware and repeated at commit + boundaries; validation of a path string alone is insufficient. +- **PK-SEC-013:** processkit MUST preserve restrictive permissions for private + runtime state and MUST not broaden permissions silently. +- **PK-SEC-014:** subprocesses, when unavoidable, use argument arrays, + controlled working directories, allowlisted environment, bounded IO, + timeout, and cancellation; shell evaluation is prohibited by default. + +## MCP and instruction safety + +- **PK-SEC-020:** MCP HTTP transport binds to loopback unless a reviewed remote + security profile is explicitly enabled. +- **PK-SEC-021:** mutating and destructive capabilities MUST be labeled for + harness policy and independently checked by processkit. +- **PK-SEC-022:** content from packages, entities, external references, and + imported bundles is untrusted data; it MUST NOT silently acquire executable + or higher-authority semantics because an agent reads it. +- **PK-SEC-023:** imported skills and processes remain disabled until package + trust and project policy accept them. +- **PK-SEC-024:** diagnostics MUST not recommend bypassing containment, + signature, validation, approval, or recovery checks. + +## Dependencies and privacy + +- **PK-SEC-030:** every direct runtime dependency MUST have a documented + purpose and reviewed license, maintenance, provenance, and transitive cost. +- **PK-SEC-031:** dependency and application lockfiles are committed and release + builds fail on unresolved or mutable dependency inputs. +- **PK-SEC-032:** default operation emits no telemetry and performs no network + egress. +- **PK-SEC-033:** tests use synthetic data, reserved domains, temporary roots, + and no ambient credentials or user configuration. +- **PK-SEC-034:** security defects add permanent negative regression coverage + and follow coordinated disclosure without moving published tags. + +## Threat-driven acceptance + +- **PK-SEC-040:** the release suite MUST include adversarial archives, symlink + races where the platform permits testing, malformed YAML/JSON, oversized + inputs, untrusted Markdown instructions, MCP request flooding, stale plans, + interrupted writes, signature failures, malicious package paths, and + redaction boundary cases. diff --git a/spec/doc/v1/09-architecture-and-language.md b/spec/doc/v1/09-architecture-and-language.md new file mode 100644 index 00000000..1c960f4c --- /dev/null +++ b/spec/doc/v1/09-architecture-and-language.md @@ -0,0 +1,95 @@ +# Architecture and language assessment + +## Decision drivers + +The implementation language is evaluated against the product defined here, +not against prior sunk cost. Highest-weight drivers are: + +1. correctness of schema, file, lifecycle, and reconciliation behavior; +2. speed of evolving process contracts before v1 stability; +3. MCP and AI-tooling ecosystem fit; +4. cross-platform installation and isolated dependency management; +5. testability of filesystems, failures, and protocol boundaries; +6. maintainer accessibility and extension authoring; +7. startup and memory efficiency; and +8. supply-chain surface and release complexity. + +## Assessment + +| Driver | Python | Go | Rust | +|---|---|---|---| +| Contract iteration and schema tooling | Strong | Good | Adequate | +| MCP and agent ecosystem integration | Strong | Good | Developing | +| Safe high-level YAML/Markdown processing | Strong | Good | Good but costly | +| Single native executable | Weak | Strong | Strong | +| Transactional filesystem implementation | Good with disciplined design | Strong | Strong | +| Extension and contributor accessibility | Strong | Good | Adequate | +| Cross-platform packaging | Strong with uv/PyPI | Strong | Strong | +| Runtime performance | Adequate | Strong | Strongest | +| Implementation complexity for this product | Lowest | Medium | Highest | + +Python wins because processkit is primarily a contract, content, filesystem, +and integration product whose model will continue to evolve through v1 +prereleases. Its performance requirements are modest and IO-bound. `uv tool +install` provides an isolated, reproducible application installation path, so +the absence of one native executable is not decisive. + +Go would be preferred if the dominant product requirement were a native, +dependency-free executable or a long-running high-concurrency service. Rust +would be preferred for a smaller security-critical native installer with +strict resource or embedded constraints. Neither is the primary v1 product. + +The earlier Rust CLI plus Python MCP split demonstrated useful safety ideas but +also created duplicated contracts, two toolchains, cross-language fixtures, +release complexity, and an unclear source of behavioral truth. v1 therefore +chooses one implementation language unless measured evidence later justifies a +narrow native component. + +## Reference architecture + +- **PK-ARCH-001:** the reference implementation MUST use Python 3.12 or later + as its sole required application language. +- **PK-ARCH-002:** the CLI, MCP server, validation, reconciliation, indexing, + migration, and generation surfaces MUST share one application core. +- **PK-ARCH-003:** public behavior MUST be defined by versioned schemas and + conformance fixtures, not Python module layout or implementation classes. +- **PK-ARCH-004:** the core MUST use explicit ports for filesystem, clock, + process, network, terminal, and index dependencies so tests can control them. +- **PK-ARCH-005:** a future native component requires measured need, a narrow + versioned boundary, independent fixtures, failure isolation, and an accepted + architecture decision. + +## Component boundaries + +```text +CLI / MCP adapters + ↓ +application services + ↓ +domain model and policies + ↓ +ports: repository, index, package, clock, process, network, rendering + ↓ +local adapters: filesystem, SQLite/FTS, uv/Python packaging, stdio/HTTP +``` + +- **PK-ARCH-010:** domain behavior MUST not depend on CLI parsing, MCP SDK + objects, SQLite rows, or ambient process globals. +- **PK-ARCH-011:** canonical repository mutation MUST have one implementation + path shared by CLI, MCP, migration, and reconciliation. +- **PK-ARCH-012:** SQLite with FTS is the default derived query adapter; a + different adapter MAY be added without changing canonical storage semantics. +- **PK-ARCH-013:** Pydantic or equivalent typed boundary models MAY be used, + but published JSON Schemas and fixtures remain the interoperability contract. +- **PK-ARCH-014:** network release resolution and external connectors are + optional adapters and MUST not enter the local domain core. + +## Dependency posture + +- **PK-ARCH-020:** the initial implementation SHOULD prefer maintained focused + libraries for CLI, MCP, YAML, JSON Schema, models, and platform directories. +- **PK-ARCH-021:** it SHOULD use the standard library for hashing, archives + where safely sufficient, atomic file operations, subprocess control, + logging foundations, and SQLite. Dependency selection is finalized during + implementation planning with locked versions and contract tests; this + specification does not bless a library by name. diff --git a/spec/doc/v1/10-verification-strategy.md b/spec/doc/v1/10-verification-strategy.md new file mode 100644 index 00000000..a48e42a5 --- /dev/null +++ b/spec/doc/v1/10-verification-strategy.md @@ -0,0 +1,79 @@ +# Verification strategy + +## Principles + +Default checks are offline, deterministic, credential-free, parallel-safe, +locale-independent, and isolated from real home directories and repositories. +Tests assert observable contracts and failure behavior, not only code paths. + +## Layers + +| Layer | Required evidence | +|---|---| +| Unit | Domain invariants, merge decisions, lifecycle guards, parsing, rendering, redaction. | +| Component | Repository transactions, indexes, package resolution, configuration, migration, MCP dispatch. | +| Contract | Schemas, positive/negative fixtures, CLI/MCP envelopes, generated-reference drift. | +| Black box | Installed CLI and MCP workflows in temporary repositories. | +| Integration | Supported Python, OS, filesystem, terminal, uv, Git, and harness adapters. | +| Disposable end to end | Signed artifact install, first workflow, update conflict, recovery, removal, and published-artifact verification. | + +## Required suites + +- **PK-TEST-001:** schema metaschema tests and positive/negative fixtures MUST + cover every public contract and format assertion. +- **PK-TEST-002:** every EntityType MUST test create, read, valid transition, + invalid transition, unknown field, malformed reference, concurrency conflict, + emitted event, and terminal behavior as applicable. +- **PK-TEST-003:** mutation tests MUST inject failures before and after each + durability boundary and assert canonical files, journals, indexes, and + reported recovery state. +- **PK-TEST-004:** install/update tests MUST cover clean install, idempotence, + unchanged update, local modification, compatible merge, conflict, stale plan, + interruption, recovery, downgrade refusal, and conservative uninstall. +- **PK-TEST-005:** MCP tests MUST compare runtime discovery with published + schemas and execute requests over stdio; HTTP tests cover loopback security, + concurrency, cancellation, bounds, and shutdown when HTTP ships. +- **PK-TEST-006:** query tests MUST compare indexed results with a canonical + scan across randomized create/update/archive sequences. +- **PK-TEST-007:** security suites MUST exercise every threat-driven case in + the security chapter and verify refusal plus redaction. +- **PK-TEST-008:** documentation examples and generated references MUST be + executed or schema-validated and checked for drift. +- **PK-TEST-009:** confirmed defects MUST gain permanent regression coverage at + the narrowest useful layer and at a public boundary when user-visible. + +## Property and fuzz testing + +- **PK-TEST-010:** property tests SHOULD cover serialization round trips, path + containment, three-way reconciliation invariants, state-machine + reachability, relation inverse rules, deterministic plans, and index + equivalence. Fuzz smoke tests cover structured parsers, frontmatter + boundaries, archives, machine envelopes, and MCP requests with bounded + resource use. + +## Platform matrix + +Every supported Python minor and release operating system is represented in +pre-release evidence. Filesystem-sensitive behavior is tested on case-sensitive +and case-insensitive filesystems where supported. Windows path, locking, +replacement, signal, and terminal differences receive explicit black-box +tests rather than being inferred from Linux success. + +## Gates + +- **Local fast:** formatting, lint, type check, unit/component subset, + contract fixtures, affected docs. +- **Change risk:** local fast plus selected migration, concurrency, fuzz, + security, compatibility, performance, and platform checks. +- **Pre-release:** complete matrix, dependency/license/vulnerability/secret + review, generated drift, docs, packages, clean-room extension conformance. +- **Release candidate:** exact wheel/source/archive verification and installed + black-box journeys. +- **Published release:** download, integrity/authenticity verification, + isolated installation, `version`, `help`, MCP startup, and first workflow. + +- **PK-TEST-020:** unexplained skips fail required gates. +- **PK-TEST-021:** flaky tests are defects; quarantine requires owner, issue, + scope, and expiry. +- **PK-TEST-022:** coverage is reviewed by risk and MUST NOT be substituted for + behavioral evidence or set as a context-free universal percentage. diff --git a/spec/doc/v1/11-compatibility-migration-and-release.md b/spec/doc/v1/11-compatibility-migration-and-release.md new file mode 100644 index 00000000..62913840 --- /dev/null +++ b/spec/doc/v1/11-compatibility-migration-and-release.md @@ -0,0 +1,117 @@ +# Compatibility, migration, and release + +## Version axes + +processkit versions these axes independently: + +- product release SemVer; +- entity API; +- package manifest; +- lifecycle plan and journal; +- machine result; +- event vocabulary; +- skill and ProcessDefinition contracts; and +- extension metaschemas. + +The proposed v1 identifiers are: + +| Contract | Identifier | +|---|---| +| Entity envelope and standard EntityTypes | `processkit.projectious.work/entity/v1` | +| Package and profile manifests | `processkit.projectious.work/package/v1` | +| Lifecycle plans and journals | `processkit.projectious.work/plan/v1` | +| Machine results | `processkit.projectious.work/result/v1` | +| Event vocabulary | `processkit.projectious.work/event/v1` | +| Application configuration | `processkit.projectious.work/config/v1` | +| Extension metadata | `processkit.projectious.work/extension/v1` | + +- **PK-COMPAT-000:** contract identifiers MUST include their semantic surface + and version. The previous unqualified `processkit.projectious.work/v2` + Entity API is a migration source, not the identifier for the clean v1 + contract family. + +- **PK-COMPAT-001:** `processkit version --format json` MUST report supported + versions for every public contract axis. +- **PK-COMPAT-002:** each contract MUST define unknown-version, unknown-field, + supported-window, deprecation, migration, and rollback behavior. +- **PK-COMPAT-003:** persisted data MUST NOT be silently reinterpreted under + changed semantics. +- **PK-COMPAT-004:** stricter validation, changed defaults, ordering changes, + new authority requirements, and performance-guarantee changes MUST be + classified for compatibility even when schema shape is unchanged. + +## Compatibility policy + +- **PK-COMPAT-005:** before v1.0.0, prereleases MAY make breaking changes with + migration notes and fixture updates. From v1.0.0 through v1.x: + +- additive optional fields and commands may be minor changes; +- bug fixes preserving declared semantics may be patches; +- removal, required-field addition, semantic reinterpretation, incompatible + validation, or persisted-layout break requires v2 unless an already-declared + v1 migration boundary permits it; +- deprecated public names remain for at least one minor release and six months, + unless a security issue requires faster removal. + +## Migration + +- **PK-MIG-001:** migration is an explicit source-contract to target-contract + transformation with preconditions, operations, expected hashes, validation, + evidence, and rollback limits. +- **PK-MIG-002:** analysis and planning MUST be read-only and available in the + machine result contract. +- **PK-MIG-003:** application MUST operate on a clean Git worktree or create a + complete contained backup, unless the user explicitly accepts a narrower + documented recovery boundary. +- **PK-MIG-004:** migrations MUST preserve unknown project-owned extensions or + stop; they MUST NOT drop fields to make data validate. +- **PK-MIG-005:** append-only events are not rewritten. Identity changes use + aliases, successor/predecessor relations, and new correction events. +- **PK-MIG-006:** v0 and earlier-v1-alpha importers are compatibility adapters, + not sources of v1 semantics. Each has representative golden corpora and a + field-level preservation report. +- **PK-MIG-007:** an unsupported or ambiguous transformation produces a manual + action and blocks completion; migration MUST NOT guess intent. + +## Release topology + +The v1 line follows the company version-line standard: + +```text +v1.x-dev → v1.x-pre-release → v1.x-release → main +``` + +Topic branches target `v1.x-dev`. Promotion branches are fast-forward-only +pointers and receive no unique commits. Because earlier experimental v1 +history already exists, adoption of this specification requires a separate +reviewed branch-reconciliation decision; this PR does not authorize rewriting +or force-updating a protected branch. + +## Artifacts and provenance + +- **PK-REL-001:** releases originate from a clean worktree and exact annotated, + preferably signed tag. +- **PK-REL-002:** publish wheel, source distribution, source archive, resolved + package manifests, schemas and fixtures, checksums, SBOMs, curated notes, + installation guidance, and signatures or attestations required by policy. +- **PK-REL-003:** build metadata MUST identify source commit, Python and uv + versions, dependency lock digest, supported contract versions, and platform + scope. +- **PK-REL-004:** candidate artifacts MUST be installed and tested without + repository-relative imports or undeclared network access. +- **PK-REL-005:** published artifacts MUST be downloaded and independently + verified before publication is considered complete. +- **PK-REL-006:** tags and artifacts are immutable; corrections use a new + version. + +## v1 acceptance sequence + +- `alpha`: kernel contracts, repository transactions, install/verify, and + minimal MCP workflow proven. +- `beta`: managed profile, extension conformance, migration corpus, complete + security and platform matrices proven; feature freeze begins. +- `rc`: documentation, compatibility, performance, package set, and exact + candidate journeys complete with no unexplained skips. +- final: every normative requirement classified, all blockers closed, stable + tag and artifacts independently verified, and migration/support policy + published. diff --git a/spec/doc/v1/12-documentation-and-acceptance.md b/spec/doc/v1/12-documentation-and-acceptance.md new file mode 100644 index 00000000..60fb3e90 --- /dev/null +++ b/spec/doc/v1/12-documentation-and-acceptance.md @@ -0,0 +1,78 @@ +# Documentation and acceptance + +## Documentation system + +- **PK-DOC-001:** public documentation MUST describe shipped behavior for the + selected version line and label planned behavior explicitly. +- **PK-DOC-002:** source, schemas, examples, CLI/MCP reference, and development + notes MUST evolve in the same change as the behavior they describe. +- **PK-DOC-003:** CLI, MCP, configuration, schema, package, and event references + MUST be generated or mechanically checked against canonical contracts. +- **PK-DOC-004:** the documentation site MUST build locally and publish static + output from `gh-pages` without project-authored GitHub Actions. +- **PK-DOC-005:** versioned documentation MUST preserve supported v0 material + during v1 development and clearly distinguish stable from prerelease lines. +- **PK-DOC-006:** maintained examples are product contracts and MUST run or + validate in release gates. + +The public information architecture covers overview, getting started, +concepts, how-to guides, reference, troubleshooting, roadmap, releases and +migration, contributing, and security. The README remains a concise entry +point, not a second specification. + +## Development evidence + +- **PK-DOC-010:** every non-trivial roadmap phase maintains a development note + recording implementation, boundaries, decisions, deviations, tests, + security, compatibility, documentation, and owned follow-up work. +- **PK-DOC-011:** `roadmap.yaml` is the canonical roadmap and validates against + the company-compatible roadmap schema. +- **PK-DOC-012:** an item becomes `shipped` only when it names a release and + development note and its conformance evidence is accepted. + +## Specification conformance + +Implementation follows the company spec-driven development-cycle standard. +The accepted baseline consists of every file in this directory, its schemas, +examples, governing decisions, and applicable company standards. + +- **PK-ACCEPT-001:** planning MUST inventory every normative requirement and + map it to implementation work, tests, documentation, and evidence. +- **PK-ACCEPT-002:** an independent reviewer MUST review both the plan and the + integrated result against every applicable requirement and executable + contract. +- **PK-ACCEPT-003:** specification defects stop affected implementation and + require an explicit corrective amendment and plan revision. +- **PK-ACCEPT-004:** implementation convenience MUST NOT silently redefine the + contract, and existing behavior MUST NOT be grandfathered without an + explicit compatibility decision. +- **PK-ACCEPT-005:** final conformance classifies every requirement as + satisfied, accepted not-applicable, authorized deferral, or blocker; unknown + and partially satisfied are not completion. + +## Final acceptance journeys + +1. Install an exact authenticated release into an empty temporary repository + on every supported platform. +2. Verify the installed profile and inspect effective configuration. +3. Start MCP over stdio and discover the declared capability catalog. +4. Create, query, transition, relate, and supersede representative entities; + verify events and index equivalence. +5. Run a durable process with a gate, evidence, interruption, and resumption. +6. Add and validate a namespaced extension package without core modification. +7. Preview and apply an update with unchanged, locally modified, mergeable, + conflicting, generated, and project-owned files. +8. Recover from injected interruption at each mutation boundary. +9. Import representative v0 and earlier-v1-alpha corpora with preservation + reports and explicit manual blockers. +10. Export a sanitized cross-repository handoff and receive it as local state. +11. Conservatively uninstall processkit while preserving modified and + project-owned content. +12. Build documentation and verify the exact published release artifacts. + +## Definition of v1.0.0 complete + +v1.0.0 is complete only when all normative requirements and acceptance +journeys are evidenced; security, migration, compatibility, documentation, +and platform support are published; no required check has an unexplained skip; +and the exact release artifacts pass independent post-publication verification. diff --git a/spec/doc/v1/13-standard-entity-types.md b/spec/doc/v1/13-standard-entity-types.md new file mode 100644 index 00000000..0380f48f --- /dev/null +++ b/spec/doc/v1/13-standard-entity-types.md @@ -0,0 +1,148 @@ +# Standard entity types + +This chapter defines the semantic minimum for the managed profile. The +implementation phase produces closed JSON Schemas, positive and negative +fixtures, and state-machine documents conforming to these requirements. + +## Work and reasoning + +### WorkItem + +- **PK-ENTITY-001:** WorkItem MUST record title, type, lifecycle state, + priority, description or acceptance outcome, and optional assignee, parent, + scope, dependencies, blockers, and governing decisions. +- **PK-ENTITY-002:** standard WorkItem types are `task`, `story`, `bug`, + `epic`, `spike`, and `chore`; extensions use namespaced values. +- **PK-ENTITY-003:** the default lifecycle is + `backlog → in_progress → review → done`, with explicit `blocked`, + `cancelled`, reopen, and correction paths. Terminal completion records + completion time and evidence where required. + +### DecisionRecord + +- **PK-ENTITY-010:** DecisionRecord MUST contain title, state, context, + decision, rationale, alternatives, consequences, deciders, and decision time + when accepted. +- **PK-ENTITY-011:** its lifecycle is `proposed → accepted → superseded` or + `proposed → rejected`; accepted history is not edited to represent a new + decision. +- **PK-ENTITY-012:** supersession MUST link both records and preserve the old + rationale independently of the new record. + +### Discussion + +- **PK-ENTITY-020:** Discussion MUST contain a driving question, state, + participants or audience, related subjects, and chronological contributions + or a durable body representing the inquiry. +- **PK-ENTITY-021:** discussion outcomes reference accepted DecisionRecords, + created WorkItems, promoted Artifacts, or an explicit no-decision result. +- **PK-ENTITY-022:** closing a Discussion MUST NOT imply agreement unless an + accepted outcome says so. + +### Note + +- **PK-ENTITY-030:** Note captures bounded uncommitted information as one of + `fleeting`, `insight`, `question`, or `reference`, with title, body, source, + tags, and optional review time. +- **PK-ENTITY-031:** promotion creates or links a durable target; it does not + silently mutate a Note into a different EntityType. + +## Evidence and governance + +### Artifact + +- **PK-ENTITY-040:** Artifact identifies a durable deliverable or external + pointer with name, kind, location or body, format, version, ownership, + producer, digest where reproducibility matters, and related subjects. +- **PK-ENTITY-041:** registration does not assert that an external location is + available or trusted; verification state and observed revision remain + explicit. + +### Gate + +- **PK-ENTITY-050:** Gate defines a stable check with description, kind, + validator contract, required authority, blocking behavior, and evidence + requirement. +- **PK-ENTITY-051:** evaluations are append-only events referencing the Gate; + a Gate definition MUST NOT be mutated after evaluation history in a way that + changes the meaning of past results. +- **PK-ENTITY-052:** outcomes are `passed`, `failed`, or `waived`; waiver + requires authority, reason, scope, and expiry or review condition. + +### Scope + +- **PK-ENTITY-060:** Scope defines a bounded project, release, milestone, + sprint, quarter, or namespaced interval with goals, optional parent, time + bounds, and lifecycle. +- **PK-ENTITY-061:** closing Scope MUST evaluate required completion gates and + record unresolved owned work rather than implying it disappeared. + +### Migration + +- **PK-ENTITY-070:** Migration records source/target contracts, state, + preconditions, operations, affected paths or entities, evidence, progress, + and applied or rejection outcome. +- **PK-ENTITY-071:** migration lifecycle and semantics follow the migration + requirements in the compatibility chapter and cannot embed arbitrary code. + +### LogEntry + +- **PK-ENTITY-080:** LogEntry uses the event contract from the conceptual model + and is append-only after successful creation. +- **PK-ENTITY-081:** event types have a registered owner and schema; unknown + event details MUST NOT be interpreted as a known event type. + +## People, teams, and relations + +### Actor + +- **PK-ENTITY-090:** Actor represents a human, AI agent, service, or + organization with display identity, active status, optional contact or + handle, declared capabilities, and privacy classification. +- **PK-ENTITY-091:** provider credentials, secret model identifiers, and + mutable runtime session state MUST NOT be stored in ordinary Actor entities. + +### Role + +- **PK-ENTITY-100:** Role defines provider-neutral responsibilities, required + capabilities or skills, and default scope; a Role is not a person or model. +- **PK-ENTITY-101:** changing the meaning of a Role with historical bindings + requires versioning or supersession rather than silent reinterpretation. + +### TeamMember + +- **PK-ENTITY-110:** TeamMember composes an Actor identity with team-facing + role defaults, persona, capability references, and bounded memory locations. +- **PK-ENTITY-111:** private memory, credentials, and runtime working state use + separately classified storage and are excluded from exports by default. +- **PK-ENTITY-112:** TeamMember identity remains provider-neutral; runtime + model selection is a policy or Binding resolved at invocation time. + +### Binding + +- **PK-ENTITY-120:** Binding is the canonical scoped or time-bounded relation + entity and contains relation type, subject, target, optional scope, + validity, conditions, and description. +- **PK-ENTITY-121:** Binding validation enforces the relation registry's + endpoint, cardinality, inverse, and temporal rules. + +## ProcessRun + +- **PK-ENTITY-130:** ProcessRun binds an exact ProcessDefinition version to a + project root, scope, initiator, inputs, ordered state, produced entities, + evidence, and completion or recovery outcome. +- **PK-ENTITY-131:** ProcessRun MUST expose the current actionable step and + MUST distinguish waiting, blocked, failed, cancelled, and completed. +- **PK-ENTITY-132:** process execution may coordinate external work but records + observed handoffs and results; it MUST NOT claim external completion without + evidence from the owning system or repository. + +## Schema acceptance + +- **PK-ENTITY-140:** every standard EntityType MUST publish a closed schema, + state machine where applicable, storage declaration, relation constraints, + event vocabulary, and valid/invalid fixtures. +- **PK-ENTITY-141:** schemas MUST reuse one versioned common envelope and + fragments without generating divergent copies of shared semantics. +- **PK-ENTITY-142:** generated schemas are release artifacts and MUST match + generator inputs byte-for-byte under the deterministic generation command. diff --git a/spec/doc/v1/14-performance-and-operations.md b/spec/doc/v1/14-performance-and-operations.md new file mode 100644 index 00000000..f6aeb50f --- /dev/null +++ b/spec/doc/v1/14-performance-and-operations.md @@ -0,0 +1,74 @@ +# Performance and operations + +processkit is local tooling, not a high-throughput distributed database. +Performance requirements protect interactive agent use and bound resource +exhaustion without allowing caches to redefine correctness. + +## Scale profile + +The v1 reference profile is one repository containing up to: + +- 100,000 canonical entities; +- 1,000,000 LogEntries; +- 10,000 relations returned by an explicitly bounded traversal; +- 1 GiB total structured context excluding externally referenced artifacts; +- 500 installed skills and ProcessDefinitions; and +- 16 concurrent read requests with one serialized root mutation. + +- **PK-PERF-000:** larger repositories MAY work but are outside the v1 + performance guarantee. + +## Interactive budgets + +- **PK-PERF-001:** after warm startup and with a verified index, single-entity + lookup and bounded metadata listing SHOULD complete within 100 ms at the + reference scale on the published reference machine. +- **PK-PERF-002:** bounded full-text search SHOULD return its first page within + 500 ms at the reference scale. +- **PK-PERF-003:** ordinary single-entity validation and mutation excluding + lock wait SHOULD complete within 500 ms and MUST not rebuild the full index. +- **PK-PERF-004:** CLI help and version SHOULD complete within 300 ms warm and + one second cold on the reference machine. +- **PK-PERF-005:** MCP stdio startup SHOULD advertise capabilities within two + seconds with installed dependencies and no network access. + +These are release objectives, not semantic timeouts. A slower correct result +must report measurement and remain cancellable; it must not bypass validation. + +## Bounds and degradation + +- **PK-PERF-010:** list, search, event, and traversal operations MUST require or + apply documented result limits and stable pagination. +- **PK-PERF-011:** relation traversal MUST bound depth, visited nodes, returned + edges, and execution time and report truncation explicitly. +- **PK-PERF-012:** index rebuild MUST stream or batch input and MUST NOT require + all entity bodies in memory simultaneously. +- **PK-PERF-013:** when an index is absent or stale, processkit MAY fall back to + bounded canonical scans but MUST identify degraded completeness or latency. +- **PK-PERF-014:** corrupted indexes are quarantined and rebuilt; they MUST NOT + cause canonical entity deletion or mutation. +- **PK-PERF-015:** request and parser limits are configurable only within + system/user authority bounds; project policy cannot disable protection. + +## Operational behavior + +- **PK-OPS-001:** `doctor` reports runtime, contract support, root identity, + lock and journal state, canonical validation, ownership drift, projection + drift, index generation, package consistency, and configured MCP readiness. +- **PK-OPS-002:** health output MUST distinguish `healthy`, `degraded`, + `blocked`, and `recovery_required`; unavailable optional checks are not + successes. +- **PK-OPS-003:** every finding has a stable code, severity, scope, evidence, + next action, and optional registered reconciler. +- **PK-OPS-004:** diagnostic collection MUST be available as a sanitized local + bundle with an explicit manifest and exclusion report. +- **PK-OPS-005:** processkit MUST expose its effective resource limits and + current derived-state generations in machine-readable diagnostics. + +## Benchmarks + +Pre-release evidence records reference hardware, operating system, Python +version, filesystem, corpus generator seed and digest, cold/warm state, sample +count, percentiles, and variance. Performance regression thresholds compare +like-for-like profiles and require review rather than silently updating a +golden number. diff --git a/spec/doc/v1/15-review-decisions.md b/spec/doc/v1/15-review-decisions.md new file mode 100644 index 00000000..2442544e --- /dev/null +++ b/spec/doc/v1/15-review-decisions.md @@ -0,0 +1,104 @@ +# Review decisions + +This draft is internally coherent but intentionally does not manufacture +approval for consequential choices. Review must accept, amend, or reject each +item before the specification becomes the implementation baseline. + +## D1 — Product kernel instead of ontology breadth + +**Proposal:** adopt the small kernel and standard managed EntityTypes in this +specification. Treat the former 89-concept T/P/D/C ontology as optional package +research, not the v1 kernel or release gate. + +**Reason:** only concepts requiring consistent cross-domain lifecycle +enforcement belong in the core. Vocabulary breadth multiplies migration, +schema, query, documentation, and agent-training obligations without proving +user value. + +**Impact:** previous ontology-first alpha behavior is not automatically carried +forward. Useful domain concepts can return through versioned packages. + +## D2 — Python as the sole required implementation language + +**Proposal:** implement CLI, MCP, domain services, reconciliation, migrations, +generation, and indexing in Python 3.12+, installed as an isolated application +with uv or an equivalent tool. + +**Reason:** Python narrowly outranks Go for this contract- and integration-heavy +product once uv weakens the native single-executable advantage. Rust does not +justify its additional delivery cost for the specified workload. + +**Impact:** the Rust installer is replaced, but its security, transaction, and +recovery fixtures remain implementation evidence. A native component requires +a later measured justification and versioned boundary. + +## D3 — One application core + +**Proposal:** CLI and MCP become adapters over one application and domain core; +per-skill servers may remain compatibility adapters but own no semantics. + +**Reason:** one mutation, validation, event, and recovery path prevents the +current split authority from recurring. + +**Impact:** module and process boundaries may change substantially even when a +public tool name survives. + +## D4 — Compatibility posture + +**Proposal:** support explicit migrations from maintained v0 corpora and +released earlier-v1-alpha corpora, while refusing to preserve alpha behavior +that conflicts with the accepted new contract. + +**Reason:** users deserve preservation and transparent incompatibility, not an +assumption that prerelease implementation details define the replacement. + +**Impact:** each source line needs golden corpora, field-level preservation +reports, manual-blocker behavior, and migration documentation. + +## D5 — Existing v1 branch reconciliation + +**Proposal:** keep this specification PR non-destructive. After acceptance, +prepare a separate reviewed reconciliation plan for the existing `v1.x-dev` +history and promotion branches. + +The plan must identify whether implementation proceeds by removing/replacing +experimental files through ordinary commits, introducing a new version line, +or another ancestry-preserving method. Force-push, tag movement, and unique +commits on promotion branches remain prohibited. + +**Reason:** accepting a new product baseline does not authorize rewriting +published alpha history or protected branches. + +**Impact:** implementation cannot begin until the target branch and handling of +existing alpha support are explicit. + +## D6 — Specification artifact location + +**Proposal:** use `spec/doc/v1/` and `spec/schemas/v1/` for this baseline while +the company discussion on OpenSpec, specifications, and processkit remains +open. Treat this as a project-local choice, not a company-wide directory +standard. + +**Reason:** the implementation needs a bounded reviewable baseline now, while +the broader question of representing specifications as processkit artifacts is +still unresolved. + +**Impact:** a later accepted company model may migrate these files without +changing their normative meaning or history. + +## D7 — Contract namespaces + +**Proposal:** use surface-qualified identifiers such as +`processkit.projectious.work/entity/v1` and +`processkit.projectious.work/result/v1` instead of continuing the old +unqualified `processkit.projectious.work/v2` value. + +**Reason:** product release, entities, packages, machine results, plans, +events, configuration, and extensions have independent compatibility +lifecycles. One unqualified counter cannot express or evolve those contracts +safely. + +**Impact:** existing `processkit.projectious.work/v2` entities require an +explicit source adapter. The apparent numeric move from `v2` to a qualified +`entity/v1` is a namespace change, not a claim that old data has been silently +downgraded. diff --git a/spec/doc/v1/README.md b/spec/doc/v1/README.md new file mode 100644 index 00000000..a91aa865 --- /dev/null +++ b/spec/doc/v1/README.md @@ -0,0 +1,54 @@ +# processkit v1.x product specification + +Status: **draft for review** + +This directory defines the proposed normative baseline for a clean processkit +v1.x implementation. Existing v0 code, the earlier v1 alpha implementation, +and its Rust/Python architecture are evidence only. They do not define this +contract unless a requirement below deliberately preserves their behavior. + +Normative terms `MUST`, `MUST NOT`, `SHOULD`, `SHOULD NOT`, and `MAY` have the +meanings defined by RFC 2119 and RFC 8174. + +## Reading order + +1. [From-scratch assessment](00-from-scratch-assessment.md) +2. [Product definition](01-product-definition.md) +3. [Conceptual model](02-conceptual-model.md) +4. [Project storage and ownership](03-project-storage-and-ownership.md) +5. [Content, packages, and extensions](04-content-packages-and-extensions.md) +6. [Application and lifecycle](05-application-and-lifecycle.md) +7. [Agent protocol and query surface](06-agent-protocol-and-query-surface.md) +8. [Configuration, output, and + evidence](07-configuration-output-and-evidence.md) +9. [Security and trust](08-security-and-trust.md) +10. [Architecture and language assessment](09-architecture-and-language.md) +11. [Verification strategy](10-verification-strategy.md) +12. [Compatibility, migration, and + release](11-compatibility-migration-and-release.md) +13. [Documentation and acceptance](12-documentation-and-acceptance.md) +14. [Standard entity types](13-standard-entity-types.md) +15. [Performance and operations](14-performance-and-operations.md) +16. [Review decisions](15-review-decisions.md) +17. [Roadmap](roadmap.yaml) + +## Contract hierarchy + +Where documents disagree, executable schemas and fixtures govern structural +shape, numbered normative requirements govern semantics, and explanatory prose +provides intent. A contradiction is a specification defect and requires an +explicit baseline amendment before affected implementation continues. + +## Product profiles + +processkit is a composite product with these company-standard profiles: + +- CLI application; +- local service or worker for MCP transports; +- schema, protocol, and process package; +- Python library for internal composition and tested extension points; and +- documentation website. + +The v1 implementation follows the company standards for configuration, +application output and logging, compatibility, security, verification, +roadmaps, documentation, branching, and spec-driven development. diff --git a/spec/doc/v1/roadmap.yaml b/spec/doc/v1/roadmap.yaml new file mode 100644 index 00000000..1d40a30d --- /dev/null +++ b/spec/doc/v1/roadmap.yaml @@ -0,0 +1,84 @@ +apiVersion: roadmap.projectious.work/v1 +kind: ProductRoadmap +metadata: + project: processkit + versionLine: v1.x +groups: + - id: foundation + title: Product and contract foundation + items: + - id: PK1-P0 + title: Accept the v1 product baseline + summary: >- + Establish one coherent normative product contract and reconcile the + existing experimental branch without inheriting accidental design. + status: in_progress + dependencies: [] + decisions: + - "DEC-20260807_1003-LucidGarnet-re-specify-and-\ + reimplement-the-processkit" + issues: + - "BACK-20260807_1003-WarmHawk-specify-processkit-v1-from-\ + first-principles" + - id: PK1-P1 + title: Prove the kernel and repository transaction model + summary: >- + Deliver typed kernel contracts, safe canonical storage, lifecycle + enforcement, events, and deterministic recovery. + status: planned + dependencies: [PK1-P0] + - id: PK1-P2 + title: Deliver standalone installation and verification + summary: >- + Let users install, plan, update, verify, recover, and conservatively + remove an exact release without aibox. + status: planned + dependencies: [PK1-P1] + - id: agent-surface + title: Agent and authoring surface + items: + - id: PK1-P3 + title: Deliver the minimal MCP workflow + summary: >- + Provide discovery, query, validated mutation, events, configuration + inspection, and stdio transport from one application core. + status: planned + dependencies: [PK1-P1, PK1-P2] + - id: PK1-P4 + title: Stabilize managed packages and extensions + summary: >- + Ship deterministic profiles, provider-neutral skills and processes, + conformance tooling, and safe harness projections. + status: planned + dependencies: [PK1-P3] + - id: PK1-P5 + title: Prove migration and cross-repository handoff + summary: >- + Preserve representative v0 and alpha corpora and exchange bounded + handoffs without distributed ownership claims. + status: planned + dependencies: [PK1-P3, PK1-P4] + - id: release + title: Stabilization and release + items: + - id: PK1-P6 + title: Complete beta conformance + summary: >- + Pass the full contract, security, extension, migration, platform, + documentation, and package matrices and enter feature freeze. + status: planned + dependencies: [PK1-P5] + - id: PK1-P7 + title: Verify release candidates + summary: >- + Prove every acceptance journey using exact candidate artifacts with + no unexplained skips. + status: planned + dependencies: [PK1-P6] + - id: PK1-P8 + title: Publish and verify processkit v1.0.0 + summary: >- + Publish the accepted stable commit and independently verify + installation, MCP, migration, documentation, and first-use behavior. + status: planned + dependencies: [PK1-P7] diff --git a/spec/schemas/v1/roadmap.schema.json b/spec/schemas/v1/roadmap.schema.json new file mode 100644 index 00000000..c8fa5f8b --- /dev/null +++ b/spec/schemas/v1/roadmap.schema.json @@ -0,0 +1,78 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.projectious.work/processkit/v1/roadmap.schema.json", + "title": "processkit v1 roadmap", + "type": "object", + "additionalProperties": false, + "required": ["apiVersion", "kind", "metadata", "groups"], + "properties": { + "apiVersion": {"const": "roadmap.projectious.work/v1"}, + "kind": {"const": "ProductRoadmap"}, + "metadata": { + "type": "object", + "additionalProperties": false, + "required": ["project", "versionLine"], + "properties": { + "project": {"const": "processkit"}, + "versionLine": {"const": "v1.x"} + } + }, + "groups": { + "type": "array", + "minItems": 1, + "items": {"$ref": "#/$defs/group"} + } + }, + "$defs": { + "id": {"type": "string", "pattern": "^[A-Z][A-Z0-9]+(?:-[A-Z0-9]+)+$"}, + "group": { + "type": "object", + "additionalProperties": false, + "required": ["id", "title", "items"], + "properties": { + "id": {"type": "string", "pattern": "^[a-z][a-z0-9-]+$"}, + "title": {"type": "string", "minLength": 1}, + "items": { + "type": "array", + "minItems": 1, + "items": {"$ref": "#/$defs/item"} + } + } + }, + "item": { + "type": "object", + "additionalProperties": false, + "required": ["id", "title", "summary", "status", "dependencies"], + "properties": { + "id": {"$ref": "#/$defs/id"}, + "title": {"type": "string", "minLength": 1}, + "summary": {"type": "string", "minLength": 1}, + "status": {"enum": ["idea", "planned", "in_progress", "shipped", "cancelled"]}, + "target": {"type": "string", "minLength": 1}, + "dependencies": { + "type": "array", + "items": {"$ref": "#/$defs/id"}, + "uniqueItems": true + }, + "issues": { + "type": "array", + "items": {"type": "string", "minLength": 1}, + "uniqueItems": true + }, + "decisions": { + "type": "array", + "items": {"type": "string", "minLength": 1}, + "uniqueItems": true + }, + "devNote": {"type": "string", "minLength": 1}, + "release": {"type": "string", "minLength": 1} + }, + "allOf": [ + { + "if": {"properties": {"status": {"const": "shipped"}}}, + "then": {"required": ["devNote", "release"]} + } + ] + } + } +} diff --git a/spec/tests/v1/roadmap/invalid-broken-dependency.yaml b/spec/tests/v1/roadmap/invalid-broken-dependency.yaml new file mode 100644 index 00000000..916b7131 --- /dev/null +++ b/spec/tests/v1/roadmap/invalid-broken-dependency.yaml @@ -0,0 +1,14 @@ +apiVersion: roadmap.projectious.work/v1 +kind: ProductRoadmap +metadata: + project: processkit + versionLine: v1.x +groups: + - id: invalid + title: Invalid + items: + - id: PK1-BAD1 + title: Broken dependency + summary: References an absent roadmap item. + status: planned + dependencies: [PK1-MISSING] diff --git a/spec/tests/v1/roadmap/invalid-cycle.yaml b/spec/tests/v1/roadmap/invalid-cycle.yaml new file mode 100644 index 00000000..3dd13bef --- /dev/null +++ b/spec/tests/v1/roadmap/invalid-cycle.yaml @@ -0,0 +1,19 @@ +apiVersion: roadmap.projectious.work/v1 +kind: ProductRoadmap +metadata: + project: processkit + versionLine: v1.x +groups: + - id: invalid + title: Invalid + items: + - id: PK1-BAD1 + title: First cyclic item + summary: Depends on the second cyclic item. + status: planned + dependencies: [PK1-BAD2] + - id: PK1-BAD2 + title: Second cyclic item + summary: Depends on the first cyclic item. + status: planned + dependencies: [PK1-BAD1] diff --git a/spec/tests/v1/roadmap/invalid-duplicate-id.yaml b/spec/tests/v1/roadmap/invalid-duplicate-id.yaml new file mode 100644 index 00000000..bf050f82 --- /dev/null +++ b/spec/tests/v1/roadmap/invalid-duplicate-id.yaml @@ -0,0 +1,19 @@ +apiVersion: roadmap.projectious.work/v1 +kind: ProductRoadmap +metadata: + project: processkit + versionLine: v1.x +groups: + - id: invalid + title: Invalid + items: + - id: PK1-BAD1 + title: First duplicate + summary: Uses a duplicated roadmap ID. + status: planned + dependencies: [] + - id: PK1-BAD1 + title: Second duplicate + summary: Uses the same roadmap ID. + status: planned + dependencies: [] diff --git a/spec/tests/v1/roadmap/invalid-shipped-evidence.yaml b/spec/tests/v1/roadmap/invalid-shipped-evidence.yaml new file mode 100644 index 00000000..d4631aa6 --- /dev/null +++ b/spec/tests/v1/roadmap/invalid-shipped-evidence.yaml @@ -0,0 +1,14 @@ +apiVersion: roadmap.projectious.work/v1 +kind: ProductRoadmap +metadata: + project: processkit + versionLine: v1.x +groups: + - id: invalid + title: Invalid + items: + - id: PK1-BAD1 + title: Shipped without evidence + summary: Omits the required release and development note. + status: shipped + dependencies: [] diff --git a/spec/tests/v1/roadmap/invalid-status.yaml b/spec/tests/v1/roadmap/invalid-status.yaml new file mode 100644 index 00000000..9bdfa1e6 --- /dev/null +++ b/spec/tests/v1/roadmap/invalid-status.yaml @@ -0,0 +1,14 @@ +apiVersion: roadmap.projectious.work/v1 +kind: ProductRoadmap +metadata: + project: processkit + versionLine: v1.x +groups: + - id: invalid + title: Invalid + items: + - id: PK1-BAD1 + title: Unknown status + summary: Uses a status outside the standard vocabulary. + status: almost_done + dependencies: [] From b8f3cdc39ffd3cb4d5bf79266290bc96317179fe Mon Sep 17 00:00:00 2001 From: projectious Date: Fri, 7 Aug 2026 17:53:17 +0200 Subject: [PATCH 2/6] docs(spec): require complete v1 ontology --- spec/doc/v1/00-from-scratch-assessment.md | 142 ------------------ spec/doc/v1/01-product-definition.md | 7 + spec/doc/v1/02-conceptual-model.md | 111 ++++++++------ .../v1/03-project-storage-and-ownership.md | 8 + .../v1/04-content-packages-and-extensions.md | 14 +- .../v1/06-agent-protocol-and-query-surface.md | 8 + spec/doc/v1/09-architecture-and-language.md | 18 ++- spec/doc/v1/10-verification-strategy.md | 4 + .../11-compatibility-migration-and-release.md | 9 +- .../doc/v1/12-documentation-and-acceptance.md | 23 ++- spec/doc/v1/13-standard-entity-types.md | 52 +++++-- spec/doc/v1/14-performance-and-operations.md | 2 +- spec/doc/v1/15-review-decisions.md | 21 +-- spec/doc/v1/README.md | 33 ++-- spec/doc/v1/roadmap.yaml | 19 ++- 15 files changed, 212 insertions(+), 259 deletions(-) delete mode 100644 spec/doc/v1/00-from-scratch-assessment.md diff --git a/spec/doc/v1/00-from-scratch-assessment.md b/spec/doc/v1/00-from-scratch-assessment.md deleted file mode 100644 index 942577ce..00000000 --- a/spec/doc/v1/00-from-scratch-assessment.md +++ /dev/null @@ -1,142 +0,0 @@ -# From-scratch product and implementation assessment - -## Method - -This assessment begins with the product outcomes in this specification. It -does not assume that existing v0 behavior, the earlier v1 RFC, the 89-concept -ontology, released alpha artifacts, the Rust installer, or Python MCP servers -are the correct solution. - -Existing material was reviewed only to answer: - -- which user problems have demonstrated value; -- which failure modes and compatibility obligations are real; -- which architecture choices created duplicated authority or release cost; -- which experiments provide reusable evidence; and -- what existing adopters would need from an explicit migration. - -## Durable product findings - -The strongest validated product idea is not a particular ontology or -installer. It is a Git-native, human-readable process layer with validated -agent operations and durable evidence. WorkItems, decisions, discussions, -events, skills, and repository-local policy have repeatedly supported real -coordination. MCP is the appropriate provider-neutral agent boundary. - -These findings survive a clean redesign: - -1. Canonical project memory should remain in inspectable repository files. -2. Normal mutations need validated tools and lifecycle enforcement. -3. Derived indexes are valuable but must never become canonical state. -4. Installed content needs explicit ownership and safe three-way updates. -5. Harness projections should derive from one provider-neutral catalog. -6. A project must be usable without aibox or a hosted processkit service. -7. Cross-repository coordination requires explicit handoffs and ownership, - not a global shared writable context. - -## Root causes of drift - -### No single normative product baseline - -Product claims are distributed across an RFC, planning pages, architecture -notes, issue-status pages, release scripts, schemas, skills, MCP servers, -installer contracts, and observed dogfood behavior. Several development pages -explicitly describe themselves as historical while remaining the nearest -thing to a product specification. This makes conformance circular: current -code can be interpreted as the intended contract when prose is incomplete. - -### Ontology-first scope - -The former v1 effort made an 89-concept T/P/D/C ontology and first-ART coverage -central success measures. That work contains useful modeling research, but it -committed product scope before proving that each kernel concept required -cross-domain lifecycle enforcement. Vocabulary breadth increased schema, -migration, documentation, query, and agent-training obligations at once. - -The replacement uses a kernel test: a core concept must have cross-domain -lifecycle semantics that packages cannot safely express. Other vocabulary is -an extension, not a v1 release blocker. - -### Split behavioral authority - -The experimental architecture divided lifecycle installation and filesystem -mutation into Rust while leaving entity behavior, MCP, schema handling, -indexing, and skills in Python. This produced two model systems, two error -surfaces, two dependency and release toolchains, and machine contracts between -components whose ownership boundary followed implementation history rather -than product semantics. - -The replacement has one Python application core shared by CLI and MCP. Native -components remain possible only behind a measured, narrow contract. - -### Release machinery ahead of product closure - -The former branch invested substantially in native artifact signing, -installer requests, platform bootstrap, prerelease promotion, and recovery -while foundational entity, package, extension, and runtime semantics were -still evolving. Supply-chain and recovery work remains mandatory, but it -should prove an accepted product contract rather than stabilize an accidental -one. - -### Producer, dogfood, generated, and project state ambiguity - -The repository has needed repeated drift controls between producer content, -installed `context/`, generated schemas, MCP manifests, harness configuration, -and derived-project customizations. The replacement makes ownership class and -source-of-truth status part of package and installation contracts rather than -inferring them from directory conventions. - -## Language assessment - -The following weighting reflects this specification, not a generic language -comparison. - -| Criterion | Weight | Python | Go | Rust | -|---|---:|---:|---:|---:| -| Contract iteration and content tooling | 20 | 5 | 4 | 3 | -| MCP and agent ecosystem fit | 15 | 5 | 4 | 3 | -| Filesystem correctness and testability | 15 | 4 | 5 | 5 | -| Cross-platform application installation | 10 | 4 | 5 | 5 | -| Contributor and extension accessibility | 15 | 5 | 4 | 3 | -| Runtime performance and concurrency | 5 | 3 | 5 | 5 | -| One-language architectural coherence | 10 | 5 | 5 | 5 | -| Dependency and release simplicity | 10 | 4 | 5 | 3 | -| **Weighted result out of 500** | **100** | **455** | **450** | **380** | - -The numerical difference between Python and Go is intentionally small. Go is -the better choice for a native executable product; Python is the better choice -for the processkit product as specified because rapid contract iteration, -MCP integration, structured-content tooling, and contributor accessibility -slightly outweigh native distribution. `uv tool install` weakens the main Go -distribution advantage sufficiently to make Python the recommended choice. - -Rust offers excellent local safety but does not provide enough additional -product value to offset implementation and cross-ecosystem cost. The previous -work remains valuable as test cases for transactions, archives, trust, and -recovery, not as a language commitment. - -## Reuse, replace, and retire - -| Existing evidence | Treatment | -|---|---| -| Git-backed canonical entities | Preserve the product principle; re-specify formats. | -| MCP gateway and domain tools | Reuse behavior only where new conformance fixtures approve it. | -| SQLite/FTS indexing | Retain as the default derived adapter; rewrite behind a port. | -| Rust installer | Mine adversarial fixtures and transaction cases; replace implementation. | -| Python per-skill servers | Consolidate semantics into one application core; adapters may remain thin. | -| 89-concept ontology | Retain as optional package research; do not make it the kernel or GA gate. | -| v0 and v1-alpha corpora | Preserve as migration fixtures and compatibility evidence. | -| Signed release and recovery tests | Adapt to Python artifacts and the new ownership contract. | -| Existing public documentation | Archive by version; rewrite v1 docs from accepted behavior. | - -## Recommendation - -Accept this specification as a new baseline, reconcile the existing v1 branch -through a separate non-destructive branch plan, and implement the phases in -`roadmap.yaml` using Python 3.12+, uv, one shared application core, strict -public schemas, Git-native canonical state, and derived local indexes. - -Do not begin by porting Rust modules to Python. Begin with conformance fixtures -for the kernel, repository transaction, ownership, machine-result, and MCP -contracts. Existing code may then be retained only when it passes those -fixtures without redefining them. diff --git a/spec/doc/v1/01-product-definition.md b/spec/doc/v1/01-product-definition.md index 12152eba..1537d96d 100644 --- a/spec/doc/v1/01-product-definition.md +++ b/spec/doc/v1/01-product-definition.md @@ -43,6 +43,10 @@ The product answers four questions without replaying chat history: repositories. - **PK-PROD-007:** project state MUST remain authoritative when indexes, caches, generated references, or harness projections are absent. +- **PK-PROD-008:** v1 MUST provide the complete 89-concept T/P/D/C ontology + defined in the conceptual-model chapter so users can express broad process, + organizational, evidence, planning, and agentic-work concepts without + overloading a reduced set of generic records. ## Non-goals @@ -103,3 +107,6 @@ and cross-agent coordination. - **PK-PROD-026:** a project MUST be able to export a sanitized, bounded handoff bundle and record an external reference without surrendering local ownership or exposing private context by default. +- **PK-PROD-027:** a user MUST be able to validate, create or compose, query, + relate, and inspect every applicable concept in the complete v1 ontology + through its declared schema and interfaces. diff --git a/spec/doc/v1/02-conceptual-model.md b/spec/doc/v1/02-conceptual-model.md index 896c588d..7dd36caa 100644 --- a/spec/doc/v1/02-conceptual-model.md +++ b/spec/doc/v1/02-conceptual-model.md @@ -1,53 +1,71 @@ -# Conceptual model +# Conceptual model and ontology ## Design rule -The core model is deliberately small. A concept belongs in the v1 kernel only -when processkit must validate its lifecycle or relationships consistently -across unrelated projects. Domain taxonomies belong in packages or project -extensions. +The complete v1 ontology is a primary product capability, not an experiment or +optional extension. processkit v0 already demonstrated that a smaller +Git-native process model and validated agent operations work in principle. +v1 adds the semantic breadth required to express processes, organizations, +evidence, plans, communication, resources, and agentic work without forcing +unrelated concepts into generic tags or records. -The earlier 89-concept T/P/D/C model is useful research, but breadth is not a -v1 success criterion. The clean v1 model optimizes for coherent invariants, -composability, and migration rather than maximum vocabulary coverage. +The ontology remains framework-neutral. Domain packages may compose and extend +it, but MUST NOT redefine its canonical concepts or their class semantics. -## Kernel concepts +## T/P/D/C class system -| Concept | Purpose | +| Class | Count | Contract | +|---|---:|---| +| T — foundational concept | 19 | Reusable schema and lifecycle mechanic without independent persistence. | +| P — primitive | 22 | Atomic persistent entity family with identity, schema, storage, lifecycle, and interfaces. | +| D — discriminator | 24 | Closed typed variant of a parent primitive that inherits its storage and lifecycle. | +| C — composition | 24 | Named concept assembled from primitives and foundational fragments, with a generated schema and declared lifecycle. | +| **Total** | **89** | Complete mandatory v1 ontology. | + +- **PK-MODEL-000:** the v1 ontology MUST contain exactly the 89 canonical + concepts named below: 19 T, 22 P, 24 D, and 24 C concepts. +- **PK-MODEL-008:** a product profile MAY expose a smaller operational tool + surface, but the managed v1 distribution MUST install and validate the + complete ontology. Profile selection MUST NOT change concept meaning. + +## Canonical ontology inventory + +### T — foundational concepts (19) + +State, Transition, StateMachine, Lifecycle, Constraint, Guard, Identity, +Versioning, Ownership, Immutability, Schema, Composition, Inheritance, +Uniqueness, Interface, ValidationMode, Provenance, Visibility, and +Cardinality. + +### P — atomic primitives (22) + +Actor, Artifact, Binding, Capability, Channel, Command, Container, Event, +Gate, Location, Note, Outcome, Policy, Proposition, Queue, Record, Recurrence, +Resource, Role, Skill, Specification, and WorkItem. + +### D — discriminator variants (24) + +| Parent primitive | Discriminators | |---|---| -| Entity | Persisted typed project record with identity and version. | -| EntityType | Schema, lifecycle, storage, and interface declaration. | -| StateMachine | Allowed states, transitions, guards, and terminal states. | -| Relation | Typed edge between addressable subjects. | -| Event | Append-only fact describing an observed process change. | -| Policy | Project-owned rule controlling authority or validation. | -| Package | Versioned set of content and compatibility declarations. | -| Capability | Discoverable operation or knowledge surface. | -| ProcessDefinition | Reusable ordered or branching workflow contract. | -| ProcessRun | Project-owned execution state and evidence for a definition. | - -## Standard entity types - -- **PK-MODEL-000:** the managed profile MUST include these standard - EntityTypes: - -- WorkItem; -- DecisionRecord; -- Discussion; -- Note; -- Artifact; -- Actor; -- Role; -- TeamMember; -- Binding; -- Scope; -- Gate; -- Migration; -- LogEntry; and -- ProcessRun. - -- **PK-MODEL-008:** profiles MAY omit EntityTypes they do not expose, but - installed schemas and tools MUST agree exactly. +| Proposition | Risk, Belief, WorldFact, WSJFEstimate, Assumption | +| Location | GeographicRegion, Site, Coordinate, LogicalRegion, Timezone | +| Capability | Disposition | +| Container | Portfolio, ValueStream, ART, Team, Project, Scope | +| Binding | Hierarchy, Position, ProvenanceLink, Correlation, Dependency, OwnershipLink, RelatedTo | + +### C — compositions (24) + +TeamMember, DecisionRecord, LogEntry, Measurement, Archive, +ProcessSpecification, GoalSpecification, Service, RoleSpecification, +GateSpecification, SchemaSpecification, ScheduleSpecification, +TestSpecification, ChannelSpecification, QueueSpecification, WorkItemTemplate, +Migration, ScopePlan, Roadmap, ProgramIncrement, Iteration, Release, +Discussion, and EvaluationRun. + +- **PK-MODEL-009:** canonical names, classes, parent primitives, and + composition membership MUST be represented in one versioned ontology + registry from which schemas, references, query metadata, and coverage + reports are generated or mechanically checked. ## Common envelope @@ -110,7 +128,8 @@ composability, and migration rather than maximum vocabulary coverage. ## Extensibility test -- **PK-MODEL-026:** a proposed new kernel concept MUST demonstrate at least two - unrelated product domains, lifecycle semantics that packages cannot express - safely, and a migration path. Otherwise it belongs in a package or project +- **PK-MODEL-026:** additions beyond the canonical 89-concept v1 ontology MUST + demonstrate reusable meaning across at least two unrelated product domains, + declare whether they are T, P, D, or C, and provide compatibility and + migration treatment. Otherwise they belong in a package or project namespace. diff --git a/spec/doc/v1/03-project-storage-and-ownership.md b/spec/doc/v1/03-project-storage-and-ownership.md index 9e34ee77..95049c3f 100644 --- a/spec/doc/v1/03-project-storage-and-ownership.md +++ b/spec/doc/v1/03-project-storage-and-ownership.md @@ -25,10 +25,18 @@ metadata live below `.processkit/` and are not domain entities. ## Sources of truth +- **PK-STORE-006:** v1 MUST preserve the product principle of Git-backed, + human-readable canonical entities while defining their formats anew from + this specification. Existing file shapes are migration inputs, not v1 + format authority. - **PK-STORE-001:** canonical entities, accepted project policy, and local extensions MUST be ordinary files suitable for Git review. - **PK-STORE-002:** SQLite databases, search indexes, caches, rendered indexes, and harness projections MUST be rebuildable derived state. +- **PK-STORE-007:** SQLite with FTS MUST remain the default derived index + adapter, reimplemented behind the repository query port. Existing index + schemas and code are evidence only and MUST NOT constrain canonical storage + or public query semantics. - **PK-STORE-003:** generated schemas MAY be committed for review, but their generator inputs and generation metadata MUST identify the authoritative source and support a drift check. diff --git a/spec/doc/v1/04-content-packages-and-extensions.md b/spec/doc/v1/04-content-packages-and-extensions.md index 2a31f175..5868e25d 100644 --- a/spec/doc/v1/04-content-packages-and-extensions.md +++ b/spec/doc/v1/04-content-packages-and-extensions.md @@ -6,7 +6,7 @@ processkit distributes process capability as independently inspectable files: - EntityType schemas and state machines; - skills containing instructions, tools, configuration, and references; -- ProcessDefinitions; +- ProcessSpecifications; - templates and maintained examples; - policies and validation rules; - harness-neutral capability metadata; @@ -45,13 +45,15 @@ processkit distributes process capability as independently inspectable files: ## Processes -- **PK-PKG-020:** a ProcessDefinition MUST declare ordered or branching steps, +- **PK-PKG-020:** a ProcessSpecification MUST declare ordered or branching + steps, entry conditions, completion conditions, required capabilities, evidence, failure behavior, and resumability. -- **PK-PKG-021:** ProcessDefinitions describe coordination semantics; they MUST - NOT embed arbitrary executable code. -- **PK-PKG-022:** starting a durable process MUST create a ProcessRun or a - declared set of linked WorkItems so execution state is inspectable. +- **PK-PKG-021:** ProcessSpecifications describe coordination semantics; they + MUST NOT embed arbitrary executable code. +- **PK-PKG-022:** starting a durable process MUST create a declared execution + record composed from the canonical ontology, or a declared set of linked + WorkItems, so execution state is inspectable. - **PK-PKG-023:** process overrides MUST identify the upstream definition and compatibility range they replace. diff --git a/spec/doc/v1/06-agent-protocol-and-query-surface.md b/spec/doc/v1/06-agent-protocol-and-query-surface.md index 53bfeadc..50c403c9 100644 --- a/spec/doc/v1/06-agent-protocol-and-query-surface.md +++ b/spec/doc/v1/06-agent-protocol-and-query-surface.md @@ -10,6 +10,14 @@ The default runtime is a single local process exposing a configured capability catalog. Per-domain servers can be supported for isolation or debugging, but do not define competing behavior. +- **PK-MCP-006:** behavior from the existing gateway and domain tools MAY be + reused only when new v1 conformance fixtures approve it. Existing tool + implementations and observed behavior are not normative. +- **PK-MCP-007:** semantics currently distributed across Python per-skill + servers MUST be consolidated into the shared application core. Per-domain + or per-skill servers MAY remain as thin protocol adapters with no independent + validation, mutation, lifecycle, or event authority. + ## Discovery - **PK-MCP-001:** runtime discovery MUST expose tool name, version, description, diff --git a/spec/doc/v1/09-architecture-and-language.md b/spec/doc/v1/09-architecture-and-language.md index 1c960f4c..e70dc92f 100644 --- a/spec/doc/v1/09-architecture-and-language.md +++ b/spec/doc/v1/09-architecture-and-language.md @@ -39,10 +39,12 @@ dependency-free executable or a long-running high-concurrency service. Rust would be preferred for a smaller security-critical native installer with strict resource or embedded constraints. Neither is the primary v1 product. -The earlier Rust CLI plus Python MCP split demonstrated useful safety ideas but -also created duplicated contracts, two toolchains, cross-language fixtures, -release complexity, and an unclear source of behavioral truth. v1 therefore -chooses one implementation language unless measured evidence later justifies a +The earlier Rust CLI plus Python MCP split is not an implementation baseline. +No module, architecture boundary, API, or behavior is inherited merely because +it exists in that implementation. It may supply adversarial fixtures and +evidence for transaction, archive, trust, migration, and recovery requirements +only after those fixtures are reviewed against this specification. v1 uses a +new one-language implementation unless measured evidence later justifies a narrow native component. ## Reference architecture @@ -58,6 +60,14 @@ narrow native component. - **PK-ARCH-005:** a future native component requires measured need, a narrow versioned boundary, independent fixtures, failure isolation, and an accepted architecture decision. +- **PK-ARCH-006:** implementation MUST begin from the accepted specification + and conformance fixtures, not by porting or adapting modules from the prior + Rust v1 implementation. Reuse requires an explicit file-level review proving + conformance and must not import prior architecture by default. +- **PK-ARCH-007:** the Rust installer MUST be replaced. Its adversarial + transaction, interruption, archive, and recovery cases SHOULD be extracted + as implementation-independent fixtures before replacement where they remain + applicable to the accepted contracts. ## Component boundaries diff --git a/spec/doc/v1/10-verification-strategy.md b/spec/doc/v1/10-verification-strategy.md index a48e42a5..637b11d2 100644 --- a/spec/doc/v1/10-verification-strategy.md +++ b/spec/doc/v1/10-verification-strategy.md @@ -41,6 +41,10 @@ Tests assert observable contracts and failure behavior, not only code paths. executed or schema-validated and checked for drift. - **PK-TEST-009:** confirmed defects MUST gain permanent regression coverage at the narrowest useful layer and at a public boundary when user-visible. +- **PK-TEST-013:** applicable signed-release, interrupted-installation, and + recovery cases from prior implementations MUST be adapted to the Python + artifacts and the new ownership contract. Passing an old implementation's + test unchanged is not evidence when its asserted contract differs from v1. ## Property and fuzz testing diff --git a/spec/doc/v1/11-compatibility-migration-and-release.md b/spec/doc/v1/11-compatibility-migration-and-release.md index 62913840..11a03488 100644 --- a/spec/doc/v1/11-compatibility-migration-and-release.md +++ b/spec/doc/v1/11-compatibility-migration-and-release.md @@ -10,7 +10,7 @@ processkit versions these axes independently: - lifecycle plan and journal; - machine result; - event vocabulary; -- skill and ProcessDefinition contracts; and +- skill and ProcessSpecification contracts; and - extension metaschemas. The proposed v1 identifiers are: @@ -70,6 +70,9 @@ The proposed v1 identifiers are: - **PK-MIG-006:** v0 and earlier-v1-alpha importers are compatibility adapters, not sources of v1 semantics. Each has representative golden corpora and a field-level preservation report. +- **PK-MIG-008:** maintained v0 and released v1-alpha corpora MUST be preserved + as immutable migration fixtures and compatibility evidence. Fixture + preservation does not grandfather their schemas, ontology, or behavior. - **PK-MIG-007:** an unsupported or ambiguous transformation produces a manual action and blocks completion; migration MUST NOT guess intent. @@ -106,8 +109,8 @@ or force-updating a protected branch. ## v1 acceptance sequence -- `alpha`: kernel contracts, repository transactions, install/verify, and - minimal MCP workflow proven. +- `alpha`: the complete 89-concept ontology registry and generated contracts, + repository transactions, install/verify, and MCP workflow proven. - `beta`: managed profile, extension conformance, migration corpus, complete security and platform matrices proven; feature freeze begins. - `rc`: documentation, compatibility, performance, package set, and exact diff --git a/spec/doc/v1/12-documentation-and-acceptance.md b/spec/doc/v1/12-documentation-and-acceptance.md index 60fb3e90..a701a93b 100644 --- a/spec/doc/v1/12-documentation-and-acceptance.md +++ b/spec/doc/v1/12-documentation-and-acceptance.md @@ -14,6 +14,10 @@ during v1 development and clearly distinguish stable from prerelease lines. - **PK-DOC-006:** maintained examples are product contracts and MUST run or validate in release gates. +- **PK-DOC-007:** existing public documentation MUST be retained in its + applicable versioned archive. v1 documentation MUST be rewritten from the + accepted specification and shipped behavior, not edited as though historical + pages already described the new product. The public information architecture covers overview, getting started, concepts, how-to guides, reference, troubleshooting, roadmap, releases and @@ -58,17 +62,20 @@ examples, governing decisions, and applicable company standards. 3. Start MCP over stdio and discover the declared capability catalog. 4. Create, query, transition, relate, and supersede representative entities; verify events and index equivalence. -5. Run a durable process with a gate, evidence, interruption, and resumption. -6. Add and validate a namespaced extension package without core modification. -7. Preview and apply an update with unchanged, locally modified, mergeable, +5. Generate and validate coverage for all 89 canonical ontology concepts, + exercise every persistent P and C schema, every D discriminator, and every + T fragment through at least one consuming contract. +6. Run a durable process with a gate, evidence, interruption, and resumption. +7. Add and validate a namespaced extension package without core modification. +8. Preview and apply an update with unchanged, locally modified, mergeable, conflicting, generated, and project-owned files. -8. Recover from injected interruption at each mutation boundary. -9. Import representative v0 and earlier-v1-alpha corpora with preservation +9. Recover from injected interruption at each mutation boundary. +10. Import representative v0 and earlier-v1-alpha corpora with preservation reports and explicit manual blockers. -10. Export a sanitized cross-repository handoff and receive it as local state. -11. Conservatively uninstall processkit while preserving modified and +11. Export a sanitized cross-repository handoff and receive it as local state. +12. Conservatively uninstall processkit while preserving modified and project-owned content. -12. Build documentation and verify the exact published release artifacts. +13. Build documentation and verify the exact published release artifacts. ## Definition of v1.0.0 complete diff --git a/spec/doc/v1/13-standard-entity-types.md b/spec/doc/v1/13-standard-entity-types.md index 0380f48f..64f520ae 100644 --- a/spec/doc/v1/13-standard-entity-types.md +++ b/spec/doc/v1/13-standard-entity-types.md @@ -1,8 +1,30 @@ -# Standard entity types - -This chapter defines the semantic minimum for the managed profile. The -implementation phase produces closed JSON Schemas, positive and negative -fixtures, and state-machine documents conforming to these requirements. +# Ontology contracts + +This chapter refines high-use ontology concepts and defines the conformance +contract for the complete inventory in the conceptual-model chapter. The +named refinements below do not reduce v1 scope: every one of the 89 canonical +concepts is a release requirement. + +## Complete-ontology requirements + +- **PK-ENTITY-000:** the release MUST publish a machine-readable ontology + registry containing every canonical concept, its T/P/D/C class, description, + owner, interfaces, dependencies, and schema or fragment location. +- **PK-ENTITY-004:** every P primitive and C composition MUST have a closed + entity schema, storage declaration, identity policy, interface metadata, + lifecycle declaration where mutable, and positive and negative fixtures. +- **PK-ENTITY-005:** every D discriminator MUST be a closed variant of its + declared parent P schema, inherit the parent's lifecycle and storage rules, + and publish fixtures proving both valid specialization and invalid mixing. +- **PK-ENTITY-006:** every T foundational concept MUST have one canonical + schema fragment or registry contract and MUST be exercised by at least one + generated P or C schema. +- **PK-ENTITY-007:** ontology generation MUST fail on an unknown class, + duplicate canonical name, missing parent, dependency cycle, unconsumed T + concept, uncovered discriminator, or composition with unresolved parts. +- **PK-ENTITY-008:** a release coverage report MUST prove 19/19 T, 22/22 P, + 24/24 D, and 24/24 C concepts complete. Partial ontology coverage prevents + v1.0.0 release. ## Work and reasoning @@ -126,22 +148,24 @@ fixtures, and state-machine documents conforming to these requirements. - **PK-ENTITY-121:** Binding validation enforces the relation registry's endpoint, cardinality, inverse, and temporal rules. -## ProcessRun +## Durable execution record -- **PK-ENTITY-130:** ProcessRun binds an exact ProcessDefinition version to a - project root, scope, initiator, inputs, ordered state, produced entities, - evidence, and completion or recovery outcome. -- **PK-ENTITY-131:** ProcessRun MUST expose the current actionable step and - MUST distinguish waiting, blocked, failed, cancelled, and completed. +- **PK-ENTITY-130:** a durable execution record binds an exact + ProcessSpecification version to a project root, Scope, initiator, inputs, + ordered state, produced entities, evidence, and completion or recovery + Outcome. +- **PK-ENTITY-131:** a durable execution record MUST expose the current + actionable step and MUST distinguish waiting, blocked, failed, cancelled, + and completed. - **PK-ENTITY-132:** process execution may coordinate external work but records observed handoffs and results; it MUST NOT claim external completion without evidence from the owning system or repository. ## Schema acceptance -- **PK-ENTITY-140:** every standard EntityType MUST publish a closed schema, - state machine where applicable, storage declaration, relation constraints, - event vocabulary, and valid/invalid fixtures. +- **PK-ENTITY-140:** every persistent P or C concept MUST publish a closed + schema, state machine where applicable, storage declaration, relation + constraints, event vocabulary, and valid/invalid fixtures. - **PK-ENTITY-141:** schemas MUST reuse one versioned common envelope and fragments without generating divergent copies of shared semantics. - **PK-ENTITY-142:** generated schemas are release artifacts and MUST match diff --git a/spec/doc/v1/14-performance-and-operations.md b/spec/doc/v1/14-performance-and-operations.md index f6aeb50f..86ec1326 100644 --- a/spec/doc/v1/14-performance-and-operations.md +++ b/spec/doc/v1/14-performance-and-operations.md @@ -12,7 +12,7 @@ The v1 reference profile is one repository containing up to: - 1,000,000 LogEntries; - 10,000 relations returned by an explicitly bounded traversal; - 1 GiB total structured context excluding externally referenced artifacts; -- 500 installed skills and ProcessDefinitions; and +- 500 installed skills and ProcessSpecifications; and - 16 concurrent read requests with one serialized root mutation. - **PK-PERF-000:** larger repositories MAY work but are outside the v1 diff --git a/spec/doc/v1/15-review-decisions.md b/spec/doc/v1/15-review-decisions.md index 2442544e..fcaca927 100644 --- a/spec/doc/v1/15-review-decisions.md +++ b/spec/doc/v1/15-review-decisions.md @@ -4,19 +4,20 @@ This draft is internally coherent but intentionally does not manufacture approval for consequential choices. Review must accept, amend, or reject each item before the specification becomes the implementation baseline. -## D1 — Product kernel instead of ontology breadth +## D1 — Complete 89-concept ontology in v1 -**Proposal:** adopt the small kernel and standard managed EntityTypes in this -specification. Treat the former 89-concept T/P/D/C ontology as optional package -research, not the v1 kernel or release gate. +**Accepted:** ship the complete 89-concept T/P/D/C ontology as mandatory v1 +scope and a v1.0.0 release gate. processkit v0 is sufficient proof that the +Git-native, validated process model works; v1 does not need another +reduced-scope product experiment. -**Reason:** only concepts requiring consistent cross-domain lifecycle -enforcement belong in the core. Vocabulary breadth multiplies migration, -schema, query, documentation, and agent-training obligations without proving -user value. +**Reason:** a principal value of v1 is enough semantic breadth to express the +processes, artifacts, organizational structures, evidence, resources, and +agentic-work concepts users may need without misusing generic records or tags. -**Impact:** previous ontology-first alpha behavior is not automatically carried -forward. Useful domain concepts can return through versioned packages. +**Impact:** all 19 T, 22 P, 24 D, and 24 C concepts require registry coverage, +schema or fragment treatment, query metadata, fixtures, documentation, and +release evidence. Delivery may be phased, but v1.0.0 cannot omit concepts. ## D2 — Python as the sole required implementation language diff --git a/spec/doc/v1/README.md b/spec/doc/v1/README.md index a91aa865..e5549bce 100644 --- a/spec/doc/v1/README.md +++ b/spec/doc/v1/README.md @@ -12,25 +12,24 @@ meanings defined by RFC 2119 and RFC 8174. ## Reading order -1. [From-scratch assessment](00-from-scratch-assessment.md) -2. [Product definition](01-product-definition.md) -3. [Conceptual model](02-conceptual-model.md) -4. [Project storage and ownership](03-project-storage-and-ownership.md) -5. [Content, packages, and extensions](04-content-packages-and-extensions.md) -6. [Application and lifecycle](05-application-and-lifecycle.md) -7. [Agent protocol and query surface](06-agent-protocol-and-query-surface.md) -8. [Configuration, output, and +1. [Product definition](01-product-definition.md) +2. [Conceptual model and ontology](02-conceptual-model.md) +3. [Project storage and ownership](03-project-storage-and-ownership.md) +4. [Content, packages, and extensions](04-content-packages-and-extensions.md) +5. [Application and lifecycle](05-application-and-lifecycle.md) +6. [Agent protocol and query surface](06-agent-protocol-and-query-surface.md) +7. [Configuration, output, and evidence](07-configuration-output-and-evidence.md) -9. [Security and trust](08-security-and-trust.md) -10. [Architecture and language assessment](09-architecture-and-language.md) -11. [Verification strategy](10-verification-strategy.md) -12. [Compatibility, migration, and +8. [Security and trust](08-security-and-trust.md) +9. [Architecture and language](09-architecture-and-language.md) +10. [Verification strategy](10-verification-strategy.md) +11. [Compatibility, migration, and release](11-compatibility-migration-and-release.md) -13. [Documentation and acceptance](12-documentation-and-acceptance.md) -14. [Standard entity types](13-standard-entity-types.md) -15. [Performance and operations](14-performance-and-operations.md) -16. [Review decisions](15-review-decisions.md) -17. [Roadmap](roadmap.yaml) +12. [Documentation and acceptance](12-documentation-and-acceptance.md) +13. [Ontology contracts](13-standard-entity-types.md) +14. [Performance and operations](14-performance-and-operations.md) +15. [Review decisions](15-review-decisions.md) +16. [Roadmap](roadmap.yaml) ## Contract hierarchy diff --git a/spec/doc/v1/roadmap.yaml b/spec/doc/v1/roadmap.yaml index 1d40a30d..d47bdd68 100644 --- a/spec/doc/v1/roadmap.yaml +++ b/spec/doc/v1/roadmap.yaml @@ -21,10 +21,11 @@ groups: - "BACK-20260807_1003-WarmHawk-specify-processkit-v1-from-\ first-principles" - id: PK1-P1 - title: Prove the kernel and repository transaction model + title: Implement the complete ontology and transaction model summary: >- - Deliver typed kernel contracts, safe canonical storage, lifecycle - enforcement, events, and deterministic recovery. + Deliver the versioned registry and all 89 T/P/D/C concepts with + generated contracts, safe canonical storage, lifecycle enforcement, + events, query metadata, fixtures, and deterministic recovery. status: planned dependencies: [PK1-P0] - id: PK1-P2 @@ -38,10 +39,11 @@ groups: title: Agent and authoring surface items: - id: PK1-P3 - title: Deliver the minimal MCP workflow + title: Deliver the ontology-aware MCP workflow summary: >- - Provide discovery, query, validated mutation, events, configuration - inspection, and stdio transport from one application core. + Provide discovery, polymorphic ontology query, validated mutation, + events, configuration inspection, and stdio transport from one + application core. status: planned dependencies: [PK1-P1, PK1-P2] - id: PK1-P4 @@ -64,8 +66,9 @@ groups: - id: PK1-P6 title: Complete beta conformance summary: >- - Pass the full contract, security, extension, migration, platform, - documentation, and package matrices and enter feature freeze. + Pass full 89-concept coverage plus the contract, security, extension, + migration, platform, documentation, and package matrices and enter + feature freeze. status: planned dependencies: [PK1-P5] - id: PK1-P7 From 641b9033ce573235d983517a86aa822798f2d1a3 Mon Sep 17 00:00:00 2001 From: projectious Date: Fri, 7 Aug 2026 18:00:30 +0200 Subject: [PATCH 3/6] docs(spec): center agent context and memory --- spec/doc/v1/01-product-definition.md | 47 ++++++++++++++----- .../v1/03-project-storage-and-ownership.md | 13 ++++- .../v1/06-agent-protocol-and-query-surface.md | 11 +++++ spec/doc/v1/08-security-and-trust.md | 11 ++++- spec/doc/v1/09-architecture-and-language.md | 10 +++- spec/doc/v1/10-verification-strategy.md | 4 ++ .../doc/v1/12-documentation-and-acceptance.md | 21 +++++---- spec/doc/v1/roadmap.yaml | 13 ++--- 8 files changed, 99 insertions(+), 31 deletions(-) diff --git a/spec/doc/v1/01-product-definition.md b/spec/doc/v1/01-product-definition.md index 1537d96d..56ad9b61 100644 --- a/spec/doc/v1/01-product-definition.md +++ b/spec/doc/v1/01-product-definition.md @@ -2,23 +2,35 @@ ## Purpose -processkit is a local-first, provider-neutral process and project-memory -substrate for humans and AI agents working in software repositories. It turns -important project state into typed, inspectable, versioned records and exposes -safe operations over that state through a CLI and MCP. - -The product answers four questions without replaying chat history: - -1. What work, decisions, evidence, and risks exist? -2. What state are they in, and which transitions are valid? -3. Why did the state change, who or what changed it, and what evidence exists? -4. Which process capability should an agent use next? +processkit is a local-first, provider-neutral AI-agent context and memory +management system for humans and agents working in Git repositories. It turns +repository text files into durable, typed, inspectable memory and provides the +shared ontology through which humans and agents describe work, knowledge, +decisions, evidence, organizations, capabilities, and processes in +conversation. + +Human-readable Git files are always canonical. Local databases, full-text +indexes, and embedding/vector entries augment retrieval and context assembly, +but remain disposable client-side projections that can be rebuilt from the +repository. processkit also installs, versions, discovers, and governs skills +and MCP servers that let agents understand and safely operate on this context. + +The product answers these questions without depending on replay of a chat +history or one model provider's private memory: + +1. What project and organizational context should an agent know now? +2. Which durable memories, decisions, evidence, relationships, and history + support that context? +3. How can a human and an agent express new information in the same ontology? +4. What state are process entities in, and which transitions are valid? +5. Which skill, MCP tool, or process capability should an agent use next? ## Users - A project owner installs and upgrades a coherent process capability set. - A human contributor reads and reviews canonical state in Git. -- An AI agent queries and mutates project state through validated tools. +- An AI agent retrieves bounded relevant context, queries durable memory, and + records or mutates project state through validated tools. - A process author creates reusable skills, schemas, state machines, and process definitions. - A harness or orchestrator integrates through stable MCP and machine @@ -47,6 +59,12 @@ The product answers four questions without replaying chat history: defined in the conceptual-model chapter so users can express broad process, organizational, evidence, planning, and agentic-work concepts without overloading a reduced set of generic records. +- **PK-PROD-009:** processkit MUST assemble bounded, attributable agent context + from canonical entities and verified derived indexes without treating model + conversation history as authoritative project memory. +- **PK-PROD-016:** skills and MCP servers MUST be managed as versioned, + inspectable capabilities with ownership, discovery, configuration, + compatibility, and verification contracts. ## Non-goals @@ -72,6 +90,11 @@ processkit owns: - local installation and reconciliation of processkit-owned files; - validated CLI and MCP operations; - derived local indexes and generated harness projections; +- context discovery, retrieval, ranking, and bounded context assembly; +- local full-text and embedding/vector projections derived from canonical + repository content; +- versioned skills and MCP server capability manifests, installation, and + verification; - compatibility, migration, verification, and diagnostic behavior. The consuming repository owns: diff --git a/spec/doc/v1/03-project-storage-and-ownership.md b/spec/doc/v1/03-project-storage-and-ownership.md index 95049c3f..57db4eb1 100644 --- a/spec/doc/v1/03-project-storage-and-ownership.md +++ b/spec/doc/v1/03-project-storage-and-ownership.md @@ -31,12 +31,21 @@ metadata live below `.processkit/` and are not domain entities. format authority. - **PK-STORE-001:** canonical entities, accepted project policy, and local extensions MUST be ordinary files suitable for Git review. -- **PK-STORE-002:** SQLite databases, search indexes, caches, rendered indexes, - and harness projections MUST be rebuildable derived state. +- **PK-STORE-002:** SQLite databases, full-text indexes, embedding/vector + indexes and entries, caches, rendered indexes, and harness projections MUST + be rebuildable derived state. None may become the only copy of project + context or memory. - **PK-STORE-007:** SQLite with FTS MUST remain the default derived index adapter, reimplemented behind the repository query port. Existing index schemas and code are evidence only and MUST NOT constrain canonical storage or public query semantics. +- **PK-STORE-008:** embedding text, vectors, chunk metadata, and similarity + indexes MUST identify the canonical source ID, source revision or digest, + projection version, embedding model contract, and generation. Stale or + untraceable entries MUST NOT contribute to a complete or verified result. +- **PK-STORE-009:** deleting every derived database and embedding entry MUST + lose no canonical information; `rebuild` MUST reproduce functionally + equivalent indexes from Git-backed files and declared local configuration. - **PK-STORE-003:** generated schemas MAY be committed for review, but their generator inputs and generation metadata MUST identify the authoritative source and support a drift check. diff --git a/spec/doc/v1/06-agent-protocol-and-query-surface.md b/spec/doc/v1/06-agent-protocol-and-query-surface.md index 50c403c9..61e2eda0 100644 --- a/spec/doc/v1/06-agent-protocol-and-query-surface.md +++ b/spec/doc/v1/06-agent-protocol-and-query-surface.md @@ -40,12 +40,15 @@ The managed profile provides operations equivalent to: get_entity(id | path) list_entities(type?, state?, scope?, limit?, cursor?) search_entities(text, filters?, limit?, cursor?) +semantic_search_entities(text, filters?, limit?, cursor?) +hybrid_search_entities(text, filters?, limit?, cursor?) query_by_interface(interface, filters?, limit?, cursor?) traverse_relations(subject, relation?, direction?, depth?) events_for_subject(subject, after?, limit?, cursor?) find_skill(task_description) route_task(task_description, constraints?) get_effective_configuration() +assemble_context(task, constraints?, token_budget?, provenance?) ``` - **PK-MCP-010:** reads MUST come from canonical files or a verified index @@ -56,6 +59,14 @@ get_effective_configuration() identity, and completeness claims MUST be explicit. - **PK-MCP-013:** a query MUST not expose private entity bodies or sensitive fields beyond the caller's configured local policy. +- **PK-MCP-014:** semantic and hybrid search MUST return canonical entity IDs, + source digests, ranking method, and index generation. Similarity is a + retrieval signal, not evidence that a proposition is true or current. +- **PK-MCP-015:** context assembly MUST be bounded by explicit size or token + limits, preserve source attribution, report omissions and stale indexes, and + prefer canonical relationships and policy over embedding similarity alone. +- **PK-MCP-016:** every context result MUST remain reproducible enough to fetch + its canonical source records without relying on an embedding database row. ## Mutation surface diff --git a/spec/doc/v1/08-security-and-trust.md b/spec/doc/v1/08-security-and-trust.md index 05af42a6..e37f2041 100644 --- a/spec/doc/v1/08-security-and-trust.md +++ b/spec/doc/v1/08-security-and-trust.md @@ -5,7 +5,9 @@ Protected assets include project entities, unpublished discussions and notes, credentials referenced by integrations, Git history, release packages, ownership manifests, migration evidence, harness configuration, and generated -agent instructions. +agent instructions. Derived embedding text and vectors are protected at the +highest sensitivity of their canonical sources because they may reveal source +meaning even when the original text is absent. Trust boundaries exist between: @@ -71,6 +73,13 @@ Trust boundaries exist between: and no ambient credentials or user configuration. - **PK-SEC-034:** security defects add permanent negative regression coverage and follow coordinated disclosure without moving published tags. +- **PK-SEC-035:** embedding generation and semantic retrieval MUST run locally + by default. Sending source text or derived representations to a remote model + or vector service requires explicit configuration, disclosure of affected + data classes and destination, and project policy authorization. +- **PK-SEC-036:** private or excluded canonical content MUST remain excluded + from embedding, similarity search, context assembly, logs, and exports unless + the same caller is explicitly authorized for that content. ## Threat-driven acceptance diff --git a/spec/doc/v1/09-architecture-and-language.md b/spec/doc/v1/09-architecture-and-language.md index e70dc92f..bb1c6ff2 100644 --- a/spec/doc/v1/09-architecture-and-language.md +++ b/spec/doc/v1/09-architecture-and-language.md @@ -78,9 +78,11 @@ application services ↓ domain model and policies ↓ -ports: repository, index, package, clock, process, network, rendering +ports: repository, lexical index, semantic index, package, clock, process, + network, rendering ↓ -local adapters: filesystem, SQLite/FTS, uv/Python packaging, stdio/HTTP +local adapters: filesystem, SQLite/FTS, embedding/vector index, + uv/Python packaging, stdio/HTTP ``` - **PK-ARCH-010:** domain behavior MUST not depend on CLI parsing, MCP SDK @@ -89,6 +91,10 @@ local adapters: filesystem, SQLite/FTS, uv/Python packaging, stdio/HTTP path shared by CLI, MCP, migration, and reconciliation. - **PK-ARCH-012:** SQLite with FTS is the default derived query adapter; a different adapter MAY be added without changing canonical storage semantics. +- **PK-ARCH-015:** embedding generation and vector search MUST be behind + replaceable local ports. Their model, dimensions, chunking, distance metric, + and projection version are adapter metadata and MUST NOT enter canonical + entity semantics. - **PK-ARCH-013:** Pydantic or equivalent typed boundary models MAY be used, but published JSON Schemas and fixtures remain the interoperability contract. - **PK-ARCH-014:** network release resolution and external connectors are diff --git a/spec/doc/v1/10-verification-strategy.md b/spec/doc/v1/10-verification-strategy.md index 637b11d2..ecc3a4a8 100644 --- a/spec/doc/v1/10-verification-strategy.md +++ b/spec/doc/v1/10-verification-strategy.md @@ -35,6 +35,10 @@ Tests assert observable contracts and failure behavior, not only code paths. concurrency, cancellation, bounds, and shutdown when HTTP ships. - **PK-TEST-006:** query tests MUST compare indexed results with a canonical scan across randomized create/update/archive sequences. +- **PK-TEST-014:** semantic and hybrid retrieval tests MUST cover deterministic + fixture embeddings or a controlled fake adapter, source attribution, + sensitivity filters, stale projections, model changes, complete rebuild, + bounded context assembly, and operation with semantic indexing disabled. - **PK-TEST-007:** security suites MUST exercise every threat-driven case in the security chapter and verify refusal plus redaction. - **PK-TEST-008:** documentation examples and generated references MUST be diff --git a/spec/doc/v1/12-documentation-and-acceptance.md b/spec/doc/v1/12-documentation-and-acceptance.md index a701a93b..8c1fba91 100644 --- a/spec/doc/v1/12-documentation-and-acceptance.md +++ b/spec/doc/v1/12-documentation-and-acceptance.md @@ -65,17 +65,22 @@ examples, governing decisions, and applicable company standards. 5. Generate and validate coverage for all 89 canonical ontology concepts, exercise every persistent P and C schema, every D discriminator, and every T fragment through at least one consuming contract. -6. Run a durable process with a gate, evidence, interruption, and resumption. -7. Add and validate a namespaced extension package without core modification. -8. Preview and apply an update with unchanged, locally modified, mergeable, +6. Assemble bounded, attributed agent context through lexical, semantic, and + hybrid retrieval; delete every derived index, rebuild it from canonical Git + files, and obtain functionally equivalent sources without memory loss. +7. Install, discover, verify, and invoke a managed skill and MCP server through + their versioned capability manifests. +8. Run a durable process with a gate, evidence, interruption, and resumption. +9. Add and validate a namespaced extension package without core modification. +10. Preview and apply an update with unchanged, locally modified, mergeable, conflicting, generated, and project-owned files. -9. Recover from injected interruption at each mutation boundary. -10. Import representative v0 and earlier-v1-alpha corpora with preservation +11. Recover from injected interruption at each mutation boundary. +12. Import representative v0 and earlier-v1-alpha corpora with preservation reports and explicit manual blockers. -11. Export a sanitized cross-repository handoff and receive it as local state. -12. Conservatively uninstall processkit while preserving modified and +13. Export a sanitized cross-repository handoff and receive it as local state. +14. Conservatively uninstall processkit while preserving modified and project-owned content. -13. Build documentation and verify the exact published release artifacts. +15. Build documentation and verify the exact published release artifacts. ## Definition of v1.0.0 complete diff --git a/spec/doc/v1/roadmap.yaml b/spec/doc/v1/roadmap.yaml index d47bdd68..be887e07 100644 --- a/spec/doc/v1/roadmap.yaml +++ b/spec/doc/v1/roadmap.yaml @@ -39,18 +39,19 @@ groups: title: Agent and authoring surface items: - id: PK1-P3 - title: Deliver the ontology-aware MCP workflow + title: Deliver agent context, memory, and MCP workflows summary: >- - Provide discovery, polymorphic ontology query, validated mutation, - events, configuration inspection, and stdio transport from one - application core. + Provide lexical, semantic, and hybrid retrieval, bounded attributed + context assembly, polymorphic ontology query, validated mutation, + events, configuration inspection, and stdio transport from one core. status: planned dependencies: [PK1-P1, PK1-P2] - id: PK1-P4 - title: Stabilize managed packages and extensions + title: Stabilize skills, MCP servers, packages, and extensions summary: >- Ship deterministic profiles, provider-neutral skills and processes, - conformance tooling, and safe harness projections. + versioned MCP server manifests, conformance tooling, and safe harness + projections. status: planned dependencies: [PK1-P3] - id: PK1-P5 From f870f1a1208347aa966e706f62d294a889c03570 Mon Sep 17 00:00:00 2001 From: projectious Date: Fri, 7 Aug 2026 18:17:00 +0200 Subject: [PATCH 4/6] docs(spec): stage CLI management capabilities --- .../v1/04-content-packages-and-extensions.md | 19 +++++++++++++ spec/doc/v1/05-application-and-lifecycle.md | 27 +++++++++++++++++++ .../doc/v1/12-documentation-and-acceptance.md | 27 ++++++++++--------- 3 files changed, 61 insertions(+), 12 deletions(-) diff --git a/spec/doc/v1/04-content-packages-and-extensions.md b/spec/doc/v1/04-content-packages-and-extensions.md index 5868e25d..3af053e9 100644 --- a/spec/doc/v1/04-content-packages-and-extensions.md +++ b/spec/doc/v1/04-content-packages-and-extensions.md @@ -43,6 +43,11 @@ processkit distributes process capability as independently inspectable files: - **PK-PKG-014:** extension skills MUST NOT impersonate a reserved processkit identity or override a core capability without explicit policy. +Provider-neutral prompt assets and slash-command projections are a post-v1 +package capability. A future contract must separate canonical prompt purpose, +inputs, outputs, safety, and versioning from provider- or harness-specific +command syntax. + ## Processes - **PK-PKG-020:** a ProcessSpecification MUST declare ordered or branching @@ -83,3 +88,17 @@ processkit distributes process capability as independently inspectable files: verification, CLI use, or manual MCP configuration. - **PK-PKG-043:** adding a harness adapter MUST NOT change core entity or process semantics. + +## Future organizational distributions + +Organizations may eventually publish a governed processkit adaptation that +preselects or adds mandatory profiles, processes, policies, skills, prompts, +and MCP capabilities for their developers. The organization-specific +distribution is not part of the v1 contract. + +Its future design must preserve upstream processkit identity and provenance, +distinguish upstream and organization-owned content, support private +distribution and authenticated installation, declare compatibility with an +exact upstream range, and provide a continuous update and conflict-resolution +path. A downstream Git fork requiring indefinite manual merges is one option +to evaluate, not the assumed product model. diff --git a/spec/doc/v1/05-application-and-lifecycle.md b/spec/doc/v1/05-application-and-lifecycle.md index 5405e07a..11ad87a0 100644 --- a/spec/doc/v1/05-application-and-lifecycle.md +++ b/spec/doc/v1/05-application-and-lifecycle.md @@ -17,6 +17,7 @@ archive, checksums, SBOM, and signature or attestation material. |---|---| | `processkit version` | Report product, source, runtime, and contract versions. | | `processkit help` | Show stable command help. | +| `processkit list KIND` | List installed `skills`, `ontology`, `packages`, `profiles`, `mcp-servers`, or other declared catalog kinds. | | `processkit init` | Create a new installation plan for an uninitialized root. | | `processkit plan` | Preview install, update, profile, adapter, or removal changes. | | `processkit apply --plan PLAN` | Apply an exact reviewed plan. | @@ -32,6 +33,12 @@ archive, checksums, SBOM, and signature or attestation material. - **PK-CLI-009:** EntityType- and skill-specific convenience commands MAY be added after their MCP operations are stable. They use the same application services rather than reimplementing semantics. +- **PK-CLI-013:** `list` MUST be read-only and return canonical identity, + version, source package, installation status, enabled state where + applicable, and compatibility metadata in text and versioned machine form. +- **PK-CLI-014:** listable kinds MUST derive from the installed ontology and + capability catalogs. The CLI MUST NOT maintain a second hard-coded catalog + that can drift from MCP discovery or package manifests. ## Lifecycle requirements @@ -91,3 +98,23 @@ archive, checksums, SBOM, and signature or attestation material. - **PK-CLI-025:** root discovery MUST NOT search configured root lists, cross a filesystem boundary implicitly, select a descendant, or choose between multiple repositories by basename. + +## Post-v1 CLI directions + +These directions are intentionally outside the v1.0.0 release gate and need +separate accepted contracts before implementation: + +- skill authoring, installation, update, enablement, deprecation, and removal; +- provider-neutral prompt assets and their harness-specific slash-command + projections; +- memory review, promotion, compaction, archival, restoration, retention, and + pruning, informed by v0 behavior; and +- company-specific processkit distributions carrying organization-wide + processes, policy, skills, prompts, profiles, and MCP capabilities. + +Memory lifecycle design MUST first distinguish durable repository memory from +harness conversation/session context and analyze overlap with harnesses such +as tau. Company-distribution design MUST compare upstream package composition, +private distributions, overlays, and downstream forks, and define provenance, +trust, naming, compatibility, update cadence, and continuous upstream +reconciliation. No particular adaptation mechanism is selected by v1. diff --git a/spec/doc/v1/12-documentation-and-acceptance.md b/spec/doc/v1/12-documentation-and-acceptance.md index 8c1fba91..a99367ff 100644 --- a/spec/doc/v1/12-documentation-and-acceptance.md +++ b/spec/doc/v1/12-documentation-and-acceptance.md @@ -60,27 +60,30 @@ examples, governing decisions, and applicable company standards. on every supported platform. 2. Verify the installed profile and inspect effective configuration. 3. Start MCP over stdio and discover the declared capability catalog. -4. Create, query, transition, relate, and supersede representative entities; +4. List installed skills, ontology concepts, packages, profiles, and MCP + servers in both text and machine form and reconcile the result with package + manifests and MCP discovery. +5. Create, query, transition, relate, and supersede representative entities; verify events and index equivalence. -5. Generate and validate coverage for all 89 canonical ontology concepts, +6. Generate and validate coverage for all 89 canonical ontology concepts, exercise every persistent P and C schema, every D discriminator, and every T fragment through at least one consuming contract. -6. Assemble bounded, attributed agent context through lexical, semantic, and +7. Assemble bounded, attributed agent context through lexical, semantic, and hybrid retrieval; delete every derived index, rebuild it from canonical Git files, and obtain functionally equivalent sources without memory loss. -7. Install, discover, verify, and invoke a managed skill and MCP server through +8. Install, discover, verify, and invoke a managed skill and MCP server through their versioned capability manifests. -8. Run a durable process with a gate, evidence, interruption, and resumption. -9. Add and validate a namespaced extension package without core modification. -10. Preview and apply an update with unchanged, locally modified, mergeable, +9. Run a durable process with a gate, evidence, interruption, and resumption. +10. Add and validate a namespaced extension package without core modification. +11. Preview and apply an update with unchanged, locally modified, mergeable, conflicting, generated, and project-owned files. -11. Recover from injected interruption at each mutation boundary. -12. Import representative v0 and earlier-v1-alpha corpora with preservation +12. Recover from injected interruption at each mutation boundary. +13. Import representative v0 and earlier-v1-alpha corpora with preservation reports and explicit manual blockers. -13. Export a sanitized cross-repository handoff and receive it as local state. -14. Conservatively uninstall processkit while preserving modified and +14. Export a sanitized cross-repository handoff and receive it as local state. +15. Conservatively uninstall processkit while preserving modified and project-owned content. -15. Build documentation and verify the exact published release artifacts. +16. Build documentation and verify the exact published release artifacts. ## Definition of v1.0.0 complete From ae3c29c552b487e19ce99c6eeda80a10677e494f Mon Sep 17 00:00:00 2001 From: projectious Date: Fri, 7 Aug 2026 18:29:37 +0200 Subject: [PATCH 5/6] docs(spec): standardize MCP serve command --- spec/doc/v1/05-application-and-lifecycle.md | 5 ++++- spec/doc/v1/06-agent-protocol-and-query-surface.md | 3 ++- 2 files changed, 6 insertions(+), 2 deletions(-) diff --git a/spec/doc/v1/05-application-and-lifecycle.md b/spec/doc/v1/05-application-and-lifecycle.md index 11ad87a0..e2239aee 100644 --- a/spec/doc/v1/05-application-and-lifecycle.md +++ b/spec/doc/v1/05-application-and-lifecycle.md @@ -26,7 +26,7 @@ archive, checksums, SBOM, and signature or attestation material. | `processkit migrate` | Plan or apply an explicit contract/data migration. | | `processkit reindex` | Rebuild disposable indexes from canonical files. | | `processkit generate` | Regenerate declared schemas, indexes, docs, or projections. | -| `processkit mcp serve` | Serve the configured MCP capability set. | +| `processkit mcp serve --stdio` | Serve the configured MCP capability set over standard input/output. | | `processkit mcp proxy` | Adapt stdio to an explicitly configured local MCP endpoint. | | `processkit package validate` | Validate a package or extension in isolation. | @@ -39,6 +39,9 @@ archive, checksums, SBOM, and signature or attestation material. - **PK-CLI-014:** listable kinds MUST derive from the installed ontology and capability catalogs. The CLI MUST NOT maintain a second hard-coded catalog that can drift from MCP discovery or package manifests. +- **PK-CLI-015:** products exposing a local MCP server MUST use the common + command shape ` mcp serve --stdio`. Product-specific root and + capability options MAY extend this shape without renaming the command. ## Lifecycle requirements diff --git a/spec/doc/v1/06-agent-protocol-and-query-surface.md b/spec/doc/v1/06-agent-protocol-and-query-surface.md index 61e2eda0..746455d7 100644 --- a/spec/doc/v1/06-agent-protocol-and-query-surface.md +++ b/spec/doc/v1/06-agent-protocol-and-query-surface.md @@ -90,7 +90,8 @@ operations as applicable. ## Runtime and transports -- **PK-MCP-030:** stdio MUST be supported for local harness integration. +- **PK-MCP-030:** stdio MUST be supported for local harness integration and + started with `processkit mcp serve --stdio`. - **PK-MCP-031:** streamable HTTP MAY be supported only on loopback by default; non-loopback binding requires explicit authorization and an authentication and transport-security profile. From 4bc373df8473042ee043bb09737d5791ebfc8733 Mon Sep 17 00:00:00 2001 From: projectious Date: Sat, 15 Aug 2026 09:00:46 +0200 Subject: [PATCH 6/6] docs(spec): align v1 with repository-scoped agents --- spec/doc/v1/01-product-definition.md | 29 +++++- spec/doc/v1/02-conceptual-model.md | 19 +++- .../v1/03-project-storage-and-ownership.md | 19 +++- .../v1/04-content-packages-and-extensions.md | 42 +++++++-- spec/doc/v1/05-application-and-lifecycle.md | 88 ++++++++++++++---- .../v1/06-agent-protocol-and-query-surface.md | 54 ++++++++--- .../07-configuration-output-and-evidence.md | 10 +- spec/doc/v1/08-security-and-trust.md | 23 ++++- spec/doc/v1/09-architecture-and-language.md | 18 +++- spec/doc/v1/10-verification-strategy.md | 16 +++- .../11-compatibility-migration-and-release.md | 3 +- .../doc/v1/12-documentation-and-acceptance.md | 23 ++++- spec/doc/v1/13-standard-entity-types.md | 23 ++++- spec/doc/v1/14-performance-and-operations.md | 12 +++ spec/doc/v1/15-review-decisions.md | 92 ++++++++++++++++++- spec/doc/v1/README.md | 2 +- spec/doc/v1/roadmap.yaml | 25 +++-- 17 files changed, 428 insertions(+), 70 deletions(-) diff --git a/spec/doc/v1/01-product-definition.md b/spec/doc/v1/01-product-definition.md index 56ad9b61..ff9dd6b5 100644 --- a/spec/doc/v1/01-product-definition.md +++ b/spec/doc/v1/01-product-definition.md @@ -9,6 +9,12 @@ shared ontology through which humans and agents describe work, knowledge, decisions, evidence, organizations, capabilities, and processes in conversation. +One processkit installation belongs to one Git repository representing one +project or coordination scope. Its `context/` is the authoritative shared +process memory of that scope, not the private memory of one agent. Any number +of human, permanent-agent, and ephemeral-agent TeamMembers may participate by +working with ordinary clones, branches, reviews, and merges. + Human-readable Git files are always canonical. Local databases, full-text indexes, and embedding/vector entries augment retrieval and context assembly, but remain disposable client-side projections that can be rebuilt from the @@ -53,6 +59,17 @@ history or one model provider's private memory: - **PK-PROD-006:** processkit MUST support one repository as one concern while allowing explicit references and handoffs between independently owned repositories. +- **PK-PROD-017:** one repository MUST have at most one active processkit + installation and one authoritative context root; nested Git repositories or + submodules are independent roots and MUST NOT be absorbed implicitly. +- **PK-PROD-018:** a processkit root MUST support multiple human and AI + participants and MUST NOT imply one repository or one processkit + installation per agent. +- **PK-PROD-019:** every reference runtime MUST operate locally against one + selected working copy. A long-lived local MCP daemon MAY serve several + authorized clients for that working copy, but it is not shared repository + authority or a second project database. Git synchronization and review + transfer accepted state between working copies. - **PK-PROD-007:** project state MUST remain authoritative when indexes, caches, generated references, or harness projections are absent. - **PK-PROD-008:** v1 MUST provide the complete 89-concept T/P/D/C ontology @@ -80,6 +97,9 @@ history or one model provider's private memory: claim that unstructured documentation has lifecycle semantics. - **PK-PROD-015:** processkit v1 MUST NOT provide portfolio-wide distributed transactions or pretend cross-repository operations are atomic. +- **PK-PROD-028:** processkit MUST NOT create branches, commits, pull + requests, issues, discussions, merges, pushes, or fetches as implicit side + effects. Humans, agents, harnesses, and forge adapters own those workflows. ## Product boundary @@ -105,9 +125,12 @@ The consuming repository owns: - authorization to mutate the repository; - credentials and external-system integrations. -The harness or orchestrator owns model execution, prompts outside shipped -skills, conversation state, task scheduling, agent isolation, cost control, -and cross-agent coordination. +The harness or orchestrator owns agent identity bootstrap, model execution, +prompts outside shipped skills, conversation and runtime memory, heartbeat, +task scheduling, agent isolation, cost control, and cross-agent coordination. +Company modelling, teams-of-teams orchestration, simulation, message delivery, +and portfolio views belong to products such as Kaits, which consume +processkit contracts without becoming repository authority. ## Required user journeys diff --git a/spec/doc/v1/02-conceptual-model.md b/spec/doc/v1/02-conceptual-model.md index 7dd36caa..bf9a8cb6 100644 --- a/spec/doc/v1/02-conceptual-model.md +++ b/spec/doc/v1/02-conceptual-model.md @@ -12,6 +12,12 @@ unrelated concepts into generic tags or records. The ontology remains framework-neutral. Domain packages may compose and extend it, but MUST NOT redefine its canonical concepts or their class semantics. +The ontology is applied recursively at different organizational levels. A +deliverable repository may use it to govern product work, while a coordinating +repository may use the same concepts for strategy, portfolio goals, standards, +or cross-project decisions. This semantic consistency does not create a global +database: each repository remains authoritative only for the entities it owns. + ## T/P/D/C class system | Class | Count | Contract | @@ -25,7 +31,7 @@ it, but MUST NOT redefine its canonical concepts or their class semantics. - **PK-MODEL-000:** the v1 ontology MUST contain exactly the 89 canonical concepts named below: 19 T, 22 P, 24 D, and 24 C concepts. - **PK-MODEL-008:** a product profile MAY expose a smaller operational tool - surface, but the managed v1 distribution MUST install and validate the + surface, but the standard v1 distribution MUST install and validate the complete ontology. Profile selection MUST NOT change concept meaning. ## Canonical ontology inventory @@ -114,6 +120,17 @@ Discussion, and EvaluationRun. object identity, and observed revision where reproducibility matters. - **PK-MODEL-025:** unresolved external references MUST remain visible and MUST NOT be treated as validated local relations. +- **PK-MODEL-027:** every persistent entity MUST have exactly one authoritative + repository context. Other contexts MUST use qualified references, imported + evidence, or explicitly non-authoritative projections rather than competing + writable copies. +- **PK-MODEL-028:** authority MUST be scoped to a decision surface. A + coordinating repository MAY own broader intent, policy, dependencies, and + coordination processes, but MUST NOT thereby acquire implicit write + authority over participant repositories. +- **PK-MODEL-029:** organizational structure MAY form a multi-level graph of + coordinating and participating repositories. Where authority overlaps, the + applicable contract MUST define precedence or require explicit resolution. ## Events diff --git a/spec/doc/v1/03-project-storage-and-ownership.md b/spec/doc/v1/03-project-storage-and-ownership.md index 57db4eb1..39ad61f8 100644 --- a/spec/doc/v1/03-project-storage-and-ownership.md +++ b/spec/doc/v1/03-project-storage-and-ownership.md @@ -2,9 +2,11 @@ ## Canonical layout -- **PK-STORE-000:** the default installed root is `context/`. A project MAY - configure another contained root before installation. The selected root is - recorded in processkit state and cannot change implicitly. +- **PK-STORE-000:** the processkit root is the selected repository root. The + default context directory is `/context/`. A project MAY + configure another contained context directory before installation. Both the + repository identity and contained context path are recorded in processkit + state and cannot change implicitly. ```text context/ @@ -23,6 +25,14 @@ Exact sharding beneath an EntityType is declared by its storage contract. Index databases, journals, locks, ownership manifests, and installed-release metadata live below `.processkit/` and are not domain entities. +- **PK-STORE-000A:** root discovery MUST resolve exactly one repository and + one contained context directory. It MUST reject ambiguous nested roots, + context paths outside the selected repository, and attempts to combine + several repositories into one invocation. +- **PK-STORE-000B:** each clone or worktree MAY maintain its own runtime locks + and disposable indexes. Those derived stores do not coordinate Git branches + and MUST never be treated as shared authority between working copies. + ## Sources of truth - **PK-STORE-006:** v1 MUST preserve the product principle of Git-backed, @@ -109,6 +119,9 @@ Every managed path is classified as one of: rules, and cleanliness for safety evidence but MUST NOT commit, merge, rebase, push, fetch, switch branches, or modify Git configuration as an implicit side effect of a lifecycle or entity operation. +- **PK-STORE-038:** processkit MUST report the selected repository identity, + working-copy revision, context path, and relevant worktree state in plans + and machine results whenever they affect reproducibility or mutation safety. - **PK-STORE-036:** a command requiring a clean worktree MUST report the exact relevant dirty paths and allow no blanket assumption that unrelated changes belong to processkit. diff --git a/spec/doc/v1/04-content-packages-and-extensions.md b/spec/doc/v1/04-content-packages-and-extensions.md index 3af053e9..30d8b2af 100644 --- a/spec/doc/v1/04-content-packages-and-extensions.md +++ b/spec/doc/v1/04-content-packages-and-extensions.md @@ -23,13 +23,19 @@ processkit distributes process capability as independently inspectable files: ranges, duplicate ownership, or ambiguous capability providers. - **PK-PKG-003:** profiles MUST be named selections of packages; they MUST NOT duplicate package contents or alter package semantics implicitly. -- **PK-PKG-004:** the initial profiles are `minimal`, `managed`, `product`, - `research`, and `software`; each MUST publish an exact resolved manifest. +- **PK-PKG-004:** v1 MUST publish one complete `standard` profile. Additional + profiles MAY select different packages, but are not separate v1 conformance + targets and MUST publish an exact resolved manifest when supplied. - **PK-PKG-005:** package and profile selection MUST be previewable without filesystem mutation. ## Skills +A skill has one canonical processkit representation. It is not authored once +per harness. Its package contains a harness-neutral manifest and instruction +document plus any declared references, templates, assets, scripts, and MCP +capabilities. Harness-native files are disposable projections of that source. + - **PK-PKG-010:** a skill MUST declare stable identity, version, purpose, triggers, inputs, outputs, owned capabilities, dependencies, side effects, safety constraints, and progressive-disclosure resources. @@ -42,11 +48,13 @@ processkit distributes process capability as independently inspectable files: project-mutating, externally mutating, privileged, or destructive. - **PK-PKG-014:** extension skills MUST NOT impersonate a reserved processkit identity or override a core capability without explicit policy. - -Provider-neutral prompt assets and slash-command projections are a post-v1 -package capability. A future contract must separate canonical prompt purpose, -inputs, outputs, safety, and versioning from provider- or harness-specific -command syntax. +- **PK-PKG-015:** a canonical skill MUST declare which parts are normative + semantics and which are explanatory text. A harness adapter MUST preserve + purpose, triggers, inputs, outputs, safety, side effects, required tools, and + progressive-disclosure order; formatting and invocation syntax MAY differ. +- **PK-PKG-016:** scripts and MCP tools remain separately executable declared + capabilities. Project text or generated prompt files MUST NOT silently gain + executable authority. ## Processes @@ -80,6 +88,11 @@ command syntax. ## Harness projections +A harness adapter maps the canonical skill and capability catalogs to one +documented harness contract: discovery paths, instruction wrappers, command +aliases, MCP configuration, and supported metadata. Adapters do not own skill +semantics. + - **PK-PKG-040:** one canonical capability catalog MUST generate supported harness configuration and command/skill projections. - **PK-PKG-041:** projection generation MUST preserve user-owned configuration @@ -88,6 +101,21 @@ command syntax. verification, CLI use, or manual MCP configuration. - **PK-PKG-043:** adding a harness adapter MUST NOT change core entity or process semantics. +- **PK-PKG-044:** each adapter MUST publish a support matrix. If a harness + cannot represent a required skill constraint, generation MUST report the + loss and verification MUST fail when that projection is required by policy. +- **PK-PKG-045:** `init` MAY detect supported harnesses and include their + projections in its installation plan, but MUST NOT install every known + adapter implicitly. Explicitly configured or selected targets take + precedence over detection. +- **PK-PKG-046:** one plan MAY contain several harness targets. Applying it + MUST generate all selected projections from the same canonical catalog and + record adapter versions and source digests, allowing one repository to + support several harnesses without maintaining several skill sources. +- **PK-PKG-047:** selected harness targets and adapter options MUST be + declarative desired state in project configuration. Projection files and + merged harness MCP configuration are observed state; deleting or changing + them creates detectable drift rather than changing the desired catalog. ## Future organizational distributions diff --git a/spec/doc/v1/05-application-and-lifecycle.md b/spec/doc/v1/05-application-and-lifecycle.md index e2239aee..bb90c82f 100644 --- a/spec/doc/v1/05-application-and-lifecycle.md +++ b/spec/doc/v1/05-application-and-lifecycle.md @@ -8,8 +8,8 @@ application installer. Releases publish a wheel, source distribution, source archive, checksums, SBOM, and signature or attestation material. - **PK-CLI-000:** the installed CLI is `processkit`; `pk` MAY be supplied as a - documented alias. All commands accept `--root` and operate on exactly one - project root. + documented alias. All repository commands accept `--root`, where root means + exactly one repository working copy rather than its `context/` directory. ## Command surface @@ -17,22 +17,39 @@ archive, checksums, SBOM, and signature or attestation material. |---|---| | `processkit version` | Report product, source, runtime, and contract versions. | | `processkit help` | Show stable command help. | -| `processkit list KIND` | List installed `skills`, `ontology`, `packages`, `profiles`, `mcp-servers`, or other declared catalog kinds. | -| `processkit init` | Create a new installation plan for an uninitialized root. | -| `processkit plan` | Preview install, update, profile, adapter, or removal changes. | +| `processkit list KIND` | List installed `skills`, `ontology`, `packages`, `profiles`, `mcp-servers`, `harness-adapters`, or another declared catalog kind. | +| `processkit show KIND NAME` | Describe one catalog entry and its source, version, compatibility, and enabled state. | +| `processkit init [--harness TARGET...]` | Convenience form of `plan install` for an uninitialized repository; it creates a reviewable plan and does not apply it. | +| `processkit plan OPERATION` | Preview install, update, reconcile, profile, adapter, or removal changes. | | `processkit apply --plan PLAN` | Apply an exact reviewed plan. | | `processkit verify` | Verify ownership, contracts, projections, and derived state. | | `processkit doctor [--reconcile]` | Diagnose and optionally apply bounded safe repairs. | -| `processkit migrate` | Plan or apply an explicit contract/data migration. | -| `processkit reindex` | Rebuild disposable indexes from canonical files. | -| `processkit generate` | Regenerate declared schemas, indexes, docs, or projections. | +| `processkit migrate plan|apply|verify` | Operate an explicit contract or data migration through reviewed phases. | +| `processkit index status|rebuild` | Inspect or rebuild disposable lexical, semantic, and vector indexes. | +| `processkit generate TARGET` | Regenerate declared schemas, documentation, or manifests that do not require installation reconciliation. | +| `processkit entity get ID` | Read one canonical entity by typed ID or exact repository-relative path. | +| `processkit entity list [TYPE]` | List entities with state, scope, relation, and pagination filters. | +| `processkit entity search QUERY` | Run lexical, semantic, or hybrid retrieval with explicit method and filters. | +| `processkit entity create TYPE` | Create an entity from structured input through its declared operation. | +| `processkit entity update ID` | Update fields allowed by the entity contract. | +| `processkit entity transition ID STATE` | Apply a declared lifecycle transition. | +| `processkit entity link SUBJECT RELATION TARGET` | Create a validated relation or Binding. | +| `processkit entity supersede OLD NEW` | Supersede historical state without silent rewriting. | +| `processkit entity archive ID` | Apply the entity's declared archival operation. | +| `processkit event list` | Query canonical domain events by subject, actor, type, outcome, and time. | +| `processkit context assemble` | Assemble bounded attributed context from one repository for a supplied task. | +| `processkit skill find|route` | Find an applicable skill or route a task through installed policy. | +| `processkit harness detect|verify` | Detect applicable harnesses and verify generated projections; the general catalog lists adapters. | +| `processkit handoff export|import` | Export or import a bounded cross-repository handoff without remote mutation. | | `processkit mcp serve --stdio` | Serve the configured MCP capability set over standard input/output. | -| `processkit mcp proxy` | Adapt stdio to an explicitly configured local MCP endpoint. | +| `processkit mcp serve --http` | Run the same repository-bound MCP application as a long-lived authenticated loopback daemon. | +| `processkit mcp proxy` | Bridge a harness's stdio connection to the configured local daemon. | | `processkit package validate` | Validate a package or extension in isolation. | -- **PK-CLI-009:** EntityType- and skill-specific convenience commands MAY be - added after their MCP operations are stable. They use the same application - services rather than reimplementing semantics. +- **PK-CLI-009:** the generic entity, event, context, skill, and handoff + command groups are mandatory v1 surfaces. EntityType- and skill-specific + convenience aliases MAY be added after their contracts are stable, but use + the same application services and machine envelopes. - **PK-CLI-013:** `list` MUST be read-only and return canonical identity, version, source package, installation status, enabled state where applicable, and compatibility metadata in text and versioned machine form. @@ -42,6 +59,42 @@ archive, checksums, SBOM, and signature or attestation material. - **PK-CLI-015:** products exposing a local MCP server MUST use the common command shape ` mcp serve --stdio`. Product-specific root and capability options MAY extend this shape without renaming the command. +- **PK-CLI-016:** CLI and MCP need not use identical names, but every + repository read or mutation available through both adapters MUST resolve to + the same application operation and produce equivalent outcomes, events, + authorization checks, and recovery behavior. +- **PK-CLI-017:** structured input MUST be accepted from a versioned JSON or + YAML document through an explicit file or standard input. Repeated `--set` + flags MAY support simple interactive use but MUST NOT define a second data + model or silently coerce ambiguous values. +- **PK-CLI-018:** every data-bearing command MUST support a versioned machine + result. Text output is a human projection and MUST NOT be the only way to + recover IDs, revisions, diagnostics, events, or recovery state. +- **PK-CLI-019:** entity mutation commands modify only the selected working + copy. They MUST NOT stage, commit, branch, merge, push, open a pull request, + or contact a Git forge unless a separately named future adapter command is + explicitly invoked. +- **PK-CLI-027:** stdio is the universal v1 MCP baseline. V1 also supports an + optional local daemon over authenticated loopback HTTP and a lightweight + stdio proxy. Remote, unauthenticated, and hosted endpoints are outside v1. +- **PK-CLI-028:** harness projection changes use the ordinary lifecycle: + `processkit plan adapter --harness TARGET...` followed by + `processkit apply --plan PLAN`. `TARGET` is data resolved through the adapter + catalog; v1 MUST NOT add a different top-level command per harness. +- **PK-CLI-029:** `processkit init --harness detected` MAY include every + confidently detected supported harness in the initial plan. With no harness + selection it MUST leave projections unconfigured and report the exact plan + command to add them later. +- **PK-CLI-030:** `processkit plan reconcile` MUST compare the complete + declared repository configuration with observed installed packages, + profiles, harness adapters, generated projections, ownership state, and + derived-state generations. Applying its reviewed plan converges only those + processkit-owned or mergeable surfaces whose preconditions still match. +- **PK-CLI-031:** `processkit plan adapter --harness TARGET...` MAY propose + both the declarative configuration change and its resulting projections. + Once accepted configuration names those targets, ordinary `plan reconcile`, + `apply`, and `verify` MUST be sufficient for later automation; callers do + not need harness-specific imperative commands. ## Lifecycle requirements @@ -101,17 +154,18 @@ archive, checksums, SBOM, and signature or attestation material. - **PK-CLI-025:** root discovery MUST NOT search configured root lists, cross a filesystem boundary implicitly, select a descendant, or choose between multiple repositories by basename. +- **PK-CLI-026:** an invocation MUST report an error when `--root` names the + context directory instead of the repository root unless the implementation + can unambiguously normalize it to the owning repository and reports the + normalized root before mutation. ## Post-v1 CLI directions These directions are intentionally outside the v1.0.0 release gate and need separate accepted contracts before implementation: -- skill authoring, installation, update, enablement, deprecation, and removal; -- provider-neutral prompt assets and their harness-specific slash-command - projections; -- memory review, promotion, compaction, archival, restoration, retention, and - pruning, informed by v0 behavior; and +- harness conversation-memory review or synchronization; repository entity + archival is already part of the v1 entity surface; - company-specific processkit distributions carrying organization-wide processes, policy, skills, prompts, profiles, and MCP capabilities. diff --git a/spec/doc/v1/06-agent-protocol-and-query-surface.md b/spec/doc/v1/06-agent-protocol-and-query-surface.md index 746455d7..09a14a78 100644 --- a/spec/doc/v1/06-agent-protocol-and-query-surface.md +++ b/spec/doc/v1/06-agent-protocol-and-query-surface.md @@ -6,17 +6,24 @@ MCP is processkit's primary agent-facing protocol. The CLI and MCP adapters invoke the same application services and enforce identical validation, authority, mutation, event, and recovery semantics. -The default runtime is a single local process exposing a configured capability -catalog. Per-domain servers can be supported for isolation or debugging, but -do not define competing behavior. +The MCP server serves one explicitly selected repository root. It may be +launched by Airunner, Tau, another harness, an IDE, or a human-operated shell, +but the launcher does not change repository authority. The reference profile +runs locally inside the contributor's execution environment against that +contributor's working copy. + +The runtime exposes one repository's configured capability catalog. It may be +an on-demand stdio process or one long-lived local daemon reused through +direct HTTP clients and lightweight stdio proxies. Both execute the same +application core and enforce the same repository root, policy, locking, +transactions, events, and result contracts. - **PK-MCP-006:** behavior from the existing gateway and domain tools MAY be reused only when new v1 conformance fixtures approve it. Existing tool implementations and observed behavior are not normative. - **PK-MCP-007:** semantics currently distributed across Python per-skill - servers MUST be consolidated into the shared application core. Per-domain - or per-skill servers MAY remain as thin protocol adapters with no independent - validation, mutation, lifecycle, or event authority. + servers MUST be consolidated into the shared application core. Legacy + per-domain servers are migration inputs, not an additional v1 runtime model. ## Discovery @@ -31,10 +38,13 @@ do not define competing behavior. verification failure, not a silently omitted tool. - **PK-MCP-005:** list/read/search tools MUST be clearly distinguishable from project-mutating and externally mutating tools. +- **PK-MCP-008:** discovery MUST expose the selected repository identity, + context path, working-copy revision, read/write capability, and index + freshness without exposing ambient credentials. ## Core read surface -The managed profile provides operations equivalent to: +The standard profile provides operations equivalent to: ```text get_entity(id | path) @@ -73,6 +83,10 @@ assemble_context(task, constraints?, token_budget?, provenance?) EntityTypes own typed create, update, transition, link, supersede, and archive operations as applicable. +The generic CLI entity commands and typed MCP tools are projections of these +same operations. The ontology and capability registries, not adapter-specific +hard-coded lists, determine which operations apply to each EntityType. + - **PK-MCP-020:** mutating tools MUST accept structured requests and return a versioned result containing outcome, affected IDs, emitted event IDs, warnings, and recovery state. @@ -87,14 +101,18 @@ operations as applicable. be retried by orchestrators. - **PK-MCP-025:** authorization is local policy plus host-process authority; MCP connectivity alone MUST NOT grant permission to bypass policy. +- **PK-MCP-026:** a successful mutation changes canonical files only in the + selected working copy. It MUST NOT imply that the change was staged, + committed, reviewed, merged, pushed, or accepted by another clone. ## Runtime and transports - **PK-MCP-030:** stdio MUST be supported for local harness integration and started with `processkit mcp serve --stdio`. -- **PK-MCP-031:** streamable HTTP MAY be supported only on loopback by default; - non-loopback binding requires explicit authorization and an authentication - and transport-security profile. +- **PK-MCP-031:** `processkit mcp serve --http` MAY run as a long-lived daemon + bound to loopback for exactly one repository root. It MUST require + per-client authentication, publish health and catalog-generation metadata, + and reject a request attempting to select another root. - **PK-MCP-032:** requests MUST have size and concurrency limits, cancellation, timeouts, and bounded error payloads. - **PK-MCP-033:** the server MUST isolate request context and correlation data; @@ -102,14 +120,28 @@ operations as applicable. - **PK-MCP-034:** graceful shutdown MUST stop accepting work, complete or cancel active operations according to contract, flush evidence, and release locks. +- **PK-MCP-035:** `processkit mcp proxy` MUST be a bounded transport bridge; it + MUST NOT load tools, reinterpret schemas, weaken authentication, select a + different root, or acquire independent mutation authority. +- **PK-MCP-036:** daemon reuse MUST invalidate or atomically refresh its + capability catalog and derived indexes when the installed manifest, + configuration, canonical generation, or adapter plan changes. A stale + catalog MUST be reported rather than silently served as current. +- **PK-MCP-037:** processkit provides a foreground daemon process and health + contract, not a cross-platform service manager. Aibox, an operating-system + supervisor, or another authorized runtime MAY own start, restart, and stop. ## Cross-repository coordination - **PK-MCP-040:** processkit MAY expose export/import and external-reference - operations, but each call remains scoped to one explicitly selected root. + operations, but each call remains scoped to one explicitly selected root + and returns a bundle for transport by Git, a forge, a harness, or Kaits. - **PK-MCP-041:** a cross-repository handoff MUST identify source repository, source revision, owning entity, requested outcome, and sanitized evidence. - **PK-MCP-042:** receiving a handoff MUST create local project-owned state; it MUST NOT mutate the source repository or claim distributed completion. - **PK-MCP-043:** portfolio orchestration remains a consumer of processkit contracts and is outside the processkit agent runtime. +- **PK-MCP-044:** processkit v1 MUST NOT poll repositories, route messages, + retry remote delivery, manage forge issues or discussions, or run + cross-repository heartbeats. Those are adapter or orchestration concerns. diff --git a/spec/doc/v1/07-configuration-output-and-evidence.md b/spec/doc/v1/07-configuration-output-and-evidence.md index 6967877c..8fb10c84 100644 --- a/spec/doc/v1/07-configuration-output-and-evidence.md +++ b/spec/doc/v1/07-configuration-output-and-evidence.md @@ -27,7 +27,8 @@ compiled defaults configuration with winning and overridden sources and rejected settings. - **PK-CONFIG-006:** invocation overrides are ephemeral unless a dedicated write command explicitly changes project-owned configuration. -- **PK-CONFIG-007:** project configuration is `/processkit.toml` by +- **PK-CONFIG-007:** project configuration is + `/processkit.toml` by default; project policy and mutable operational state MUST NOT share one file. - **PK-CONFIG-008:** system and user files use the operating system's published @@ -36,6 +37,10 @@ compiled defaults - **PK-CONFIG-009:** environment and invocation layers MUST NOT change the selected root after root discovery has loaded project policy; root selection is resolved before other project configuration. +- **PK-CONFIG-010:** project configuration MUST declare the desired profile, + packages, skills, MCP capabilities, and harness-adapter targets needed for + deterministic reconciliation. Machine-local daemon addresses, credentials, + and supervisor state MUST remain in higher-authority local configuration. ## Result envelope @@ -59,6 +64,9 @@ apiVersion, command, outcome, result, diagnostics, correlationId - **PK-OUTPUT-005:** `version` output MUST report product version, source commit, build/package provenance, Python runtime, platform, and supported entity, package, plan, event, and machine-result contract versions. +- **PK-OUTPUT-006:** repository-scoped results MUST identify the normalized + repository root, context path, observed Git revision when available, and + canonical or index generation relevant to the operation. ## Operational logging diff --git a/spec/doc/v1/08-security-and-trust.md b/spec/doc/v1/08-security-and-trust.md index e37f2041..c7062bfc 100644 --- a/spec/doc/v1/08-security-and-trust.md +++ b/spec/doc/v1/08-security-and-trust.md @@ -18,6 +18,7 @@ Trust boundaries exist between: - canonical files and untrusted indexes or caches; - package instructions and executable tools; - one repository and external repositories or services. +- one clone or worktree and another clone or worktree of the same repository. ## Release trust @@ -49,8 +50,15 @@ Trust boundaries exist between: ## MCP and instruction safety -- **PK-SEC-020:** MCP HTTP transport binds to loopback unless a reviewed remote - security profile is explicitly enabled. +- **PK-SEC-020:** stdio is the universal local transport. The optional v1 HTTP + daemon MUST bind to loopback, authenticate every client using credentials + kept outside project-controlled files, enforce origin and request-isolation + controls applicable to the selected MCP transport, and disclose residual + same-host risks. Non-loopback binding is outside v1. +- **PK-SEC-028:** daemon and proxy diagnostics MUST redact bearer material and + MUST NOT place credentials in command arguments, repository configuration, + generated skill projections, or MCP discovery responses. Credential files + require owner-only permissions where the platform supports them. - **PK-SEC-021:** mutating and destructive capabilities MUST be labeled for harness policy and independently checked by processkit. - **PK-SEC-022:** content from packages, entities, external references, and @@ -60,6 +68,17 @@ Trust boundaries exist between: trust and project policy accept them. - **PK-SEC-024:** diagnostics MUST not recommend bypassing containment, signature, validation, approval, or recovery checks. +- **PK-SEC-025:** repository content, including processkit entities changed by + another participant, MUST be treated as untrusted input until normal project + review and validation policy accepts it. A valid schema does not establish + the truth, authorization, or safety of its claims. +- **PK-SEC-026:** processkit MUST NOT infer caller identity or mutation + authority solely from mutable TeamMember files, Git author metadata, harness + prompts, or environment variables. Authority-sensitive operations require an + authenticated runtime principal or an explicit local policy decision. +- **PK-SEC-027:** project TeamMember records MUST NOT be used as storage for + model-provider credentials, harness session secrets, or private conversational + memory. ## Dependencies and privacy diff --git a/spec/doc/v1/09-architecture-and-language.md b/spec/doc/v1/09-architecture-and-language.md index bb1c6ff2..e0fc89e1 100644 --- a/spec/doc/v1/09-architecture-and-language.md +++ b/spec/doc/v1/09-architecture-and-language.md @@ -68,6 +68,13 @@ narrow native component. transaction, interruption, archive, and recovery cases SHOULD be extracted as implementation-independent fixtures before replacement where they remain applicable to the accepted contracts. +- **PK-ARCH-008:** the reference runtime is an on-demand CLI or MCP process, + or an optional long-lived local MCP daemon, bound to one repository working + copy. A sidecar, shared database, remote daemon, or hosted processkit service + MUST NOT be required for v1. +- **PK-ARCH-009:** the Python application MUST remain useful without Aibox, + Airunner, Tau, Kaits, or a Git forge. Those products may launch or consume + it through the documented CLI, MCP, file, and handoff contracts. ## Component boundaries @@ -82,9 +89,14 @@ ports: repository, lexical index, semantic index, package, clock, process, network, rendering ↓ local adapters: filesystem, SQLite/FTS, embedding/vector index, - uv/Python packaging, stdio/HTTP + uv/Python packaging, MCP stdio and loopback HTTP ``` +Each running application instance binds the repository port to one working +copy and the index ports to disposable state derived from that copy. Separate +agents normally have separate clones and index generations; Git review and +merge, not shared index state, reconcile their accepted work. + - **PK-ARCH-010:** domain behavior MUST not depend on CLI parsing, MCP SDK objects, SQLite rows, or ambient process globals. - **PK-ARCH-011:** canonical repository mutation MUST have one implementation @@ -99,6 +111,10 @@ local adapters: filesystem, SQLite/FTS, embedding/vector index, but published JSON Schemas and fixtures remain the interoperability contract. - **PK-ARCH-014:** network release resolution and external connectors are optional adapters and MUST not enter the local domain core. +- **PK-ARCH-016:** Git and forge automation MAY be implemented later as + explicit adapters over proposed changes and handoff bundles. It MUST NOT be + embedded in entity application services or make GitHub-specific concepts + part of the ontology. ## Dependency posture diff --git a/spec/doc/v1/10-verification-strategy.md b/spec/doc/v1/10-verification-strategy.md index ecc3a4a8..a40c9e89 100644 --- a/spec/doc/v1/10-verification-strategy.md +++ b/spec/doc/v1/10-verification-strategy.md @@ -31,8 +31,12 @@ Tests assert observable contracts and failure behavior, not only code paths. unchanged update, local modification, compatible merge, conflict, stale plan, interruption, recovery, downgrade refusal, and conservative uninstall. - **PK-TEST-005:** MCP tests MUST compare runtime discovery with published - schemas and execute requests over stdio; HTTP tests cover loopback security, - concurrency, cancellation, bounds, and shutdown when HTTP ships. + schemas and execute requests over stdio and the authenticated daemon/proxy + path, including concurrency, cancellation, bounds, malformed input, + authentication refusal, catalog refresh, root isolation, and shutdown. +- **PK-TEST-015:** every application operation exposed through both CLI and + MCP MUST have adapter-equivalence tests for successful, refused, stale, + invalid, interrupted, and recovery-required outcomes. - **PK-TEST-006:** query tests MUST compare indexed results with a canonical scan across randomized create/update/archive sequences. - **PK-TEST-014:** semantic and hybrid retrieval tests MUST cover deterministic @@ -49,6 +53,14 @@ Tests assert observable contracts and failure behavior, not only code paths. recovery cases from prior implementations MUST be adapted to the Python artifacts and the new ownership contract. Passing an old implementation's test unchanged is not evidence when its asserted contract differs from v1. +- **PK-TEST-016:** multi-participant tests MUST use independent clones or + worktrees with separate indexes, integrate canonical changes through Git, + and prove that no local lock, cache, or database is mistaken for + cross-working-copy authority. +- **PK-TEST-017:** each supported harness adapter MUST project one canonical + fixture skill, MCP capability, and safety constraint; tests MUST verify + provenance, conflict preservation, idempotence, support-matrix reporting, + and equivalence across all generated harness forms. ## Property and fuzz testing diff --git a/spec/doc/v1/11-compatibility-migration-and-release.md b/spec/doc/v1/11-compatibility-migration-and-release.md index 11a03488..ef811749 100644 --- a/spec/doc/v1/11-compatibility-migration-and-release.md +++ b/spec/doc/v1/11-compatibility-migration-and-release.md @@ -111,7 +111,8 @@ or force-updating a protected branch. - `alpha`: the complete 89-concept ontology registry and generated contracts, repository transactions, install/verify, and MCP workflow proven. -- `beta`: managed profile, extension conformance, migration corpus, complete +- `beta`: standard profile, harness-adapter and extension conformance, + migration corpus, complete security and platform matrices proven; feature freeze begins. - `rc`: documentation, compatibility, performance, package set, and exact candidate journeys complete with no unexplained skips. diff --git a/spec/doc/v1/12-documentation-and-acceptance.md b/spec/doc/v1/12-documentation-and-acceptance.md index a99367ff..f9d5dd89 100644 --- a/spec/doc/v1/12-documentation-and-acceptance.md +++ b/spec/doc/v1/12-documentation-and-acceptance.md @@ -59,20 +59,24 @@ examples, governing decisions, and applicable company standards. 1. Install an exact authenticated release into an empty temporary repository on every supported platform. 2. Verify the installed profile and inspect effective configuration. -3. Start MCP over stdio and discover the declared capability catalog. +3. Start MCP over stdio, then reuse the same capability catalog through an + authenticated local daemon and stdio proxy; prove equivalent operations, + root isolation, refresh, and shutdown behavior. 4. List installed skills, ontology concepts, packages, profiles, and MCP servers in both text and machine form and reconcile the result with package manifests and MCP discovery. 5. Create, query, transition, relate, and supersede representative entities; - verify events and index equivalence. + verify equivalent CLI and MCP outcomes, events, and index state without an + implicit Git commit. 6. Generate and validate coverage for all 89 canonical ontology concepts, exercise every persistent P and C schema, every D discriminator, and every T fragment through at least one consuming contract. 7. Assemble bounded, attributed agent context through lexical, semantic, and hybrid retrieval; delete every derived index, rebuild it from canonical Git files, and obtain functionally equivalent sources without memory loss. -8. Install, discover, verify, and invoke a managed skill and MCP server through - their versioned capability manifests. +8. Install one canonical skill and MCP capability, project them into two + supported harness formats in one reviewed adapter plan, and prove equivalent + discovery, safety metadata, invocation, provenance, and conflict handling. 9. Run a durable process with a gate, evidence, interruption, and resumption. 10. Add and validate a namespaced extension package without core modification. 11. Preview and apply an update with unchanged, locally modified, mergeable, @@ -84,6 +88,17 @@ examples, governing decisions, and applicable company standards. 15. Conservatively uninstall processkit while preserving modified and project-owned content. 16. Build documentation and verify the exact published release artifacts. +17. Run two independently indexed clones as different TeamMembers, integrate + their proposed context changes through an ordinary reviewed Git merge, + rebuild both indexes, and verify that canonical state converges without a + shared processkit database. +18. Confirm that one repository supports human, permanent-agent, and + ephemeral-agent participants while TeamMember state remains project-local + and runtime memory remains outside canonical entities. +19. Add a newly installed harness target to declarative project configuration, + preview and apply the adapter reconciliation, verify convergence, and then + obtain an empty plan from the same desired state without a harness-specific + imperative command. ## Definition of v1.0.0 complete diff --git a/spec/doc/v1/13-standard-entity-types.md b/spec/doc/v1/13-standard-entity-types.md index 64f520ae..ff488daf 100644 --- a/spec/doc/v1/13-standard-entity-types.md +++ b/spec/doc/v1/13-standard-entity-types.md @@ -133,12 +133,27 @@ concepts is a release requirement. ### TeamMember -- **PK-ENTITY-110:** TeamMember composes an Actor identity with team-facing - role defaults, persona, capability references, and bounded memory locations. -- **PK-ENTITY-111:** private memory, credentials, and runtime working state use - separately classified storage and are excluded from exports by default. +- **PK-ENTITY-110:** TeamMember is the selected repository's local + representation of a human, permanent-agent, or ephemeral-agent participant. + It composes an Actor or qualified Actor reference with project-facing role + defaults, persona projection, capability references, engagement class, and + lifecycle. +- **PK-ENTITY-111:** a project TeamMember MUST NOT silently become the + canonical cross-repository identity, private memory store, credential store, + or Airunner session record for that participant. Credentials and runtime + working state remain outside ordinary project entities and exports. - **PK-ENTITY-112:** TeamMember identity remains provider-neutral; runtime model selection is a policy or Binding resolved at invocation time. +- **PK-ENTITY-113:** permanent and ephemeral participation MUST be explicit. + Ephemeral engagement may declare an end condition and narrower authority but + uses the same Actor, Role, Binding, event, and evidence contracts. +- **PK-ENTITY-114:** one TeamMember may hold a scoped team-leader Role without + becoming a different Actor kind. Human companion agents remain AI Actors and + may exercise human authority only through an explicit scoped Binding. +- **PK-ENTITY-115:** resolution of a company-wide canonical identity and its + projection into Airunner is an external identity contract in v1. A project + MAY use a revision-bound qualified reference and retain only locally owned + membership, role, and participation state. ### Binding diff --git a/spec/doc/v1/14-performance-and-operations.md b/spec/doc/v1/14-performance-and-operations.md index 86ec1326..45af8af6 100644 --- a/spec/doc/v1/14-performance-and-operations.md +++ b/spec/doc/v1/14-performance-and-operations.md @@ -15,6 +15,11 @@ The v1 reference profile is one repository containing up to: - 500 installed skills and ProcessSpecifications; and - 16 concurrent read requests with one serialized root mutation. +This is a per-working-copy profile. Multiple agents may operate independent +clones of the same repository; processkit does not coordinate their local +locks or indexes. Git integration detects and resolves concurrent proposed +changes at branch and review boundaries. + - **PK-PERF-000:** larger repositories MAY work but are outside the v1 performance guarantee. @@ -31,6 +36,9 @@ The v1 reference profile is one repository containing up to: one second cold on the reference machine. - **PK-PERF-005:** MCP stdio startup SHOULD advertise capabilities within two seconds with installed dependencies and no network access. +- **PK-PERF-006:** a warm local daemon SHOULD avoid repeated application and + tool-catalog import cost across client connections and report startup, + catalog-load, refresh, request, and proxy overhead separately. These are release objectives, not semantic timeouts. A slower correct result must report measurement and remain cancellable; it must not bypass validation. @@ -55,6 +63,10 @@ must report measurement and remain cancellable; it must not bypass validation. - **PK-OPS-001:** `doctor` reports runtime, contract support, root identity, lock and journal state, canonical validation, ownership drift, projection drift, index generation, package consistency, and configured MCP readiness. +- **PK-OPS-006:** status and diagnostic output MUST distinguish repository + root, context directory, Git revision, canonical generation, and local index + generation so an agent cannot mistake a stale clone or index for current + accepted state. - **PK-OPS-002:** health output MUST distinguish `healthy`, `degraded`, `blocked`, and `recovery_required`; unavailable optional checks are not successes. diff --git a/spec/doc/v1/15-review-decisions.md b/spec/doc/v1/15-review-decisions.md index fcaca927..7dc82a33 100644 --- a/spec/doc/v1/15-review-decisions.md +++ b/spec/doc/v1/15-review-decisions.md @@ -35,8 +35,8 @@ a later measured justification and versioned boundary. ## D3 — One application core -**Proposal:** CLI and MCP become adapters over one application and domain core; -per-skill servers may remain compatibility adapters but own no semantics. +**Proposal:** CLI and MCP become adapters over one application and domain core. +Earlier per-skill servers are migration evidence, not another v1 runtime. **Reason:** one mutation, validation, event, and recovery path prevents the current split authority from recurring. @@ -103,3 +103,91 @@ safely. explicit source adapter. The apparent numeric move from `v2` to a qualified `entity/v1` is a namespace change, not a claim that old data has been silently downgraded. + +## D8 — Repository-scoped process memory + +**Accepted company architecture:** one repository represents one project or +coordination scope and contains one authoritative processkit context. The +context is shared project memory for any number of human and AI participants, +not an agent-private memory repository. + +**Reason:** the repository already supplies the authority, deliverable, +history, collaboration, and review boundary. Agents can use ordinary clones +and branches while processkit gives their shared context typed semantics and +validated operations. + +**Impact:** root means repository root; local indexes are per working copy; +TeamMember is project-local participation state; and processkit does not own +Airunner runtime memory, heartbeat, Git synchronization, or Kaits company +orchestration. + +## D9 — Python command surface + +**Proposal:** ship one Python application with lifecycle, catalog, entity, +event, context, skill, handoff, index, generation, package, and MCP command +groups. CLI and MCP are adapters over identical application operations; typed +MCP tools and optional convenience commands do not create separate semantics. + +**Reason:** humans, scripts, harnesses, and conformance tests need the same +repository capabilities without reproducing validation in shell scripts or +requiring MCP for local administration. Namespaced generic commands avoid a +flat CLI containing one command for every EntityType and skill. + +**Impact:** generic entity and retrieval commands move into mandatory v1 +scope. The tool changes only one selected working copy and never implies Git +commit, review, push, or cross-repository acceptance. + +## D10 — Canonical skills with generated harness adapters + +**Proposal:** processkit continues to own and version skills. Each skill has +one harness-neutral source contract; versioned adapters generate native +discovery files, command aliases, and MCP configuration for selected harnesses. +Initialization may detect and propose supported targets, while the ordinary +plan/apply lifecycle performs changes. There is no top-level command per +harness and no implicit installation of all known adapters. + +**Reason:** harnesses differ in file locations, metadata, invocation syntax, +and MCP configuration, but those differences do not justify divergent copies +of a skill's purpose, safety rules, inputs, or outputs. A generated projection +keeps processkit authoritative while making loss of semantics visible. + +**Impact:** skill authoring and harness projection are v1 capabilities rather +than post-v1 ideas. The release requires adapter support matrices, provenance, +idempotent regeneration, conflict preservation, and cross-harness conformance +fixtures. + +## D11 — Retain the efficient local MCP daemon + +**Proposal:** support both an on-demand stdio server and the useful v0-style +long-lived local gateway daemon with lightweight stdio proxies. The v1 daemon +executes the unified application core directly, serves exactly one repository +root, binds only to loopback, authenticates every client, and refreshes its +catalog safely. Process supervision remains external. + +**Reason:** repeated interpreter startup and registration of a large tool +catalog is avoidable overhead, especially when several harness sessions use +the same working copy. Removing the daemon would discard a proven operational +benefit merely to obtain a smaller topology diagram. + +**Impact:** daemon and proxy are v1 surfaces with root-isolation, credential, +catalog-refresh, concurrency, health, shutdown, and adapter-equivalence tests. +They do not restore per-skill runtime authority, create a shared project +database, or make a hosted service necessary. + +## D12 — Declarative harness reconciliation + +**Proposal:** desired profiles, packages, skills, MCP capabilities, and harness +targets live in versioned project configuration. `plan reconcile` computes the +drift and `apply --plan` converges it. `plan adapter --harness ...` is an +onboarding convenience that proposes the desired-state change as well as the +projection actions. + +**Reason:** adding Tau or another harness later should use the same reviewed, +idempotent plan/apply model as installation and upgrade. A declarative source +also permits future CI/CD or GitOps controllers to run reconciliation without +embedding a separate imperative command sequence. + +**Impact:** v1 does not need to ship a controller, Argo CD integration, or +continuous reconciler. It must provide stable desired-state, plan, machine +result, drift, idempotence, and verification contracts from which those +systems can be built. diff --git a/spec/doc/v1/README.md b/spec/doc/v1/README.md index e5549bce..80bb1e70 100644 --- a/spec/doc/v1/README.md +++ b/spec/doc/v1/README.md @@ -43,7 +43,7 @@ explicit baseline amendment before affected implementation continues. processkit is a composite product with these company-standard profiles: - CLI application; -- local service or worker for MCP transports; +- local per-repository MCP process; - schema, protocol, and process package; - Python library for internal composition and tested extension points; and - documentation website. diff --git a/spec/doc/v1/roadmap.yaml b/spec/doc/v1/roadmap.yaml index be887e07..58b4bbf3 100644 --- a/spec/doc/v1/roadmap.yaml +++ b/spec/doc/v1/roadmap.yaml @@ -29,35 +29,40 @@ groups: status: planned dependencies: [PK1-P0] - id: PK1-P2 - title: Deliver standalone installation and verification + title: Deliver the standalone repository tool summary: >- - Let users install, plan, update, verify, recover, and conservatively - remove an exact release without aibox. + Let users install, inspect, query, mutate, index, verify, recover, + and conservatively remove an exact release against one repository + working copy without aibox, a harness, or a shared service. status: planned dependencies: [PK1-P1] - id: agent-surface title: Agent and authoring surface items: - id: PK1-P3 - title: Deliver agent context, memory, and MCP workflows + title: Deliver equivalent CLI and agent workflows summary: >- Provide lexical, semantic, and hybrid retrieval, bounded attributed context assembly, polymorphic ontology query, validated mutation, - events, configuration inspection, and stdio transport from one core. + events, configuration inspection, generic CLI commands, stdio MCP, + and an authenticated reusable local daemon/proxy path from one + application core. status: planned dependencies: [PK1-P1, PK1-P2] - id: PK1-P4 title: Stabilize skills, MCP servers, packages, and extensions summary: >- - Ship deterministic profiles, provider-neutral skills and processes, - versioned MCP server manifests, conformance tooling, and safe harness - projections. + Ship the standard profile, canonical provider-neutral skills and + processes, versioned MCP manifests, conformance tooling, and + provenance-preserving declarative harness adapters with explicit + support matrices and plan/apply reconciliation. status: planned dependencies: [PK1-P3] - id: PK1-P5 - title: Prove migration and cross-repository handoff + title: Prove migration and Git-mediated collaboration summary: >- - Preserve representative v0 and alpha corpora and exchange bounded + Preserve representative v0 and alpha corpora, converge independent + agent clones through reviewed Git changes, and exchange bounded handoffs without distributed ownership claims. status: planned dependencies: [PK1-P3, PK1-P4]