diff --git a/ACTIVE_SLICE.md b/ACTIVE_SLICE.md index df8d6c1..b74d814 100644 --- a/ACTIVE_SLICE.md +++ b/ACTIVE_SLICE.md @@ -1,11 +1,17 @@ # Active slice +All planned DocForge gates, DFG-0 through DFG-9, are complete. No implementation gate is active. + ```text -Slice: DFG-9 controlled application decision +Slice: DFG-9 controlled application decision (complete) Goal: Decide from DFG-7 and DFG-8 evidence whether a developer-only canonical changeset application command is justified. In scope: Review read-only and proposal workflow evidence; define the exact human authorization boundary; evaluate repeated integration work; require clean base hashes and repeat validation; and either specify one narrow application command or record manual integration as permanent policy. Out of scope: OpenClaw canonical application; automatic commit, push, deployment, or publication; arbitrary commands; accounts; HTTP transport; a web UI; and implementation before the evidence review supports it. Done when: The project records either a proven narrow developer-only application contract or a reasoned decision to keep proposals manually integrated. Owners: DocForge owns proposal evidence and generic safety constraints. Each project owns canonical source semantics and integration policy. A developer retains authorization, review, build, Git, and publication ownership. -Proof: DFG-8 bound OpenClaw to content-only updates for existing AssetForge chapters. A real changeset validated, diffed, previewed, and was manually integrated through the Worldforge builder. Create, move, delete, metadata, relationship, root-manifest, and cross-family changes were denied. Conflict, stale-source, raw-HTML escaping, canonical preservation, and post-integration base-conflict proofs passed. +Decision: Manual canonical integration is the permanent DocForge 0.x policy. No application command was added. +Proof: DFG-8 required one reviewed content replacement after DocForge had already validated, diffed, and previewed the proposal. It completed without failure or material repeated work. An application command would add canonical writers, authorization, rollback, and project-format ownership without measured need. Existing protocol and proposal tests prove that MCP and proposal workflows cannot alter canonical sources. ``` + +**Next gate:** None planned. Monitor real adoption. Reopening canonical application requires a new +approved gate and measured evidence under `docs/APPLICATION_DECISION.md`. diff --git a/README.md b/README.md index f60d83a..d28e3ae 100644 --- a/README.md +++ b/README.md @@ -8,14 +8,15 @@ DocForge does not own project facts. It does not select project work, apply prop commands, or perform Git and deployment operations. It may write only configured derived output and isolated previews through the explicit render boundary. -## Current gate +## Current state -DFG-1 through DFG-8 are complete. Worldforge uses separate read-only sessions and an optional -AssetForge-only proposal process. OpenClaw can update existing AssetForge chapter prose through -isolated, validated changesets and escaped previews; canonical integration remains a developer -review step through Worldforge's established builder. DFG-9 is the active gate: decide from recorded -evidence whether any developer-only application command is justified. Canonical application remains -external and closed to MCP. +DFG-0 through DFG-9 are complete. Worldforge uses separate read-only sessions and an optional +AssetForge-only proposal process. OpenClaw can propose updates to existing AssetForge chapter prose +through isolated, validated changesets and escaped previews. Canonical integration remains a +developer review step through Worldforge's established builder. DFG-9 found no measured need for an +application command, so manual canonical integration is the permanent DocForge 0.x policy. +Canonical application remains external and closed to the library, CLI, and MCP server. See +[`docs/APPLICATION_DECISION.md`](docs/APPLICATION_DECISION.md). ## Development diff --git a/SLICE_HISTORY.md b/SLICE_HISTORY.md index 9b70da5..c6a1ea9 100644 --- a/SLICE_HISTORY.md +++ b/SLICE_HISTORY.md @@ -1,5 +1,37 @@ # Completed slices +## DFG-9 controlled application decision + +### Decision + +- Retained manual canonical integration as the permanent DocForge 0.x policy. +- Added no application command to the library, CLI, or MCP server. +- Kept project builders, tests, Git, deployment, and publication under developer or project-owner + control. +- Required a new approved gate with measured multi-project evidence before canonical application + can be reconsidered. + +### Evidence + +- DFG-8 produced one real content-only AssetForge proposal and one manual chapter replacement. +- Validation, conflicts, diffs, previews, and stale-source handling were already automated. +- Manual integration completed without an error, lost work, or meaningful repeated cost. +- Automating the remaining step would require canonical writers, developer authorization, atomic + rollback, failure recovery, and project-format ownership that the current evidence does not + justify. +- Existing exact-surface MCP tests prohibit application tools, and proposal tests preserve + canonical source bytes. + +### Limits + +- DocForge does not apply, commit, push, build, deploy, or publish canonical changes. +- Reopening the decision requires a separately approved, versioned contract and cannot add MCP + canonical application. + +### Next gate + +No further DFG gate is planned. Continue measured adoption through project-owned integrations. + ## DFG-0 contract freeze and DFG-1 standalone read-only core ### Changed diff --git a/docs/APPLICATION_DECISION.md b/docs/APPLICATION_DECISION.md new file mode 100644 index 0000000..084c347 --- /dev/null +++ b/docs/APPLICATION_DECISION.md @@ -0,0 +1,62 @@ +# Canonical application decision + +**Status:** DFG-9 complete. + +**Decision:** DocForge does not apply changesets to canonical project files. Accepted proposals are +manually integrated through the owning project's established source, build, test, and Git workflow. +This is the permanent DocForge 0.x policy, not a deferred implementation item. + +## Evidence + +DFG-8 produced one real AssetForge proposal. DocForge automated source-hash checks, writer scope, +changeset storage, conflict detection, project validation, structured diffing, and escaped preview +rendering. The remaining integration step was one reviewed content replacement in one existing +Markdown chapter. That step completed without an integration failure, lost work, or material delay. + +There is no recorded evidence of repeated manual-integration errors, costly multi-file application, +or another project requiring canonical application. A generic application command would therefore +add more authority and failure handling than the observed workflow needs. It would require: + +- project-specific Markdown and TOML writers instead of the current read and validation adapters; +- atomic rollback across every affected canonical file; +- recovery when source application succeeds but a project build or validation later fails; +- a developer authorization boundary that cannot be reached through MCP or an agent writer; +- exact handling for create, move, delete, metadata, relationship, and manifest ownership; and +- new cross-project proof that the generic core does not assume Worldforge source semantics. + +Adding those capabilities to remove one deliberate copy step would weaken the existing ownership +boundary without measured benefit. + +## Permanent boundary + +DocForge may read canonical sources and write only configured indexes, changesets, previews, and +declared derived renders. It may validate, diff, and preview a proposed graph. It does not write, +rename, or delete canonical sources through its library, CLI, or MCP server. + +The developer or project owner retains these actions: + +1. review the complete changeset diff and preview; +2. confirm the current canonical source and base hashes still match; +3. manually integrate only the accepted content through the project's canonical source owner; +4. run the project's builder, index refresh, tests, and generated-output checks; and +5. inspect, commit, push, deploy, or publish through the project's normal workflow. + +If canonical state changes before integration, the proposal must be refreshed or recreated. A +developer must not bypass a stale or conflicting changeset by applying it mechanically. + +## Reopening criteria + +DFG-9 is closed. Canonical application may be reconsidered only through a new explicitly approved +gate with measured evidence of repeated integration failures or meaningful repeated work across +more than one project. That gate must define source-format ownership, developer authorization, +atomic rollback, failure recovery, compatibility, and complete cross-project proof before code is +written. It must not add an MCP application tool. + +## Proof + +- The MCP protocol test asserts the exact tool list and rejects any tool name containing `apply`, + `commit`, `push`, `deploy`, `publish`, or `shell`. +- Proposal and adapter tests prove canonical source bytes remain unchanged during create, validate, + diff, preview, conflict, and stale-source operations. +- DFG-8 completed a real reviewed proposal through manual integration and the Worldforge canonical + builder without an application command. diff --git a/docs/CONTRACT.md b/docs/CONTRACT.md index fd04329..2974e3d 100644 --- a/docs/CONTRACT.md +++ b/docs/CONTRACT.md @@ -10,6 +10,11 @@ only isolated changesets. Canonical application, project builds, Git mutation, d publication remain external integration actions. Passive revision detection may read the current Git commit when Git is available; it cannot change repository state. +DFG-9 made manual canonical integration the permanent DocForge 0.x policy. The library, CLI, and +MCP server do not apply changesets to canonical files. Reconsidering that boundary requires a new +approved contract and measured cross-project evidence; it is not an unimplemented 0.x feature. See +`APPLICATION_DECISION.md`. + ## Versioned contracts - Project descriptor schema: `schemas/project.schema.json`, version 1. diff --git a/docs/MCP_CONTRACT.md b/docs/MCP_CONTRACT.md index f22f276..f09aa70 100644 --- a/docs/MCP_CONTRACT.md +++ b/docs/MCP_CONTRACT.md @@ -62,5 +62,9 @@ The normal server never exposes shell execution, arbitrary reads or writes, cano application, declared project-output rendering, arbitrary renderer execution, Git mutation, project builds, deployment, publication, global project selection, or cross-project retrieval. +DFG-9 permanently retained manual canonical integration for DocForge 0.x. No application tool is +planned for MCP. A future local developer workflow may be considered only through a new approved +contract, and it must not make canonical application reachable from an MCP writer. + DocForge pins the official stable Python MCP SDK to the compatible `mcp>=1.28,<2` release line. Migration to a later major release requires a separate contract and protocol compatibility review.