Skip to content

docs(project-harness): add rollback evidence case study - #202

Open
Garfielk wants to merge 1 commit into
QoderAI:mainfrom
Garfielk:docs/recovery-evidence-case-study
Open

Garfielk wants to merge 1 commit into
QoderAI:mainfrom
Garfielk:docs/recovery-evidence-case-study

Conversation

@Garfielk

Copy link
Copy Markdown

Summary

Add a fictional deployment rollback case study that explains what Present, Wired, and Exercised evidence can establish. Link it from the existing recovery inspection guide so readers can compare the abstract rules with a worked example.

The example separates an observed attempt from a successful recovery and explicitly states that its synthetic receipts prove no actual execution.

Why

  • Issue/Story: No linked issue. This is a focused documentation/community contribution through the examples surface in docs/community.md; it changes no public behavior or contract.
  • User or maintainer outcome: Readers can distinguish an existing mechanism, a connected recovery route, and a recorded exercise without overstating production or data-restoration evidence.

Traceability and Scope

  • Spec/ADR, if applicable: No new behavior spec is needed for this documentation-only example. Canonical inspection rules remain in references/project-harness/recovery-evidence.md; scoring remains owned by models/agent-work-loop.md.
  • Acceptance criteria addressed: Show the three evidence levels; state the fictional and non-runtime boundary; illustrate a failed exercise and unobserved production evidence; provide resolvable links.
  • Canonical owners changed: Add case-studies/project-harness/rollback-rehearsal-evidence.md; add only a conditional example link to references/project-harness/recovery-evidence.md.
  • Explicit non-goals: No runtime logic, schema, scoring change, command, hook, host adapter, deployment, or recovery execution.

Change Type

  • Feature
  • Bug fix
  • Tests only
  • Documentation/community
  • Refactor with no intended behavior change
  • Dependency, packaging, or infrastructure

Test and Review Evidence

Checks ran on macOS using Node.js v24.21.0 selected through mise exec node@24.21.0 --.

Check Result
mise exec node@24.21.0 -- node scripts/doc-link-graph/cli.mjs skills/better-harness Passed; 39 files, 56 links; generated graph unchanged.
mise exec node@24.21.0 -- npx vitest run test/skills-docs/doc-link-graph.test.mjs Passed: 1 test file, 8 tests.
mise exec node@24.21.0 -- npm run pack:verify Passed: npm package 747 entries; runtime ZIP 1008 entries.
git diff --check Passed before staging.
Independent AI Standards and Spec review of the final document 0 actionable findings on either axis.

Manual or visual evidence: Before this change, the recovery guide described the evidence levels without this worked example. Afterward, its example link leads to a fictional scenario, evidence comparison, synthetic receipt, and bounded review return. The contributor chose the scope and requested the final simplification. No independent human technical validation or real recovery exercise is claimed. Runtime, browser, and full cross-platform suites were not run for this prose-only change.

Risk and Recovery

  • Compatibility and cross-platform impact: Prose and relative Markdown links only; no platform-specific executable commands are introduced. Local checks ran on macOS and do not establish Windows or Linux execution evidence.
  • Package, plugin, schema, or generated-file impact: The case study is included through the existing documentation package surface; package verification passed. No manifest, schema, dependency, or generated-file changes.
  • Rollback or recovery path: Door: two-way. Blast radius: documentation. Revert this documentation commit, including the inbound example link.
  • Residual risk or unverified boundary: Synthetic records could be mistaken for real observations; the scope and receipt sections explicitly exclude that interpretation. No actual deployment, production recovery, data restoration, or recovery-time result was tested.

AI Involvement

  • Level: Generated. Codex authored and simplified the document; separate read-only AI reviewers checked standards and the confirmed requirements.
  • Human review and validation: The contributor selected the contribution and approved the simplification/submission workflow. No independent human review of technical correctness or live recovery validation is recorded.

Checklist

  • I followed AGENTS.md, CONTRIBUTING.md, and the relevant canonical-owner guidance.
  • The change is focused and does not include unrelated local or generated state.
  • Tests and documentation match the behavior actually delivered.
  • Markdown links were checked when documentation moved or changed.
  • Cross-platform behavior was considered for Windows, macOS, and Linux.
  • Package/runtime verification was run when shipped files or dependencies changed.
  • User-facing or compatibility changes are recorded in CHANGELOG.md. Not applicable: this adds a reference example without changing installation, commands, output, compatibility, or extension contracts; AGENTS.md excludes unsolicited changelog edits.
  • I have the right to contribute this work under the repository's MIT License.

Add a fictional deployment rollback example that distinguishes Present,
Wired, and Exercised evidence, including an exercised recovery that fails
its postcondition. Keep the inspection and scoring owners unchanged, and
link the example from the existing recovery guide.

This focused documentation contribution needs no new behavior spec. The
synthetic records provide no evidence of real deployment or recovery.
Validated with the doc-link graph suite (8 tests), graph regeneration,
package verification, and independent standards and requirements review.

Co-authored-by: Codex (GPT-6) <codex@openai.com>

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant