{ "schema_version": "0.1", "decisions": [ { "id": "DEC-001", "title": "Autonomy tier is standing consent to ship; the hard floor is only the dangerous/out-of-scope set", "status": "accepted", "decision": "The consent floor is split in two. (1) Shipping the sanctioned work — commit, push, merge to the work's own main, tag, and publish the package it produces to its configured remote/registry — is governed by automation.autonomy_level, not treated as a blocker. In `autonomous`, the tier is the user's standing consent: the agent ships end-to-end and reports, with the single precondition that the full gate (tests + release/state/gap checks) is green. In `key_decision`/`guided`, the agent still stops for explicit consent before push/merge/publish. (2) A hard floor never unlocks in any tier, including `autonomous`: committing or exposing secrets; force-push or any history-destroying/irreversibly-destructive operation; editing or acting on another repository/service the agent was not pointed at; and spending money or any irreversible outward action that is not shipping this work — plus project-blocker-resolution's human-authority set.", "rationale": "A tier that stops at the ship step is not autonomy. The user opts into `autonomous` per repo; that opt-in is the consent for the outward steps that complete the work. The genuinely irreversible or out-of-scope actions are separated out and kept always-ask, so 'autonomous' never becomes 'unsafe'. Gate-green precondition prevents shipping red.", "options": [ "Keep the absolute floor (autonomous still stops to ship) — rejected: defeats the tier", "Unlock everything in autonomous incl. force-push/other-repos — rejected: unsafe, out of scope", "Split: tier governs shipping, hard set stays (chosen)" ], "consequences": [ "autonomous mode ships without prompting when the gate is green", "force-push, secrets, other-repo edits, and irreversible spend still stop in every tier", "decision-policy skill, CLAUDE/AGENTS (hub+skeleton), git-workflow, and method docs all restate the tiered floor" ], "sources": [ "REQ-059" ], "links": [ "REQ-059", "TRK-049" ], "created_from_session": "SES-CLAUDE-20260710", "created_by_agent": "AGENT-CLAUDE", "created_at": "2026-07-10", "decided_by": "user_requested", "autonomy_tier": "key_decision" }, { "id": "DEC-002", "title": "PRD Plugin owns delegated-reporting policy; AI-Collab owns model execution", "status": "accepted", "decision": "Keep .prd_plugin/config.json as the canonical reporting-delegation policy and expose validated prd_config.py toggles plus deterministic bundle/result contracts. AI-Collab maps model profiles to providers and performs execution; PRD Plugin never stores credentials or calls model APIs.", "rationale": "This preserves the plugin's provider-neutral, zero-runtime-dependency architecture while allowing downstream repositories to opt into cheaper reporting models without splitting configuration truth.", "sources": [ "REQ-084", "ARCH-DEC-008" ], "created_from_session": "SES-001", "created_by_agent": "AGENT-001", "created_at": "2026-07-12", "decided_by": "user_requested", "autonomy_tier": "autonomous" }, { "id": "DEC-003", "summary": "Extend the existing MCP server with five small state tools; reuse the current locked atomic JSON store and add no database, secondary index, reservation subsystem, or new state format.", "decided_by": "user_requested", "autonomy_tier": "autonomous", "linked_ids": [ "REQ-085", "PRD-002", "ARCH-002" ], "owner_agent": "AGENT-MCP", "created_at": "2026-07-12", "rationale": "The user explicitly required a simple but effective CRAFTE design with duplicate IDs made impossible.", "consequences": [ "Record creation owns ID allocation", "Queries are bounded", "Generic mutations are schema-limited", "prd_next_id remains only for embedded planning IDs" ] }, { "id": "DEC-004", "summary": "Use pre-allocated per-worker DBR tracking files with serialized canonical promotion for parallel agents.", "decided_by": "user_requested", "autonomy_tier": "autonomous", "linked_ids": [ "REQ-087", "TRK-079", "HLT-008", "EV-060" ], "owner_agent": "AGENT-MCP", "created_at": "2026-07-13", "rationale": "Separate Git worktrees do not share a live registry or filesystem lock. Pre-allocation gives each worker a distinct mergeable file while keeping canonical TRK and DBR-MERGE allocation under one lead-owned lock.", "options": [ "Keep all project state single-writer and make workers return prose", "Add a database or remote distributed lock", "Pre-allocate one DBR file per worker and promote serially" ], "consequences": [ "Workers never allocate canonical IDs", "Distinct tracking files merge without shared-state conflicts", "The lead must seed branches before fan-out and promote them after merge" ] }, { "id": "DEC-005", "summary": "Run the Substrate adapter in AI-Collab while PRD Plugin retains canonical state and publishes a disabled-by-default off/observe/coordinate configuration and versioned contracts.", "decided_by": "user_requested", "autonomy_tier": "autonomous", "linked_ids": [ "REQ-091", "PRD-005", "ARCH-005", "IMP-006", "TRK-091" ], "owner_agent": "AGENT-CODEX", "created_at": "2026-07-14", "rationale": "AI-Collab already owns Substrate connectivity, workspace permissions, subscriptions, routing, and model execution. PRD Plugin already owns durable project truth, duplicate-safe IDs, validation, graph export, reporting bundles, and MCP mutations.", "options": [ "Build a new PRD-hosted Substrate service", "Keep fragmented hand-written AI-Collab integration", "Use a thin AI-Collab adapter over official PRD contracts" ], "consequences": [ "PRD Plugin remains independently usable when AI-Collab is absent.", "AI-Collab-local bindings and credentials stay out of committed repo configuration.", "Coordinate mode must invoke MCP tools and cannot write canonical JSON directly." ] }, { "id": "DEC-006", "summary": "Adopt one configurable deterministic workflow engine with explicit validated LLM judgment boundaries", "decided_by": "user_requested", "autonomy_tier": "autonomous", "linked_ids": [ "REQ-096", "TRK-101", "PRD-008", "ARCH-008", "ARCH-DEC-030", "ARCH-DEC-033" ], "owner_agent": "AGENT-MCP", "created_at": "2026-07-14", "rationale": "Finite, source-backed rules should own orchestration, policy, state, validation, evidence, and lifecycle mechanics. Only irreducible judgment should reach an LLM, through immutable inputs and schema-validated outputs with no direct canonical write authority.", "options": [ "Leave orchestration in host prompts", "Add isolated deterministic helpers", "Adopt one complete deterministic workflow authority with bounded judgment overlays" ], "consequences": [ "Completed runs require declared postconditions", "External runtime owns optional model execution", "Workflow configuration, catalog, run state, tools, hooks, skills, installer, and documentation become downstream-facing contracts" ] }, { "id": "DEC-007", "summary": "Agents must discover and use available Substrate memory, LLM wiki, and PRD/UTCP capabilities before raw file/history search; subagents require an explicit user request, remain few, and may not spawn descendants.", "decided_by": "user_requested", "autonomy_tier": "autonomous", "linked_ids": [ "TRK-109" ], "owner_agent": "codex", "created_at": "2026-07-15", "rationale": "Durable structured knowledge and tool discovery reduce repeated derivation and token burn; uncontrolled recursive delegation increases cost, coordination risk, and state contention.", "options": [ "Raw repo search first with optional Substrate recall", "Substrate/wiki/tool discovery first with raw search fallback", "Unrestricted recursive subagent fan-out" ], "consequences": [ "Resolve-before-ask order changes across hub and downstream instructions.", "Subagent use becomes opt-in, capped, and one level deep.", "Raw code and git search remain a fallback for exact implementation facts or unavailable/stale higher-level knowledge." ] }, { "id": "DEC-008", "summary": "Use one executable, version-negotiated Substrate bridge with PRD Plugin canonical authority, per-workflow capability profiles, and complete local fallback", "decided_by": "autonomous", "autonomy_tier": "autonomous", "linked_ids": [ "REQ-099", "TRK-111", "PRD-009", "ARCH-009" ], "owner_agent": "AGENT-MCP", "created_at": "2026-07-15", "rationale": "The audit found an export-only adapter and disconnected request bundles; a central bridge avoids duplicated direct calls and enables Knowledge Hub, memory/context, verification, goals, bus, and optional services without creating a second project-truth authority.", "options": [ "Keep the export-only adapter and document manual execution", "Add direct Substrate calls independently to each workflow", "Use one negotiated bridge and capability-policy layer" ], "consequences": [ "PRD remains the canonical state writer", "External features are independently configurable and default to safe fallbacks", "Cross-version contract fixtures and downstream parity become release requirements" ] }, { "id": "DEC-009", "summary": "Add a versioned repository service consume/provide manifest to the Substrate parity implementation", "decided_by": "user_requested", "autonomy_tier": "autonomous", "linked_ids": [ "REQ-099", "REQ-100", "TRK-112", "PRD-009", "ARCH-009", "IMP-010" ], "owner_agent": "AGENT-MCP", "created_at": "2026-07-15", "rationale": "The manifest supplies deterministic service discovery, compatibility, and fallback intent for every PRD-enabled repository and prevents capability inference drift.", "options": [ "Infer services dynamically from code and config", "Store declarations only in central Substrate state", "Ship a local canonical services.json and advertise it through the bridge" ], "consequences": [ "Installer creates and preserves the manifest", "Validated CRUD and audit tooling becomes part of the plugin", "Handshake and federation consume the manifest while local operation remains possible" ] }, { "id": "DEC-010", "summary": "Ship D:\\Projects\\prd-plugin as the default upstream request hub", "decided_by": "user_requested", "autonomy_tier": "autonomous", "linked_ids": [ "TRK-114" ], "owner_agent": "AGENT-CODEX", "created_at": "2026-07-15", "rationale": "The workspace has one stable hub and downstream request delivery must work immediately after install or safe update.", "consequences": [ "Fresh installs are pre-routed to the workspace hub.", "Safe updates repair null routing values.", "Explicit non-null repository overrides and PRD_UPSTREAM_HUB remain authoritative." ] }, { "id": "DEC-011", "summary": "Addressed routing: the channel guard warns rather than refuses (BR-Q-011), and a message to a repo with no active agent queues durably rather than ageing out (BR-Q-013).", "decided_by": "user_requested", "autonomy_tier": "autonomous", "linked_ids": [ "REQ-133", "REQ-134" ], "owner_agent": "AGENT-CLAUDE", "created_at": "2026-07-19", "rationale": "Owner asked for both open questions to be decided against the quality bar. Both land on one principle: never solve a visibility problem with a destructive or blocking mechanism. BR-Q-011 - an in-workspace send crosses no boundary (same workspace, same substrate, no new surface, no secret exposure), so hard refusal buys no security while blocking a legitimate durable-record intent. Workspace membership is DERIVED from the service manifest, so a stale or missing field would turn refusal into an unoverridable block on legitimate traffic - the failure direction this project keeps hitting. Refusal also strictly costs more, forcing an override plus override auditing. Strictness belongs instead on writes into an UNDECLARED peer's inbox, the genuinely exposed boundary. BR-Q-013 - delivery and being read are different things (REQ-133); a dormant repo may become active later; time-based destructive deletion contradicts both the no-timescales rule and the storage contract accepted from ai-collab-v3 (rotation never deletes unacknowledged data); and expiry needs clock-dependent tests this codebase avoids. The black-hole fear is real but is a visibility problem, solved by reporting delivered-but-unacknowledged messages on the sender's side.", "options": [ "BR-Q-011 hard-refuse in-workspace sends: enforces the boundary absolutely, but blocks durable-record intent, needs an override mechanism, and makes a stale manifest field an unoverridable block.", "BR-Q-011 warn and proceed (CHOSEN): named finding recommending the workspace's own chat, message still delivered; degrades safely when derived data is wrong.", "BR-Q-013 age out with a staleness finding: prevents silent black holes, but destroys unacknowledged records on a timer and needs clock-dependent tests.", "BR-Q-013 queue durably and report unacknowledged delivery (CHOSEN): the record never dies, the silence becomes visible to the sender." ], "consequences": [ "The channel guard is advisory, so in-workspace agents can still file durable requests deliberately; the finding keeps default routing honest without a block.", "Hard refusal must be implemented on the undeclared-peer boundary instead (BR-DEC-026; BR-Q-008/009 remain open).", "No expiry sweeper, tombstones, or recovery path is needed; the queue is existing behaviour plus a report.", "message_check gains a delivered-but-unacknowledged report so a silent peer is visible without data loss." ] }, { "id": "DEC-012", "summary": "Addressed routing, remaining four: one peers map holding paths (BR-Q-007), one-sided declaration (BR-Q-008), undeclared refuses delivery but never the filing while unreachable holds and reports (BR-Q-009), and workspace equality as the boundary (BR-Q-012).", "decided_by": "user_requested", "autonomy_tier": "autonomous", "linked_ids": [ "DEC-011", "REQ-133", "REQ-134" ], "owner_agent": "AGENT-CLAUDE", "created_at": "2026-07-19", "rationale": "Owner's constraint is the deciding input: this should have been a tool that drops a file in a peer's inbox folder, and it has been over-engineered. Every answer is therefore the smallest sufficient mechanism, and nothing new may block a message. BR-Q-007 - the service manifest declares service relationships but holds NO filesystem paths, so it cannot be the source of truth for delivery; a single requests.peers map of repo id -> path is the exact generalization of the existing, proven requests.upstream_hub_path, where a configured path IS the consent to deliver there. One registry, already precedented, no manifest changes. BR-Q-008 - one-sided: A declaring B suffices. An inbox is a mailbox, not canonical state; import remains the recipient's explicit act, so an unsolicited package cannot corrupt their truth. Mutual declaration doubles configuration and creates a deadlock where neither side can start, for no safety gain. BR-Q-009 - the filing is local and always succeeds, because refusing it destroys what the agent wrote. An UNDECLARED target refuses DELIVERY only (consent floor: never write into a repo you were not pointed at) and names the fix. An UNREACHABLE declared target holds in the outbox with a named finding and retries on the next flush - identical to the behaviour REQ-133 already ships for replies. BR-Q-012 - workspace equality: static, declared, deterministic. Substrate reachability is runtime-dependent and flaps, and since the guard is advisory (DEC-011) a flapping advisory is pure noise.", "options": [ "BR-Q-007 manifest as directory: semantically meaningful but holds no paths, so it cannot answer 'where do I write this'.", "BR-Q-007 single requests.peers map of id -> path (CHOSEN): generalizes upstream_hub_path, one place, no second registry of the same fact.", "BR-Q-008 mutual declaration: prevents unsolicited traffic, but doubles config and deadlocks first contact.", "BR-Q-008 one-sided declaration (CHOSEN): an inbox is a mailbox; import stays the recipient's explicit act.", "BR-Q-009 refuse the filing outright: loses the agent's written content.", "BR-Q-009 file locally always; refuse delivery when undeclared, hold and report when unreachable (CHOSEN).", "BR-Q-012 substrate reachability: more accurate but flaps at runtime.", "BR-Q-012 workspace equality (CHOSEN): already declared, deterministic, sufficient for an advisory guard." ], "consequences": [ "New surface is small: one config map, one lifecycle field (target_repo), one routing module, and the destinations tool. Transport, provenance, import, reply and flush already exist and are verified.", "A message can never be lost by a routing decision: the filing always succeeds and undelivered packages persist with a named finding.", "Delivering to a peer requires only that the sender configure the peer's path; the recipient does nothing until they choose to import.", "The workspace guard stays advisory and static, so it cannot flap or block." ] }, { "id": "DEC-013", "summary": "Add Bounded as the eighth dimension of the decision-quality bar: CRAFTES becomes CRAFTESB.", "decided_by": "user_requested", "autonomy_tier": "autonomous", "linked_ids": [ "DEC-011", "DEC-012" ], "owner_agent": "AGENT-CLAUDE", "created_at": "2026-07-19", "rationale": "Owner reported agents over-engineering and inflating scope, naming a weaker model as especially prone to it. Efficient already said 'smallest sufficient implementation' and agents over-engineered anyway - including in the session that produced this dimension. The cause is identifiable in the old wording: 'without reducing scope' bounds scope DOWNWARD only. It forbids under-delivering and says nothing about growing the problem, so a minimal, elegant implementation of three features nobody asked for passed the bar cleanly. Efficient bounds the size of the SOLUTION; Bounded bounds the size of the PROBLEM - genuinely different failures. A distinct letter was chosen over redefining Efficient because the stated target is weak models: salience in the acronym repeated in every prompt is the intervention, and the empirical evidence that Efficient alone is insufficient is that it already existed and failed. Bounded is falsifiable rather than a virtue rating - it asks a question with a wrong answer ('name the smallest thing that satisfies the literal ask; if you cannot state the smaller alternative you rejected, you have not considered one') and names concrete scope-inflation patterns.", "options": [ "Redefine Efficient to be two-sided (CHOSEN AGAINST): fixes the wording gap but has no salience for a model that skims, and Efficient already failed empirically.", "Add Bounded as a distinct dimension, CRAFTESB (CHOSEN): names a genuinely different failure and is visible in every prompt.", "Add a scope-detection gate check (CHOSEN AGAINST): building a scope-policing subsystem to enforce an anti-over-engineering rule would be the failure it forbids; a text-pinning test is proportionate." ], "consequences": [ "The bar is CRAFTESB across all twelve stating surfaces; a test pins Bounded everywhere so it cannot silently drift or be dropped.", "'without reducing scope' is removed from every normative statement; the wiki keeps it only as a historical quotation explaining the gap.", "Bounded explicitly does not soften 'implement, don't file' - it decides WHAT is implemented, not WHETHER, so a gap inside the ask is still fixed now.", "Fixed a defect shipped by the 0.16.27 Secure edit: four always-in-force docs stated 'Efficient - Secure - Secure' with the dimension duplicated." ] }, { "id": "DEC-014", "summary": "UTCP-first is achieved by inverting DEFINITION authority to templates/tool-spec.json; @utcp/mcp-bridge ships as a supported, verified configuration rather than replacing the validated named-tool MCP server as the downstream default.", "decided_by": "autonomous", "autonomy_tier": "autonomous", "linked_ids": [ "REQ-107", "HLT-020" ], "owner_agent": "AGENT-CLAUDE", "created_at": "2026-07-21", "rationale": "Owner directed UTCP-first with the MCP bridge as the official SDK way. Grounding the bridge's actual contract changed what the right implementation is. @utcp/mcp-bridge does NOT proxy a manual's tools as named MCP tools: mounted against our manual it exposes a 7 meta-tool facade - register_manual, deregister_manual, call_tool, search_tools, list_tools, get_required_keys_for_tool, tool_info - so an MCP client would call call_tool('prd_plugin.prd_file_request', ...) rather than prd_file_request. Making that the downstream DEFAULT would replace 62 first-class named tools with 7 generic ones and break every skill, command and doc that names a tool, in every downstream repo. CRAFTESB: Correct and Robust reject that regression; Bounded says UTCP-first is a statement about AUTHORITY, which the inversion delivers; and Faithful notes REQ-107's own wording is 'retired as a HAND-MAINTAINED surface', which is now literally true because the server reads its definitions from the spec instead of declaring them. So the substance of REQ-107 lands without the ergonomic regression.", "options": [ "Point downstream .mcp.json at @utcp/mcp-bridge as the default (REJECTED): faithful to one clause of REQ-107 but collapses 62 named tools into a 7-tool search/call facade and breaks every named-tool reference.", "Invert definition authority to the spec; ship the bridge as a supported verified config (CHOSEN): manual is the source, neither surface can drift, UTCP hosts get the full manual, MCP clients keep validated named tools.", "Leave authority with the server (REJECTED): the MCP-first wrapper the owner correctly identified as wrong." ], "consequences": [ "templates/tool-spec.json is the source of tool definitions; mcp/server.cjs reads it and tool-metadata.json is a derived projection checked AGAINST it.", "The manual is generated from the spec, so a tool cannot exist on one transport and be missing from the other.", "templates/utcp-config.json ships so any UTCP host or the official bridge can mount the full manual; verified against @utcp/mcp-bridge 1.1.0.", "Handler execution is untouched by this phase - locking, allocation, validation and atomic writes migrate to native entry points tool by tool, so the canonical write path is never rewritten in one leap." ] }, { "id": "DEC-015", "summary": "REQ-072 (opencode run-until-done) is closed as an upstream host limitation, not deferred work: OpenCode's session.idle is a notification, not a vetoable stop.", "decided_by": "autonomous", "autonomy_tier": "autonomous", "linked_ids": [ "REQ-072" ], "owner_agent": "AGENT-CLAUDE", "created_at": "2026-07-21", "rationale": "The stop guard enforces run-until-done by BLOCKING a stop. That requires a host event the plugin can veto. Claude exposes Stop and Codex exposes Stop, both vetoable via exit code 2. OpenCode exposes session.idle, which is a notification fired after the fact - there is nothing to block. No implementation on our side can create a veto the host does not offer, so leaving this open misrepresents reachable work as pending. The behaviour already degrades correctly to a printed reminder, and the limitation is documented in wiki/hooks/claude-code-hooks.md under cross-host parity. Every other hook behaviour reaches full parity on all three hosts. Reopen if OpenCode ships a blocking stop event.", "options": [ "Keep it open as pending work (REJECTED): nothing we can build closes it, so it inflates the backlog with an unreachable item.", "Close as a host limitation with the rationale recorded (CHOSEN): honest about what is and is not reachable, and reopenable if the host changes.", "Poll or re-inject after session.idle to simulate a block (REJECTED): fights the host, cannot actually prevent the stop, and would fire after the session has already ended." ], "consequences": [ "run-until-done is enforceable on Claude and Codex, and advisory on OpenCode - stated plainly rather than implied as a gap.", "The wiki already documents it; no further work is scheduled.", "Reopen only if OpenCode gains a vetoable stop event." ] }, { "id": "DEC-016", "summary": "REQ-104: do not exempt prd_file_request from the parallel-worker write boundary. Keep REQ-104 open as designed work and answer ai-collab-v3 with the finding plus the two paths that already work.", "decided_by": "autonomous", "autonomy_tier": "autonomous", "linked_ids": [ "REQ-104" ], "owner_agent": "AGENT-MCP", "created_at": "2026-07-21", "rationale": "The obvious small fix - drop prd_file_request from CANONICAL_WRITE_TOOLS - looked like the bounded answer and is wrong. Filing a request ALLOCATES a REQ id, and the boundary guarantees, with a test asserting the registry is byte-unchanged, that a worker session allocates no canonical IDs at all. That invariant exists so a lead's ID space is not churned by workers it does not control; weakening it to unblock one caller trades a system-wide guarantee for a local convenience. What REQ-104 actually needs is an intake lane that does not allocate at file time - a queued proposal the lead materialises into a REQ - which is designed work, not a one-line exemption tacked onto a release.", "options": [ { "option": "Exempt prd_file_request from the worker boundary", "outcome": "rejected: breaks the no-canonical-ID-allocation invariant workers rely on" }, { "option": "Queued proposals materialised by the lead", "outcome": "the right shape; designed work, stays in REQ-104" }, { "option": "Use the paths that already work", "outcome": "adopted as the interim answer, no hub change needed" } ], "consequences": [ "REQ-104 stays in_review as designed work rather than being closed or half-built.", "Their room agents are treated as workers only because PRD_WORKER_SESSION or PRD_TRACKING_BRANCH_ID/OWNER is set; tracking.branching.require_for_parallel_agents controls the enforcement if that is mis-scoped for their topology.", "The cross-repo path, prd_send_request into this hub's inbox, is how every other report they have filed reached us and needs no local canonical allocation." ] } ] }