Publish DevRunbook source

PACK_REVIEW.md

@@ -0,0 +1,52 @@
+# DevRunbook build-pack review
+
+## Review conclusion
+
+Version 1.0 was a sound product specification and a valid archive, but it was not yet a complete autonomous implementation contract. Its validator proved that the six examples and three JSON Schemas were syntactically valid; it did not prove that the product could be built without major interpretation.
+
+## Material gaps found in v1.0
+
+1. The catalog described 72 concepts but contained only six complete Playbook Packages.
+2. Milestone 1 required the complete seed catalog to import, while 66 entries had no package files to import.
+3. The domain model referenced users, workspaces, memberships, jobs, feedback and audit records without defining their core fields or constraints.
+4. The OpenAPI file covered only a small subset of the documented API and used open-ended objects for important resources.
+5. Conditional fields used unparsed free-text expressions, creating ambiguity and an unsafe temptation to use dynamic evaluation.
+6. The package specification said that only declared files were digested/exported, but the manifest had no file declaration model.
+7. The package and Run Pack digest algorithms were not precise enough to guarantee cross-platform reproducibility.
+8. A playbook had no explicit default work mode, although the seed catalog did.
+9. Repository capability names were not governed; one example required `test`, which did not match repository command roles.
+10. Authentication, first-run ownership, password recovery and workspace authorization were under-specified.
+11. Exact configuration limits, import limits, retention defaults and Gitea network policy were not centralized.
+12. There was no requirements-to-milestone-to-test traceability matrix.
+13. There were no canonical sample Repository Profile and Run Pack artifacts to validate round trips.
+14. Screen-level states and error/recovery behavior remained too high-level for a consistent premium implementation.
+
+## Changes made in v1.1
+
+- Added 28 publishable P0 built-in Playbook Packages; the 72-entry catalog now distinguishes delivered packages from authored backlog.
+- Added explicit package-file declarations, a safe condition AST, default work modes and governed capability vocabulary.
+- Added schemas for conditions, evaluation cases, seed catalog and instance configuration.
+- Added a complete reference PostgreSQL data model and expanded API contract.
+- Added authentication/authorization, first-run, configuration, canonicalization, screen-state, traceability, risk and glossary documents.
+- Added canonical sample profile and Run Pack fixtures.
+- Strengthened pack validation to check cross-file consistency, P0 delivery, semantic rules, sample digests, internal references and required API/database coverage.
+
+## Additional final-audit gaps found after v1.1
+
+1. The pack specified deterministic composition but contained no executable reference renderer or full golden output for every publishable playbook.
+2. Operator start instructions were spread across README and the master prompt rather than one exact Codex entry point.
+3. Parallel agent, worktree, browser-verification and interruption-recovery behavior were not governed.
+4. The initial monorepo bootstrap and canonical root commands remained recommended rather than normative.
+5. The Codex integration document did not yet reflect the current skills/plugins, subagent, worktree, browser and automation workflow surface.
+
+## Changes made in v1.2
+
+- Added one exact Codex operator entry point and resumable execution protocol.
+- Added an executable reference composer, manifest schema and 28 byte-stable golden prompts.
+- Added current Codex-native workflow guidance while keeping product runtime independent of one Codex surface.
+- Added a normative bootstrap repository contract, canonical commands and first vertical-slice proof.
+- Extended offline validation and deterministic archive checks to cover all new artifacts.
+
+## Remaining honest boundaries
+
+This remains a build pack, not a prebuilt application. Version 1.2 removes the remaining material specification and execution-workflow ambiguity found in the final audit, but Codex must still implement and verify the product. Exact third-party package versions must be selected and verified at implementation time. P1 and P2 content is intentionally a reviewed product backlog rather than falsely presented as publishable optimized prompts. Direct Codex execution and write access to Gitea remain outside the MVP.