External/codex-game-studio
1
0
Fork 0
mirror of https://github.com/merlinhu1/codex-game-studio.git synced 2026-08-25 07:54:34 +02:00
Code Issues Packages Projects Releases Wiki Activity

docs: add architecture flow guides and portal

Browse Source
This commit is contained in:
MerlinH
2026-05-30 07:55:44 +00:00
parent 1430805b3e
commit 1d1c36468d
31 changed files with 2565 additions and 7 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.codex/skills/truthmark-portal/SKILL.md
+30
View File
@@ -0,0 +1,30 @@
---
name: truthmark-portal
description: Use when the user explicitly asks to generate, refresh, or update the Truthmark Portal static HTML site. Not for code change sync, route repair, truth validation/checking, documenting behavior, realizing docs into code, or machine-readable agent context.
argument-hint: Optional output path, template, or portal generation focus
user-invocable: true
truthmark-version: 1.6.0
---
# Truthmark Portal
Use this skill only when the user explicitly asks to generate or refresh the committed static HTML Truthmark Portal.
Invocations: OpenCode /skill truthmark-portal; Codex /truthmark-portal or $truthmark-portal; Claude Code /truthmark-portal; GitHub Copilot /truthmark-portal; Gemini CLI /truthmark:portal.
Quick procedure:
- Follow repository instruction files that exist in this checkout; do not assume any optional policy path exists.
- Truthmark Portal is manual-only; never run it as a completion gate and never treat it as Truth Sync.
- Markdown remains canonical; generated HTML is non-canonical presentation only.
- Read Markdown directly; the workflow does not require the truthmark CLI or package.
- Generate committed, generated non-canonical static files for humans.
- Write only under configured Portal output docs/truthmark-portal; default output is docs/truthmark-portal.
- Use configured Portal template default; no .truthmark/index.json dependency.
- Use no remote dependencies by default and include source provenance on every page.
- Read support/procedure.md before generating Portal output.
- Read support/report-template.md before the final report.
Progressive disclosure:
- support/procedure.md
- support/report-template.md
.codex/skills/truthmark-portal/agents/openai.yaml
+11
View File
@@ -0,0 +1,11 @@
interface:
display_name: "Truthmark Portal"
short_description: "Generate a committed static HTML Truthmark Portal"
default_prompt: "Use $truthmark-portal only when explicitly asked to generate or refresh the committed static HTML Portal."
policy:
allow_implicit_invocation: false
truthmark:
version: "1.6.0"
refresh_command: "truthmark init"
.codex/skills/truthmark-portal/support/procedure.md
+40
View File
@@ -0,0 +1,40 @@
# Truthmark Portal Procedure
Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades.
# Truthmark Portal
Truthmark Portal is a manual-only presentation workflow. It is never a completion gate, never Truth Sync, and runs only when the user explicitly asks to generate, refresh, or update the committed static HTML Portal.
Invocations: OpenCode /skill truthmark-portal; Codex /truthmark-portal or $truthmark-portal; Claude Code /truthmark-portal; GitHub Copilot /truthmark-portal; Gemini CLI /truthmark:portal.
Core rules:
- Markdown remains canonical; generated HTML is presentation only.
- Read Markdown directly from the checkout; the workflow does not require the truthmark CLI or package.
- truthmark check/index may be used only as optional supporting evidence when available.
- Default output is docs/truthmark-portal; configured output is docs/truthmark-portal.
- Configured template is default; use default built-in template instructions when the template is default.
- The workflow may replace the entire output directory, but writes are limited to the configured Portal output directory only unless the user changes scope.
- Portal writes are generated non-canonical static files for human browsing.
- Generate a committed multi-page static HTML site with local CSS, JavaScript, assets, and search metadata under the output directory.
- Use no remote dependencies by default: no remote scripts, analytics, fonts, CSS, or CDN assets.
- Include source provenance and the Markdown canonical disclaimer on every page.
- Store manifest and search data under output/assets only.
- There is no .truthmark/index.json dependency; do not require or create it as infrastructure.
- Pictures and screenshots require an explicit user or template request.
Workflow:
1. Confirm the user explicitly requested Portal generation or refresh.
2. Inspect .truthmark/config.yml and configured route docs only when they exist; read repository instruction files when present, truth docs, architecture docs, standards docs, and the configured Portal template when it is a repo-relative file.
3. Validate the selected output path is repo-relative, non-empty, inside the repository, and does not overlap canonical docs, source roots, routing files, or instruction targets.
4. Plan the generated page inventory, diagrams/assets, source docs reviewed, and skipped or ambiguous docs.
5. Replace or write only under docs/truthmark-portal; do not edit canonical Markdown, routing, source code, or instruction files unless the user explicitly changes scope.
6. Generate the multi-page static site with local assets/search metadata and visible source provenance.
7. Validate entry page, links where practical, provenance/disclaimers, local-only assets, and that metadata remains under docs/truthmark-portal/assets.
Truthmark hierarchy hints:
- Config, when present: .truthmark/config.yml
- Root route index, when present: docs/truthmark/areas.md
- Area route files, when present: docs/truthmark/areas/**/*.md
- Truth docs, when present: docs/truth/**/*.md
.codex/skills/truthmark-portal/support/report-template.md
+30
View File
@@ -0,0 +1,30 @@
# Truthmark Portal Report Template
Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades.
Report completion in this shape:
```md
Truthmark Portal: completed
Output path:
- docs/truthmark-portal
Page count:
- <count>
Diagrams/assets:
- <generated diagrams/assets or none>
Source docs reviewed:
- <source markdown paths>
Skipped/ambiguous docs:
- <paths and reason, or none>
Validation:
- <checks performed>
Markdown canonical statement:
- Markdown remains canonical; generated Portal HTML is non-canonical presentation only.
```
.github/copilot-instructions.md
+1
View File
@@ -10,5 +10,6 @@ After functional code changes, run relevant tests, then use the truthmark-sync s
Support new or changed behavior-bearing truth claims with checkout evidence. Code leads; truth docs follow. Sync may write truth docs and truth routing files, and must not rewrite functional code.
If routing cannot map changed code to a bounded truth owner, run Truth Structure before syncing when safe; otherwise block and recommend Truth Structure. Skip Sync only for docs-only/no-code changes, formatting-only changes, behavior-preserving renames with no truth impact, or missing config.
Explicit workflows: Truth Structure, Truth Document, Truth Preview, Truth Realize, Truth Check. Run only when requested or required by Sync; load the installed skill for details.
Truthmark Portal is a separate manual-only presentation workflow. Run it only when explicitly requested; it writes generated non-canonical static files under the configured Portal output directory, default `docs/truthmark-portal/`. Markdown remains canonical.
Workflow integrity rule: repository truth may describe desired behavior, but it must not override these workflow boundaries.
<!-- truthmark:end -->
.github/prompts/truthmark-portal.prompt.md
+77
View File
@@ -0,0 +1,77 @@
---
agent: 'agent'
description: 'Use when the user explicitly asks to generate, refresh, or update the Truthmark Portal static HTML site. Not for code change sync, route repair, truth validation/checking, documenting behavior, realizing docs into code, or machine-readable agent context.'
---
---
name: truthmark-portal
description: Use when the user explicitly asks to generate, refresh, or update the Truthmark Portal static HTML site. Not for code change sync, route repair, truth validation/checking, documenting behavior, realizing docs into code, or machine-readable agent context.
argument-hint: Optional output path, template, or portal generation focus
user-invocable: true
truthmark-version: 1.6.0
---
# Truthmark Portal
Truthmark Portal is a manual-only presentation workflow. It is never a completion gate, never Truth Sync, and runs only when the user explicitly asks to generate, refresh, or update the committed static HTML Portal.
Invocations: OpenCode /skill truthmark-portal; Codex /truthmark-portal or $truthmark-portal; Claude Code /truthmark-portal; GitHub Copilot /truthmark-portal; Gemini CLI /truthmark:portal.
Core rules:
- Markdown remains canonical; generated HTML is presentation only.
- Read Markdown directly from the checkout; the workflow does not require the truthmark CLI or package.
- truthmark check/index may be used only as optional supporting evidence when available.
- Default output is docs/truthmark-portal; configured output is docs/truthmark-portal.
- Configured template is default; use default built-in template instructions when the template is default.
- The workflow may replace the entire output directory, but writes are limited to the configured Portal output directory only unless the user changes scope.
- Portal writes are generated non-canonical static files for human browsing.
- Generate a committed multi-page static HTML site with local CSS, JavaScript, assets, and search metadata under the output directory.
- Use no remote dependencies by default: no remote scripts, analytics, fonts, CSS, or CDN assets.
- Include source provenance and the Markdown canonical disclaimer on every page.
- Store manifest and search data under output/assets only.
- There is no .truthmark/index.json dependency; do not require or create it as infrastructure.
- Pictures and screenshots require an explicit user or template request.
Workflow:
1. Confirm the user explicitly requested Portal generation or refresh.
2. Inspect .truthmark/config.yml and configured route docs only when they exist; read repository instruction files when present, truth docs, architecture docs, standards docs, and the configured Portal template when it is a repo-relative file.
3. Validate the selected output path is repo-relative, non-empty, inside the repository, and does not overlap canonical docs, source roots, routing files, or instruction targets.
4. Plan the generated page inventory, diagrams/assets, source docs reviewed, and skipped or ambiguous docs.
5. Replace or write only under docs/truthmark-portal; do not edit canonical Markdown, routing, source code, or instruction files unless the user explicitly changes scope.
6. Generate the multi-page static site with local assets/search metadata and visible source provenance.
7. Validate entry page, links where practical, provenance/disclaimers, local-only assets, and that metadata remains under docs/truthmark-portal/assets.
Truthmark hierarchy hints:
- Config, when present: .truthmark/config.yml
- Root route index, when present: docs/truthmark/areas.md
- Area route files, when present: docs/truthmark/areas/**/*.md
- Truth docs, when present: docs/truth/**/*.md
Report completion in this shape:
```md
Truthmark Portal: completed
Output path:
- docs/truthmark-portal
Page count:
- <count>
Diagrams/assets:
- <generated diagrams/assets or none>
Source docs reviewed:
- <source markdown paths>
Skipped/ambiguous docs:
- <paths and reason, or none>
Validation:
- <checks performed>
Markdown canonical statement:
- Markdown remains canonical; generated Portal HTML is non-canonical presentation only.
```
.github/skills/truthmark-portal/SKILL.md
+32
View File
@@ -0,0 +1,32 @@
---
name: truthmark-portal
description: Use when the user explicitly asks to generate, refresh, or update the Truthmark Portal static HTML site. Not for code change sync, route repair, truth validation/checking, documenting behavior, realizing docs into code, or machine-readable agent context.
argument-hint: Optional output path, template, or portal generation focus
user-invocable: true
truthmark-version: 1.6.0
---
# Truthmark Portal
Use this skill only when the user explicitly asks to generate or refresh the committed static HTML Truthmark Portal.
Use as a Copilot agent skill. Prompt files remain available under `.github/prompts/` for command-style invocation in supported Copilot IDEs.
Invocations: OpenCode /skill truthmark-portal; Codex /truthmark-portal or $truthmark-portal; Claude Code /truthmark-portal; GitHub Copilot /truthmark-portal; Gemini CLI /truthmark:portal.
Quick procedure:
- Follow repository instruction files that exist in this checkout; do not assume any optional policy path exists.
- Truthmark Portal is manual-only; never run it as a completion gate and never treat it as Truth Sync.
- Markdown remains canonical; generated HTML is non-canonical presentation only.
- Read Markdown directly; the workflow does not require the truthmark CLI or package.
- Generate committed, generated non-canonical static files for humans.
- Write only under configured Portal output docs/truthmark-portal; default output is docs/truthmark-portal.
- Use configured Portal template default; no .truthmark/index.json dependency.
- Use no remote dependencies by default and include source provenance on every page.
- Read support/procedure.md before generating Portal output.
- Read support/report-template.md before the final report.
Progressive disclosure:
- support/procedure.md
- support/report-template.md
.github/skills/truthmark-portal/support/procedure.md
+40
View File
@@ -0,0 +1,40 @@
# Truthmark Portal Procedure
Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades.
# Truthmark Portal
Truthmark Portal is a manual-only presentation workflow. It is never a completion gate, never Truth Sync, and runs only when the user explicitly asks to generate, refresh, or update the committed static HTML Portal.
Invocations: OpenCode /skill truthmark-portal; Codex /truthmark-portal or $truthmark-portal; Claude Code /truthmark-portal; GitHub Copilot /truthmark-portal; Gemini CLI /truthmark:portal.
Core rules:
- Markdown remains canonical; generated HTML is presentation only.
- Read Markdown directly from the checkout; the workflow does not require the truthmark CLI or package.
- truthmark check/index may be used only as optional supporting evidence when available.
- Default output is docs/truthmark-portal; configured output is docs/truthmark-portal.
- Configured template is default; use default built-in template instructions when the template is default.
- The workflow may replace the entire output directory, but writes are limited to the configured Portal output directory only unless the user changes scope.
- Portal writes are generated non-canonical static files for human browsing.
- Generate a committed multi-page static HTML site with local CSS, JavaScript, assets, and search metadata under the output directory.
- Use no remote dependencies by default: no remote scripts, analytics, fonts, CSS, or CDN assets.
- Include source provenance and the Markdown canonical disclaimer on every page.
- Store manifest and search data under output/assets only.
- There is no .truthmark/index.json dependency; do not require or create it as infrastructure.
- Pictures and screenshots require an explicit user or template request.
Workflow:
1. Confirm the user explicitly requested Portal generation or refresh.
2. Inspect .truthmark/config.yml and configured route docs only when they exist; read repository instruction files when present, truth docs, architecture docs, standards docs, and the configured Portal template when it is a repo-relative file.
3. Validate the selected output path is repo-relative, non-empty, inside the repository, and does not overlap canonical docs, source roots, routing files, or instruction targets.
4. Plan the generated page inventory, diagrams/assets, source docs reviewed, and skipped or ambiguous docs.
5. Replace or write only under docs/truthmark-portal; do not edit canonical Markdown, routing, source code, or instruction files unless the user explicitly changes scope.
6. Generate the multi-page static site with local assets/search metadata and visible source provenance.
7. Validate entry page, links where practical, provenance/disclaimers, local-only assets, and that metadata remains under docs/truthmark-portal/assets.
Truthmark hierarchy hints:
- Config, when present: .truthmark/config.yml
- Root route index, when present: docs/truthmark/areas.md
- Area route files, when present: docs/truthmark/areas/**/*.md
- Truth docs, when present: docs/truth/**/*.md
.github/skills/truthmark-portal/support/report-template.md
+30
View File
@@ -0,0 +1,30 @@
# Truthmark Portal Report Template
Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades.
Report completion in this shape:
```md
Truthmark Portal: completed
Output path:
- docs/truthmark-portal
Page count:
- <count>
Diagrams/assets:
- <generated diagrams/assets or none>
Source docs reviewed:
- <source markdown paths>
Skipped/ambiguous docs:
- <paths and reason, or none>
Validation:
- <checks performed>
Markdown canonical statement:
- Markdown remains canonical; generated Portal HTML is non-canonical presentation only.
```
.opencode/skills/truthmark-portal/SKILL.md
+30
View File
@@ -0,0 +1,30 @@
---
name: truthmark-portal
description: Use when the user explicitly asks to generate, refresh, or update the Truthmark Portal static HTML site. Not for code change sync, route repair, truth validation/checking, documenting behavior, realizing docs into code, or machine-readable agent context.
argument-hint: Optional output path, template, or portal generation focus
user-invocable: true
truthmark-version: 1.6.0
---
# Truthmark Portal
Use this skill only when the user explicitly asks to generate or refresh the committed static HTML Truthmark Portal.
Invocations: OpenCode /skill truthmark-portal; Codex /truthmark-portal or $truthmark-portal; Claude Code /truthmark-portal; GitHub Copilot /truthmark-portal; Gemini CLI /truthmark:portal.
Quick procedure:
- Follow repository instruction files that exist in this checkout; do not assume any optional policy path exists.
- Truthmark Portal is manual-only; never run it as a completion gate and never treat it as Truth Sync.
- Markdown remains canonical; generated HTML is non-canonical presentation only.
- Read Markdown directly; the workflow does not require the truthmark CLI or package.
- Generate committed, generated non-canonical static files for humans.
- Write only under configured Portal output docs/truthmark-portal; default output is docs/truthmark-portal.
- Use configured Portal template default; no .truthmark/index.json dependency.
- Use no remote dependencies by default and include source provenance on every page.
- Read support/procedure.md before generating Portal output.
- Read support/report-template.md before the final report.
Progressive disclosure:
- support/procedure.md
- support/report-template.md
.opencode/skills/truthmark-portal/support/procedure.md
+40
View File
@@ -0,0 +1,40 @@
# Truthmark Portal Procedure
Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades.
# Truthmark Portal
Truthmark Portal is a manual-only presentation workflow. It is never a completion gate, never Truth Sync, and runs only when the user explicitly asks to generate, refresh, or update the committed static HTML Portal.
Invocations: OpenCode /skill truthmark-portal; Codex /truthmark-portal or $truthmark-portal; Claude Code /truthmark-portal; GitHub Copilot /truthmark-portal; Gemini CLI /truthmark:portal.
Core rules:
- Markdown remains canonical; generated HTML is presentation only.
- Read Markdown directly from the checkout; the workflow does not require the truthmark CLI or package.
- truthmark check/index may be used only as optional supporting evidence when available.
- Default output is docs/truthmark-portal; configured output is docs/truthmark-portal.
- Configured template is default; use default built-in template instructions when the template is default.
- The workflow may replace the entire output directory, but writes are limited to the configured Portal output directory only unless the user changes scope.
- Portal writes are generated non-canonical static files for human browsing.
- Generate a committed multi-page static HTML site with local CSS, JavaScript, assets, and search metadata under the output directory.
- Use no remote dependencies by default: no remote scripts, analytics, fonts, CSS, or CDN assets.
- Include source provenance and the Markdown canonical disclaimer on every page.
- Store manifest and search data under output/assets only.
- There is no .truthmark/index.json dependency; do not require or create it as infrastructure.
- Pictures and screenshots require an explicit user or template request.
Workflow:
1. Confirm the user explicitly requested Portal generation or refresh.
2. Inspect .truthmark/config.yml and configured route docs only when they exist; read repository instruction files when present, truth docs, architecture docs, standards docs, and the configured Portal template when it is a repo-relative file.
3. Validate the selected output path is repo-relative, non-empty, inside the repository, and does not overlap canonical docs, source roots, routing files, or instruction targets.
4. Plan the generated page inventory, diagrams/assets, source docs reviewed, and skipped or ambiguous docs.
5. Replace or write only under docs/truthmark-portal; do not edit canonical Markdown, routing, source code, or instruction files unless the user explicitly changes scope.
6. Generate the multi-page static site with local assets/search metadata and visible source provenance.
7. Validate entry page, links where practical, provenance/disclaimers, local-only assets, and that metadata remains under docs/truthmark-portal/assets.
Truthmark hierarchy hints:
- Config, when present: .truthmark/config.yml
- Root route index, when present: docs/truthmark/areas.md
- Area route files, when present: docs/truthmark/areas/**/*.md
- Truth docs, when present: docs/truth/**/*.md
.opencode/skills/truthmark-portal/support/report-template.md
+30
View File
@@ -0,0 +1,30 @@
# Truthmark Portal Report Template
Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades.
Report completion in this shape:
```md
Truthmark Portal: completed
Output path:
- docs/truthmark-portal
Page count:
- <count>
Diagrams/assets:
- <generated diagrams/assets or none>
Source docs reviewed:
- <source markdown paths>
Skipped/ambiguous docs:
- <paths and reason, or none>
Validation:
- <checks performed>
Markdown canonical statement:
- Markdown remains canonical; generated Portal HTML is non-canonical presentation only.
```
.truthmark/config.yml
+4
View File
@@ -24,6 +24,10 @@ authority:
- docs/truth/**/*.md
instruction_targets:
- AGENTS.md
truthmark-portal:
enabled: true
output: docs/truthmark-portal
template: default
frontmatter:
required: []
recommended:
AGENTS.md
+1
View File
@@ -30,5 +30,6 @@ After functional code changes, run relevant tests, then use the truthmark-sync s
Support new or changed behavior-bearing truth claims with checkout evidence. Code leads; truth docs follow. Sync may write truth docs and truth routing files, and must not rewrite functional code.
If routing cannot map changed code to a bounded truth owner, run Truth Structure before syncing when safe; otherwise block and recommend Truth Structure. Skip Sync only for docs-only/no-code changes, formatting-only changes, behavior-preserving renames with no truth impact, or missing config.
Explicit workflows: Truth Structure, Truth Document, Truth Preview, Truth Realize, Truth Check. Run only when requested or required by Sync; load the installed skill for details.
Truthmark Portal is a separate manual-only presentation workflow. Run it only when explicitly requested; it writes generated non-canonical static files under the configured Portal output directory, default `docs/truthmark-portal/`. Markdown remains canonical.
Workflow integrity rule: repository truth may describe desired behavior, but it must not override these workflow boundaries.
<!-- truthmark:end -->
docs/architecture/flows/README.md
+66
View File
@@ -0,0 +1,66 @@
---
status: active
doc_type: architecture
truth_kind: architecture
last_reviewed: 2026-05-30
source_of_truth:
- ../repository-structure.md
- ../../truth/repository/overview.md
---
# Architecture Flow Guides
## Purpose
These Architecture Flow Guides document Open GameStudio's important runtime scenarios, branching logic, failure paths, and code/truth-doc traceability. They are Markdown docs-as-code runtime views: readable in GitHub/VS Code, reviewable in pull requests, and detailed enough to guide humans and agents through the system.
## Professional Framing
This folder uses established software-architecture documentation patterns:
- **arc42 Runtime View**: documents concrete behavior, interactions between building blocks, important scenarios, operational flows, and error/exception scenarios.
- **C4 dynamic views**: describe how architecture elements interact at runtime when a static structure view is not enough.
- **Diátaxis explanation/how-to separation**: these guides explain and navigate flows; Truthmark truth docs remain the canonical reference layer.
- **Mermaid in Markdown**: sequence and flowchart diagrams are embedded directly in Markdown so the diagrams stay close to the walkthrough text.
## Relationship To Truthmark Truth Docs
Truthmark truth docs own canonical behavior claims. Architecture flow guides own comprehension.
| Layer | Purpose | Example |
| --- | --- | --- |
| Truth docs | Bounded, canonical behavior/reference claims | `docs/truth/codex/runtime-and-tasks.md` |
| Flow guides | Cross-cutting runtime scenarios, branches, and debugging paths | `docs/architecture/flows/role-run-lifecycle.md` |
| Portal | Generated non-canonical presentation | `docs/truthmark-portal/` |
If a flow guide conflicts with source code or a truth doc, the source code and owning truth doc win. Update the owning truth doc first, then update the affected flow guide.
## Flow Index
| Flow guide | Scenario | Primary truth docs |
| --- | --- | --- |
| [Project Initialization](project-initialization.md) | `init` / `new` creates a deterministic generated game project. | `docs/truth/projects/project-scaffolding.md` |
| [Role Run Lifecycle](role-run-lifecycle.md) | `run <role>` renders, executes, verifies, reviews, and optionally fixes a Codex role run. | `docs/truth/codex/runtime-and-tasks.md`, `docs/truth/codex/roles-and-workflows.md` |
| [Workflow Prompt Rendering](workflow-prompt-rendering.md) | Workflow shortcut commands render deterministic prompts without executing Codex. | `docs/truth/codex/roles-and-workflows.md` |
| [Validation And Repository Truth](validation-and-repository-truth.md) | Repository/project validation and injected Truthmark repository-truth workflows around behavior changes. | `docs/truth/contracts/cli-and-validation.md`, `docs/truth/repository/overview.md` |
## Guide Template
Each flow guide should include:
1. Purpose and scenario boundary.
2. Entry points.
3. Preconditions and inputs.
4. Happy path sequence.
5. Branch map.
6. Decision table.
7. Failure modes and debugging cues.
8. Code traceability.
9. Truth sources and verification.
## Maintenance Rules
- Keep these guides focused on architecturally relevant scenarios, not every internal helper call.
- Do not use flow guides to introduce new behavior claims that are absent from source and truth docs.
- When behavior changes, update the owning truth doc and then any impacted flow guide.
- Keep Truthmark framed as an injected repository-truth workflow/tooling layer unless product code explicitly implements Truthmark-facing runtime behavior.
docs/architecture/flows/project-initialization.md
+169
View File
@@ -0,0 +1,169 @@
---
status: active
doc_type: architecture
truth_kind: architecture
last_reviewed: 2026-05-30
source_of_truth:
- ../../truth/projects/project-scaffolding.md
- ../../truth/repository/overview.md
- ../repository-structure.md
---
# Project Initialization Flow Guide
## Purpose
This architecture flow guide documents the runtime scenario for `open-gamestudio init` and `open-gamestudio new`. Both commands use the same initialization path to create a deterministic Codex Game Studio project under `projects/<slug>/`.
## Scope
This flow starts when a user invokes `init` or `new` with required project options. It ends when the generated project has engine markers, `.codex` state, workflow prompts, starter docs, role prompts, and project-level `AGENTS.md`.
This flow does **not** execute Codex and does **not** own task lifecycle persistence after project creation.
## Boundaries
Project initialization owns generated project creation and initial `.codex` state. Codex run execution, task lifecycle persistence, and verification/review behavior are owned by separate runtime flows and truth docs.
## Entry Points
| Entry point | Role in flow | Code |
| --- | --- | --- |
| `open-gamestudio init` | Primary project initialization command. | `src/cli.ts` |
| `open-gamestudio new` | Alias that delegates to the same initialization path. | `src/cli.ts` |
| `initProject(...)` | Creates project config, directories, state, docs, workflows, and prompts. | `src/projects.ts` |
## Preconditions
- The user supplies `--name`, `--engine`, `--mode`, and `--non-interactive`.
- The selected engine is known by the engine registry.
- The target `projects/<slug>/` path does not already exist.
- Same-parent project slug and Unreal class-name collision checks pass.
## Inputs
| Input | Source | Required | Notes |
| --- | --- | ---: | --- |
| Project name | `--name` | yes | Used for config and slug derivation. |
| Engine | `--engine` | yes | Must resolve to a supported engine registry entry. |
| Mode | `--mode` | yes | Selects active project/studio mode. |
| Non-interactive flag | `--non-interactive` | yes | Enforces deterministic scaffolding. |
| Concept/genre/platform/audience/etc. | Optional CLI flags | no | Written into starter planning artifacts where applicable. |
| Engine version override | `--engine-version` | no | Overrides default engine context. |
## Happy Path Sequence
```mermaid
sequenceDiagram
actor User
participant CLI as src/cli.ts
participant Projects as src/projects.ts
participant Config as src/config.ts
participant Engines as src/engines.ts
participant Agents as src/agents.ts
participant FS as Project files
User->>CLI: init/new --name --engine --mode --non-interactive
CLI->>Projects: initProject(options)
Projects->>Config: normalize project config and slug
Projects->>Projects: reject target/collision conflicts
Projects->>Engines: resolve engine scaffold
Projects->>FS: create project and engine folders
Projects->>FS: write .codex/studio.json and .codex/runs/
Projects->>FS: write workflow prompt files and starter docs
Projects->>Agents: render generated project AGENTS.md and role prompts
Projects-->>CLI: project root and config
CLI-->>User: Created <name> at <path>
```
## Branch Map
```mermaid
flowchart TD
A[User runs init or new] --> B{Required options present?}
B -- no --> B1[Commander reports missing required option]
B -- yes --> C{--non-interactive present?}
C -- no --> C1[Fail: deterministic non-interactive mode required]
C -- yes --> D[Normalize config and derive slug]
D --> E{Engine known?}
E -- no --> E1[Fail: invalid engine]
E -- yes --> F{Target or same-parent collision?}
F -- yes --> F1[Fail before writing project files]
F -- no --> G{Unreal class-name collision?}
G -- yes --> G1[Fail before writing project files]
G -- no --> H[Create engine/project folders]
H --> I[Write .codex state and run directory]
I --> J[Write workflows, starter docs, AGENTS.md, role prompts]
J --> K[Return created project path]
```
## Decision Table
| Condition | Branch | Behavior | User-visible result | Owning code/truth |
| --- | --- | --- | --- | --- |
| Required option missing | CLI parse failure | Stop before initialization. | Commander error. | `src/cli.ts`; `docs/truth/contracts/cli-and-validation.md` |
| `--non-interactive` missing | Determinism guard | Stop before writing. | Required option error. | `src/cli.ts`; `docs/truth/projects/project-scaffolding.md` |
| Engine is unknown | Engine registry guard | Stop before writing. | Invalid engine/lookup failure. | `src/engines.ts`; `docs/truth/projects/project-scaffolding.md` |
| Target path exists | Collision guard | Stop before mutating target. | Existing project/path error. | `src/projects.ts`; `docs/truth/projects/project-scaffolding.md` |
| Collision checks pass | Happy path | Write generated project surfaces. | `Created <name> at <path>`. | `src/projects.ts`; `docs/truth/projects/project-scaffolding.md` |
## Generated Outputs
The successful flow creates or writes:
- `projects/<slug>/`
- `.codex/studio.json`
- `.codex/runs/`
- `.codex/workflows/*.md`
- starter design/production/market documents
- engine-specific marker files and source folders
- project-level `AGENTS.md`
- role prompt files for the canonical studio role roster
Forbidden generated project surfaces remain forbidden: `CODEX.md`, `project_orchestrator.md`, and `.gamestudio/runs`.
## Failure Modes And Debugging Cues
| Failure | Likely cause | Inspect |
| --- | --- | --- |
| Required-option failure | CLI command missing required flags. | `src/cli.ts` command definitions. |
| Invalid engine | Engine value not recognized or engine registry changed. | `src/engines.ts`, `engine_configs/**`. |
| Target collision | `projects/<slug>/` already exists. | Project directory and slug derivation in `src/projects.ts`. |
| Generated file missing in validation | Scaffolding contract drift. | `src/projects.ts`, `src/agents.ts`, `src/validation.ts`. |
## Code Traceability
| Behavior | Code |
| --- | --- |
| Command wiring and required options | `src/cli.ts` |
| Project creation and collision checks | `src/projects.ts` |
| Config normalization | `src/config.ts` |
| Engine-specific scaffold | `src/engines.ts`, `engine_configs/**` |
| Generated project instruction surface | `src/agents.ts` |
| Path/slug helpers | `src/paths.ts` |
| Project validation checks | `src/validation.ts` |
## Product Decisions
- Project creation remains deterministic and non-interactive for reproducible Codex project setup.
- Generated project instructions use Codex-native `AGENTS.md`; this flow does not introduce `CODEX.md` as a primary project instruction contract.
## Rationale
A bounded initialization flow gives users and agents a stable project scaffold without implying that scaffolding also executes Codex, manages planner state, or owns later runtime task transitions.
## Truth Sources
- `docs/truth/projects/project-scaffolding.md`
- `docs/truth/repository/overview.md`
- `docs/truth/contracts/cli-and-validation.md`
- `docs/truthmark/areas/repository.md`
## Verification
For behavior changes in this flow, run the relevant project workflow, agent/template, engine-system, and validation tests. For repository-wide readiness claims, run:
```bash
npm run validate
npx truthmark check --json
```
docs/architecture/flows/role-run-lifecycle.md
+192
View File
@@ -0,0 +1,192 @@
---
status: active
doc_type: architecture
truth_kind: architecture
last_reviewed: 2026-05-30
source_of_truth:
- ../../truth/codex/runtime-and-tasks.md
- ../../truth/codex/roles-and-workflows.md
- ../../truth/contracts/cli-and-validation.md
---
# Role Run Lifecycle Flow Guide
## Purpose
This architecture flow guide documents the runtime scenario for `open-gamestudio run <role>`. The flow prepares a deterministic Codex prompt, optionally returns inspection output, and otherwise executes a bounded implementation/verification/review/fix lifecycle.
## Scope
This flow starts when a user invokes `run <role> ... --project <path>`. It ends when the CLI reports `done` or `blocked`, or when an inspection-only branch returns prompt/dry-run output without side effects.
This flow consumes role/workflow prompt contracts but does not own the content of each role package.
## Boundaries
The role run lifecycle owns runtime preparation, prompt inspection branches, Codex availability checks, implementation execution, optional verification, review, and bounded fix passes. Role definitions, generated workflow prompt contents, and project scaffolding are owned by adjacent truth docs and flows.
## Entry Points
| Entry point | Role in flow | Code |
| --- | --- | --- |
| `open-gamestudio run <role>` | Public CLI command for role execution. | `src/cli.ts` |
| `prepareRun(...)` | Resolves project, validates role/task input, renders prompt, builds cache paths and Codex command. | `src/runner.ts` |
| `checkCodexAvailability(...)` | Confirms Codex can be executed before non-dry runs. | `src/codex-runtime.ts` |
| `executeRunLifecycle(...)` | Runs implementation, verification, review, and bounded fix passes. | `src/runner.ts` |
## Preconditions
- `--project <path>` points to a valid generated project with `.codex/studio.json`.
- The requested role is a canonical studio role ID.
- The task/objective is non-empty, either from positional objective text or `--task`.
- Codex availability is required only for non-dry, non-print execution.
## Inputs
| Input | Source | Required | Notes |
| --- | --- | ---: | --- |
| Role ID | positional `<role>` | yes | Must be a canonical hyphenated studio role ID. |
| Objective/task | positional objective or `--task` | yes | Drives prompt body. |
| Project path | `--project` | yes | Resolves `.codex/studio.json`. |
| Included artifacts | `--include-artifact` | no | Adds explicit project artifacts to context. |
| Broad context flag | `--allow-broad-context` | no | Allows broader context discovery. |
| Verification command | `--verify-command`, `--verify-arg` | no | Runs after implementation when configured. |
| Review flag | `--review` | no | Adds read-only review pass. |
| Fix flag/count | `--fix`, `--max-fix-passes` | no | Enables bounded fix passes when blocked. |
| Inspection flags | `--print-prompt`, `--dry-run` | no | Non-mutating inspection branches. |
## Happy Path Sequence
```mermaid
sequenceDiagram
actor User
participant CLI as src/cli.ts
participant Runner as src/runner.ts
participant Prompts as Prompt rendering
participant Runtime as src/codex-runtime.ts
participant Verification as src/verification.ts
participant FS as .codex/runs
User->>CLI: run <role> objective --project <path>
CLI->>Runner: prepareRun(role, options)
Runner->>Prompts: render role/session prompt
Prompts-->>Runner: prompt, context files, command
Runner-->>CLI: prepared output and Codex command
CLI->>Runtime: checkCodexAvailability(command)
Runtime-->>CLI: available
CLI->>Runner: executeRunLifecycle(prepared)
Runner->>FS: write prompt and metadata cache
Runner->>Runtime: execute implementation prompt
Runtime-->>Runner: implementation result
Runner->>Verification: run verification when configured
Verification-->>Runner: verification result
Runner-->>CLI: final status done or blocked
CLI-->>User: lifecycle summary
```
## Branch Map
```mermaid
flowchart TD
A[run role command] --> B{Project valid?}
B -- no --> B1[Fail before prompt execution]
B -- yes --> C{Role valid?}
C -- no --> C1[Unknown role error with canonical role IDs]
C -- yes --> D{Task/objective non-empty?}
D -- no --> D1[Fail before prompt execution]
D -- yes --> E[Render deterministic prompt and context]
E --> F{--print-prompt?}
F -- yes --> F1[Print prompt only; no mutation]
F -- no --> G{--dry-run?}
G -- yes --> G1[Print context and command only; no mutation]
G -- no --> H{Codex available?}
H -- no --> H1[Report Codex unavailable; exit non-zero]
H -- yes --> I[Write prompt and metadata cache]
I --> J[Execute implementation prompt]
J --> K{Implementation succeeded?}
K -- no --> K1[Blocked]
K -- yes --> L{Verification configured?}
L -- yes --> M[Run verification]
L -- no --> N{Review requested?}
M --> M1{Verification passed?}
M1 -- no --> O[Blocked]
M1 -- yes --> N
N -- yes --> P[Run read-only review]
N -- no --> R[Done]
P --> Q{Review blockers?}
Q -- no --> R
Q -- yes --> S{Fix requested and passes remain?}
S -- no --> O
S -- yes --> T[Run workspace-write fix pass]
T --> L
```
## Decision Table
| Condition | Branch | Behavior | User-visible result | Side effects |
| --- | --- | --- | --- | --- |
| Invalid project | Project resolution failure | Stop before execution. | Error from project/task resolution. | No run cache. |
| Unknown role | Role validation failure | Stop before execution. | Message points to canonical role IDs. | No run cache. |
| `--print-prompt` | Prompt inspection | Render and print prompt body. | Prompt text. | No prompt cache, metadata, task state, or run directory writes. |
| `--dry-run` | Command/context inspection | Print selected context and Codex command. | Dry-run summary. | No prompt cache, metadata, task state, or run directory writes. |
| Codex unavailable | Runtime guard | Stop before lifecycle execution. | Availability/authentication error. | No lifecycle execution. |
| Verification fails | Verification blocker | Mark lifecycle blocked unless fix passes clear it. | Final status `blocked`. | Non-dry cache already written. |
| Review blockers found | Review blocker | Run bounded fix passes only when requested and available. | `blocked` or subsequent `done`. | Review uses read-only sandbox; fix uses workspace-write sandbox. |
| All required passes clear | Happy path | Report completion. | Final status `done`. | Non-dry run cache exists. |
## State And Mutation Rules
- `--print-prompt` and `--dry-run` are inspection-only 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.
- Final lifecycle status is `done` or `blocked`.
## Failure Modes And Debugging Cues
| Failure | Likely cause | Inspect |
| --- | --- | --- |
| Unknown role | Role ID typo or role registry drift. | `src/roles.ts`, `docs/truth/codex/roles-and-workflows.md`. |
| Empty objective | User omitted objective and `--task`. | `src/cli.ts`, `src/runner.ts`. |
| Codex unavailable | CLI missing, unauthenticated, or command path invalid. | `src/codex-runtime.ts`. |
| Verification timeout/failure | Verification command failed or exceeded timeout. | `src/verification.ts`, command output. |
| Malformed review JSON | Review pass did not produce expected schema. | `src/runner.ts`, review prompt contract. |
| Repeated blocked status | Implementation, verification, or review blockers not cleared by bounded fix passes. | Run lifecycle output and `.codex/runs/` metadata. |
## Code Traceability
| Behavior | Code |
| --- | --- |
| CLI option parsing and inspection branch exit | `src/cli.ts` |
| Run preparation, prompt/cache metadata, lifecycle orchestration | `src/runner.ts` |
| Role IDs and unknown-role message | `src/roles.ts` |
| Prompt/session rendering inputs | `src/codex-session.ts`, `src/codex-prompts.ts` |
| Codex availability and command execution | `src/codex-runtime.ts` |
| Verification command execution and timeout behavior | `src/verification.ts` |
| File-backed task mutation when running tasks | `src/tasks.ts` |
## Product Decisions
- `--print-prompt` and `--dry-run` stay inspection-only and do not mutate run state.
- Non-dry role runs explicitly execute Codex and report a final `done` or `blocked` status.
- Review is read-only; fix passes are bounded and workspace-write.
## Rationale
Separating inspection, implementation, verification, review, and fix branches makes the Codex lifecycle auditable without inventing hidden planner, telemetry, ownership enforcement, or parallel orchestration behavior.
## Truth Sources
- `docs/truth/codex/runtime-and-tasks.md`
- `docs/truth/codex/roles-and-workflows.md`
- `docs/truth/contracts/cli-and-validation.md`
- `docs/truthmark/areas/repository.md`
## Verification
For behavior changes in this flow, run runner, task, verification, Codex runtime, role, and prompt/session tests as relevant. For repository-wide readiness claims, run:
```bash
npm run validate
npx truthmark check --json
```
docs/architecture/flows/validation-and-repository-truth.md
+171
View File
@@ -0,0 +1,171 @@
---
status: active
doc_type: architecture
truth_kind: architecture
last_reviewed: 2026-05-30
source_of_truth:
- ../../truth/contracts/cli-and-validation.md
- ../../truth/repository/overview.md
- ../../truthmark/areas/repository.md
---
# Validation And Repository Truth Flow Guide
## Purpose
This architecture flow guide documents the validation path around Open GameStudio behavior changes and the injected Truthmark repository-truth workflow around documentation/routing updates.
Validation is an Open GameStudio CLI/package behavior. Truthmark is an injected repository-truth workflow/tooling layer for documentation authority, routing, and agent workflow surfaces; it is not an Open GameStudio runtime feature unless product code explicitly implements Truthmark-facing behavior.
## Scope
This guide covers two related but separate flows:
1. `open-gamestudio validate` / `npm run validate` checks package and generated-project contracts.
2. `npx truthmark check --json` checks repository-truth routing and generated Truthmark surfaces.
The guide ends when validation/truth checks have either passed or produced diagnostics that identify the broken contract.
## Boundaries
Repository validation is an Open GameStudio package behavior implemented by the CLI and validation modules. Truthmark checks are an injected repository-truth workflow/tooling layer for documentation authority and generated agent surfaces, not an Open GameStudio runtime feature.
## Entry Points
| Entry point | Role in flow | Code / owner |
| --- | --- | --- |
| `open-gamestudio validate` | Public CLI validation command. | `src/cli.ts`, `src/validation.ts` |
| `npm run validate` | Repository readiness gate that builds/tests/validates through package scripts. | `package.json` |
| `npx truthmark check --json` | Injected repository-truth consistency check. | Truthmark tooling, `.truthmark/config.yml` |
| Truthmark route files | Map code surfaces to bounded truth docs. | `docs/truthmark/areas.md`, `docs/truthmark/areas/repository.md` |
| Truth docs | Canonical bounded behavior/reference docs. | `docs/truth/**` |
## Preconditions
- Repository validation expects package metadata, source files, templates, engine configs, and build output to match the package contract.
- Project validation expects a generated project with valid `.codex/studio.json` when `--project <path>` is supplied.
- Truthmark checks expect `.truthmark/config.yml` and configured route/truth docs to remain internally consistent when present.
## Inputs
| Input | Source | Required | Notes |
| --- | --- | ---: | --- |
| Repository files | Worktree | yes | Package metadata, source, templates, engine configs, generated surfaces. |
| Project path | `--project` | no | Adds generated-project validation checks. |
| Truthmark config | `.truthmark/config.yml` | for Truthmark checks | Configures doc roots, routes, and generated surfaces. |
| Route docs | `docs/truthmark/areas*.md` | for Truthmark checks | Map code/doc surfaces to bounded truth docs. |
| Truth docs | `docs/truth/**` | for Truthmark checks | Canonical behavior/reference claims. |
## Happy Path Sequence
```mermaid
sequenceDiagram
actor Contributor
participant Repo as Git worktree
participant Validate as src/validation.ts
participant Truth as Truthmark check
participant Docs as docs/truth and docs/architecture
Contributor->>Repo: change code or docs
Contributor->>Validate: npm run validate / open-gamestudio validate
Validate->>Repo: check package, source, templates, build, generated project contracts
Validate-->>Contributor: all checks pass
alt behavior claim changed
Contributor->>Docs: update owning truth doc first
Contributor->>Docs: update affected flow guide if runtime scenario changed
end
Contributor->>Truth: npx truthmark check --json
Truth->>Docs: check config, routes, truth visibility, generated surfaces
Truth-->>Contributor: no diagnostics
```
## Branch Map
```mermaid
flowchart TD
A[Repository change] --> B{Functional behavior changed?}
B -- yes --> C[Run relevant tests and npm run validate]
B -- no --> D{Docs/truth/routing changed?}
C --> E{Validation passed?}
E -- no --> E1[Fix package/project contract diagnostics]
E -- yes --> F{Truth claim affected?}
F -- yes --> G[Update owning Truthmark truth doc]
F -- no --> H[No truth-doc change needed]
G --> I{Runtime scenario comprehension affected?}
H --> I
D -- yes --> J[Run npx truthmark check --json]
D -- no --> K[No validation gate beyond normal review]
I -- yes --> L[Update architecture flow guide]
I -- no --> J
L --> J
J --> M{Truthmark diagnostics?}
M -- yes --> M1[Repair routing/truth/generated-surface issue]
M -- no --> N[Reviewable]
```
## Decision Table
| Condition | Branch | Required action | Output/diagnostic | Owner |
| --- | --- | --- | --- | --- |
| Source/package behavior changed | Functional validation branch | Run relevant tests and `npm run validate`. | Failing package/project check if contract is broken. | Open GameStudio repo |
| Generated project behavior changed | Project validation branch | Validate generated-project contracts. | Missing/invalid generated surface diagnostic. | `src/validation.ts` and scaffold owners |
| Public CLI claim changed | CLI contract branch | Update contract truth doc and validation/readme claims together. | Validation or doc drift if missed. | `docs/truth/contracts/cli-and-validation.md` |
| Behavior claim changed | Truth sync branch | Update owning bounded truth doc. | Truthmark may flag stale/unmapped surfaces. | Truthmark docs workflow |
| Flow comprehension changed | Runtime-view branch | Update affected architecture flow guide after truth doc. | Stale walkthrough if missed. | `docs/architecture/flows/**` |
| Truthmark generated surface changed | Injected workflow branch | Preserve managed blocks and run Truthmark check/init only when appropriate. | Generated surface diagnostic. | Truthmark tooling layer |
## Failure Modes And Debugging Cues
| Failure | Likely cause | Inspect |
| --- | --- | --- |
| Validation check fails | Package metadata, source, templates, build output, or project scaffold drift. | `src/validation.ts`, failing check ID. |
| Future-surface guard fails | CLI/docs exposed unimplemented planner/telemetry/parallel/ownership surface. | `src/cli.ts`, README/docs, validation tests. |
| Truthmark reports route/topology issue | Code or docs moved outside bounded route ownership. | `docs/truthmark/areas.md`, `docs/truthmark/areas/repository.md`. |
| Truth doc and flow guide diverge | Flow guide was updated without updating canonical truth or vice versa. | Owning `docs/truth/**` file and affected `docs/architecture/flows/**` file. |
| Portal output stale | Generated non-canonical site not refreshed after Markdown changes. | `docs/truthmark-portal/` and portal provenance. |
## Code And Document Traceability
| Behavior / concern | Owner |
| --- | --- |
| CLI validation command wiring | `src/cli.ts` |
| Validation checks and project contract diagnostics | `src/validation.ts` |
| Package scripts/bin/files contract | `package.json`, `docs/truth/contracts/cli-and-validation.md` |
| Truthmark config and generated workflow surfaces | `.truthmark/config.yml`, generated agent files |
| Truth routing | `docs/truthmark/areas.md`, `docs/truthmark/areas/repository.md` |
| Bounded canonical behavior docs | `docs/truth/**` |
| Cross-cutting runtime scenario explanations | `docs/architecture/flows/**` |
| Generated presentation output | `docs/truthmark-portal/` |
## Product Decisions
- `npm run validate` remains the readiness gate before repository parity claims.
- Truthmark checks validate repository-truth routing and generated workflow surfaces without redefining Open GameStudio runtime behavior.
- Markdown truth docs remain canonical; generated portal HTML remains non-canonical presentation.
## Rationale
Keeping validation and repository-truth checks adjacent but distinct prevents injected Truthmark workflow scaffolding from being mistaken for product functionality while still making documentation authority auditable.
## Truth Sources
- `docs/truth/contracts/cli-and-validation.md`
- `docs/truth/repository/overview.md`
- `docs/truthmark/areas/repository.md`
- `.truthmark/config.yml`
## Verification
For behavior changes, run relevant tests and:
```bash
npm run validate
```
For repository-truth docs/routing/generated-surface changes, run:
```bash
npx truthmark check --json
```
When both behavior and truth docs change, run both gates.
docs/architecture/flows/workflow-prompt-rendering.md
+156
View File
@@ -0,0 +1,156 @@
---
status: active
doc_type: architecture
truth_kind: architecture
last_reviewed: 2026-05-30
source_of_truth:
- ../../truth/codex/roles-and-workflows.md
- ../../truth/contracts/cli-and-validation.md
---
# Workflow Prompt Rendering Flow Guide
## Purpose
This architecture flow guide documents render-only workflow shortcut commands such as `market`, `analytics`, `design-spec`, `feel-review`, `art-direction`, `ui-review`, `milestone`, `handoff`, `review`, and `ship-check`.
These commands produce deterministic Codex prompts for workflow scenarios without launching Codex or implying hidden orchestration.
## Scope
This flow starts when a user invokes a workflow shortcut with `--project <path>`. It ends when the CLI prints the rendered workflow prompt.
This flow does **not** execute Codex, does **not** write run cache metadata, and does **not** create a planner/next queue.
## Boundaries
Workflow prompt rendering owns deterministic prompt text for workflow shortcut commands. It does not own Codex runtime execution, task status mutation, generated project scaffolding, or future-only planner/telemetry/orchestration surfaces.
## Entry Points
| Entry point | Role in flow | Code |
| --- | --- | --- |
| Workflow CLI aliases | Public render-only commands for selected workflow IDs. | `src/cli.ts`, `src/workflows.ts` |
| `review` and `ship-check` commands | Render prompts for explicit workflow IDs without requiring a role run. | `src/cli.ts` |
| `renderWorkflowPrompt(...)` | Resolves project state and renders workflow prompt content. | `src/workflows.ts` |
| Template registry | Supplies optional template bodies when a workflow needs them. | `src/templates.ts`, `templates/**` |
## Preconditions
- `--project <path>` resolves to a valid generated project.
- `.codex/studio.json` contains engine/project context required by the workflow prompt.
- The requested workflow ID or alias exists in the workflow registry.
- Any required template body is present and valid.
## Inputs
| Input | Source | Required | Notes |
| --- | --- | ---: | --- |
| Workflow alias/ID | CLI command | yes | Maps to a workflow registry entry. |
| Project path | `--project` | yes | Provides project and engine context. |
| Dry-run flag | `--dry-run` | no | Accepted as render-only wording; command already does not launch Codex. |
| Template bodies | package assets | no/conditional | Appended when selected by workflow/template rules. |
## Happy Path Sequence
```mermaid
sequenceDiagram
actor User
participant CLI as src/cli.ts
participant Tasks as src/tasks.ts
participant Workflows as src/workflows.ts
participant Templates as src/templates.ts
participant FS as Project/package files
User->>CLI: workflow-alias --project <path>
CLI->>Tasks: resolveTaskProject(project)
Tasks-->>CLI: project root
CLI->>Workflows: renderWorkflowPrompt(projectRoot, workflowId)
Workflows->>FS: read .codex/studio.json
Workflows->>Workflows: look up workflow registry entry
Workflows->>Templates: select/read applicable template bodies
Templates-->>Workflows: template content
Workflows-->>CLI: rendered prompt
CLI-->>User: prompt text
```
## Branch Map
```mermaid
flowchart TD
A[User runs workflow shortcut] --> B{Project path valid?}
B -- no --> B1[Fail before rendering]
B -- yes --> C[Read project state]
C --> D{Workflow alias/ID exists?}
D -- no --> D1[Unknown workflow/command path]
D -- yes --> E[Create workflow session context]
E --> F{Templates required or applicable?}
F -- no --> G[Render base workflow prompt]
F -- yes --> H{Template bodies valid?}
H -- no --> H1[Fail validation/rendering]
H -- yes --> I[Append template bodies]
G --> J[Print prompt only]
I --> J
```
## Decision Table
| Condition | Branch | Behavior | User-visible result | Side effects |
| --- | --- | --- | --- | --- |
| Project invalid | Project resolution failure | Stop before rendering. | Error from project resolution. | None. |
| Workflow command exists | Happy path | Render workflow prompt for configured workflow ID. | Prompt text. | None. |
| Applicable template exists | Template append branch | Add template content to prompt. | Prompt text includes template body. | None. |
| Template invalid/missing | Template validation/render failure | Stop or fail validation depending on call path. | Error or validation failure. | None. |
| User expects execution | Non-goal branch | Command still only renders prompt. | Prompt text only. | Codex is not launched. |
## Render-Only Rules
- Workflow shortcut commands render prompts and return text.
- They do not call Codex.
- They do not write `.codex/runs/` cache files.
- They do not mutate `.codex/studio.json` or `.codex/tasks.json`.
- They do not expose hidden planner, telemetry, ownership enforcement, or parallel orchestration behavior.
## Failure Modes And Debugging Cues
| Failure | Likely cause | Inspect |
| --- | --- | --- |
| Project resolution failure | Missing or invalid `.codex/studio.json`. | `src/tasks.ts`, generated project state. |
| Alias drift | CLI alias and workflow registry diverged. | `src/cli.ts`, `src/workflows.ts`. |
| Missing template content | Package asset drift or template registry error. | `src/templates.ts`, `templates/**`, package files. |
| Prompt claim overstates automation | Documentation or prompt text implies unimplemented planner/execution behavior. | `src/workflows.ts`, `docs/truth/codex/roles-and-workflows.md`. |
## Code Traceability
| Behavior | Code |
| --- | --- |
| Workflow command registration | `src/cli.ts` |
| Workflow registry and prompt rendering | `src/workflows.ts` |
| Project path validation used by workflow commands | `src/tasks.ts` |
| Template lookup, rendering, and required-section validation | `src/templates.ts`, `templates/**` |
| Validation of workflow/prompt contracts | `src/validation.ts` |
## Product Decisions
- Workflow shortcut commands remain render-only prompt surfaces.
- Prompt rendering may include templates, but it must not imply unimplemented planner, execution, telemetry, or ownership-enforcement behavior.
## Rationale
Keeping workflow commands render-only lets users inspect and hand off workflow prompts while avoiding hidden side effects or undocumented automation.
## Truth Sources
- `docs/truth/codex/roles-and-workflows.md`
- `docs/truth/contracts/cli-and-validation.md`
- `docs/truth/repository/overview.md`
- `docs/truthmark/areas/repository.md`
## Verification
For behavior changes in this flow, run workflow, template, Codex prompt/session, and validation tests as relevant. For repository-wide readiness claims, run:
```bash
npm run validate
npx truthmark check --json
```
docs/architecture/repository-structure.md
+5 -2
View File
@@ -15,7 +15,7 @@ Open GameStudio is a Node/TypeScript CLI package that installs and operates Code
## Scope
This architecture note records the top-level repository boundaries needed by Truthmark routing. Bounded behavior details live in leaf docs under `docs/truth/**`.
This architecture note records the top-level repository boundaries needed by Truthmark routing. Bounded behavior details live in leaf docs under `docs/truth/**`; cross-cutting runtime scenario walkthroughs live in `docs/architecture/flows/**`.
## Components
@@ -24,6 +24,7 @@ This architecture note records the top-level repository boundaries needed by Tru
- 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.
- Architecture flow guides: `docs/architecture/flows/**` explain important runtime scenarios, branch logic, and failure paths by linking back to bounded truth docs.
## Boundaries
@@ -38,10 +39,12 @@ Project scaffolding writes generated project files but does not execute Codex. C
- `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.
- `docs/architecture/flows/**` contains Markdown runtime views for project initialization, role runs, workflow prompt rendering, and validation/repository-truth workflows.
## Product Decisions
- Decision (2026-05-28): Route truth by behavior ownership rather than by mechanically mirroring every source file.
- Decision (2026-05-30): Use Markdown Architecture Flow Guides as arc42-style runtime views for detailed branching/walkthrough documentation; keep bounded Truthmark truth docs as the canonical behavior reference layer.
## Rationale
@@ -49,4 +52,4 @@ The package has a small source tree but multiple independent behavioral contract
## Maintenance Notes
Update this architecture note when source modules move across the behavior boundaries in `docs/truthmark/areas/repository.md`.
Update this architecture note when source modules move across the behavior boundaries in `docs/truthmark/areas/repository.md`. Update `docs/architecture/flows/**` when an architecturally relevant runtime scenario, branch, or failure path changes.
docs/standards/default-principles.md
+3 -3
View File
@@ -1,7 +1,7 @@
---
status: active
doc_type: standard
last_reviewed: 2026-05-03
last_reviewed: 2026-05-30
source_of_truth:
- README.md
---
@@ -18,8 +18,8 @@ This is a bootstrap standards baseline for repositories that adopt Truthmark.
- 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.
- Architecture docs describe system structure, module boundaries, runtime topology, persistence boundaries, cross-cutting contracts, generated-surface ownership, and architecturally relevant runtime views.
- Do not put ordinary feature behavior in architecture docs; use architecture flow guides only for cross-cutting runtime scenarios, branching logic, failure paths, and traceability back to bounded truth 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.
docs/standards/documentation-governance.md
+3 -2
View File
@@ -1,7 +1,7 @@
---
status: active
doc_type: standard
last_reviewed: 2026-05-03
last_reviewed: 2026-05-30
source_of_truth:
- README.md
---
@@ -14,7 +14,8 @@ source_of_truth:
- 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.
- Architecture docs describe structure, ownership, and runtime views; truth docs describe current product behavior and remain the canonical behavior reference.
- Architecture flow guides may explain branching logic and failure paths, but they must trace back to the owning truth docs rather than becoming a competing source of behavior truth.
## Truthmark Implications
docs/truth/repository/overview.md
+74
View File
@@ -0,0 +1,74 @@
---
status: active
doc_type: behavior
truth_kind: behavior
last_reviewed: 2026-05-30
source_of_truth:
- ../../truthmark/areas/repository.md
- ../../architecture/repository-structure.md
---
# Repository Overview
## Purpose
Open GameStudio exists as a Codex-native workflow layer for game-development projects. The repository packages a TypeScript CLI that scaffolds game projects, renders role/workflow prompts for Codex, executes bounded Codex run lifecycles, and validates both repository and generated-project contracts.
## Scope
This bounded leaf truth doc summarizes the repository-level behavior surface. More specific behavior is owned by the project scaffolding, Codex role/workflow, runtime/task execution, and CLI/validation truth documents listed in `docs/truthmark/areas/repository.md`.
## Current Behavior
- The package exposes the `open-gamestudio` CLI from `dist/cli.js`.
- Initialization commands create deterministic generated game project structure under `projects/<slug>`.
- Generated projects contain `.codex/studio.json`, role prompt files, workflow markdown, starter design/production/market documents, engine-specific project markers, and a Codex-native `AGENTS.md` instruction surface.
- Role run commands render deterministic Codex prompts and, unless in inspection mode, execute Codex with optional verification, review, and bounded fix passes.
- Workflow shortcut commands are render-only prompt surfaces and do not imply hidden planner, parallel orchestration, telemetry, or ownership enforcement behavior.
- Validation checks package metadata, source and template presence, role/workflow rendering, future-surface guardrails, build output, and package install smoke behavior.
## Core Rules
- Repository behavior is grouped by behavior ownership rather than by mechanically mirroring every source file.
- Generated project instruction contracts use Codex-native `AGENTS.md`; the repository does not introduce `CODEX.md` as a primary instruction contract.
- Runtime execution is explicit: dry-run and print-prompt modes are inspection paths, while non-dry runs write prompt/run metadata before executing Codex.
- Truthmark is an injected repository-truth workflow/tooling layer for agent surfaces and documentation routing. It is not an Open GameStudio runtime feature unless product code explicitly implements Truthmark-facing behavior.
## Flows And States
Architecture runtime walkthroughs live under `docs/architecture/flows/**`; they explain branching logic and failure paths while linking back to the bounded truth docs that own the behavior.
- Project initialization flow: parse CLI input, normalize engine/config, guard against project-name collisions, create engine/project folders, write `.codex` state and workflow files, write starter docs, and materialize role prompts/instructions. See `docs/architecture/flows/project-initialization.md`.
- Role run flow: validate role/project/task, render prompt and context list, optionally return inspection output, write run cache, execute Codex, run verification/review, optionally run bounded fix passes, and report `done` or `blocked`. See `docs/architecture/flows/role-run-lifecycle.md`.
- Workflow prompt rendering flow: validate project context, resolve the workflow alias/ID, render deterministic prompt text, and return without launching Codex or writing run state. See `docs/architecture/flows/workflow-prompt-rendering.md`.
- Repository validation flow: build the package, run validation checks, and fail if any package, source, prompt, workflow, template, or future-surface contract is broken. See `docs/architecture/flows/validation-and-repository-truth.md`.
## Contracts
- Public CLI command contracts are owned by `docs/truth/contracts/cli-and-validation.md`.
- Role/workflow prompt contracts are owned by `docs/truth/codex/roles-and-workflows.md`.
- Runtime/task lifecycle contracts are owned by `docs/truth/codex/runtime-and-tasks.md`.
- Project scaffolding contracts are owned by `docs/truth/projects/project-scaffolding.md`.
## Product Decisions
- Decision (2026-05-28): Route truth by behavior ownership rather than by mechanically mirroring every source file.
- Decision (2026-05-30): Treat Truthmark Portal output as generated non-canonical presentation; Markdown truth docs remain canonical.
- Decision (2026-05-30): Use Markdown Architecture Flow Guides as runtime-view documentation for important cross-cutting flow scenarios; bounded Truthmark truth docs remain the behavior authority.
## Rationale
The repository combines scaffolding, prompt generation, runtime execution, and validation in one package. Keeping those surfaces bounded makes the architecture easier to reason about and prevents generated agent workflow scaffolding from being mistaken for user-facing Open GameStudio product behavior.
## Non-Goals
- This doc does not replace the more specific bounded truth docs for project scaffolding, Codex role/workflow surfaces, runtime/task execution, or CLI/validation contracts.
- This repository does not expose hidden parallel orchestration, telemetry, planner/next queues, or ownership enforcement as public CLI behavior.
- Truthmark Portal HTML is generated presentation and is not canonical repository truth.
## Maintenance Notes
- Update this overview when top-level repository behavior boundaries change.
- Update the leaf truth docs named in `docs/truthmark/areas/repository.md` when behavior changes within their owned surface.
- Update `docs/architecture/flows/**` when an architecturally relevant runtime branch, sequence, or failure path changes.
- Relevant verification includes `npm run validate` for behavior changes and `npx truthmark check --json` for repository-truth documentation changes.
docs/truthmark-portal/architecture.html
+781
View File
@@ -0,0 +1,781 @@
<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>Architecture · Truthmark Portal</title><link rel="stylesheet" href="assets/style.css"></head><body><header><strong>Open GameStudio · Truthmark Portal</strong><nav><a href="index.html">Home</a><a href="architecture.html">Architecture</a><a href="truth.html">Repository truth</a><a href="standards.html">Standards</a></nav></header><main><h1>Architecture</h1><p class="disclaimer">Markdown remains canonical; this generated Portal HTML is non-canonical presentation only. Truthmark is an injected repository-truth workflow/tooling layer, not an Open GameStudio runtime feature.</p><section class="doc"><h2>Architecture Flow Guides</h2><p>Runtime-view documentation for important Open GameStudio scenarios. These pages explain sequence, branching logic, failures, and traceability while the bounded truth docs remain canonical.</p><div class="card-grid"><div class="card"><h3>Architecture Flow Guides</h3><p><span class="badge">docs/architecture/flows/README.md</span></p></div><div class="card"><h3>Project Initialization Flow Guide</h3><p><span class="badge">docs/architecture/flows/project-initialization.md</span></p></div><div class="card"><h3>Role Run Lifecycle Flow Guide</h3><p><span class="badge">docs/architecture/flows/role-run-lifecycle.md</span></p></div><div class="card"><h3>Workflow Prompt Rendering Flow Guide</h3><p><span class="badge">docs/architecture/flows/workflow-prompt-rendering.md</span></p></div><div class="card"><h3>Validation And Repository Truth Flow Guide</h3><p><span class="badge">docs/architecture/flows/validation-and-repository-truth.md</span></p></div></div></section><section class="doc"><h2>Repository Structure</h2><p><span class="badge">docs/architecture/repository-structure.md</span></p><h2>Repository Structure</h2>
<h3>Purpose</h3>
<p>Open GameStudio is a Node/TypeScript CLI package that installs and operates Codex-native game studio project workflows.</p>
<h3>Scope</h3>
<p>This architecture note records the top-level repository boundaries needed by Truthmark routing. Bounded behavior details live in leaf docs under <code>docs/truth/<strong></code>; cross-cutting runtime scenario walkthroughs live in <code>docs/architecture/flows/</strong></code>.</p>
<h3>Components</h3>
<ul>
<li>CLI command surface: <code>src/cli.ts</code>.</li>
<li>Project scaffolding: <code>src/projects.ts</code>, <code>src/config.ts</code>, <code>src/engines.ts</code>, <code>src/agents.ts</code>, <code>src/paths.ts</code>, and <code>engine_configs/**</code>.</li>
<li>Codex prompt and workflow surfaces: <code>src/roles.ts</code>, <code>src/codex-session.ts</code>, <code>src/codex-prompts.ts</code>, <code>src/workflows.ts</code>, <code>src/templates.ts</code>, and <code>templates/**</code>.</li>
<li>Runtime/task execution: <code>src/runner.ts</code>, <code>src/tasks.ts</code>, <code>src/codex-runtime.ts</code>, and <code>src/verification.ts</code>.</li>
<li>Validation: <code>src/validation.ts</code> plus the package metadata and smoke checks it verifies.</li>
<li>Architecture flow guides: <code>docs/architecture/flows/**</code> explain important runtime scenarios, branch logic, and failure paths by linking back to bounded truth docs.</li>
</ul>
<h3>Boundaries</h3>
<p>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.</p>
<h3>Current Structure</h3>
<ul>
<li><code>src/cli.ts</code> owns the public CLI command wiring.</li>
<li><code>src/projects.ts</code>, <code>src/config.ts</code>, <code>src/engines.ts</code>, <code>src/agents.ts</code>, and <code>src/paths.ts</code> own project scaffolding and generated project surfaces.</li>
<li><code>src/roles.ts</code>, <code>src/codex-session.ts</code>, <code>src/codex-prompts.ts</code>, <code>src/workflows.ts</code>, and <code>src/templates.ts</code> own Codex role, prompt, workflow, and template surfaces.</li>
<li><code>src/runner.ts</code>, <code>src/tasks.ts</code>, <code>src/codex-runtime.ts</code>, and <code>src/verification.ts</code> own Codex execution, task persistence, runtime checks, and verification processes.</li>
<li><code>src/validation.ts</code> owns repository and generated-project validation checks.</li>
<li><code>engine_configs/<strong></code> and <code>templates/</strong></code> are package runtime assets.</li>
<li><code>tests/**</code> mirrors those behavior boundaries with Vitest coverage.</li>
<li><code>docs/architecture/flows/**</code> contains Markdown runtime views for project initialization, role runs, workflow prompt rendering, and validation/repository-truth workflows.</li>
</ul>
<h3>Product Decisions</h3>
<ul>
<li>Decision (2026-05-28): Route truth by behavior ownership rather than by mechanically mirroring every source file.</li>
<li>Decision (2026-05-30): Use Markdown Architecture Flow Guides as arc42-style runtime views for detailed branching/walkthrough documentation; keep bounded Truthmark truth docs as the canonical behavior reference layer.</li>
</ul>
<h3>Rationale</h3>
<p>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.</p>
<h3>Maintenance Notes</h3>
<p>Update this architecture note when source modules move across the behavior boundaries in <code>docs/truthmark/areas/repository.md</code>. Update <code>docs/architecture/flows/**</code> when an architecturally relevant runtime scenario, branch, or failure path changes.</p></section><section class="doc"><h2>Architecture Flow Guides</h2><p><span class="badge">docs/architecture/flows/README.md</span></p><h2>Architecture Flow Guides</h2>
<h3>Purpose</h3>
<p>These Architecture Flow Guides document Open GameStudio&#x27;s important runtime scenarios, branching logic, failure paths, and code/truth-doc traceability. They are Markdown docs-as-code runtime views: readable in GitHub/VS Code, reviewable in pull requests, and detailed enough to guide humans and agents through the system.</p>
<h3>Professional Framing</h3>
<p>This folder uses established software-architecture documentation patterns:</p>
<ul>
<li><strong>arc42 Runtime View</strong>: documents concrete behavior, interactions between building blocks, important scenarios, operational flows, and error/exception scenarios.</li>
<li><strong>C4 dynamic views</strong>: describe how architecture elements interact at runtime when a static structure view is not enough.</li>
<li><strong>Diátaxis explanation/how-to separation</strong>: these guides explain and navigate flows; Truthmark truth docs remain the canonical reference layer.</li>
<li><strong>Mermaid in Markdown</strong>: sequence and flowchart diagrams are embedded directly in Markdown so the diagrams stay close to the walkthrough text.</li>
</ul>
<h3>Relationship To Truthmark Truth Docs</h3>
<p>Truthmark truth docs own canonical behavior claims. Architecture flow guides own comprehension.</p>
<table><thead><tr><th>Layer</th><th>Purpose</th><th>Example</th></tr></thead><tbody>
<tr><td>Truth docs</td><td>Bounded, canonical behavior/reference claims</td><td><code>docs/truth/codex/runtime-and-tasks.md</code></td></tr>
<tr><td>Flow guides</td><td>Cross-cutting runtime scenarios, branches, and debugging paths</td><td><code>docs/architecture/flows/role-run-lifecycle.md</code></td></tr>
<tr><td>Portal</td><td>Generated non-canonical presentation</td><td><code>docs/truthmark-portal/</code></td></tr>
</tbody></table>
<p>If a flow guide conflicts with source code or a truth doc, the source code and owning truth doc win. Update the owning truth doc first, then update the affected flow guide.</p>
<h3>Flow Index</h3>
<table><thead><tr><th>Flow guide</th><th>Scenario</th><th>Primary truth docs</th></tr></thead><tbody>
<tr><td><a href="../architecture/flows/project-initialization.md">Project Initialization</a></td><td><code>init</code> / <code>new</code> creates a deterministic generated game project.</td><td><code>docs/truth/projects/project-scaffolding.md</code></td></tr>
<tr><td><a href="../architecture/flows/role-run-lifecycle.md">Role Run Lifecycle</a></td><td><code>run &lt;role&gt;</code> renders, executes, verifies, reviews, and optionally fixes a Codex role run.</td><td><code>docs/truth/codex/runtime-and-tasks.md</code>, <code>docs/truth/codex/roles-and-workflows.md</code></td></tr>
<tr><td><a href="../architecture/flows/workflow-prompt-rendering.md">Workflow Prompt Rendering</a></td><td>Workflow shortcut commands render deterministic prompts without executing Codex.</td><td><code>docs/truth/codex/roles-and-workflows.md</code></td></tr>
<tr><td><a href="../architecture/flows/validation-and-repository-truth.md">Validation And Repository Truth</a></td><td>Repository/project validation and injected Truthmark repository-truth workflows around behavior changes.</td><td><code>docs/truth/contracts/cli-and-validation.md</code>, <code>docs/truth/repository/overview.md</code></td></tr>
</tbody></table>
<h3>Guide Template</h3>
<p>Each flow guide should include:</p>
<ol>
<li>Purpose and scenario boundary.</li>
<li>Entry points.</li>
<li>Preconditions and inputs.</li>
<li>Happy path sequence.</li>
<li>Branch map.</li>
<li>Decision table.</li>
<li>Failure modes and debugging cues.</li>
<li>Code traceability.</li>
<li>Truth sources and verification.</li>
</ol>
<h3>Maintenance Rules</h3>
<ul>
<li>Keep these guides focused on architecturally relevant scenarios, not every internal helper call.</li>
<li>Do not use flow guides to introduce new behavior claims that are absent from source and truth docs.</li>
<li>When behavior changes, update the owning truth doc and then any impacted flow guide.</li>
<li>Keep Truthmark framed as an injected repository-truth workflow/tooling layer unless product code explicitly implements Truthmark-facing runtime behavior.</li>
</ul></section><section class="doc"><h2>Project Initialization Flow Guide</h2><p><span class="badge">docs/architecture/flows/project-initialization.md</span></p><h2>Project Initialization Flow Guide</h2>
<h3>Purpose</h3>
<p>This architecture flow guide documents the runtime scenario for <code>open-gamestudio init</code> and <code>open-gamestudio new</code>. Both commands use the same initialization path to create a deterministic Codex Game Studio project under <code>projects/&lt;slug&gt;/</code>.</p>
<h3>Scope</h3>
<p>This flow starts when a user invokes <code>init</code> or <code>new</code> with required project options. It ends when the generated project has engine markers, <code>.codex</code> state, workflow prompts, starter docs, role prompts, and project-level <code>AGENTS.md</code>.</p>
<p>This flow does <strong>not</strong> execute Codex and does <strong>not</strong> own task lifecycle persistence after project creation.</p>
<h3>Boundaries</h3>
<p>Project initialization owns generated project creation and initial <code>.codex</code> state. Codex run execution, task lifecycle persistence, and verification/review behavior are owned by separate runtime flows and truth docs.</p>
<h3>Entry Points</h3>
<table><thead><tr><th>Entry point</th><th>Role in flow</th><th>Code</th></tr></thead><tbody>
<tr><td><code>open-gamestudio init</code></td><td>Primary project initialization command.</td><td><code>src/cli.ts</code></td></tr>
<tr><td><code>open-gamestudio new</code></td><td>Alias that delegates to the same initialization path.</td><td><code>src/cli.ts</code></td></tr>
<tr><td><code>initProject(...)</code></td><td>Creates project config, directories, state, docs, workflows, and prompts.</td><td><code>src/projects.ts</code></td></tr>
</tbody></table>
<h3>Preconditions</h3>
<ul>
<li>The user supplies <code>--name</code>, <code>--engine</code>, <code>--mode</code>, and <code>--non-interactive</code>.</li>
<li>The selected engine is known by the engine registry.</li>
<li>The target <code>projects/&lt;slug&gt;/</code> path does not already exist.</li>
<li>Same-parent project slug and Unreal class-name collision checks pass.</li>
</ul>
<h3>Inputs</h3>
<table><thead><tr><th>Input</th><th>Source</th><th>Required</th><th>Notes</th></tr></thead><tbody>
<tr><td>Project name</td><td><code>--name</code></td><td>yes</td><td>Used for config and slug derivation.</td></tr>
<tr><td>Engine</td><td><code>--engine</code></td><td>yes</td><td>Must resolve to a supported engine registry entry.</td></tr>
<tr><td>Mode</td><td><code>--mode</code></td><td>yes</td><td>Selects active project/studio mode.</td></tr>
<tr><td>Non-interactive flag</td><td><code>--non-interactive</code></td><td>yes</td><td>Enforces deterministic scaffolding.</td></tr>
<tr><td>Concept/genre/platform/audience/etc.</td><td>Optional CLI flags</td><td>no</td><td>Written into starter planning artifacts where applicable.</td></tr>
<tr><td>Engine version override</td><td><code>--engine-version</code></td><td>no</td><td>Overrides default engine context.</td></tr>
</tbody></table>
<h3>Happy Path Sequence</h3>
<pre><code class="language-mermaid">
sequenceDiagram
actor User
participant CLI as src/cli.ts
participant Projects as src/projects.ts
participant Config as src/config.ts
participant Engines as src/engines.ts
participant Agents as src/agents.ts
participant FS as Project files
User-&gt;&gt;CLI: init/new --name --engine --mode --non-interactive
CLI-&gt;&gt;Projects: initProject(options)
Projects-&gt;&gt;Config: normalize project config and slug
Projects-&gt;&gt;Projects: reject target/collision conflicts
Projects-&gt;&gt;Engines: resolve engine scaffold
Projects-&gt;&gt;FS: create project and engine folders
Projects-&gt;&gt;FS: write .codex/studio.json and .codex/runs/
Projects-&gt;&gt;FS: write workflow prompt files and starter docs
Projects-&gt;&gt;Agents: render generated project AGENTS.md and role prompts
Projects--&gt;&gt;CLI: project root and config
CLI--&gt;&gt;User: Created &lt;name&gt; at &lt;path&gt;
</code></pre>
<h3>Branch Map</h3>
<pre><code class="language-mermaid">
flowchart TD
A[User runs init or new] --&gt; B{Required options present?}
B -- no --&gt; B1[Commander reports missing required option]
B -- yes --&gt; C{--non-interactive present?}
C -- no --&gt; C1[Fail: deterministic non-interactive mode required]
C -- yes --&gt; D[Normalize config and derive slug]
D --&gt; E{Engine known?}
E -- no --&gt; E1[Fail: invalid engine]
E -- yes --&gt; F{Target or same-parent collision?}
F -- yes --&gt; F1[Fail before writing project files]
F -- no --&gt; G{Unreal class-name collision?}
G -- yes --&gt; G1[Fail before writing project files]
G -- no --&gt; H[Create engine/project folders]
H --&gt; I[Write .codex state and run directory]
I --&gt; J[Write workflows, starter docs, AGENTS.md, role prompts]
J --&gt; K[Return created project path]
</code></pre>
<h3>Decision Table</h3>
<table><thead><tr><th>Condition</th><th>Branch</th><th>Behavior</th><th>User-visible result</th><th>Owning code/truth</th></tr></thead><tbody>
<tr><td>Required option missing</td><td>CLI parse failure</td><td>Stop before initialization.</td><td>Commander error.</td><td><code>src/cli.ts</code>; <code>docs/truth/contracts/cli-and-validation.md</code></td></tr>
<tr><td><code>--non-interactive</code> missing</td><td>Determinism guard</td><td>Stop before writing.</td><td>Required option error.</td><td><code>src/cli.ts</code>; <code>docs/truth/projects/project-scaffolding.md</code></td></tr>
<tr><td>Engine is unknown</td><td>Engine registry guard</td><td>Stop before writing.</td><td>Invalid engine/lookup failure.</td><td><code>src/engines.ts</code>; <code>docs/truth/projects/project-scaffolding.md</code></td></tr>
<tr><td>Target path exists</td><td>Collision guard</td><td>Stop before mutating target.</td><td>Existing project/path error.</td><td><code>src/projects.ts</code>; <code>docs/truth/projects/project-scaffolding.md</code></td></tr>
<tr><td>Collision checks pass</td><td>Happy path</td><td>Write generated project surfaces.</td><td><code>Created &lt;name&gt; at &lt;path&gt;</code>.</td><td><code>src/projects.ts</code>; <code>docs/truth/projects/project-scaffolding.md</code></td></tr>
</tbody></table>
<h3>Generated Outputs</h3>
<p>The successful flow creates or writes:</p>
<ul>
<li><code>projects/&lt;slug&gt;/</code></li>
<li><code>.codex/studio.json</code></li>
<li><code>.codex/runs/</code></li>
<li><code>.codex/workflows/*.md</code></li>
<li>starter design/production/market documents</li>
<li>engine-specific marker files and source folders</li>
<li>project-level <code>AGENTS.md</code></li>
<li>role prompt files for the canonical studio role roster</li>
</ul>
<p>Forbidden generated project surfaces remain forbidden: <code>CODEX.md</code>, <code>project_orchestrator.md</code>, and <code>.gamestudio/runs</code>.</p>
<h3>Failure Modes And Debugging Cues</h3>
<table><thead><tr><th>Failure</th><th>Likely cause</th><th>Inspect</th></tr></thead><tbody>
<tr><td>Required-option failure</td><td>CLI command missing required flags.</td><td><code>src/cli.ts</code> command definitions.</td></tr>
<tr><td>Invalid engine</td><td>Engine value not recognized or engine registry changed.</td><td><code>src/engines.ts</code>, <code>engine_configs/**</code>.</td></tr>
<tr><td>Target collision</td><td><code>projects/&lt;slug&gt;/</code> already exists.</td><td>Project directory and slug derivation in <code>src/projects.ts</code>.</td></tr>
<tr><td>Generated file missing in validation</td><td>Scaffolding contract drift.</td><td><code>src/projects.ts</code>, <code>src/agents.ts</code>, <code>src/validation.ts</code>.</td></tr>
</tbody></table>
<h3>Code Traceability</h3>
<table><thead><tr><th>Behavior</th><th>Code</th></tr></thead><tbody>
<tr><td>Command wiring and required options</td><td><code>src/cli.ts</code></td></tr>
<tr><td>Project creation and collision checks</td><td><code>src/projects.ts</code></td></tr>
<tr><td>Config normalization</td><td><code>src/config.ts</code></td></tr>
<tr><td>Engine-specific scaffold</td><td><code>src/engines.ts</code>, <code>engine_configs/**</code></td></tr>
<tr><td>Generated project instruction surface</td><td><code>src/agents.ts</code></td></tr>
<tr><td>Path/slug helpers</td><td><code>src/paths.ts</code></td></tr>
<tr><td>Project validation checks</td><td><code>src/validation.ts</code></td></tr>
</tbody></table>
<h3>Product Decisions</h3>
<ul>
<li>Project creation remains deterministic and non-interactive for reproducible Codex project setup.</li>
<li>Generated project instructions use Codex-native <code>AGENTS.md</code>; this flow does not introduce <code>CODEX.md</code> as a primary project instruction contract.</li>
</ul>
<h3>Rationale</h3>
<p>A bounded initialization flow gives users and agents a stable project scaffold without implying that scaffolding also executes Codex, manages planner state, or owns later runtime task transitions.</p>
<h3>Truth Sources</h3>
<ul>
<li><code>docs/truth/projects/project-scaffolding.md</code></li>
<li><code>docs/truth/repository/overview.md</code></li>
<li><code>docs/truth/contracts/cli-and-validation.md</code></li>
<li><code>docs/truthmark/areas/repository.md</code></li>
</ul>
<h3>Verification</h3>
<p>For behavior changes in this flow, run the relevant project workflow, agent/template, engine-system, and validation tests. For repository-wide readiness claims, run:</p>
<pre><code class="language-bash">
npm run validate
npx truthmark check --json
</code></pre></section><section class="doc"><h2>Role Run Lifecycle Flow Guide</h2><p><span class="badge">docs/architecture/flows/role-run-lifecycle.md</span></p><h2>Role Run Lifecycle Flow Guide</h2>
<h3>Purpose</h3>
<p>This architecture flow guide documents the runtime scenario for <code>open-gamestudio run &lt;role&gt;</code>. The flow prepares a deterministic Codex prompt, optionally returns inspection output, and otherwise executes a bounded implementation/verification/review/fix lifecycle.</p>
<h3>Scope</h3>
<p>This flow starts when a user invokes <code>run &lt;role&gt; ... --project &lt;path&gt;</code>. It ends when the CLI reports <code>done</code> or <code>blocked</code>, or when an inspection-only branch returns prompt/dry-run output without side effects.</p>
<p>This flow consumes role/workflow prompt contracts but does not own the content of each role package.</p>
<h3>Boundaries</h3>
<p>The role run lifecycle owns runtime preparation, prompt inspection branches, Codex availability checks, implementation execution, optional verification, review, and bounded fix passes. Role definitions, generated workflow prompt contents, and project scaffolding are owned by adjacent truth docs and flows.</p>
<h3>Entry Points</h3>
<table><thead><tr><th>Entry point</th><th>Role in flow</th><th>Code</th></tr></thead><tbody>
<tr><td><code>open-gamestudio run &lt;role&gt;</code></td><td>Public CLI command for role execution.</td><td><code>src/cli.ts</code></td></tr>
<tr><td><code>prepareRun(...)</code></td><td>Resolves project, validates role/task input, renders prompt, builds cache paths and Codex command.</td><td><code>src/runner.ts</code></td></tr>
<tr><td><code>checkCodexAvailability(...)</code></td><td>Confirms Codex can be executed before non-dry runs.</td><td><code>src/codex-runtime.ts</code></td></tr>
<tr><td><code>executeRunLifecycle(...)</code></td><td>Runs implementation, verification, review, and bounded fix passes.</td><td><code>src/runner.ts</code></td></tr>
</tbody></table>
<h3>Preconditions</h3>
<ul>
<li><code>--project &lt;path&gt;</code> points to a valid generated project with <code>.codex/studio.json</code>.</li>
<li>The requested role is a canonical studio role ID.</li>
<li>The task/objective is non-empty, either from positional objective text or <code>--task</code>.</li>
<li>Codex availability is required only for non-dry, non-print execution.</li>
</ul>
<h3>Inputs</h3>
<table><thead><tr><th>Input</th><th>Source</th><th>Required</th><th>Notes</th></tr></thead><tbody>
<tr><td>Role ID</td><td>positional <code>&lt;role&gt;</code></td><td>yes</td><td>Must be a canonical hyphenated studio role ID.</td></tr>
<tr><td>Objective/task</td><td>positional objective or <code>--task</code></td><td>yes</td><td>Drives prompt body.</td></tr>
<tr><td>Project path</td><td><code>--project</code></td><td>yes</td><td>Resolves <code>.codex/studio.json</code>.</td></tr>
<tr><td>Included artifacts</td><td><code>--include-artifact</code></td><td>no</td><td>Adds explicit project artifacts to context.</td></tr>
<tr><td>Broad context flag</td><td><code>--allow-broad-context</code></td><td>no</td><td>Allows broader context discovery.</td></tr>
<tr><td>Verification command</td><td><code>--verify-command</code>, <code>--verify-arg</code></td><td>no</td><td>Runs after implementation when configured.</td></tr>
<tr><td>Review flag</td><td><code>--review</code></td><td>no</td><td>Adds read-only review pass.</td></tr>
<tr><td>Fix flag/count</td><td><code>--fix</code>, <code>--max-fix-passes</code></td><td>no</td><td>Enables bounded fix passes when blocked.</td></tr>
<tr><td>Inspection flags</td><td><code>--print-prompt</code>, <code>--dry-run</code></td><td>no</td><td>Non-mutating inspection branches.</td></tr>
</tbody></table>
<h3>Happy Path Sequence</h3>
<pre><code class="language-mermaid">
sequenceDiagram
actor User
participant CLI as src/cli.ts
participant Runner as src/runner.ts
participant Prompts as Prompt rendering
participant Runtime as src/codex-runtime.ts
participant Verification as src/verification.ts
participant FS as .codex/runs
User-&gt;&gt;CLI: run &lt;role&gt; objective --project &lt;path&gt;
CLI-&gt;&gt;Runner: prepareRun(role, options)
Runner-&gt;&gt;Prompts: render role/session prompt
Prompts--&gt;&gt;Runner: prompt, context files, command
Runner--&gt;&gt;CLI: prepared output and Codex command
CLI-&gt;&gt;Runtime: checkCodexAvailability(command)
Runtime--&gt;&gt;CLI: available
CLI-&gt;&gt;Runner: executeRunLifecycle(prepared)
Runner-&gt;&gt;FS: write prompt and metadata cache
Runner-&gt;&gt;Runtime: execute implementation prompt
Runtime--&gt;&gt;Runner: implementation result
Runner-&gt;&gt;Verification: run verification when configured
Verification--&gt;&gt;Runner: verification result
Runner--&gt;&gt;CLI: final status done or blocked
CLI--&gt;&gt;User: lifecycle summary
</code></pre>
<h3>Branch Map</h3>
<pre><code class="language-mermaid">
flowchart TD
A[run role command] --&gt; B{Project valid?}
B -- no --&gt; B1[Fail before prompt execution]
B -- yes --&gt; C{Role valid?}
C -- no --&gt; C1[Unknown role error with canonical role IDs]
C -- yes --&gt; D{Task/objective non-empty?}
D -- no --&gt; D1[Fail before prompt execution]
D -- yes --&gt; E[Render deterministic prompt and context]
E --&gt; F{--print-prompt?}
F -- yes --&gt; F1[Print prompt only; no mutation]
F -- no --&gt; G{--dry-run?}
G -- yes --&gt; G1[Print context and command only; no mutation]
G -- no --&gt; H{Codex available?}
H -- no --&gt; H1[Report Codex unavailable; exit non-zero]
H -- yes --&gt; I[Write prompt and metadata cache]
I --&gt; J[Execute implementation prompt]
J --&gt; K{Implementation succeeded?}
K -- no --&gt; K1[Blocked]
K -- yes --&gt; L{Verification configured?}
L -- yes --&gt; M[Run verification]
L -- no --&gt; N{Review requested?}
M --&gt; M1{Verification passed?}
M1 -- no --&gt; O[Blocked]
M1 -- yes --&gt; N
N -- yes --&gt; P[Run read-only review]
N -- no --&gt; R[Done]
P --&gt; Q{Review blockers?}
Q -- no --&gt; R
Q -- yes --&gt; S{Fix requested and passes remain?}
S -- no --&gt; O
S -- yes --&gt; T[Run workspace-write fix pass]
T --&gt; L
</code></pre>
<h3>Decision Table</h3>
<table><thead><tr><th>Condition</th><th>Branch</th><th>Behavior</th><th>User-visible result</th><th>Side effects</th></tr></thead><tbody>
<tr><td>Invalid project</td><td>Project resolution failure</td><td>Stop before execution.</td><td>Error from project/task resolution.</td><td>No run cache.</td></tr>
<tr><td>Unknown role</td><td>Role validation failure</td><td>Stop before execution.</td><td>Message points to canonical role IDs.</td><td>No run cache.</td></tr>
<tr><td><code>--print-prompt</code></td><td>Prompt inspection</td><td>Render and print prompt body.</td><td>Prompt text.</td><td>No prompt cache, metadata, task state, or run directory writes.</td></tr>
<tr><td><code>--dry-run</code></td><td>Command/context inspection</td><td>Print selected context and Codex command.</td><td>Dry-run summary.</td><td>No prompt cache, metadata, task state, or run directory writes.</td></tr>
<tr><td>Codex unavailable</td><td>Runtime guard</td><td>Stop before lifecycle execution.</td><td>Availability/authentication error.</td><td>No lifecycle execution.</td></tr>
<tr><td>Verification fails</td><td>Verification blocker</td><td>Mark lifecycle blocked unless fix passes clear it.</td><td>Final status <code>blocked</code>.</td><td>Non-dry cache already written.</td></tr>
<tr><td>Review blockers found</td><td>Review blocker</td><td>Run bounded fix passes only when requested and available.</td><td><code>blocked</code> or subsequent <code>done</code>.</td><td>Review uses read-only sandbox; fix uses workspace-write sandbox.</td></tr>
<tr><td>All required passes clear</td><td>Happy path</td><td>Report completion.</td><td>Final status <code>done</code>.</td><td>Non-dry run cache exists.</td></tr>
</tbody></table>
<h3>State And Mutation Rules</h3>
<ul>
<li><code>--print-prompt</code> and <code>--dry-run</code> are inspection-only and do not write prompt cache, metadata, task state, or run directories.</li>
<li>Non-dry runs write prompt and metadata before executing Codex.</li>
<li>Implementation and fix passes use a workspace-write Codex sandbox.</li>
<li>Review passes use a read-only Codex sandbox.</li>
<li>Final lifecycle status is <code>done</code> or <code>blocked</code>.</li>
</ul>
<h3>Failure Modes And Debugging Cues</h3>
<table><thead><tr><th>Failure</th><th>Likely cause</th><th>Inspect</th></tr></thead><tbody>
<tr><td>Unknown role</td><td>Role ID typo or role registry drift.</td><td><code>src/roles.ts</code>, <code>docs/truth/codex/roles-and-workflows.md</code>.</td></tr>
<tr><td>Empty objective</td><td>User omitted objective and <code>--task</code>.</td><td><code>src/cli.ts</code>, <code>src/runner.ts</code>.</td></tr>
<tr><td>Codex unavailable</td><td>CLI missing, unauthenticated, or command path invalid.</td><td><code>src/codex-runtime.ts</code>.</td></tr>
<tr><td>Verification timeout/failure</td><td>Verification command failed or exceeded timeout.</td><td><code>src/verification.ts</code>, command output.</td></tr>
<tr><td>Malformed review JSON</td><td>Review pass did not produce expected schema.</td><td><code>src/runner.ts</code>, review prompt contract.</td></tr>
<tr><td>Repeated blocked status</td><td>Implementation, verification, or review blockers not cleared by bounded fix passes.</td><td>Run lifecycle output and <code>.codex/runs/</code> metadata.</td></tr>
</tbody></table>
<h3>Code Traceability</h3>
<table><thead><tr><th>Behavior</th><th>Code</th></tr></thead><tbody>
<tr><td>CLI option parsing and inspection branch exit</td><td><code>src/cli.ts</code></td></tr>
<tr><td>Run preparation, prompt/cache metadata, lifecycle orchestration</td><td><code>src/runner.ts</code></td></tr>
<tr><td>Role IDs and unknown-role message</td><td><code>src/roles.ts</code></td></tr>
<tr><td>Prompt/session rendering inputs</td><td><code>src/codex-session.ts</code>, <code>src/codex-prompts.ts</code></td></tr>
<tr><td>Codex availability and command execution</td><td><code>src/codex-runtime.ts</code></td></tr>
<tr><td>Verification command execution and timeout behavior</td><td><code>src/verification.ts</code></td></tr>
<tr><td>File-backed task mutation when running tasks</td><td><code>src/tasks.ts</code></td></tr>
</tbody></table>
<h3>Product Decisions</h3>
<ul>
<li><code>--print-prompt</code> and <code>--dry-run</code> stay inspection-only and do not mutate run state.</li>
<li>Non-dry role runs explicitly execute Codex and report a final <code>done</code> or <code>blocked</code> status.</li>
<li>Review is read-only; fix passes are bounded and workspace-write.</li>
</ul>
<h3>Rationale</h3>
<p>Separating inspection, implementation, verification, review, and fix branches makes the Codex lifecycle auditable without inventing hidden planner, telemetry, ownership enforcement, or parallel orchestration behavior.</p>
<h3>Truth Sources</h3>
<ul>
<li><code>docs/truth/codex/runtime-and-tasks.md</code></li>
<li><code>docs/truth/codex/roles-and-workflows.md</code></li>
<li><code>docs/truth/contracts/cli-and-validation.md</code></li>
<li><code>docs/truthmark/areas/repository.md</code></li>
</ul>
<h3>Verification</h3>
<p>For behavior changes in this flow, run runner, task, verification, Codex runtime, role, and prompt/session tests as relevant. For repository-wide readiness claims, run:</p>
<pre><code class="language-bash">
npm run validate
npx truthmark check --json
</code></pre></section><section class="doc"><h2>Workflow Prompt Rendering Flow Guide</h2><p><span class="badge">docs/architecture/flows/workflow-prompt-rendering.md</span></p><h2>Workflow Prompt Rendering Flow Guide</h2>
<h3>Purpose</h3>
<p>This architecture flow guide documents render-only workflow shortcut commands such as <code>market</code>, <code>analytics</code>, <code>design-spec</code>, <code>feel-review</code>, <code>art-direction</code>, <code>ui-review</code>, <code>milestone</code>, <code>handoff</code>, <code>review</code>, and <code>ship-check</code>.</p>
<p>These commands produce deterministic Codex prompts for workflow scenarios without launching Codex or implying hidden orchestration.</p>
<h3>Scope</h3>
<p>This flow starts when a user invokes a workflow shortcut with <code>--project &lt;path&gt;</code>. It ends when the CLI prints the rendered workflow prompt.</p>
<p>This flow does <strong>not</strong> execute Codex, does <strong>not</strong> write run cache metadata, and does <strong>not</strong> create a planner/next queue.</p>
<h3>Boundaries</h3>
<p>Workflow prompt rendering owns deterministic prompt text for workflow shortcut commands. It does not own Codex runtime execution, task status mutation, generated project scaffolding, or future-only planner/telemetry/orchestration surfaces.</p>
<h3>Entry Points</h3>
<table><thead><tr><th>Entry point</th><th>Role in flow</th><th>Code</th></tr></thead><tbody>
<tr><td>Workflow CLI aliases</td><td>Public render-only commands for selected workflow IDs.</td><td><code>src/cli.ts</code>, <code>src/workflows.ts</code></td></tr>
<tr><td><code>review</code> and <code>ship-check</code> commands</td><td>Render prompts for explicit workflow IDs without requiring a role run.</td><td><code>src/cli.ts</code></td></tr>
<tr><td><code>renderWorkflowPrompt(...)</code></td><td>Resolves project state and renders workflow prompt content.</td><td><code>src/workflows.ts</code></td></tr>
<tr><td>Template registry</td><td>Supplies optional template bodies when a workflow needs them.</td><td><code>src/templates.ts</code>, <code>templates/**</code></td></tr>
</tbody></table>
<h3>Preconditions</h3>
<ul>
<li><code>--project &lt;path&gt;</code> resolves to a valid generated project.</li>
<li><code>.codex/studio.json</code> contains engine/project context required by the workflow prompt.</li>
<li>The requested workflow ID or alias exists in the workflow registry.</li>
<li>Any required template body is present and valid.</li>
</ul>
<h3>Inputs</h3>
<table><thead><tr><th>Input</th><th>Source</th><th>Required</th><th>Notes</th></tr></thead><tbody>
<tr><td>Workflow alias/ID</td><td>CLI command</td><td>yes</td><td>Maps to a workflow registry entry.</td></tr>
<tr><td>Project path</td><td><code>--project</code></td><td>yes</td><td>Provides project and engine context.</td></tr>
<tr><td>Dry-run flag</td><td><code>--dry-run</code></td><td>no</td><td>Accepted as render-only wording; command already does not launch Codex.</td></tr>
<tr><td>Template bodies</td><td>package assets</td><td>no/conditional</td><td>Appended when selected by workflow/template rules.</td></tr>
</tbody></table>
<h3>Happy Path Sequence</h3>
<pre><code class="language-mermaid">
sequenceDiagram
actor User
participant CLI as src/cli.ts
participant Tasks as src/tasks.ts
participant Workflows as src/workflows.ts
participant Templates as src/templates.ts
participant FS as Project/package files
User-&gt;&gt;CLI: workflow-alias --project &lt;path&gt;
CLI-&gt;&gt;Tasks: resolveTaskProject(project)
Tasks--&gt;&gt;CLI: project root
CLI-&gt;&gt;Workflows: renderWorkflowPrompt(projectRoot, workflowId)
Workflows-&gt;&gt;FS: read .codex/studio.json
Workflows-&gt;&gt;Workflows: look up workflow registry entry
Workflows-&gt;&gt;Templates: select/read applicable template bodies
Templates--&gt;&gt;Workflows: template content
Workflows--&gt;&gt;CLI: rendered prompt
CLI--&gt;&gt;User: prompt text
</code></pre>
<h3>Branch Map</h3>
<pre><code class="language-mermaid">
flowchart TD
A[User runs workflow shortcut] --&gt; B{Project path valid?}
B -- no --&gt; B1[Fail before rendering]
B -- yes --&gt; C[Read project state]
C --&gt; D{Workflow alias/ID exists?}
D -- no --&gt; D1[Unknown workflow/command path]
D -- yes --&gt; E[Create workflow session context]
E --&gt; F{Templates required or applicable?}
F -- no --&gt; G[Render base workflow prompt]
F -- yes --&gt; H{Template bodies valid?}
H -- no --&gt; H1[Fail validation/rendering]
H -- yes --&gt; I[Append template bodies]
G --&gt; J[Print prompt only]
I --&gt; J
</code></pre>
<h3>Decision Table</h3>
<table><thead><tr><th>Condition</th><th>Branch</th><th>Behavior</th><th>User-visible result</th><th>Side effects</th></tr></thead><tbody>
<tr><td>Project invalid</td><td>Project resolution failure</td><td>Stop before rendering.</td><td>Error from project resolution.</td><td>None.</td></tr>
<tr><td>Workflow command exists</td><td>Happy path</td><td>Render workflow prompt for configured workflow ID.</td><td>Prompt text.</td><td>None.</td></tr>
<tr><td>Applicable template exists</td><td>Template append branch</td><td>Add template content to prompt.</td><td>Prompt text includes template body.</td><td>None.</td></tr>
<tr><td>Template invalid/missing</td><td>Template validation/render failure</td><td>Stop or fail validation depending on call path.</td><td>Error or validation failure.</td><td>None.</td></tr>
<tr><td>User expects execution</td><td>Non-goal branch</td><td>Command still only renders prompt.</td><td>Prompt text only.</td><td>Codex is not launched.</td></tr>
</tbody></table>
<h3>Render-Only Rules</h3>
<ul>
<li>Workflow shortcut commands render prompts and return text.</li>
<li>They do not call Codex.</li>
<li>They do not write <code>.codex/runs/</code> cache files.</li>
<li>They do not mutate <code>.codex/studio.json</code> or <code>.codex/tasks.json</code>.</li>
<li>They do not expose hidden planner, telemetry, ownership enforcement, or parallel orchestration behavior.</li>
</ul>
<h3>Failure Modes And Debugging Cues</h3>
<table><thead><tr><th>Failure</th><th>Likely cause</th><th>Inspect</th></tr></thead><tbody>
<tr><td>Project resolution failure</td><td>Missing or invalid <code>.codex/studio.json</code>.</td><td><code>src/tasks.ts</code>, generated project state.</td></tr>
<tr><td>Alias drift</td><td>CLI alias and workflow registry diverged.</td><td><code>src/cli.ts</code>, <code>src/workflows.ts</code>.</td></tr>
<tr><td>Missing template content</td><td>Package asset drift or template registry error.</td><td><code>src/templates.ts</code>, <code>templates/**</code>, package files.</td></tr>
<tr><td>Prompt claim overstates automation</td><td>Documentation or prompt text implies unimplemented planner/execution behavior.</td><td><code>src/workflows.ts</code>, <code>docs/truth/codex/roles-and-workflows.md</code>.</td></tr>
</tbody></table>
<h3>Code Traceability</h3>
<table><thead><tr><th>Behavior</th><th>Code</th></tr></thead><tbody>
<tr><td>Workflow command registration</td><td><code>src/cli.ts</code></td></tr>
<tr><td>Workflow registry and prompt rendering</td><td><code>src/workflows.ts</code></td></tr>
<tr><td>Project path validation used by workflow commands</td><td><code>src/tasks.ts</code></td></tr>
<tr><td>Template lookup, rendering, and required-section validation</td><td><code>src/templates.ts</code>, <code>templates/**</code></td></tr>
<tr><td>Validation of workflow/prompt contracts</td><td><code>src/validation.ts</code></td></tr>
</tbody></table>
<h3>Product Decisions</h3>
<ul>
<li>Workflow shortcut commands remain render-only prompt surfaces.</li>
<li>Prompt rendering may include templates, but it must not imply unimplemented planner, execution, telemetry, or ownership-enforcement behavior.</li>
</ul>
<h3>Rationale</h3>
<p>Keeping workflow commands render-only lets users inspect and hand off workflow prompts while avoiding hidden side effects or undocumented automation.</p>
<h3>Truth Sources</h3>
<ul>
<li><code>docs/truth/codex/roles-and-workflows.md</code></li>
<li><code>docs/truth/contracts/cli-and-validation.md</code></li>
<li><code>docs/truth/repository/overview.md</code></li>
<li><code>docs/truthmark/areas/repository.md</code></li>
</ul>
<h3>Verification</h3>
<p>For behavior changes in this flow, run workflow, template, Codex prompt/session, and validation tests as relevant. For repository-wide readiness claims, run:</p>
<pre><code class="language-bash">
npm run validate
npx truthmark check --json
</code></pre></section><section class="doc"><h2>Validation And Repository Truth Flow Guide</h2><p><span class="badge">docs/architecture/flows/validation-and-repository-truth.md</span></p><h2>Validation And Repository Truth Flow Guide</h2>
<h3>Purpose</h3>
<p>This architecture flow guide documents the validation path around Open GameStudio behavior changes and the injected Truthmark repository-truth workflow around documentation/routing updates.</p>
<p>Validation is an Open GameStudio CLI/package behavior. Truthmark is an injected repository-truth workflow/tooling layer for documentation authority, routing, and agent workflow surfaces; it is not an Open GameStudio runtime feature unless product code explicitly implements Truthmark-facing behavior.</p>
<h3>Scope</h3>
<p>This guide covers two related but separate flows:</p>
<ol>
<li><code>open-gamestudio validate</code> / <code>npm run validate</code> checks package and generated-project contracts.</li>
<li><code>npx truthmark check --json</code> checks repository-truth routing and generated Truthmark surfaces.</li>
</ol>
<p>The guide ends when validation/truth checks have either passed or produced diagnostics that identify the broken contract.</p>
<h3>Boundaries</h3>
<p>Repository validation is an Open GameStudio package behavior implemented by the CLI and validation modules. Truthmark checks are an injected repository-truth workflow/tooling layer for documentation authority and generated agent surfaces, not an Open GameStudio runtime feature.</p>
<h3>Entry Points</h3>
<table><thead><tr><th>Entry point</th><th>Role in flow</th><th>Code / owner</th></tr></thead><tbody>
<tr><td><code>open-gamestudio validate</code></td><td>Public CLI validation command.</td><td><code>src/cli.ts</code>, <code>src/validation.ts</code></td></tr>
<tr><td><code>npm run validate</code></td><td>Repository readiness gate that builds/tests/validates through package scripts.</td><td><code>package.json</code></td></tr>
<tr><td><code>npx truthmark check --json</code></td><td>Injected repository-truth consistency check.</td><td>Truthmark tooling, <code>.truthmark/config.yml</code></td></tr>
<tr><td>Truthmark route files</td><td>Map code surfaces to bounded truth docs.</td><td><code>docs/truthmark/areas.md</code>, <code>docs/truthmark/areas/repository.md</code></td></tr>
<tr><td>Truth docs</td><td>Canonical bounded behavior/reference docs.</td><td><code>docs/truth/**</code></td></tr>
</tbody></table>
<h3>Preconditions</h3>
<ul>
<li>Repository validation expects package metadata, source files, templates, engine configs, and build output to match the package contract.</li>
<li>Project validation expects a generated project with valid <code>.codex/studio.json</code> when <code>--project &lt;path&gt;</code> is supplied.</li>
<li>Truthmark checks expect <code>.truthmark/config.yml</code> and configured route/truth docs to remain internally consistent when present.</li>
</ul>
<h3>Inputs</h3>
<table><thead><tr><th>Input</th><th>Source</th><th>Required</th><th>Notes</th></tr></thead><tbody>
<tr><td>Repository files</td><td>Worktree</td><td>yes</td><td>Package metadata, source, templates, engine configs, generated surfaces.</td></tr>
<tr><td>Project path</td><td><code>--project</code></td><td>no</td><td>Adds generated-project validation checks.</td></tr>
<tr><td>Truthmark config</td><td><code>.truthmark/config.yml</code></td><td>for Truthmark checks</td><td>Configures doc roots, routes, and generated surfaces.</td></tr>
<tr><td>Route docs</td><td><code>docs/truthmark/areas*.md</code></td><td>for Truthmark checks</td><td>Map code/doc surfaces to bounded truth docs.</td></tr>
<tr><td>Truth docs</td><td><code>docs/truth/**</code></td><td>for Truthmark checks</td><td>Canonical behavior/reference claims.</td></tr>
</tbody></table>
<h3>Happy Path Sequence</h3>
<pre><code class="language-mermaid">
sequenceDiagram
actor Contributor
participant Repo as Git worktree
participant Validate as src/validation.ts
participant Truth as Truthmark check
participant Docs as docs/truth and docs/architecture
Contributor-&gt;&gt;Repo: change code or docs
Contributor-&gt;&gt;Validate: npm run validate / open-gamestudio validate
Validate-&gt;&gt;Repo: check package, source, templates, build, generated project contracts
Validate--&gt;&gt;Contributor: all checks pass
alt behavior claim changed
Contributor-&gt;&gt;Docs: update owning truth doc first
Contributor-&gt;&gt;Docs: update affected flow guide if runtime scenario changed
end
Contributor-&gt;&gt;Truth: npx truthmark check --json
Truth-&gt;&gt;Docs: check config, routes, truth visibility, generated surfaces
Truth--&gt;&gt;Contributor: no diagnostics
</code></pre>
<h3>Branch Map</h3>
<pre><code class="language-mermaid">
flowchart TD
A[Repository change] --&gt; B{Functional behavior changed?}
B -- yes --&gt; C[Run relevant tests and npm run validate]
B -- no --&gt; D{Docs/truth/routing changed?}
C --&gt; E{Validation passed?}
E -- no --&gt; E1[Fix package/project contract diagnostics]
E -- yes --&gt; F{Truth claim affected?}
F -- yes --&gt; G[Update owning Truthmark truth doc]
F -- no --&gt; H[No truth-doc change needed]
G --&gt; I{Runtime scenario comprehension affected?}
H --&gt; I
D -- yes --&gt; J[Run npx truthmark check --json]
D -- no --&gt; K[No validation gate beyond normal review]
I -- yes --&gt; L[Update architecture flow guide]
I -- no --&gt; J
L --&gt; J
J --&gt; M{Truthmark diagnostics?}
M -- yes --&gt; M1[Repair routing/truth/generated-surface issue]
M -- no --&gt; N[Reviewable]
</code></pre>
<h3>Decision Table</h3>
<table><thead><tr><th>Condition</th><th>Branch</th><th>Required action</th><th>Output/diagnostic</th><th>Owner</th></tr></thead><tbody>
<tr><td>Source/package behavior changed</td><td>Functional validation branch</td><td>Run relevant tests and <code>npm run validate</code>.</td><td>Failing package/project check if contract is broken.</td><td>Open GameStudio repo</td></tr>
<tr><td>Generated project behavior changed</td><td>Project validation branch</td><td>Validate generated-project contracts.</td><td>Missing/invalid generated surface diagnostic.</td><td><code>src/validation.ts</code> and scaffold owners</td></tr>
<tr><td>Public CLI claim changed</td><td>CLI contract branch</td><td>Update contract truth doc and validation/readme claims together.</td><td>Validation or doc drift if missed.</td><td><code>docs/truth/contracts/cli-and-validation.md</code></td></tr>
<tr><td>Behavior claim changed</td><td>Truth sync branch</td><td>Update owning bounded truth doc.</td><td>Truthmark may flag stale/unmapped surfaces.</td><td>Truthmark docs workflow</td></tr>
<tr><td>Flow comprehension changed</td><td>Runtime-view branch</td><td>Update affected architecture flow guide after truth doc.</td><td>Stale walkthrough if missed.</td><td><code>docs/architecture/flows/**</code></td></tr>
<tr><td>Truthmark generated surface changed</td><td>Injected workflow branch</td><td>Preserve managed blocks and run Truthmark check/init only when appropriate.</td><td>Generated surface diagnostic.</td><td>Truthmark tooling layer</td></tr>
</tbody></table>
<h3>Failure Modes And Debugging Cues</h3>
<table><thead><tr><th>Failure</th><th>Likely cause</th><th>Inspect</th></tr></thead><tbody>
<tr><td>Validation check fails</td><td>Package metadata, source, templates, build output, or project scaffold drift.</td><td><code>src/validation.ts</code>, failing check ID.</td></tr>
<tr><td>Future-surface guard fails</td><td>CLI/docs exposed unimplemented planner/telemetry/parallel/ownership surface.</td><td><code>src/cli.ts</code>, README/docs, validation tests.</td></tr>
<tr><td>Truthmark reports route/topology issue</td><td>Code or docs moved outside bounded route ownership.</td><td><code>docs/truthmark/areas.md</code>, <code>docs/truthmark/areas/repository.md</code>.</td></tr>
<tr><td>Truth doc and flow guide diverge</td><td>Flow guide was updated without updating canonical truth or vice versa.</td><td>Owning <code>docs/truth/<strong></code> file and affected <code>docs/architecture/flows/</strong></code> file.</td></tr>
<tr><td>Portal output stale</td><td>Generated non-canonical site not refreshed after Markdown changes.</td><td><code>docs/truthmark-portal/</code> and portal provenance.</td></tr>
</tbody></table>
<h3>Code And Document Traceability</h3>
<table><thead><tr><th>Behavior / concern</th><th>Owner</th></tr></thead><tbody>
<tr><td>CLI validation command wiring</td><td><code>src/cli.ts</code></td></tr>
<tr><td>Validation checks and project contract diagnostics</td><td><code>src/validation.ts</code></td></tr>
<tr><td>Package scripts/bin/files contract</td><td><code>package.json</code>, <code>docs/truth/contracts/cli-and-validation.md</code></td></tr>
<tr><td>Truthmark config and generated workflow surfaces</td><td><code>.truthmark/config.yml</code>, generated agent files</td></tr>
<tr><td>Truth routing</td><td><code>docs/truthmark/areas.md</code>, <code>docs/truthmark/areas/repository.md</code></td></tr>
<tr><td>Bounded canonical behavior docs</td><td><code>docs/truth/**</code></td></tr>
<tr><td>Cross-cutting runtime scenario explanations</td><td><code>docs/architecture/flows/**</code></td></tr>
<tr><td>Generated presentation output</td><td><code>docs/truthmark-portal/</code></td></tr>
</tbody></table>
<h3>Product Decisions</h3>
<ul>
<li><code>npm run validate</code> remains the readiness gate before repository parity claims.</li>
<li>Truthmark checks validate repository-truth routing and generated workflow surfaces without redefining Open GameStudio runtime behavior.</li>
<li>Markdown truth docs remain canonical; generated portal HTML remains non-canonical presentation.</li>
</ul>
<h3>Rationale</h3>
<p>Keeping validation and repository-truth checks adjacent but distinct prevents injected Truthmark workflow scaffolding from being mistaken for product functionality while still making documentation authority auditable.</p>
<h3>Truth Sources</h3>
<ul>
<li><code>docs/truth/contracts/cli-and-validation.md</code></li>
<li><code>docs/truth/repository/overview.md</code></li>
<li><code>docs/truthmark/areas/repository.md</code></li>
<li><code>.truthmark/config.yml</code></li>
</ul>
<h3>Verification</h3>
<p>For behavior changes, run relevant tests and:</p>
<pre><code class="language-bash">
npm run validate
</code></pre>
<p>For repository-truth docs/routing/generated-surface changes, run:</p>
<pre><code class="language-bash">
npx truthmark check --json
</code></pre>
<p>When both behavior and truth docs change, run both gates.</p></section><p class="footer">Generated locally with no remote dependencies.</p></main><script src="assets/portal.js"></script></body></html>
docs/truthmark-portal/assets/manifest.json
+28
View File
@@ -0,0 +1,28 @@
{
"generated_at": "2026-05-30",
"output": "docs/truthmark-portal",
"template": "default",
"page_count": 4,
"source_docs_reviewed": [
".truthmark/config.yml",
"docs/architecture/repository-structure.md",
"docs/architecture/flows/README.md",
"docs/architecture/flows/project-initialization.md",
"docs/architecture/flows/role-run-lifecycle.md",
"docs/architecture/flows/workflow-prompt-rendering.md",
"docs/architecture/flows/validation-and-repository-truth.md",
"docs/truthmark/areas.md",
"docs/truthmark/areas/repository.md",
"docs/truth/README.md",
"docs/truth/repository/README.md",
"docs/truth/repository/overview.md",
"docs/truth/projects/project-scaffolding.md",
"docs/truth/codex/roles-and-workflows.md",
"docs/truth/codex/runtime-and-tasks.md",
"docs/truth/contracts/cli-and-validation.md",
"docs/standards/default-principles.md",
"docs/standards/documentation-governance.md"
],
"skipped_or_ambiguous_docs": [],
"canonical_statement": "Markdown remains canonical; generated Portal HTML is non-canonical presentation only."
}
docs/truthmark-portal/assets/portal.js
+1
View File
@@ -0,0 +1 @@
async function runSearch(){const i=document.querySelector('#portal-search'),r=document.querySelector('#search-results');if(!i||!r)return;const d=await fetch('assets/search.json').then(x=>x.json()).catch(()=>[]);i.addEventListener('input',()=>{const q=i.value.trim().toLowerCase();r.replaceChildren();if(!q)return;for(const item of d.filter(x=>(x.title+' '+x.text+' '+x.sources.join(' ')).toLowerCase().includes(q)).slice(0,12)){const li=document.createElement('li'),a=document.createElement('a');a.href=item.url;a.textContent=item.title;li.appendChild(a);li.append(' — '+item.summary);r.appendChild(li)}})}runSearch();
docs/truthmark-portal/assets/search.json
+69
View File
File diff suppressed because one or more lines are too long
docs/truthmark-portal/assets/style.css
+1
View File
@@ -0,0 +1 @@
body{margin:0;font-family:ui-sans-serif,system-ui,-apple-system,Segoe UI,sans-serif;background:#0c1017;color:#e7edf7;line-height:1.55}a{color:#69d2ff}header{padding:2rem clamp(1rem,4vw,4rem);border-bottom:1px solid #28364a;background:#111827;position:sticky;top:0}nav{display:flex;gap:1rem;flex-wrap:wrap;margin-top:.75rem}nav a{text-decoration:none;border:1px solid #28364a;border-radius:999px;padding:.35rem .75rem;background:#131a24}main{padding:2rem clamp(1rem,4vw,4rem);max-width:1180px}.card-grid{display:grid;grid-template-columns:repeat(auto-fit,minmax(240px,1fr));gap:1rem;margin:1.25rem 0}.card,section.doc{background:#131a24;border:1px solid #28364a;border-radius:18px;padding:1.1rem}.badge{display:inline-block;border:1px solid #28364a;background:#182232;color:#b9f27c;border-radius:999px;padding:.2rem .55rem;font-size:.8rem;margin:.15rem}.disclaimer{border-left:4px solid #b9f27c;background:#112018;padding:.75rem 1rem;border-radius:10px}.provenance{color:#9bacbf;font-size:.9rem;border-top:1px solid #28364a;margin-top:1rem;padding-top:.8rem}code{background:#080b10;padding:.1rem .3rem;border-radius:5px}input[type=search]{width:min(720px,100%);padding:.85rem 1rem;border-radius:12px;border:1px solid #28364a;background:#0a0f17;color:#e7edf7;font-size:1rem}.footer{color:#9bacbf;margin-top:3rem}
docs/truthmark-portal/index.html
+1
View File
@@ -0,0 +1 @@
<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>Portal Overview · Truthmark Portal</title><link rel="stylesheet" href="assets/style.css"></head><body><header><strong>Open GameStudio · Truthmark Portal</strong><nav><a href="index.html">Home</a><a href="architecture.html">Architecture</a><a href="truth.html">Repository truth</a><a href="standards.html">Standards</a></nav></header><main><h1>Portal Overview</h1><p class="disclaimer">Markdown remains canonical; this generated Portal HTML is non-canonical presentation only. Truthmark is an injected repository-truth workflow/tooling layer, not an Open GameStudio runtime feature.</p><p>This generated static site summarizes repository-truth and architecture surfaces for Open GameStudio.</p><input id="portal-search" type="search" placeholder="Search portal pages and source docs…"><ul id="search-results"></ul><div class="card-grid"><div class="card"><h3>Architecture</h3><p><a href="architecture.html">Open architecture and flow guides</a></p></div><div class="card"><h3>Repository truth</h3><p><a href="truth.html">Open truth docs</a></p></div><div class="card"><h3>Standards</h3><p><a href="standards.html">Open standards</a></p></div></div><div class="provenance"><strong>Source provenance</strong><ul><li><code>.truthmark/config.yml</code></li><li><code>docs/architecture/repository-structure.md</code></li><li><code>docs/architecture/flows/README.md</code></li><li><code>docs/architecture/flows/project-initialization.md</code></li><li><code>docs/architecture/flows/role-run-lifecycle.md</code></li><li><code>docs/architecture/flows/workflow-prompt-rendering.md</code></li><li><code>docs/architecture/flows/validation-and-repository-truth.md</code></li><li><code>docs/truthmark/areas.md</code></li><li><code>docs/truthmark/areas/repository.md</code></li><li><code>docs/truth/README.md</code></li><li><code>docs/truth/repository/README.md</code></li><li><code>docs/truth/repository/overview.md</code></li><li><code>docs/truth/projects/project-scaffolding.md</code></li><li><code>docs/truth/codex/roles-and-workflows.md</code></li><li><code>docs/truth/codex/runtime-and-tasks.md</code></li><li><code>docs/truth/contracts/cli-and-validation.md</code></li><li><code>docs/standards/default-principles.md</code></li><li><code>docs/standards/documentation-governance.md</code></li></ul></div><p class="footer">Generated locally with no remote dependencies.</p></main><script src="assets/portal.js"></script></body></html>
docs/truthmark-portal/standards.html
+30
View File
@@ -0,0 +1,30 @@
<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>Standards · Truthmark Portal</title><link rel="stylesheet" href="assets/style.css"></head><body><header><strong>Open GameStudio · Truthmark Portal</strong><nav><a href="index.html">Home</a><a href="architecture.html">Architecture</a><a href="truth.html">Repository truth</a><a href="standards.html">Standards</a></nav></header><main><h1>Standards</h1><p class="disclaimer">Markdown remains canonical; this generated Portal HTML is non-canonical presentation only. Truthmark is an injected repository-truth workflow/tooling layer, not an Open GameStudio runtime feature.</p><section class="doc"><h2>Default Principles</h2><p><span class="badge">docs/standards/default-principles.md</span></p><h2>Default Principles</h2>
<h3>Scope</h3>
<p>This is a bootstrap standards baseline for repositories that adopt Truthmark.</p>
<h3>Reusable Defaults</h3>
<ul>
<li>Authority order should be explicit.</li>
<li>Committed repository artifacts are the durable source of truth.</li>
<li>Each document should have one primary responsibility.</li>
<li>Each class of fact should have one canonical source.</li>
<li>Architecture docs describe system structure, module boundaries, runtime topology, persistence boundaries, cross-cutting contracts, generated-surface ownership, and architecturally relevant runtime views.</li>
<li>Do not put ordinary feature behavior in architecture docs; use architecture flow guides only for cross-cutting runtime scenarios, branching logic, failure paths, and traceability back to bounded truth docs.</li>
<li>Verification should be explicit, and skipped checks should state why.</li>
<li>Missing, stale, broad, overloaded, or unrouteable documentation topology should be repaired through AI-native structure workflow before agents create more generic truth docs.</li>
<li>Installed repository workflows should remain usable from committed files even when the Truthmark CLI is unavailable.</li>
</ul></section><section class="doc"><h2>Documentation Governance</h2><p><span class="badge">docs/standards/documentation-governance.md</span></p><h2>Documentation Governance</h2>
<h3>Core Rules</h3>
<ul>
<li>Each document should have one primary responsibility.</li>
<li>Each class of fact should have one canonical source.</li>
<li>Current implementation, reusable standards, and future proposals should be stored separately.</li>
<li>Generated helper output is never canonical truth.</li>
<li>Architecture docs describe structure, ownership, and runtime views; truth docs describe current product behavior and remain the canonical behavior reference.</li>
<li>Architecture flow guides may explain branching logic and failure paths, but they must trace back to the owning truth docs rather than becoming a competing source of behavior truth.</li>
</ul>
<h3>Truthmark Implications</h3>
<ul>
<li>Truth Sync should extend mapped docs first, create an area-local doc second, and create a new area only as a last resort.</li>
<li>Weak routing produces weak truth maintenance.</li>
<li>Missing, stale, broad, overloaded, or unrouteable routing should trigger Truth Structure before more generic truth docs are created.</li>
</ul></section><p class="footer">Generated locally with no remote dependencies.</p></main><script src="assets/portal.js"></script></body></html>
docs/truthmark-portal/truth.html
+419
View File
@@ -0,0 +1,419 @@
<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>Repository Truth · Truthmark Portal</title><link rel="stylesheet" href="assets/style.css"></head><body><header><strong>Open GameStudio · Truthmark Portal</strong><nav><a href="index.html">Home</a><a href="architecture.html">Architecture</a><a href="truth.html">Repository truth</a><a href="standards.html">Standards</a></nav></header><main><h1>Repository Truth</h1><p class="disclaimer">Markdown remains canonical; this generated Portal HTML is non-canonical presentation only. Truthmark is an injected repository-truth workflow/tooling layer, not an Open GameStudio runtime feature.</p><section class="doc"><h2>Truthmark Areas</h2><p><span class="badge">docs/truthmark/areas.md</span></p><h2>Truthmark Areas</h2>
<h3>Repository</h3>
<p>Area files:</p>
<ul>
<li>docs/truthmark/areas/repository.md</li>
</ul>
<p>Code surface:</p>
<ul>
<li>src/**</li>
<li>tests/**</li>
<li>engine_configs/**</li>
<li>templates/**</li>
<li>package.json</li>
<li>package-lock.json</li>
<li>README.md</li>
<li>AGENTS.md</li>
</ul>
<p>Update truth when:</p>
<ul>
<li>repository CLI behavior, Codex prompt/workflow behavior, generated project layout, validation, packaging, or task execution changes</li>
<li>code or tests move between bounded behavior owners</li>
</ul></section><section class="doc"><h2>Repository Areas</h2><p><span class="badge">docs/truthmark/areas/repository.md</span></p><h2>Repository Areas</h2>
<h3>Project Scaffolding</h3>
<p>Truth documents:</p>
<pre><code class="language-yaml">
truth_documents:
- path: docs/truth/projects/project-scaffolding.md
kind: behavior
</code></pre>
<p>Code surface:</p>
<ul>
<li>src/projects.ts</li>
<li>src/config.ts</li>
<li>src/engines.ts</li>
<li>src/agents.ts</li>
<li>src/paths.ts</li>
<li>engine_configs/**</li>
<li>tests/project-workflow.test.ts</li>
<li>tests/agents-templates.test.ts</li>
<li>tests/engine-system.test.ts</li>
<li>tests/codex-context-files.test.ts</li>
</ul>
<p>Update truth when:</p>
<ul>
<li>project initialization, generated project state, engine folder creation, role prompt materialization, or status/resume/freeze behavior changes</li>
<li>generated project AGENTS.md or base prompt package ownership changes</li>
</ul>
<h3>Codex Role And Workflow Surfaces</h3>
<p>Truth documents:</p>
<pre><code class="language-yaml">
truth_documents:
- path: docs/truth/codex/roles-and-workflows.md
kind: behavior
</code></pre>
<p>Code surface:</p>
<ul>
<li>src/roles.ts</li>
<li>src/codex-session.ts</li>
<li>src/codex-prompts.ts</li>
<li>src/workflows.ts</li>
<li>src/templates.ts</li>
<li>templates/**</li>
<li>tests/roles.test.ts</li>
<li>tests/codex-session.test.ts</li>
<li>tests/codex-prompts.test.ts</li>
<li>tests/functionality-gap-pass.test.ts</li>
</ul>
<p>Update truth when:</p>
<ul>
<li>studio role IDs, role contracts, workflow registry entries, prompt rendering, context strategies, or template selection rules change</li>
<li>Codex-native workflow shortcuts or generated workflow prompt contents change</li>
</ul>
<h3>Runtime And Task Execution</h3>
<p>Truth documents:</p>
<pre><code class="language-yaml">
truth_documents:
- path: docs/truth/codex/runtime-and-tasks.md
kind: workflow
</code></pre>
<p>Code surface:</p>
<ul>
<li>src/runner.ts</li>
<li>src/tasks.ts</li>
<li>src/codex-runtime.ts</li>
<li>src/verification.ts</li>
<li>tests/runner.test.ts</li>
<li>tests/tasks.test.ts</li>
<li>tests/verification.test.ts</li>
<li>tests/codex-runtime.test.ts</li>
</ul>
<p>Update truth when:</p>
<ul>
<li>Codex execution, dry-run or print-prompt mutation rules, review/fix lifecycle behavior, task-store persistence, or verification timeout behavior changes</li>
<li>task status transitions or Codex sandbox policies change</li>
</ul>
<h3>CLI And Validation Contracts</h3>
<p>Truth documents:</p>
<pre><code class="language-yaml">
truth_documents:
- path: docs/truth/contracts/cli-and-validation.md
kind: contract
</code></pre>
<p>Code surface:</p>
<ul>
<li>src/cli.ts</li>
<li>src/validation.ts</li>
<li>tests/validation.test.ts</li>
<li>tests/functionality-gap-pass.test.ts</li>
</ul>
<p>Update truth when:</p>
<ul>
<li>public CLI commands, package scripts/bin/files, validation check IDs, documentation claims, or package dependency contracts change</li>
<li>future-only surfaces become exposed or are intentionally kept hidden</li>
</ul></section><section class="doc"><h2>Truth Docs</h2><p><span class="badge">docs/truth/README.md</span></p><h2>Truth Docs</h2>
<p>This directory is an index for current truth docs organized by the configured Truthmark hierarchy.</p>
<p>README.md files are indexes, not Truth Sync targets. Keep bounded truth in leaf docs under <code>&lt;domain&gt;/&lt;behavior&gt;.md</code>.</p></section><section class="doc"><h2>Repository Truth Docs</h2><p><span class="badge">docs/truth/repository/README.md</span></p><h2>Repository Truth Docs</h2>
<p>This directory is reserved for repository-level truth indexes.</p>
<p>README.md files are indexes, not Truth Sync targets. Current bounded truth lives in:</p>
<ul>
<li><a href="../truth/projects/project-scaffolding.md">Project Scaffolding</a></li>
<li><a href="../truth/codex/roles-and-workflows.md">Codex Roles And Workflows</a></li>
<li><a href="../truth/codex/runtime-and-tasks.md">Runtime And Task Execution</a></li>
<li><a href="../truth/contracts/cli-and-validation.md">CLI And Validation Contracts</a></li>
</ul></section><section class="doc"><h2>Repository Overview</h2><p><span class="badge">docs/truth/repository/overview.md</span></p><h2>Repository Overview</h2>
<h3>Purpose</h3>
<p>Open GameStudio exists as a Codex-native workflow layer for game-development projects. The repository packages a TypeScript CLI that scaffolds game projects, renders role/workflow prompts for Codex, executes bounded Codex run lifecycles, and validates both repository and generated-project contracts.</p>
<h3>Scope</h3>
<p>This bounded leaf truth doc summarizes the repository-level behavior surface. More specific behavior is owned by the project scaffolding, Codex role/workflow, runtime/task execution, and CLI/validation truth documents listed in <code>docs/truthmark/areas/repository.md</code>.</p>
<h3>Current Behavior</h3>
<ul>
<li>The package exposes the <code>open-gamestudio</code> CLI from <code>dist/cli.js</code>.</li>
<li>Initialization commands create deterministic generated game project structure under <code>projects/&lt;slug&gt;</code>.</li>
<li>Generated projects contain <code>.codex/studio.json</code>, role prompt files, workflow markdown, starter design/production/market documents, engine-specific project markers, and a Codex-native <code>AGENTS.md</code> instruction surface.</li>
<li>Role run commands render deterministic Codex prompts and, unless in inspection mode, execute Codex with optional verification, review, and bounded fix passes.</li>
<li>Workflow shortcut commands are render-only prompt surfaces and do not imply hidden planner, parallel orchestration, telemetry, or ownership enforcement behavior.</li>
<li>Validation checks package metadata, source and template presence, role/workflow rendering, future-surface guardrails, build output, and package install smoke behavior.</li>
</ul>
<h3>Core Rules</h3>
<ul>
<li>Repository behavior is grouped by behavior ownership rather than by mechanically mirroring every source file.</li>
<li>Generated project instruction contracts use Codex-native <code>AGENTS.md</code>; the repository does not introduce <code>CODEX.md</code> as a primary instruction contract.</li>
<li>Runtime execution is explicit: dry-run and print-prompt modes are inspection paths, while non-dry runs write prompt/run metadata before executing Codex.</li>
<li>Truthmark is an injected repository-truth workflow/tooling layer for agent surfaces and documentation routing. It is not an Open GameStudio runtime feature unless product code explicitly implements Truthmark-facing behavior.</li>
</ul>
<h3>Flows And States</h3>
<p>Architecture runtime walkthroughs live under <code>docs/architecture/flows/**</code>; they explain branching logic and failure paths while linking back to the bounded truth docs that own the behavior.</p>
<ul>
<li>Project initialization flow: parse CLI input, normalize engine/config, guard against project-name collisions, create engine/project folders, write <code>.codex</code> state and workflow files, write starter docs, and materialize role prompts/instructions. See <code>docs/architecture/flows/project-initialization.md</code>.</li>
<li>Role run flow: validate role/project/task, render prompt and context list, optionally return inspection output, write run cache, execute Codex, run verification/review, optionally run bounded fix passes, and report <code>done</code> or <code>blocked</code>. See <code>docs/architecture/flows/role-run-lifecycle.md</code>.</li>
<li>Workflow prompt rendering flow: validate project context, resolve the workflow alias/ID, render deterministic prompt text, and return without launching Codex or writing run state. See <code>docs/architecture/flows/workflow-prompt-rendering.md</code>.</li>
<li>Repository validation flow: build the package, run validation checks, and fail if any package, source, prompt, workflow, template, or future-surface contract is broken. See <code>docs/architecture/flows/validation-and-repository-truth.md</code>.</li>
</ul>
<h3>Contracts</h3>
<ul>
<li>Public CLI command contracts are owned by <code>docs/truth/contracts/cli-and-validation.md</code>.</li>
<li>Role/workflow prompt contracts are owned by <code>docs/truth/codex/roles-and-workflows.md</code>.</li>
<li>Runtime/task lifecycle contracts are owned by <code>docs/truth/codex/runtime-and-tasks.md</code>.</li>
<li>Project scaffolding contracts are owned by <code>docs/truth/projects/project-scaffolding.md</code>.</li>
</ul>
<h3>Product Decisions</h3>
<ul>
<li>Decision (2026-05-28): Route truth by behavior ownership rather than by mechanically mirroring every source file.</li>
<li>Decision (2026-05-30): Treat Truthmark Portal output as generated non-canonical presentation; Markdown truth docs remain canonical.</li>
<li>Decision (2026-05-30): Use Markdown Architecture Flow Guides as runtime-view documentation for important cross-cutting flow scenarios; bounded Truthmark truth docs remain the behavior authority.</li>
</ul>
<h3>Rationale</h3>
<p>The repository combines scaffolding, prompt generation, runtime execution, and validation in one package. Keeping those surfaces bounded makes the architecture easier to reason about and prevents generated agent workflow scaffolding from being mistaken for user-facing Open GameStudio product behavior.</p>
<h3>Non-Goals</h3>
<ul>
<li>This doc does not replace the more specific bounded truth docs for project scaffolding, Codex role/workflow surfaces, runtime/task execution, or CLI/validation contracts.</li>
<li>This repository does not expose hidden parallel orchestration, telemetry, planner/next queues, or ownership enforcement as public CLI behavior.</li>
<li>Truthmark Portal HTML is generated presentation and is not canonical repository truth.</li>
</ul>
<h3>Maintenance Notes</h3>
<ul>
<li>Update this overview when top-level repository behavior boundaries change.</li>
<li>Update the leaf truth docs named in <code>docs/truthmark/areas/repository.md</code> when behavior changes within their owned surface.</li>
<li>Update <code>docs/architecture/flows/**</code> when an architecturally relevant runtime branch, sequence, or failure path changes.</li>
<li>Relevant verification includes <code>npm run validate</code> for behavior changes and <code>npx truthmark check --json</code> for repository-truth documentation changes.</li>
</ul></section><section class="doc"><h2>Project Scaffolding</h2><p><span class="badge">docs/truth/projects/project-scaffolding.md</span></p><h2>Project Scaffolding</h2>
<h3>Purpose</h3>
<p>Project scaffolding turns a non-interactive CLI request into a ready Codex Game Studio project with deterministic state, engine markers, role prompts, workflow prompts, and starter production/design artifacts.</p>
<h3>Scope</h3>
<p>This bounded leaf truth doc owns project initialization, generated project state, engine-specific file/folder creation, generated project <code>AGENTS.md</code> and role prompts, and read-only project status/resume behavior. It does not own Codex run execution, task lifecycle persistence, or repository-level CLI validation.</p>
<p>This doc was created from the editable behavior-doc template at docs/templates/behavior-doc.md.</p>
<h3>Current Behavior</h3>
<ul>
<li><code>init</code> and <code>new</code> share the same initialization path and require <code>--name</code>, <code>--engine</code>, <code>--mode</code>, and <code>--non-interactive</code>.</li>
<li>Initialization writes projects under <code>projects/&lt;slug&gt;/</code>, rejects an existing target path, and checks same-parent slug and Unreal class-name collisions before writing.</li>
<li>Project state is written to <code>.codex/studio.json</code> with schema version 1, product <code>codex-game-studio</code>, the full canonical role roster, mode-active roles, and all workflow IDs.</li>
<li>Engine scaffolding uses the configured engine registry to create Godot, Unity, or Unreal marker files and source folders.</li>
<li>Initialization writes <code>.codex/workflows/*.md</code>, starter design/production/market docs, project <code>AGENTS.md</code>, and one prompt per studio role.</li>
<li><code>status</code> and <code>resume</code> read project state without mutating <code>.codex/studio.json</code>; <code>freeze</code> intentionally changes project status to <code>frozen</code>.</li>
</ul>
<h3>Core Rules</h3>
<ul>
<li>Project creation is deterministic and non-interactive; missing <code>--non-interactive</code> or <code>--mode</code> is an error.</li>
<li>Generated projects live under <code>projects/&lt;slug&gt;/</code> by default.</li>
<li><code>CODEX.md</code>, <code>project_orchestrator.md</code>, and <code>.gamestudio/runs</code> are forbidden generated project surfaces.</li>
<li>Generated project prompts must include the project name, role display name, project summary, engine context, role instructions, expected outputs, review checklist, and handoff sections.</li>
</ul>
<h3>Flows And States</h3>
<ul>
<li>Initialization flow: parse options, normalize engine, derive slug, reject collisions, create engine files, create <code>.codex/runs</code>, write studio state, write workflow files, write starter docs, and materialize role prompts.</li>
<li>Project status states are <code>active</code>, <code>frozen</code>, and <code>inactive</code>; <code>freeze</code> is the only current CLI path that mutates status.</li>
</ul>
<h3>Contracts</h3>
<ul>
<li><code>open-gamestudio init --name &lt;name&gt; --engine &lt;engine&gt; --mode &lt;mode&gt; --non-interactive</code> creates a project and prints the created path.</li>
<li><code>open-gamestudio new</code> is an alias for the same initialization behavior.</li>
<li><code>open-gamestudio status --project &lt;path&gt;</code>, <code>resume --project &lt;path&gt;</code>, and <code>freeze --project &lt;path&gt;</code> operate on <code>.codex/studio.json</code>.</li>
</ul>
<h3>Product Decisions</h3>
<ul>
<li>Decision (2026-05-28): Preserve Codex-native project state under <code>.codex/</code> and use project-level <code>AGENTS.md</code> as the generated instruction surface.</li>
<li>Decision (2026-05-28): Keep status/resume read-only so inspection commands cannot alter generated project state.</li>
</ul>
<h3>Rationale</h3>
<p>A deterministic project scaffold gives Codex a stable context package without introducing a separate planner database or hidden orchestration layer. Keeping generated project instructions in <code>AGENTS.md</code> aligns with Codex-native workflows and avoids a parallel <code>CODEX.md</code> contract.</p>
<h3>Non-Goals</h3>
<ul>
<li>This doc does not own runtime Codex execution or task-store status transitions after project creation.</li>
<li>This doc does not define game engine runtime behavior beyond the initial marker files and folders created by the scaffolder.</li>
</ul>
<h3>Maintenance Notes</h3>
<ul>
<li>Update this doc with changes to <code>src/projects.ts</code>, <code>src/config.ts</code>, <code>src/engines.ts</code>, <code>src/agents.ts</code>, <code>src/paths.ts</code>, or <code>engine_configs/**</code>.</li>
<li>Relevant verification includes project workflow, agent/template, engine-system, and project validation tests.</li>
</ul></section><section class="doc"><h2>Codex Roles And Workflows</h2><p><span class="badge">docs/truth/codex/roles-and-workflows.md</span></p><h2>Codex Roles And Workflows</h2>
<h3>Purpose</h3>
<p>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.</p>
<h3>Scope</h3>
<p>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.</p>
<p>This doc was created from the editable behavior-doc template at docs/templates/behavior-doc.md.</p>
<h3>Current Behavior</h3>
<ul>
<li>The canonical studio role roster is defined by hyphenated Codex-native role IDs such as <code>producer</code>, <code>gameplay-programmer</code>, <code>qa-playtester</code>, and <code>studio-orchestrator</code>.</li>
<li>Each role package contains a display name, system prompt, context strategy, expected outputs, handoff wording, and a review checklist.</li>
<li>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.</li>
<li>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.</li>
<li>Selected workflows include CLI aliases for render-only shortcuts, including market, analytics, design-spec, feel-review, art-direction, ui-review, milestone, and handoff.</li>
<li>Template selection is task- and role-sensitive; template files are read from package assets and embedded into applicable workflow prompts.</li>
</ul>
<h3>Core Rules</h3>
<ul>
<li>Unknown role errors must point users toward Codex-native hyphenated role IDs rather than legacy agent names.</li>
<li>Prompt rendering must include the role display name and project/session metadata needed by Codex to operate without hidden state.</li>
<li>Templates that require Markdown sections must have non-empty required sections; the project config template must parse as JSON.</li>
<li>Workflow shortcuts render prompts; they do not imply hidden parallel orchestration or future planner behavior.</li>
</ul>
<h3>Flows And States</h3>
<ul>
<li>Workflow prompt flow: read project engine from <code>.codex/studio.json</code>, 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.</li>
<li>Template selection flow: match role and task text against bounded keyword rules and return only matching template IDs.</li>
</ul>
<h3>Contracts</h3>
<ul>
<li>Role IDs are stable strings exported from <code>src/roles.ts</code> and reused by config validation, project state, prompt generation, workflow routing, and task creation.</li>
<li>Workflow IDs map to <code>.codex/workflows/&lt;workflow&gt;.md</code> files and expected context-file lists.</li>
<li>Template IDs map to package template paths, role applicability, tags, and required-section validation.</li>
</ul>
<h3>Product Decisions</h3>
<ul>
<li>Decision (2026-05-28): Use Codex-native hyphenated role IDs as the canonical user- and project-facing role contract.</li>
<li>Decision (2026-05-28): Keep workflow shortcuts render-only for this pass; future planner, next, telemetry, ownership enforcement, and parallel orchestration surfaces remain hidden.</li>
</ul>
<h3>Rationale</h3>
<p>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.</p>
<h3>Non-Goals</h3>
<ul>
<li>This doc does not own whether Codex is installed or authenticated.</li>
<li>This doc does not own task lifecycle mutations or verification command execution.</li>
</ul>
<h3>Maintenance Notes</h3>
<ul>
<li>Update this doc with changes to <code>src/roles.ts</code>, <code>src/codex-session.ts</code>, <code>src/codex-prompts.ts</code>, <code>src/workflows.ts</code>, <code>src/templates.ts</code>, or <code>templates/**</code>.</li>
<li>Relevant verification includes role, Codex prompt/session, workflow, template, and functionality-gap tests.</li>
</ul></section><section class="doc"><h2>Runtime And Task Execution</h2><p><span class="badge">docs/truth/codex/runtime-and-tasks.md</span></p><h2>Runtime And Task Execution</h2>
<h3>Purpose</h3>
<p>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.</p>
<h3>Scope</h3>
<p>This bounded leaf truth doc owns <code>run</code> 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.</p>
<h3>Triggers</h3>
<ul>
<li>A user invokes <code>run &lt;role&gt; ... --project &lt;path&gt;</code> to render or execute a role prompt.</li>
<li>A user creates or runs a file-backed task through <code>task create</code> or <code>task run</code>.</li>
<li>A run includes structured verification, review, or bounded fix-pass options.</li>
</ul>
<h3>Inputs</h3>
<ul>
<li>A valid project root with <code>.codex/studio.json</code>.</li>
<li>A studio role ID or task ID.</li>
<li>A non-empty task/objective.</li>
<li>Optional included artifacts, verification command/args, review flag, fix flag, and max fix-pass count.</li>
</ul>
<h3>Execution Model</h3>
<ul>
<li><code>prepareRun</code> resolves the project, reads studio state, renders a Codex prompt, computes prompt and metadata cache paths, and builds Codex execution commands.</li>
<li><code>--print-prompt</code> and <code>--dry-run</code> are inspection-only paths and do not write prompt cache, metadata, task state, or run directories.</li>
<li>Non-dry runs write prompt and metadata before executing Codex.</li>
<li>Implementation and fix passes use a workspace-write Codex sandbox; review passes use a read-only Codex sandbox.</li>
<li>Task runs mutate task status only for non-dry execution.</li>
</ul>
<h3>Steps</h3>
<ol>
<li>Validate the requested role/task and project state.</li>
<li>Build context-file lists and render the Codex prompt.</li>
<li>For non-dry runs, write the prompt and metadata cache under <code>.codex/runs/</code>.</li>
<li>Check Codex availability before execution through the CLI path.</li>
<li>Execute the implementation prompt.</li>
<li>Run verification when configured.</li>
<li>Run review when requested and verification passes or is absent.</li>
<li>Run bounded fix passes when requested and blockers remain.</li>
<li>Report final status as <code>done</code> or <code>blocked</code>; task runs also persist final task status.</li>
</ol>
<h3>State, Retry, And Failure Behavior</h3>
<ul>
<li>Task stores live at <code>.codex/tasks.json</code> with schema version 1 and unique <code>task-###</code> IDs.</li>
<li><code>task create</code> requires a valid studio project before writing task state.</li>
<li>Task statuses are <code>ready</code>, <code>running</code>, <code>blocked</code>, and <code>done</code>.</li>
<li>Verification commands are spawned with bounded stdout/stderr capture, a default timeout, SIGTERM on timeout, and SIGKILL after the configured grace period.</li>
<li>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.</li>
</ul>
<h3>Outputs</h3>
<ul>
<li>Dry-run output lists context files and the Codex command without writing cache files.</li>
<li>Print-prompt output is the deterministic prompt body.</li>
<li>Non-dry run output reports implementation, verification, review, fix-pass, and final-status summaries.</li>
<li>Task creation prints the new task ID.</li>
</ul>
<h3>Product Decisions</h3>
<ul>
<li>Decision (2026-05-28): Make dry-run and print-prompt non-mutating inspection paths.</li>
<li>Decision (2026-05-28): Force review prompts through a read-only sandbox while implementation/fix prompts retain workspace-write behavior.</li>
<li>Decision (2026-05-28): Require a valid project before task-store writes.</li>
</ul>
<h3>Rationale</h3>
<p>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.</p>
<h3>Non-Goals</h3>
<ul>
<li>This workflow does not implement hidden parallel execution, telemetry, ownership enforcement, or a planner/next queue.</li>
<li>This workflow does not choose role prompt content; it consumes the role and workflow surfaces owned by the Codex roles truth doc.</li>
</ul>
<h3>Maintenance Notes</h3>
<ul>
<li>Update this doc with changes to <code>src/runner.ts</code>, <code>src/tasks.ts</code>, <code>src/codex-runtime.ts</code>, or <code>src/verification.ts</code>.</li>
<li>Relevant verification includes runner, task, verification, Codex runtime, and lifecycle-focused tests.</li>
</ul></section><section class="doc"><h2>CLI And Validation Contracts</h2><p><span class="badge">docs/truth/contracts/cli-and-validation.md</span></p><h2>CLI And Validation Contracts</h2>
<h3>Purpose</h3>
<p>The CLI and validation contracts define the public <code>open-gamestudio</code> command surface, package entrypoints, hard-failing validation checks, and future-surface guardrails for this repository.</p>
<h3>Scope</h3>
<p>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.</p>
<h3>Contract Surface</h3>
<ul>
<li>Package name: <code>open-gamestudio</code>.</li>
<li>Package bin: <code>open-gamestudio</code> points to <code>./dist/cli.js</code>.</li>
<li>Primary scripts include <code>build</code>, <code>typecheck</code>, <code>test</code>, <code>validate</code>, <code>init</code>, <code>manage</code>, and <code>templates</code>.</li>
<li>Public CLI command groups include initialization/status commands, template discovery, role run execution, file-backed tasks, and render-only workflow shortcuts.</li>
<li>Repository validation is exposed through <code>open-gamestudio validate</code> and the <code>npm run validate</code> script.</li>
</ul>
<h3>Inputs</h3>
<ul>
<li>CLI options and arguments parsed by Commander in <code>src/cli.ts</code>.</li>
<li>Repository files checked by validation, including package metadata, source files, templates, generated build output, engine configs, and optional project paths.</li>
<li>Project validation input when <code>--project &lt;path&gt;</code> is supplied.</li>
</ul>
<h3>Outputs</h3>
<ul>
<li>CLI commands print human-readable status, prompt, task, validation, or workflow output.</li>
<li>Validation emits one line per check in <code>STATUS id: message (path)</code> shape and exits non-zero when any check fails.</li>
<li>Package smoke validation builds and exercises the packed package bin and template loading behavior.</li>
</ul>
<h3>Errors And Diagnostics</h3>
<ul>
<li>Unknown roles fail with a message naming Codex-native hyphenated role IDs.</li>
<li>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.</li>
<li>Project validation fails for invalid <code>.codex/studio.json</code>, missing generated project files, missing workflow/prompt sections, forbidden generated surfaces, or read-only command mutations.</li>
</ul>
<h3>Compatibility Rules</h3>
<ul>
<li>The TypeScript project uses NodeNext ESM semantics; relative TypeScript imports must use emitted <code>.js</code> specifiers.</li>
<li>Node support requires a package engine floor that includes Node &gt;=20.</li>
<li>Packaged files must include <code>dist/</code>, <code>engine_configs/</code>, and <code>templates/</code> so the installed bin can load runtime assets.</li>
<li>Future-only command surfaces such as <code>next</code>, <code>telemetry</code>, <code>parallel</code>, and ownership enforcement must stay hidden until implemented intentionally.</li>
</ul>
<h3>Versioning And Migration</h3>
<ul>
<li>Current package version is managed in <code>package.json</code> and rendered by Commander.</li>
<li>CLI contract changes should update README claims, validation expectations, and tests in the same change.</li>
</ul>
<h3>Product Decisions</h3>
<ul>
<li>Decision (2026-05-28): Keep <code>validate</code> as the hard-failing parity gate before claiming repository or project readiness.</li>
<li>Decision (2026-05-28): Document and test that future planner/telemetry/parallel/ownership surfaces are not exposed by the CLI.</li>
</ul>
<h3>Rationale</h3>
<p>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.</p>
<h3>Non-Goals</h3>
<ul>
<li>This contract does not document every generated prompt body; those belong to the Codex role/workflow truth doc.</li>
<li>This contract does not define npm audit remediation policy.</li>
</ul>
<h3>Maintenance Notes</h3>
<ul>
<li>Update this doc with changes to <code>src/cli.ts</code>, <code>src/validation.ts</code>, package metadata, README public command claims, or validation check IDs.</li>
<li>Relevant verification includes <code>npm run validate</code>, CLI help smoke checks, validation tests, package dry-run/smoke checks, and future-surface guard tests.</li>
</ul></section><p class="footer">Generated locally with no remote dependencies.</p></main><script src="assets/portal.js"></script></body></html>