Finalize ConfigKit design and implementation plan

docs/development.md

@@ -1,54 +1,56 @@
 # Development
 
-This is the contributor entry point for thsi application. Use the task-specific
-reading guide below before making changes. Canonical architecture, contracts,
-component behavior, and policies remain in their owning documents.
+This is the contributor entry point for ConfigKit. Read the task-specific owners
+below before making changes. The repository is in pre-implementation: it has no
+Go module, packages, tests, or executable examples yet. The
+[component overview](internal/overview.md) owns the implementation inventory.
 
-## Initial Orientation
+## Initial orientation
 
-Before starting work:
+1. Inspect the working tree and preserve unrelated changes.
+2. Read the architecture policy for code or design work.
+3. Read the policy, contract, and internal documents applicable to the task.
+4. Inspect relevant implementation and tests where they exist before changing them.
 
-1. inspect the working tree and preserve unrelated changes;
-2. read the architecture policy for code or design work;
-3. read the policy, contract, and internal documents listed for the task;
-4. inspect the relevant implementation and tests before deciding how to change
-   them.
+## Task-specific reading guide
 
-Start with:
-
-- [Architecture policy](policy/architecture.md) for system boundaries,
-  invariants, and non-goals;
-- [Internal component overview](internal/overview.md) for the current package
-  and component map;
-- [Documentation policy](policy/documentation.md) before changing
-  documentation;
-- [Testing policy](policy/testing.md) before adding, rewriting, or deleting
-  tests.
-
-## Task-Specific Reading Guide
-
-| Task | Read before changing |
+| Task | Read |
 | --- | --- |
-| Repository orientation or component responsibility | [Internal component overview](internal/overview.md) and [architecture policy](policy/architecture.md) |
-| Examples or copyable assets | The owning contract for the demonstrated behavior and the related files under `examples/` |
-| Architecture decisions or future work | The [documentation policy](policy/documentation.md) and relevant accepted ADRs |
+| Repository orientation or component responsibility | [Architecture policy](policy/architecture.md) and [component overview](internal/overview.md) |
+| Documentation changes | [Documentation policy](policy/documentation.md) and the owning document |
+| Architecture decisions or future work | [Documentation policy](policy/documentation.md), [initial target design](roadmap/initial.md), and relevant ADRs listed below |
+| Code and test changes | [Architecture policy](policy/architecture.md), [testing policy](policy/testing.md), and owning contracts/tests as they are introduced |
+| Examples or copyable assets | The owning implemented contract and related maintained examples, once available |
+| Release preparation | [Release policy](policy/release.md) and [release-readiness gaps](roadmap/release-readiness.md); the operational runbook will be added before release |
 
-For cross-cutting changes, follow every applicable row. Internal component
-documents own detailed subsystem change recipes.
+Accepted decisions:
 
-## Baseline Validation
+- [Separate composition and overlay](adr/0001-separate-composition-and-overlay.md)
+- [Own YAML semantics behind a private parser boundary](adr/0002-own-yaml-semantics.md)
+- [Preserve presence and record application resolution](adr/0003-preserve-presence-and-resolution-history.md)
 
-Use focused checks while iterating, then run validation proportionate to the
-change and the risks described by the testing policy.
+For cross-cutting changes, follow every applicable row. The implementation plan
+remains deferred; `docs/roadmap/implementation.md` has not been created.
 
-The repository-level baseline for code changes is:
+## Baseline validation
 
-```bash
-go test ./...
-go vet ./...
-go build ./cmd/scriptorium
+For the current documentation-only repository:
+
+```sh
+git diff --check
 ```
 
-Documentation-only work does not require the full Go suite unless it changes
-commands, examples, generated output, or another behavior that the suite
-validates. Always check changed links, paths, examples, and canonical ownership.
+Also inspect new untracked documents, verify changed local links and heading
+fragments, and review paths, examples, ownership, and current-versus-planned
+claims. The command above does not check links or untracked content.
+
+Go validation is not runnable until a module and packages exist. The scaffolding
+change must establish and verify library test, vet, and build commands here,
+including their prerequisites. Do not use an application binary build as the
+library baseline. Add executable-example and other checks when those artifacts
+are introduced; do not document nonexistent tools as operational.
+
+Once code exists, use focused checks while iterating and validation proportionate
+to the change under the testing policy. Documentation-only work does not require
+Go checks unless it changes behavior-bearing examples or commands they validate.
+Release validation is a separate, stricter gate governed by release policy.