mirror of
https://github.com/merlinhu1/codex-game-studio.git
synced 2026-08-25 07:54:34 +02:00
chore: add truthmark structure and runtime safeguards
This commit is contained in:
MerlinH
@@ -0,0 +1,29 @@
|
||||
---
|
||||
status: active
|
||||
doc_type: workflow
|
||||
last_reviewed: 2026-05-28
|
||||
source_of_truth:
|
||||
- ../../AGENTS.md
|
||||
---
|
||||
|
||||
# Repository Rules
|
||||
|
||||
## Purpose
|
||||
|
||||
This file mirrors the repository-specific agent rules from `AGENTS.md` in the configured Truthmark authority tree so structure and sync workflows can find them through the documented authority roots.
|
||||
|
||||
## Rules
|
||||
|
||||
- Use `npm run validate` before any parity claim.
|
||||
- This project uses `"type": "module"`, `module: "NodeNext"`, and `moduleResolution: "NodeNext"`; relative TypeScript imports must use emitted `.js` specifiers.
|
||||
- For local development before install/link, use npm scripts that build first and exercise `node dist/cli.js`.
|
||||
- Keep generated game projects under `projects/<slug>/`.
|
||||
- Do not load all agents or all templates for a single role task.
|
||||
- `src/agents.ts` is the single owner for generated project `AGENTS.md`.
|
||||
- Direct Codex execution is the default path via `open-gamestudio run <role>`.
|
||||
- `--dry-run` and `--print-prompt` are inspection-only paths.
|
||||
- Telemetry, planner/next, ownership enforcement, and parallel orchestration are future-only.
|
||||
|
||||
## Truthmark Notes
|
||||
|
||||
Keep the Truthmark-managed block in `AGENTS.md` intact. If these rules change in `AGENTS.md`, update this file in the same pass.
|
||||
@@ -0,0 +1,52 @@
|
||||
---
|
||||
status: active
|
||||
doc_type: architecture
|
||||
truth_kind: architecture
|
||||
last_reviewed: 2026-05-28
|
||||
source_of_truth:
|
||||
- ../truthmark/areas/repository.md
|
||||
---
|
||||
|
||||
# Repository Structure
|
||||
|
||||
## Purpose
|
||||
|
||||
Open GameStudio is a Node/TypeScript CLI package that installs and operates Codex-native game studio project workflows.
|
||||
|
||||
## Scope
|
||||
|
||||
This architecture note records the top-level repository boundaries needed by Truthmark routing. Bounded behavior details live in leaf docs under `docs/truth/**`.
|
||||
|
||||
## Components
|
||||
|
||||
- CLI command surface: `src/cli.ts`.
|
||||
- Project scaffolding: `src/projects.ts`, `src/config.ts`, `src/engines.ts`, `src/agents.ts`, `src/paths.ts`, and `engine_configs/**`.
|
||||
- Codex prompt and workflow surfaces: `src/roles.ts`, `src/codex-session.ts`, `src/codex-prompts.ts`, `src/workflows.ts`, `src/templates.ts`, and `templates/**`.
|
||||
- Runtime/task execution: `src/runner.ts`, `src/tasks.ts`, `src/codex-runtime.ts`, and `src/verification.ts`.
|
||||
- Validation: `src/validation.ts` plus the package metadata and smoke checks it verifies.
|
||||
|
||||
## Boundaries
|
||||
|
||||
Project scaffolding writes generated project files but does not execute Codex. Codex prompt/workflow modules render instructions but do not persist run state. Runtime/task modules execute or persist Codex runs but consume the prompt surfaces instead of defining role contracts. CLI/validation modules expose and verify the public package contract.
|
||||
|
||||
## Current Structure
|
||||
|
||||
- `src/cli.ts` owns the public CLI command wiring.
|
||||
- `src/projects.ts`, `src/config.ts`, `src/engines.ts`, `src/agents.ts`, and `src/paths.ts` own project scaffolding and generated project surfaces.
|
||||
- `src/roles.ts`, `src/codex-session.ts`, `src/codex-prompts.ts`, `src/workflows.ts`, and `src/templates.ts` own Codex role, prompt, workflow, and template surfaces.
|
||||
- `src/runner.ts`, `src/tasks.ts`, `src/codex-runtime.ts`, and `src/verification.ts` own Codex execution, task persistence, runtime checks, and verification processes.
|
||||
- `src/validation.ts` owns repository and generated-project validation checks.
|
||||
- `engine_configs/**` and `templates/**` are package runtime assets.
|
||||
- `tests/**` mirrors those behavior boundaries with Vitest coverage.
|
||||
|
||||
## Product Decisions
|
||||
|
||||
- Decision (2026-05-28): Route truth by behavior ownership rather than by mechanically mirroring every source file.
|
||||
|
||||
## Rationale
|
||||
|
||||
The package has a small source tree but multiple independent behavioral contracts. Truthmark routing keeps project scaffolding, prompt surfaces, runtime/task execution, and CLI/validation contracts separate so future syncs can update bounded docs instead of a catch-all repository overview.
|
||||
|
||||
## Maintenance Notes
|
||||
|
||||
Update this architecture note when source modules move across the behavior boundaries in `docs/truthmark/areas/repository.md`.
|
||||
@@ -0,0 +1,25 @@
|
||||
---
|
||||
status: active
|
||||
doc_type: standard
|
||||
last_reviewed: 2026-05-03
|
||||
source_of_truth:
|
||||
- README.md
|
||||
---
|
||||
|
||||
# Default Principles
|
||||
|
||||
## Scope
|
||||
|
||||
This is a bootstrap standards baseline for repositories that adopt Truthmark.
|
||||
|
||||
## Reusable Defaults
|
||||
|
||||
- Authority order should be explicit.
|
||||
- Committed repository artifacts are the durable source of truth.
|
||||
- Each document should have one primary responsibility.
|
||||
- Each class of fact should have one canonical source.
|
||||
- Architecture docs describe system structure, module boundaries, runtime topology, persistence boundaries, cross-cutting contracts, and generated-surface ownership.
|
||||
- Do not put ordinary feature behavior in architecture docs.
|
||||
- Verification should be explicit, and skipped checks should state why.
|
||||
- Missing, stale, broad, overloaded, or unrouteable documentation topology should be repaired through AI-native structure workflow before agents create more generic truth docs.
|
||||
- Installed repository workflows should remain usable from committed files even when the Truthmark CLI is unavailable.
|
||||
@@ -0,0 +1,23 @@
|
||||
---
|
||||
status: active
|
||||
doc_type: standard
|
||||
last_reviewed: 2026-05-03
|
||||
source_of_truth:
|
||||
- README.md
|
||||
---
|
||||
|
||||
# Documentation Governance
|
||||
|
||||
## Core Rules
|
||||
|
||||
- Each document should have one primary responsibility.
|
||||
- Each class of fact should have one canonical source.
|
||||
- Current implementation, reusable standards, and future proposals should be stored separately.
|
||||
- Generated helper output is never canonical truth.
|
||||
- Architecture docs describe structure and ownership; truth docs describe current product behavior.
|
||||
|
||||
## Truthmark Implications
|
||||
|
||||
- Truth Sync should extend mapped docs first, create an area-local doc second, and create a new area only as a last resort.
|
||||
- Weak routing produces weak truth maintenance.
|
||||
- Missing, stale, broad, overloaded, or unrouteable routing should trigger Truth Structure before more generic truth docs are created.
|
||||
Vendored
+58
@@ -0,0 +1,58 @@
|
||||
---
|
||||
status: active
|
||||
doc_type: architecture
|
||||
truth_kind: architecture
|
||||
last_reviewed: 2026-05-28
|
||||
source_of_truth:
|
||||
- {{source_of_truth}}
|
||||
---
|
||||
|
||||
# {{title}}
|
||||
|
||||
## Purpose
|
||||
|
||||
{{purpose}}
|
||||
|
||||
## Scope
|
||||
|
||||
{{scope}}
|
||||
|
||||
## System Role
|
||||
|
||||
{{system_role}}
|
||||
|
||||
## Boundaries
|
||||
|
||||
{{boundaries}}
|
||||
|
||||
## Components
|
||||
|
||||
{{components}}
|
||||
|
||||
## Data And Control Flow
|
||||
|
||||
{{data_and_control_flow}}
|
||||
|
||||
## Ownership
|
||||
|
||||
{{ownership}}
|
||||
|
||||
## Cross-Cutting Constraints
|
||||
|
||||
{{cross_cutting_constraints}}
|
||||
|
||||
## Product Decisions
|
||||
|
||||
{{decision}}
|
||||
|
||||
## Rationale
|
||||
|
||||
{{rationale}}
|
||||
|
||||
## Non-Goals
|
||||
|
||||
{{non_goals}}
|
||||
|
||||
## Maintenance Notes
|
||||
|
||||
{{maintenance_notes}}
|
||||
Vendored
+81
@@ -0,0 +1,81 @@
|
||||
---
|
||||
status: active
|
||||
doc_type: behavior
|
||||
truth_kind: behavior
|
||||
last_reviewed: 2026-05-28
|
||||
source_of_truth:
|
||||
- {{source_of_truth}}
|
||||
---
|
||||
|
||||
# {{title}}
|
||||
|
||||
## Purpose
|
||||
|
||||
<!-- State why this feature exists, the user or system outcome it protects, and the problem it solves. Keep roadmap or implementation plans out of this section. -->
|
||||
|
||||
{{purpose}}
|
||||
|
||||
## Scope
|
||||
|
||||
{{scope}}
|
||||
|
||||
<!--
|
||||
This doc must own one coherent behavior surface.
|
||||
Split into another leaf doc when content introduces:
|
||||
- a distinct user or system outcome
|
||||
- a separate lifecycle or state machine
|
||||
- an unrelated rule family
|
||||
- a different external contract
|
||||
- code that should route through a different owner
|
||||
Keep README.md files as indexes only.
|
||||
-->
|
||||
|
||||
This doc was created from the editable behavior-doc template at {{template_path}}.
|
||||
|
||||
## Current Behavior
|
||||
|
||||
<!-- Describe implemented behavior in present tense. Do not include desired future behavior. -->
|
||||
|
||||
{{current_behavior}}
|
||||
|
||||
## Core Rules
|
||||
|
||||
<!-- Capture stable business rules, invariants, precedence rules, validation rules, and must-never constraints. Omit incidental implementation details. -->
|
||||
|
||||
{{core_rules}}
|
||||
|
||||
## Flows And States
|
||||
|
||||
<!-- Use for route switches, state transitions, lifecycle stages, retries, fallbacks, and important error paths. Write 'None beyond current behavior.' when no distinct flow or state model exists. -->
|
||||
|
||||
{{flows_and_states}}
|
||||
|
||||
## Contracts
|
||||
|
||||
<!-- Capture user-visible or integration contracts: CLI/API shape, inputs, outputs, diagnostics, files, events, permissions, or links to canonical contract docs. Avoid duplicating a separate canonical contract doc. -->
|
||||
|
||||
{{contracts}}
|
||||
|
||||
## Product Decisions
|
||||
|
||||
<!-- Keep active decisions only. Replace stale decisions instead of appending historical logs. -->
|
||||
|
||||
{{decision}}
|
||||
|
||||
## Rationale
|
||||
|
||||
<!-- Explain why the current behavior and active decisions are this way, including tradeoffs. -->
|
||||
|
||||
{{rationale}}
|
||||
|
||||
## Non-Goals
|
||||
|
||||
<!-- Name adjacent behavior this doc intentionally does not own, especially tempting future expansions. -->
|
||||
|
||||
{{non_goals}}
|
||||
|
||||
## Maintenance Notes
|
||||
|
||||
<!-- List related tests, routing cautions, migration notes, and common drift risks for future agents. Keep this operational, not historical. -->
|
||||
|
||||
{{maintenance_notes}}
|
||||
Vendored
+58
@@ -0,0 +1,58 @@
|
||||
---
|
||||
status: active
|
||||
doc_type: contract
|
||||
truth_kind: contract
|
||||
last_reviewed: 2026-05-28
|
||||
source_of_truth:
|
||||
- {{source_of_truth}}
|
||||
---
|
||||
|
||||
# {{title}}
|
||||
|
||||
## Purpose
|
||||
|
||||
{{purpose}}
|
||||
|
||||
## Scope
|
||||
|
||||
{{scope}}
|
||||
|
||||
## Contract Surface
|
||||
|
||||
{{contract_surface}}
|
||||
|
||||
## Inputs
|
||||
|
||||
{{inputs}}
|
||||
|
||||
## Outputs
|
||||
|
||||
{{outputs}}
|
||||
|
||||
## Errors And Diagnostics
|
||||
|
||||
{{errors_and_diagnostics}}
|
||||
|
||||
## Compatibility Rules
|
||||
|
||||
{{compatibility_rules}}
|
||||
|
||||
## Versioning And Migration
|
||||
|
||||
{{versioning_and_migration}}
|
||||
|
||||
## Product Decisions
|
||||
|
||||
{{decision}}
|
||||
|
||||
## Rationale
|
||||
|
||||
{{rationale}}
|
||||
|
||||
## Non-Goals
|
||||
|
||||
{{non_goals}}
|
||||
|
||||
## Maintenance Notes
|
||||
|
||||
{{maintenance_notes}}
|
||||
Vendored
+58
@@ -0,0 +1,58 @@
|
||||
---
|
||||
status: active
|
||||
doc_type: behavior
|
||||
truth_kind: operations
|
||||
last_reviewed: 2026-05-28
|
||||
source_of_truth:
|
||||
- {{source_of_truth}}
|
||||
---
|
||||
|
||||
# {{title}}
|
||||
|
||||
## Purpose
|
||||
|
||||
{{purpose}}
|
||||
|
||||
## Scope
|
||||
|
||||
{{scope}}
|
||||
|
||||
## Operational Surface
|
||||
|
||||
{{operational_surface}}
|
||||
|
||||
## Runtime Topology
|
||||
|
||||
{{runtime_topology}}
|
||||
|
||||
## Configuration
|
||||
|
||||
{{configuration}}
|
||||
|
||||
## Permissions
|
||||
|
||||
{{permissions}}
|
||||
|
||||
## Deployment And Rollback
|
||||
|
||||
{{deployment_and_rollback}}
|
||||
|
||||
## Availability And Observability
|
||||
|
||||
{{availability_and_observability}}
|
||||
|
||||
## Product Decisions
|
||||
|
||||
{{decision}}
|
||||
|
||||
## Rationale
|
||||
|
||||
{{rationale}}
|
||||
|
||||
## Non-Goals
|
||||
|
||||
{{non_goals}}
|
||||
|
||||
## Maintenance Notes
|
||||
|
||||
{{maintenance_notes}}
|
||||
Vendored
+58
@@ -0,0 +1,58 @@
|
||||
---
|
||||
status: active
|
||||
doc_type: behavior
|
||||
truth_kind: test-behavior
|
||||
last_reviewed: 2026-05-28
|
||||
source_of_truth:
|
||||
- {{source_of_truth}}
|
||||
---
|
||||
|
||||
# {{title}}
|
||||
|
||||
## Purpose
|
||||
|
||||
{{purpose}}
|
||||
|
||||
## Scope
|
||||
|
||||
{{scope}}
|
||||
|
||||
## Test Surface
|
||||
|
||||
{{test_surface}}
|
||||
|
||||
## Fixtures And Data Model
|
||||
|
||||
{{fixtures_and_data_model}}
|
||||
|
||||
## Execution Model
|
||||
|
||||
{{execution_model}}
|
||||
|
||||
## Assertions And Invariants
|
||||
|
||||
{{assertions_and_invariants}}
|
||||
|
||||
## Isolation Rules
|
||||
|
||||
{{isolation_rules}}
|
||||
|
||||
## Reporting And Failure Semantics
|
||||
|
||||
{{reporting_and_failure_semantics}}
|
||||
|
||||
## Product Decisions
|
||||
|
||||
{{decision}}
|
||||
|
||||
## Rationale
|
||||
|
||||
{{rationale}}
|
||||
|
||||
## Non-Goals
|
||||
|
||||
{{non_goals}}
|
||||
|
||||
## Maintenance Notes
|
||||
|
||||
{{maintenance_notes}}
|
||||
Vendored
+58
@@ -0,0 +1,58 @@
|
||||
---
|
||||
status: active
|
||||
doc_type: behavior
|
||||
truth_kind: workflow
|
||||
last_reviewed: 2026-05-28
|
||||
source_of_truth:
|
||||
- {{source_of_truth}}
|
||||
---
|
||||
|
||||
# {{title}}
|
||||
|
||||
## Purpose
|
||||
|
||||
{{purpose}}
|
||||
|
||||
## Scope
|
||||
|
||||
{{scope}}
|
||||
|
||||
## Triggers
|
||||
|
||||
{{triggers}}
|
||||
|
||||
## Inputs
|
||||
|
||||
{{inputs}}
|
||||
|
||||
## Execution Model
|
||||
|
||||
{{execution_model}}
|
||||
|
||||
## Steps
|
||||
|
||||
{{steps}}
|
||||
|
||||
## State, Retry, And Failure Behavior
|
||||
|
||||
{{state_retry_and_failure_behavior}}
|
||||
|
||||
## Outputs
|
||||
|
||||
{{outputs}}
|
||||
|
||||
## Product Decisions
|
||||
|
||||
{{decision}}
|
||||
|
||||
## Rationale
|
||||
|
||||
{{rationale}}
|
||||
|
||||
## Non-Goals
|
||||
|
||||
{{non_goals}}
|
||||
|
||||
## Maintenance Notes
|
||||
|
||||
{{maintenance_notes}}
|
||||
@@ -0,0 +1,13 @@
|
||||
---
|
||||
status: active
|
||||
doc_type: index
|
||||
last_reviewed: 2026-05-28
|
||||
source_of_truth:
|
||||
- ../truthmark/areas.md
|
||||
---
|
||||
|
||||
# Truth Docs
|
||||
|
||||
This directory is an index for current truth docs organized by the configured Truthmark hierarchy.
|
||||
|
||||
README.md files are indexes, not Truth Sync targets. Keep bounded truth in leaf docs under `<domain>/<behavior>.md`.
|
||||
@@ -0,0 +1,66 @@
|
||||
---
|
||||
status: active
|
||||
doc_type: behavior
|
||||
truth_kind: behavior
|
||||
last_reviewed: 2026-05-28
|
||||
source_of_truth:
|
||||
- ../../truthmark/areas/repository.md
|
||||
---
|
||||
|
||||
# Codex Roles And Workflows
|
||||
|
||||
## Purpose
|
||||
|
||||
Codex roles and workflows provide the role-specific prompt contracts, context boundaries, templates, and render-only workflow shortcuts that make Open GameStudio a Codex-native game-development layer.
|
||||
|
||||
## Scope
|
||||
|
||||
This bounded leaf truth doc owns studio role IDs, role package metadata, Codex session prompt rendering, workflow registry entries, template registry behavior, and generated workflow prompt content. It does not own process execution, task persistence, package installation, or generated project initialization side effects.
|
||||
|
||||
This doc was created from the editable behavior-doc template at docs/templates/behavior-doc.md.
|
||||
|
||||
## Current Behavior
|
||||
|
||||
- The canonical studio role roster is defined by hyphenated Codex-native role IDs such as `producer`, `gameplay-programmer`, `qa-playtester`, and `studio-orchestrator`.
|
||||
- Each role package contains a display name, system prompt, context strategy, expected outputs, handoff wording, and a review checklist.
|
||||
- Codex session prompts render the role display name, role ID, phase, project root, objective, engine context, context files, expected outputs, verification command, review checklist, and completion-report instructions.
|
||||
- The workflow registry defines vertical-slice, bugfix, playtest, market-analysis, analytics-setup, design-spec, game-feel-tuning, art-direction, ui-ux-review, production-milestone, handoff, review, and ship-check workflow prompts.
|
||||
- Selected workflows include CLI aliases for render-only shortcuts, including market, analytics, design-spec, feel-review, art-direction, ui-review, milestone, and handoff.
|
||||
- Template selection is task- and role-sensitive; template files are read from package assets and embedded into applicable workflow prompts.
|
||||
|
||||
## Core Rules
|
||||
|
||||
- Unknown role errors must point users toward Codex-native hyphenated role IDs rather than legacy agent names.
|
||||
- Prompt rendering must include the role display name and project/session metadata needed by Codex to operate without hidden state.
|
||||
- Templates that require Markdown sections must have non-empty required sections; the project config template must parse as JSON.
|
||||
- Workflow shortcuts render prompts; they do not imply hidden parallel orchestration or future planner behavior.
|
||||
|
||||
## Flows And States
|
||||
|
||||
- Workflow prompt flow: read project engine from `.codex/studio.json`, look up the workflow registry entry, create a Codex studio session for the owning role and phase, render the standard prompt, then append any workflow template bodies.
|
||||
- Template selection flow: match role and task text against bounded keyword rules and return only matching template IDs.
|
||||
|
||||
## Contracts
|
||||
|
||||
- Role IDs are stable strings exported from `src/roles.ts` and reused by config validation, project state, prompt generation, workflow routing, and task creation.
|
||||
- Workflow IDs map to `.codex/workflows/<workflow>.md` files and expected context-file lists.
|
||||
- Template IDs map to package template paths, role applicability, tags, and required-section validation.
|
||||
|
||||
## Product Decisions
|
||||
|
||||
- Decision (2026-05-28): Use Codex-native hyphenated role IDs as the canonical user- and project-facing role contract.
|
||||
- Decision (2026-05-28): Keep workflow shortcuts render-only for this pass; future planner, next, telemetry, ownership enforcement, and parallel orchestration surfaces remain hidden.
|
||||
|
||||
## Rationale
|
||||
|
||||
Role and workflow prompt generation is the user-facing contract that turns a generic Codex CLI into a specialized game-studio workflow. Keeping it render-only and declarative avoids overclaiming automation that is not implemented while still making the workflow packages inspectable and testable.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- This doc does not own whether Codex is installed or authenticated.
|
||||
- This doc does not own task lifecycle mutations or verification command execution.
|
||||
|
||||
## Maintenance Notes
|
||||
|
||||
- Update this doc with changes to `src/roles.ts`, `src/codex-session.ts`, `src/codex-prompts.ts`, `src/workflows.ts`, `src/templates.ts`, or `templates/**`.
|
||||
- Relevant verification includes role, Codex prompt/session, workflow, template, and functionality-gap tests.
|
||||
@@ -0,0 +1,86 @@
|
||||
---
|
||||
status: active
|
||||
doc_type: behavior
|
||||
truth_kind: workflow
|
||||
last_reviewed: 2026-05-28
|
||||
source_of_truth:
|
||||
- ../../truthmark/areas/repository.md
|
||||
---
|
||||
|
||||
# Runtime And Task Execution
|
||||
|
||||
## Purpose
|
||||
|
||||
Runtime and task execution connect prepared Codex Game Studio prompts to the Codex CLI, preserve explicit task state, and run bounded verification/review/fix loops without hidden orchestration.
|
||||
|
||||
## Scope
|
||||
|
||||
This bounded leaf truth doc owns `run` preparation and execution, Codex command construction and availability checks, task-store persistence, review/fix lifecycle behavior, sandbox policy, and structured verification command execution. It does not own role prompt content, project scaffolding, or public CLI help wording except where runtime behavior depends on those options.
|
||||
|
||||
## Triggers
|
||||
|
||||
- A user invokes `run <role> ... --project <path>` to render or execute a role prompt.
|
||||
- A user creates or runs a file-backed task through `task create` or `task run`.
|
||||
- A run includes structured verification, review, or bounded fix-pass options.
|
||||
|
||||
## Inputs
|
||||
|
||||
- A valid project root with `.codex/studio.json`.
|
||||
- A studio role ID or task ID.
|
||||
- A non-empty task/objective.
|
||||
- Optional included artifacts, verification command/args, review flag, fix flag, and max fix-pass count.
|
||||
|
||||
## Execution Model
|
||||
|
||||
- `prepareRun` resolves the project, reads studio state, renders a Codex prompt, computes prompt and metadata cache paths, and builds Codex execution commands.
|
||||
- `--print-prompt` and `--dry-run` are inspection-only paths and do not write prompt cache, metadata, task state, or run directories.
|
||||
- Non-dry runs write prompt and metadata before executing Codex.
|
||||
- Implementation and fix passes use a workspace-write Codex sandbox; review passes use a read-only Codex sandbox.
|
||||
- Task runs mutate task status only for non-dry execution.
|
||||
|
||||
## Steps
|
||||
|
||||
1. Validate the requested role/task and project state.
|
||||
2. Build context-file lists and render the Codex prompt.
|
||||
3. For non-dry runs, write the prompt and metadata cache under `.codex/runs/`.
|
||||
4. Check Codex availability before execution through the CLI path.
|
||||
5. Execute the implementation prompt.
|
||||
6. Run verification when configured.
|
||||
7. Run review when requested and verification passes or is absent.
|
||||
8. Run bounded fix passes when requested and blockers remain.
|
||||
9. Report final status as `done` or `blocked`; task runs also persist final task status.
|
||||
|
||||
## State, Retry, And Failure Behavior
|
||||
|
||||
- Task stores live at `.codex/tasks.json` with schema version 1 and unique `task-###` IDs.
|
||||
- `task create` requires a valid studio project before writing task state.
|
||||
- Task statuses are `ready`, `running`, `blocked`, and `done`.
|
||||
- Verification commands are spawned with bounded stdout/stderr capture, a default timeout, SIGTERM on timeout, and SIGKILL after the configured grace period.
|
||||
- Malformed review JSON, non-zero Codex execution, failed verification, or review blockers leave the lifecycle blocked unless a later bounded fix pass clears the blocker.
|
||||
|
||||
## Outputs
|
||||
|
||||
- Dry-run output lists context files and the Codex command without writing cache files.
|
||||
- Print-prompt output is the deterministic prompt body.
|
||||
- Non-dry run output reports implementation, verification, review, fix-pass, and final-status summaries.
|
||||
- Task creation prints the new task ID.
|
||||
|
||||
## Product Decisions
|
||||
|
||||
- Decision (2026-05-28): Make dry-run and print-prompt non-mutating inspection paths.
|
||||
- Decision (2026-05-28): Force review prompts through a read-only sandbox while implementation/fix prompts retain workspace-write behavior.
|
||||
- Decision (2026-05-28): Require a valid project before task-store writes.
|
||||
|
||||
## Rationale
|
||||
|
||||
Codex execution is intentionally explicit: users can inspect prompts without side effects, then run bounded implementation/review/fix loops with visible cache paths and verification output. Read-only review protects the review contract from accidentally becoming a second implementation pass.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- This workflow does not implement hidden parallel execution, telemetry, ownership enforcement, or a planner/next queue.
|
||||
- This workflow does not choose role prompt content; it consumes the role and workflow surfaces owned by the Codex roles truth doc.
|
||||
|
||||
## Maintenance Notes
|
||||
|
||||
- Update this doc with changes to `src/runner.ts`, `src/tasks.ts`, `src/codex-runtime.ts`, or `src/verification.ts`.
|
||||
- Relevant verification includes runner, task, verification, Codex runtime, and lifecycle-focused tests.
|
||||
@@ -0,0 +1,75 @@
|
||||
---
|
||||
status: active
|
||||
doc_type: contract
|
||||
truth_kind: contract
|
||||
last_reviewed: 2026-05-28
|
||||
source_of_truth:
|
||||
- ../../truthmark/areas/repository.md
|
||||
---
|
||||
|
||||
# CLI And Validation Contracts
|
||||
|
||||
## Purpose
|
||||
|
||||
The CLI and validation contracts define the public `open-gamestudio` command surface, package entrypoints, hard-failing validation checks, and future-surface guardrails for this repository.
|
||||
|
||||
## Scope
|
||||
|
||||
This bounded leaf truth doc owns the repository CLI command contract, package scripts/bin/files expectations, validation check behavior, and documented public-surface claims. It does not own the internal details of project scaffolding, role prompt content, or Codex runtime lifecycle beyond the options exposed through the CLI.
|
||||
|
||||
## Contract Surface
|
||||
|
||||
- Package name: `open-gamestudio`.
|
||||
- Package bin: `open-gamestudio` points to `./dist/cli.js`.
|
||||
- Primary scripts include `build`, `typecheck`, `test`, `validate`, `init`, `manage`, and `templates`.
|
||||
- Public CLI command groups include initialization/status commands, template discovery, role run execution, file-backed tasks, and render-only workflow shortcuts.
|
||||
- Repository validation is exposed through `open-gamestudio validate` and the `npm run validate` script.
|
||||
|
||||
## Inputs
|
||||
|
||||
- CLI options and arguments parsed by Commander in `src/cli.ts`.
|
||||
- Repository files checked by validation, including package metadata, source files, templates, generated build output, engine configs, and optional project paths.
|
||||
- Project validation input when `--project <path>` is supplied.
|
||||
|
||||
## Outputs
|
||||
|
||||
- CLI commands print human-readable status, prompt, task, validation, or workflow output.
|
||||
- Validation emits one line per check in `STATUS id: message (path)` shape and exits non-zero when any check fails.
|
||||
- Package smoke validation builds and exercises the packed package bin and template loading behavior.
|
||||
|
||||
## Errors And Diagnostics
|
||||
|
||||
- Unknown roles fail with a message naming Codex-native hyphenated role IDs.
|
||||
- Missing package scripts, missing package bin/files, missing source files, unavailable Codex CLI, invalid templates, exposed future surfaces, missing build output, and package smoke failures are validation failures.
|
||||
- Project validation fails for invalid `.codex/studio.json`, missing generated project files, missing workflow/prompt sections, forbidden generated surfaces, or read-only command mutations.
|
||||
|
||||
## Compatibility Rules
|
||||
|
||||
- The TypeScript project uses NodeNext ESM semantics; relative TypeScript imports must use emitted `.js` specifiers.
|
||||
- Node support requires a package engine floor that includes Node >=20.
|
||||
- Packaged files must include `dist/`, `engine_configs/`, and `templates/` so the installed bin can load runtime assets.
|
||||
- Future-only command surfaces such as `next`, `telemetry`, `parallel`, and ownership enforcement must stay hidden until implemented intentionally.
|
||||
|
||||
## Versioning And Migration
|
||||
|
||||
- Current package version is managed in `package.json` and rendered by Commander.
|
||||
- CLI contract changes should update README claims, validation expectations, and tests in the same change.
|
||||
|
||||
## Product Decisions
|
||||
|
||||
- Decision (2026-05-28): Keep `validate` as the hard-failing parity gate before claiming repository or project readiness.
|
||||
- Decision (2026-05-28): Document and test that future planner/telemetry/parallel/ownership surfaces are not exposed by the CLI.
|
||||
|
||||
## Rationale
|
||||
|
||||
The CLI is the stable integration boundary for humans, package installs, and generated project smoke checks. Validation makes those claims executable so prompt-surface and packaging drift fail before release or parity claims.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- This contract does not document every generated prompt body; those belong to the Codex role/workflow truth doc.
|
||||
- This contract does not define npm audit remediation policy.
|
||||
|
||||
## Maintenance Notes
|
||||
|
||||
- Update this doc with changes to `src/cli.ts`, `src/validation.ts`, package metadata, README public command claims, or validation check IDs.
|
||||
- Relevant verification includes `npm run validate`, CLI help smoke checks, validation tests, package dry-run/smoke checks, and future-surface guard tests.
|
||||
@@ -0,0 +1,18 @@
|
||||
---
|
||||
status: active
|
||||
doc_type: index
|
||||
last_reviewed: 2026-05-28
|
||||
source_of_truth:
|
||||
- ../../truthmark/areas/repository.md
|
||||
---
|
||||
|
||||
# Repository Truth Docs
|
||||
|
||||
This directory is reserved for repository-level truth indexes.
|
||||
|
||||
README.md files are indexes, not Truth Sync targets. Current bounded truth lives in:
|
||||
|
||||
- [Project Scaffolding](../projects/project-scaffolding.md)
|
||||
- [Codex Roles And Workflows](../codex/roles-and-workflows.md)
|
||||
- [Runtime And Task Execution](../codex/runtime-and-tasks.md)
|
||||
- [CLI And Validation Contracts](../contracts/cli-and-validation.md)
|
||||
@@ -0,0 +1,28 @@
|
||||
---
|
||||
status: active
|
||||
doc_type: route-index
|
||||
last_reviewed: 2026-05-28
|
||||
source_of_truth:
|
||||
- ../../.truthmark/config.yml
|
||||
---
|
||||
|
||||
# Truthmark Areas
|
||||
|
||||
## Repository
|
||||
|
||||
Area files:
|
||||
- docs/truthmark/areas/repository.md
|
||||
|
||||
Code surface:
|
||||
- src/**
|
||||
- tests/**
|
||||
- engine_configs/**
|
||||
- templates/**
|
||||
- package.json
|
||||
- package-lock.json
|
||||
- README.md
|
||||
- AGENTS.md
|
||||
|
||||
Update truth when:
|
||||
- repository CLI behavior, Codex prompt/workflow behavior, generated project layout, validation, packaging, or task execution changes
|
||||
- code or tests move between bounded behavior owners
|
||||
@@ -0,0 +1,101 @@
|
||||
---
|
||||
status: active
|
||||
doc_type: area-route
|
||||
last_reviewed: 2026-05-28
|
||||
source_of_truth:
|
||||
- ../../../.truthmark/config.yml
|
||||
---
|
||||
|
||||
# Repository Areas
|
||||
|
||||
## Project Scaffolding
|
||||
|
||||
Truth documents:
|
||||
```yaml
|
||||
truth_documents:
|
||||
- path: docs/truth/projects/project-scaffolding.md
|
||||
kind: behavior
|
||||
```
|
||||
|
||||
Code surface:
|
||||
- src/projects.ts
|
||||
- src/config.ts
|
||||
- src/engines.ts
|
||||
- src/agents.ts
|
||||
- src/paths.ts
|
||||
- engine_configs/**
|
||||
- tests/project-workflow.test.ts
|
||||
- tests/agents-templates.test.ts
|
||||
- tests/engine-system.test.ts
|
||||
- tests/codex-context-files.test.ts
|
||||
|
||||
Update truth when:
|
||||
- project initialization, generated project state, engine folder creation, role prompt materialization, or status/resume/freeze behavior changes
|
||||
- generated project AGENTS.md or base prompt package ownership changes
|
||||
|
||||
## Codex Role And Workflow Surfaces
|
||||
|
||||
Truth documents:
|
||||
```yaml
|
||||
truth_documents:
|
||||
- path: docs/truth/codex/roles-and-workflows.md
|
||||
kind: behavior
|
||||
```
|
||||
|
||||
Code surface:
|
||||
- src/roles.ts
|
||||
- src/codex-session.ts
|
||||
- src/codex-prompts.ts
|
||||
- src/workflows.ts
|
||||
- src/templates.ts
|
||||
- templates/**
|
||||
- tests/roles.test.ts
|
||||
- tests/codex-session.test.ts
|
||||
- tests/codex-prompts.test.ts
|
||||
- tests/functionality-gap-pass.test.ts
|
||||
|
||||
Update truth when:
|
||||
- studio role IDs, role contracts, workflow registry entries, prompt rendering, context strategies, or template selection rules change
|
||||
- Codex-native workflow shortcuts or generated workflow prompt contents change
|
||||
|
||||
## Runtime And Task Execution
|
||||
|
||||
Truth documents:
|
||||
```yaml
|
||||
truth_documents:
|
||||
- path: docs/truth/codex/runtime-and-tasks.md
|
||||
kind: workflow
|
||||
```
|
||||
|
||||
Code surface:
|
||||
- src/runner.ts
|
||||
- src/tasks.ts
|
||||
- src/codex-runtime.ts
|
||||
- src/verification.ts
|
||||
- tests/runner.test.ts
|
||||
- tests/tasks.test.ts
|
||||
- tests/verification.test.ts
|
||||
- tests/codex-runtime.test.ts
|
||||
|
||||
Update truth when:
|
||||
- Codex execution, dry-run or print-prompt mutation rules, review/fix lifecycle behavior, task-store persistence, or verification timeout behavior changes
|
||||
- task status transitions or Codex sandbox policies change
|
||||
|
||||
## CLI And Validation Contracts
|
||||
|
||||
Truth documents:
|
||||
```yaml
|
||||
truth_documents:
|
||||
- path: docs/truth/contracts/cli-and-validation.md
|
||||
kind: contract
|
||||
```
|
||||
|
||||
Code surface:
|
||||
- src/cli.ts
|
||||
- src/validation.ts
|
||||
- tests/validation.test.ts
|
||||
- tests/functionality-gap-pass.test.ts
|
||||
|
||||
Update truth when:
|
||||
- public CLI commands, package scripts/bin/files, validation check IDs, documentation claims, or package dependency contracts change
|
||||
- future-only surfaces become exposed or are intentionally kept hidden
|
||||
Reference in New Issue
Block a user