chore(openspec): restore project-runtime-01-safe-artifact-write-policy

[djm81]

Summary

Restores the OpenSpec change folder openspec/changes/project-runtime-01-safe-artifact-write-policy/ that was added in bd07b05 and removed in f174ed0 (review fixes). openspec/CHANGE_ORDER.md already references this change and specfact-cli#490 / specfact-cli-modules#177.

Validation

• openspec validate project-runtime-01-safe-artifact-write-policy --strict — pass

Notes

No bundle or registry changes; OpenSpec artifacts only.

Made with Cursor

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, you can upgrade your account or add credits to your account and enable them for code reviews in your settings.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: cd11b37e-1dfe-49b0-b35c-936c5848c7f4

📥 Commits

Reviewing files that changed from the base of the PR and between 16ba2b8 and dc37a24.

📒 Files selected for processing (8)

• openspec/changes/project-runtime-01-safe-artifact-write-policy/.openspec.yaml
• openspec/changes/project-runtime-01-safe-artifact-write-policy/CHANGE_VALIDATION.md
• openspec/changes/project-runtime-01-safe-artifact-write-policy/design.md
• openspec/changes/project-runtime-01-safe-artifact-write-policy/proposal.md
• openspec/changes/project-runtime-01-safe-artifact-write-policy/specs/backlog-add/spec.md
• openspec/changes/project-runtime-01-safe-artifact-write-policy/specs/backlog-sync/spec.md
• openspec/changes/project-runtime-01-safe-artifact-write-policy/specs/runtime-artifact-write-safety/spec.md
• openspec/changes/project-runtime-01-safe-artifact-write-policy/tasks.md

---

📝 Walkthrough

OpenSpec Restoration: project-runtime-01-safe-artifact-write-policy

This PR restores the OpenSpec change folder openspec/changes/project-runtime-01-safe-artifact-write-policy/ that defines the modules-side specification and adoption guidance for safe artifact write semantics in bundle runtime commands.

Bundle and Module Surface

Affected Commands & Capabilities:

• specfact-project, specfact-spec, and other bundle package commands that currently write directly into user repositories
• New capability: runtime-artifact-write-safety — shared safety contract for bundle runtime commands creating or mutating project artifacts
• Modified capabilities: backlog-add and backlog-sync — must apply safe-write contract and avoid silent overwrites

Design Decisions:

• Bundle runtime commands will depend on and reuse the core safe-write helper (no modules-side duplicate abstraction)
• Adoption focuses on persistent user-facing artifacts written to target repositories; internal temp files and caches are out of scope
• All adopting commands must declare ownership at the call site: fully owned, partially owned (keys/blocks), or create-only
• CI will verify adoption through behavior tests rather than a second static scanner (core owns the static contract boundary)

Manifest and Integrity

No changes to module-package.yaml, semver, signatures, or registry metadata. This is purely OpenSpec specification restoration with no code, config, or packaging changes.

Cross-Repo Dependencies

Paired Core Change: specfact-cli/openspec/changes/profile-04-safe-project-artifact-writes defines the authoritative policy language and helper contract that modules runtime packages will consume.

Related Issues:

• Bug context: specfact-cli#487 (silent overwrite failure that safe-write semantics will prevent by design)
• Paired core change: specfact-cli#490
• Modules tracking: #177 (child of parent feature #161)

Implementation Requirements:

• Bundle packages will need to import the core safe-write helper from specfact_cli
• Adoption requires the core helper contract to land or stabilize first
• May require updates to core compatibility floor for bundle packages

Documentation

Comprehensive specification and guidance now in place for implementation:

Proposal (proposal.md): High-level overview of runtime-facing artifact write adapter/utility semantics (create-only, mergeable, append-only, explicit-replace), backup/recovery metadata, and dry-run/preview surfaces.

Design (design.md): Detailed adoption architecture covering goals (reuse core contract, standardize ownership/write declarations, cover first-runner commands, add preservation tests), non-goals (avoid repo-wide refactors, keep policy in core, avoid interactive review workflows), key decisions, risks (core compatibility floor, adoption throughput, merge limitations), and migration plan (wait for core helper, wire into selected commands, add tests, document guidance).

Specifications (3 spec files):

• runtime-artifact-write-safety: Mandate that runtime commands use core safe-write helper with explicit ownership metadata; fail or require explicit replacement on unsupported merge cases
• backlog-add: Local helper flows must follow safe-write contract and preserve unrelated user content
• backlog-sync: Export/sync flows must not silently overwrite; apply safe-write contract or report behavior

Tasks (tasks.md): Structured workflow for safe-write adoption including branch setup, TDD test planning, integration steps (wire helper, declare ownership, remove raw overwrites), quality gates (format/lint/contract/smart tests), and PR opening with cross-linking.

Validation: OpenSpec strict validation passes; all artifacts present and parse successfully.

OpenSpec Change Details

• Change ID: project-runtime-01-safe-artifact-write-policy
• Status: Open for implementation
• Already tracked in openspec/CHANGE_ORDER.md with references to parent feature and paired core change
• Validation: PASS (2026-04-09)
• Open questions: First adopter command selection vs. follow-up inventory; whether ownership metadata belongs in manifests/docs or code-level declaration

Walkthrough

This PR adds a structured change directory documenting the runtime adoption of a safe artifact write policy. It includes proposal, design, specification, and task documents defining how bundle runtime packages should standardize artifact mutation through a core safe-write helper with explicit ownership metadata.

Changes

Cohort / File(s)	Summary
Change Metadata openspec/changes/project-runtime-01-safe-artifact-write-policy/.openspec.yaml, openspec/changes/project-runtime-01-safe-artifact-write-policy/CHANGE_VALIDATION.md	Adds change metadata and validation record confirming proposal/design/specs/tasks parse successfully.
Proposal & Design openspec/changes/project-runtime-01-safe-artifact-write-policy/proposal.md, openspec/changes/project-runtime-01-safe-artifact-write-policy/design.md	Introduces runtime-facing artifact write adapter layer; defines goals, non-goals, key decisions around core helper dependency, ownership declaration at call sites, and migration strategy with tests for content preservation.
Runtime & Backlog Specifications openspec/changes/project-runtime-01-safe-artifact-write-policy/specs/runtime-artifact-write-safety/spec.md, openspec/changes/project-runtime-01-safe-artifact-write-policy/specs/backlog-add/spec.md, openspec/changes/project-runtime-01-safe-artifact-write-policy/specs/backlog-sync/spec.md	Specifies requirements that bundle commands writing artifacts must use core safe-write helper, handle unsupported merge cases gracefully, preserve unrelated user content, and include regression tests.
Task Checklist openspec/changes/project-runtime-01-safe-artifact-write-policy/tasks.md	Defines structured adoption workflow: branch setup with traceability, TDD test evidence, integration with core helper using ownership metadata, post-implementation verification, quality gates, and documentation updates.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~5 minutes

Possibly related issues

• [Change] Safe project artifact writes for init and IDE setup specfact-cli#490: Paired runtime-adoption change implementing the same safe artifact write contract for init/setup flows referenced in this documentation.
• [Change] Runtime adoption of safe artifact write policy #177: Directly related specfact-cli-modules issue documenting the runtime adoption of safe artifact write policy change aligned with this PR's proposal and specifications.

Suggested labels

documentation

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch chore/recover-project-runtime-01-openspec

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}