DevRunbook-Public/PACK_REVIEW.md

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.