From 8c66205ec6e09b104c7aa2edf5197be9c1179c5d Mon Sep 17 00:00:00 2001 From: Yvonne Devlin Date: Tue, 18 Aug 2026 11:45:19 +0000 Subject: [PATCH] docs: align spec artifacts to use "overwritten" action terminology ScaffoldDCP() returns "overwritten" (consistent with Scaffold()), but three spec documents still referenced "updated". Align scaffold-dcp.md, design.md, and proposal.md to match the implementation. Identified during review of PR #79. Assisted-by: claude-opus-4-6 Signed-off-by: Yvonne Devlin --- openspec/changes/add-dcp-config/design.md | 4 ++-- openspec/changes/add-dcp-config/proposal.md | 2 +- openspec/changes/add-dcp-config/specs/scaffold-dcp.md | 6 +++--- 3 files changed, 6 insertions(+), 6 deletions(-) diff --git a/openspec/changes/add-dcp-config/design.md b/openspec/changes/add-dcp-config/design.md index fe8252b..8551780 100644 --- a/openspec/changes/add-dcp-config/design.md +++ b/openspec/changes/add-dcp-config/design.md @@ -39,7 +39,7 @@ Check for `.opencode/dcp.jsonc` first, then `.opencode/dcp.json`. If neither exi ### D4: Return single `ScaffoldResult` -`ScaffoldDCP()` returns `(ScaffoldResult, error)` with the same `Path`/`Action` shape used by `Scaffold()`. Actions: "created" (fresh), "skipped" (already has protectTags), "updated" (merged protectTags into existing file). This aligns with **Observable Quality** — consistent, machine-parseable output. +`ScaffoldDCP()` returns `(ScaffoldResult, error)` with the same `Path`/`Action` shape used by `Scaffold()`. Actions: "created" (fresh), "skipped" (already has protectTags), "overwritten" (replaced file with canonical config). This aligns with **Observable Quality** — consistent, machine-parseable output. ### D5: DCP config content matches replicator's own `.opencode/dcp.jsonc` @@ -75,7 +75,7 @@ The doctor check uses the same `strings.Contains` approach as `ScaffoldDCP()` fo ### D10: Update strategy replaces file content entirely -When `ScaffoldDCP()` encounters an existing config file without `protectTags`, the "updated" action replaces the entire file with the canonical DCP config content (from D5). This is simpler and safer than attempting to merge into an arbitrary JSONC structure, which could produce invalid JSON. The trade-off is that user customizations beyond `protectTags` are lost — but DCP configs are typically simple, and the non-goal of "supporting custom DCP config beyond `protectTags: true`" makes this acceptable. +When `ScaffoldDCP()` encounters an existing config file without `protectTags`, the "overwritten" action replaces the entire file with the canonical DCP config content (from D5). This is simpler and safer than attempting to merge into an arbitrary JSONC structure, which could produce invalid JSON. The trade-off is that user customizations beyond `protectTags` are lost — but DCP configs are typically simple, and the non-goal of "supporting custom DCP config beyond `protectTags: true`" makes this acceptable. ### D11: Both files exist — prefer `.jsonc` diff --git a/openspec/changes/add-dcp-config/proposal.md b/openspec/changes/add-dcp-config/proposal.md index 7778829..562cfea 100644 --- a/openspec/changes/add-dcp-config/proposal.md +++ b/openspec/changes/add-dcp-config/proposal.md @@ -57,7 +57,7 @@ The function is independently callable — it does not require `Scaffold()` to r **Assessment**: PASS -`ScaffoldDCP()` returns a `ScaffoldResult` with `Path` and `Action` fields (created/skipped/updated), matching the existing pattern used by `Scaffold()`. The init command renders these results using the same styled output. The DCP config file uses the standard JSON schema reference for validation. +`ScaffoldDCP()` returns a `ScaffoldResult` with `Path` and `Action` fields (created/skipped/overwritten), matching the existing pattern used by `Scaffold()`. The init command renders these results using the same styled output. The DCP config file uses the standard JSON schema reference for validation. ### IV. Testability diff --git a/openspec/changes/add-dcp-config/specs/scaffold-dcp.md b/openspec/changes/add-dcp-config/specs/scaffold-dcp.md index e3727ea..4a5ad15 100644 --- a/openspec/changes/add-dcp-config/specs/scaffold-dcp.md +++ b/openspec/changes/add-dcp-config/specs/scaffold-dcp.md @@ -20,7 +20,7 @@ The `agentkit` package MUST export a `ScaffoldDCP(targetDir string) (ScaffoldRes - **GIVEN** a target directory with `.opencode/dcp.jsonc` that does not contain `"protectTags"` - **WHEN** `ScaffoldDCP(targetDir)` is called -- **THEN** the file MUST be replaced with the canonical DCP config content (including `protectTags: true`), and the result action MUST be "updated" +- **THEN** the file MUST be replaced with the canonical DCP config content (including `protectTags: true`), and the result action MUST be "overwritten" #### Scenario: Both `.dcp.jsonc` and `.dcp.json` exist @@ -43,7 +43,7 @@ The scaffolded `.opencode/dcp.jsonc` MUST contain: ### Requirement: Init command integration -The `replicator init` command MUST call `ScaffoldDCP()` after `Scaffold()` and render the DCP result using the same styled output (green for created, dim for skipped, yellow for updated). +The `replicator init` command MUST call `ScaffoldDCP()` after `Scaffold()` and render the DCP result using the same styled output (green for created, dim for skipped, yellow for overwritten). #### Scenario: `replicator init` on a fresh directory @@ -59,7 +59,7 @@ The `replicator init` command MUST call `ScaffoldDCP()` after `Scaffold()` and r ### Requirement: ScaffoldDCP result shape -`ScaffoldDCP()` MUST return `(ScaffoldResult, error)` where `ScaffoldResult` has `Path` (string) and `Action` (string) fields. The `Action` field MUST be one of: "created", "skipped", "updated". +`ScaffoldDCP()` MUST return `(ScaffoldResult, error)` where `ScaffoldResult` has `Path` (string) and `Action` (string) fields. The `Action` field MUST be one of: "created", "skipped", "overwritten". ### Requirement: `.opencode/` directory creation