mirror of
https://github.com/merlinhu1/codex-game-studio.git
synced 2026-08-25 07:54:34 +02:00
chore: remove OpenSpec artifacts
This commit is contained in:
MerlinH
@@ -23,7 +23,7 @@ Draft an architecture decision with context, options, selected direction, conseq
|
||||
- AGENTS.md
|
||||
- .codex/studio.json
|
||||
- .codex/workflows/architecture-decision.md
|
||||
- documentation/design/gdd.md
|
||||
- design/gdd.md
|
||||
|
||||
## Role
|
||||
|
||||
|
||||
@@ -23,7 +23,7 @@ Generate bounded game ideas, feature variations, player fantasies, and tradeoff
|
||||
- AGENTS.md
|
||||
- .codex/studio.json
|
||||
- .codex/workflows/brainstorm.md
|
||||
- documentation/design/gdd.md
|
||||
- design/gdd.md
|
||||
|
||||
## Role
|
||||
|
||||
|
||||
@@ -82,3 +82,9 @@ CLI aliases:
|
||||
## Handoff
|
||||
|
||||
Report changed files, validation evidence, residual risks, and the next owner only when ownership changes.
|
||||
|
||||
## Documentation Impact
|
||||
|
||||
- After functional source, engine, or asset changes, update the owning game document or record a fresh `## Documentation Impact` decision in `production/session-state/active.md`.
|
||||
- Run `./codex-game-studio docs-impact --base <review-base>` before handoff.
|
||||
- A `no-update` decision must state why no player, architecture, production, or release document changed.
|
||||
|
||||
@@ -3,7 +3,7 @@ model: gpt-5.6-luna
|
||||
model_reasoning_effort: low
|
||||
primary-agent: release-manager
|
||||
linked-skills: [cgs-changelog, cgs-team-release]
|
||||
phase: ship
|
||||
phase: implement
|
||||
risk: high
|
||||
argument-hint: Provide a changelog request with release or milestone diff, grouped changes, migration notes, known issues, owner or handoff needs, and verification evidence.
|
||||
source-reference: .codex/workflows/changelog.md
|
||||
@@ -82,3 +82,8 @@ CLI aliases:
|
||||
## Handoff
|
||||
|
||||
Report changed files, validation evidence, residual risks, and the next owner only when ownership changes.
|
||||
|
||||
## Document Target
|
||||
|
||||
- Write the completed release record to `docs/changelog.md`.
|
||||
- Confirm the document is grounded in the release diff and validation evidence.
|
||||
|
||||
@@ -82,3 +82,9 @@ CLI aliases:
|
||||
## Handoff
|
||||
|
||||
Report changed files, validation evidence, residual risks, and the next owner only when ownership changes.
|
||||
|
||||
## Documentation Impact
|
||||
|
||||
- After functional source, engine, or asset changes, update the owning game document or record a fresh `## Documentation Impact` decision in `production/session-state/active.md`.
|
||||
- Run `./codex-game-studio docs-impact --base <review-base>` before handoff.
|
||||
- A `no-update` decision must state why no player, architecture, production, or release document changed.
|
||||
|
||||
@@ -23,8 +23,8 @@ Check design, production, architecture, UI, and validation surfaces for contradi
|
||||
- AGENTS.md
|
||||
- .codex/studio.json
|
||||
- .codex/workflows/consistency-check.md
|
||||
- documentation/design/gdd.md
|
||||
- documentation/production/timeline.md
|
||||
- design/gdd.md
|
||||
- production/timeline.md
|
||||
|
||||
## Role
|
||||
|
||||
|
||||
@@ -23,7 +23,7 @@ Create technical architecture with engine modules, data flow, integration points
|
||||
- AGENTS.md
|
||||
- .codex/studio.json
|
||||
- .codex/workflows/create-architecture.md
|
||||
- documentation/design/gdd.md
|
||||
- design/gdd.md
|
||||
|
||||
## Role
|
||||
|
||||
|
||||
@@ -23,8 +23,8 @@ Create production epics from the project goal with scope, owners, dependencies,
|
||||
- AGENTS.md
|
||||
- .codex/studio.json
|
||||
- .codex/workflows/create-epics.md
|
||||
- documentation/design/gdd.md
|
||||
- documentation/production/timeline.md
|
||||
- design/gdd.md
|
||||
- production/timeline.md
|
||||
|
||||
## Role
|
||||
|
||||
|
||||
@@ -23,7 +23,7 @@ Break an epic or feature into implementation-ready stories with role owner, file
|
||||
- AGENTS.md
|
||||
- .codex/studio.json
|
||||
- .codex/workflows/create-stories.md
|
||||
- documentation/production/timeline.md
|
||||
- production/timeline.md
|
||||
|
||||
## Role
|
||||
|
||||
|
||||
@@ -23,7 +23,7 @@ Review the concept for coherent player promise, pillars, audience fit, productio
|
||||
- AGENTS.md
|
||||
- .codex/studio.json
|
||||
- .codex/workflows/design-review-concept.md
|
||||
- documentation/design/gdd.md
|
||||
- design/gdd.md
|
||||
|
||||
## Role
|
||||
|
||||
|
||||
@@ -23,7 +23,7 @@ Review design docs for player promise, systemic consistency, production scope, e
|
||||
- AGENTS.md
|
||||
- .codex/studio.json
|
||||
- .codex/workflows/design-review.md
|
||||
- documentation/design/gdd.md
|
||||
- design/gdd.md
|
||||
|
||||
## Role
|
||||
|
||||
|
||||
@@ -23,7 +23,7 @@ Create or review a feature/design spec with rules, edge cases, implementation sl
|
||||
- AGENTS.md
|
||||
- .codex/studio.json
|
||||
- .codex/workflows/design-spec.md
|
||||
- documentation/design/gdd.md
|
||||
- design/gdd.md
|
||||
|
||||
## Role
|
||||
|
||||
|
||||
@@ -23,7 +23,7 @@ Author or update a system design with player-facing rules, data model, edge case
|
||||
- AGENTS.md
|
||||
- .codex/studio.json
|
||||
- .codex/workflows/design-system.md
|
||||
- documentation/design/gdd.md
|
||||
- design/gdd.md
|
||||
|
||||
## Role
|
||||
|
||||
|
||||
@@ -82,3 +82,9 @@ CLI aliases:
|
||||
## Handoff
|
||||
|
||||
Report changed files, validation evidence, residual risks, and the next owner only when ownership changes.
|
||||
|
||||
## Documentation Impact
|
||||
|
||||
- After functional source, engine, or asset changes, update the owning game document or record a fresh `## Documentation Impact` decision in `production/session-state/active.md`.
|
||||
- Run `./codex-game-studio docs-impact --base <review-base>` before handoff.
|
||||
- A `no-update` decision must state why no player, architecture, production, or release document changed.
|
||||
|
||||
@@ -82,3 +82,9 @@ CLI aliases:
|
||||
## Handoff
|
||||
|
||||
Report changed files, validation evidence, residual risks, and the next owner only when ownership changes.
|
||||
|
||||
## Documentation Impact
|
||||
|
||||
- After functional source, engine, or asset changes, update the owning game document or record a fresh `## Documentation Impact` decision in `production/session-state/active.md`.
|
||||
- Run `./codex-game-studio docs-impact --base <review-base>` before handoff.
|
||||
- A `no-update` decision must state why no player, architecture, production, or release document changed.
|
||||
|
||||
@@ -23,7 +23,7 @@ Create a localization plan with string scope, culturalization risks, asset depen
|
||||
- AGENTS.md
|
||||
- .codex/studio.json
|
||||
- .codex/workflows/localization-plan.md
|
||||
- documentation/design/gdd.md
|
||||
- design/gdd.md
|
||||
|
||||
## Role
|
||||
|
||||
|
||||
@@ -23,7 +23,7 @@ Map core gameplay, economy, progression, content, UI, and technical systems with
|
||||
- AGENTS.md
|
||||
- .codex/studio.json
|
||||
- .codex/workflows/map-systems.md
|
||||
- documentation/design/gdd.md
|
||||
- design/gdd.md
|
||||
|
||||
## Role
|
||||
|
||||
|
||||
@@ -23,7 +23,7 @@ Analyze audience, competitors, positioning, pricing, and market risks for the cu
|
||||
- AGENTS.md
|
||||
- .codex/studio.json
|
||||
- .codex/workflows/market-analysis.md
|
||||
- resources/market-research/market-overview.md
|
||||
- docs/market-overview.md
|
||||
|
||||
## Role
|
||||
|
||||
|
||||
@@ -23,8 +23,8 @@ Orient a contributor to the project goal, current stage, key files, active roles
|
||||
- AGENTS.md
|
||||
- .codex/studio.json
|
||||
- .codex/workflows/onboard.md
|
||||
- documentation/design/gdd.md
|
||||
- documentation/production/timeline.md
|
||||
- design/gdd.md
|
||||
- production/timeline.md
|
||||
|
||||
## Role
|
||||
|
||||
|
||||
@@ -3,7 +3,7 @@ model: gpt-5.6-luna
|
||||
model_reasoning_effort: low
|
||||
primary-agent: release-manager
|
||||
linked-skills: [cgs-patch-notes, cgs-team-release]
|
||||
phase: ship
|
||||
phase: implement
|
||||
risk: high
|
||||
argument-hint: Provide a patch notes request with release scope, fixes, known issues, validation evidence, audience, owner or handoff needs, and approval constraints.
|
||||
source-reference: .codex/workflows/patch-notes.md
|
||||
@@ -82,3 +82,8 @@ CLI aliases:
|
||||
## Handoff
|
||||
|
||||
Report changed files, validation evidence, residual risks, and the next owner only when ownership changes.
|
||||
|
||||
## Document Target
|
||||
|
||||
- Write the completed release record to `docs/patch-notes.md`.
|
||||
- Confirm the document is grounded in the release diff and validation evidence.
|
||||
|
||||
@@ -23,7 +23,7 @@ Convert current project state into milestone goals, task slices, risks, owners,
|
||||
- AGENTS.md
|
||||
- .codex/studio.json
|
||||
- .codex/workflows/production-milestone.md
|
||||
- documentation/production/timeline.md
|
||||
- production/timeline.md
|
||||
|
||||
## Role
|
||||
|
||||
|
||||
@@ -23,7 +23,7 @@ Plan the smallest playable prototype slice with owner roles, required assets, im
|
||||
- AGENTS.md
|
||||
- .codex/studio.json
|
||||
- .codex/workflows/prototype.md
|
||||
- documentation/design/gdd.md
|
||||
- design/gdd.md
|
||||
|
||||
## Role
|
||||
|
||||
|
||||
@@ -23,7 +23,7 @@ Create a QA plan with target scenarios, risk areas, test data, manual checks, au
|
||||
- AGENTS.md
|
||||
- .codex/studio.json
|
||||
- .codex/workflows/qa-plan.md
|
||||
- documentation/design/gdd.md
|
||||
- design/gdd.md
|
||||
|
||||
## Role
|
||||
|
||||
|
||||
@@ -23,7 +23,7 @@ Create a release checklist with blockers, warnings, validation commands, packagi
|
||||
- AGENTS.md
|
||||
- .codex/studio.json
|
||||
- .codex/workflows/release-checklist.md
|
||||
- documentation/production/timeline.md
|
||||
- production/timeline.md
|
||||
|
||||
## Role
|
||||
|
||||
|
||||
@@ -23,7 +23,7 @@ Review all GDD and design artifacts for contradictions, missing systems, stale a
|
||||
- AGENTS.md
|
||||
- .codex/studio.json
|
||||
- .codex/workflows/review-all-gdds.md
|
||||
- documentation/design/gdd.md
|
||||
- design/gdd.md
|
||||
|
||||
## Role
|
||||
|
||||
|
||||
@@ -23,7 +23,7 @@ Assess milestone readiness, package risk, validation status, and release blocker
|
||||
- AGENTS.md
|
||||
- .codex/studio.json
|
||||
- .codex/workflows/ship-check.md
|
||||
- documentation/production/timeline.md
|
||||
- production/timeline.md
|
||||
|
||||
## Role
|
||||
|
||||
|
||||
@@ -23,7 +23,7 @@ Plan the next sprint or iteration with committed goals, role assignments, risks,
|
||||
- AGENTS.md
|
||||
- .codex/studio.json
|
||||
- .codex/workflows/sprint-plan.md
|
||||
- documentation/production/timeline.md
|
||||
- production/timeline.md
|
||||
|
||||
## Role
|
||||
|
||||
|
||||
@@ -23,7 +23,7 @@ Summarize sprint status, completed work, blockers, risks, next owners, and verif
|
||||
- AGENTS.md
|
||||
- .codex/studio.json
|
||||
- .codex/workflows/sprint-status.md
|
||||
- documentation/production/timeline.md
|
||||
- production/timeline.md
|
||||
|
||||
## Role
|
||||
|
||||
|
||||
@@ -82,3 +82,9 @@ CLI aliases:
|
||||
## Handoff
|
||||
|
||||
Report changed files, validation evidence, residual risks, and the next owner only when ownership changes.
|
||||
|
||||
## Documentation Impact
|
||||
|
||||
- After functional source, engine, or asset changes, update the owning game document or record a fresh `## Documentation Impact` decision in `production/session-state/active.md`.
|
||||
- Run `./codex-game-studio docs-impact --base <review-base>` before handoff.
|
||||
- A `no-update` decision must state why no player, architecture, production, or release document changed.
|
||||
|
||||
@@ -23,7 +23,7 @@ Create a bounded vertical-slice plan with tasks, risks, and verification gates.
|
||||
- AGENTS.md
|
||||
- .codex/studio.json
|
||||
- .codex/workflows/vertical-slice.md
|
||||
- documentation/design/gdd.md
|
||||
- design/gdd.md
|
||||
|
||||
## Role
|
||||
|
||||
|
||||
@@ -1,20 +0,0 @@
|
||||
version: 2
|
||||
platforms:
|
||||
- codex
|
||||
truthmark:
|
||||
workspace: docs/truthmark
|
||||
generated:
|
||||
portal:
|
||||
enabled: true
|
||||
instruction_targets:
|
||||
- AGENTS.md
|
||||
frontmatter:
|
||||
required: []
|
||||
recommended:
|
||||
- status
|
||||
- last_reviewed
|
||||
ignore:
|
||||
- node_modules/**
|
||||
- vendor/**
|
||||
- dist/**
|
||||
- build/**
|
||||
@@ -47,6 +47,14 @@ Before broad inspection, use compact context helpers when available, then read o
|
||||
- Describe scene, prefab, material, animation, audio, and UI changes in handoff notes.
|
||||
- Do not modify binary assets without recording purpose and verification evidence.
|
||||
|
||||
## Documentation Impact
|
||||
|
||||
After functional changes to game source, engine configuration, or assets, make a fresh documentation-impact decision before handoff:
|
||||
|
||||
- Update the owning `design/`, `docs/`, or `production/` document when player-visible behavior, architecture, production commitments, or release communication changed.
|
||||
- Otherwise record `Decision: no-update`, `Documents: none`, and a specific reason under `## Documentation Impact` in `production/session-state/active.md`.
|
||||
- Run `./codex-game-studio docs-impact --base <review-base>` and include its evidence in the handoff. Reviewers report unresolved documentation impact; writable implementation or fix work performs the update.
|
||||
|
||||
## Studio Roles
|
||||
|
||||
- Codex custom agents live in `.codex/agents/*.toml`.
|
||||
|
||||
+3
-13
@@ -1,6 +1,6 @@
|
||||
# Codex Game Studio Docs
|
||||
|
||||
This directory is intentionally small. Keep durable user-facing guidance here and keep game-studio operating surfaces in the tracked template files:
|
||||
This directory is intentionally small. Keep durable user-facing guidance here and keep game-studio operating surfaces in tracked template files:
|
||||
|
||||
- `AGENTS.md`
|
||||
- `.codex/agents/*.toml`
|
||||
@@ -14,21 +14,11 @@ This directory is intentionally small. Keep durable user-facing guidance here an
|
||||
| [User Guide](user-guide.md) | Installation, commands, role runs, workflow prompts, tasks, validation, and troubleshooting. |
|
||||
| [Examples](examples/README.md) | Scenario-based examples for common local workflows. |
|
||||
| [Product Boundary](architecture/product-boundary.md) | Implemented scope, non-goals, and boundaries. |
|
||||
|
||||
## Repository support docs
|
||||
|
||||
| Doc | Purpose |
|
||||
| --- | --- |
|
||||
| [Repo Rules](ai/repo-rules.md) | Repository rules mirrored for agent discovery. |
|
||||
| [Documentation Governance](standards/documentation-governance.md) | Rules for keeping docs concise and linked. |
|
||||
| [Default Principles](standards/default-principles.md) | General project documentation principles. |
|
||||
|
||||
## Truthmark support
|
||||
|
||||
Truthmark support files under `docs/truthmark/` are retained only where they match the Truthmark support surface. Do not add broad product-specific truth-doc sprawl here; use tracked template files, tests, and the README/user guide first.
|
||||
| [Documentation Governance](standards/documentation-governance.md) | Ownership and maintenance rules for framework documentation. |
|
||||
|
||||
## Update rules
|
||||
|
||||
- Keep framework documentation separate from the design, architecture, production, and release records of an initialized game.
|
||||
- Do not add dated plans or one-off implementation notes under `docs/`.
|
||||
- Do not duplicate the agent, workflow, or skill catalogs in prose docs.
|
||||
- Keep the root README concise and link here only for durable guidance.
|
||||
|
||||
@@ -1,30 +0,0 @@
|
||||
---
|
||||
status: active
|
||||
doc_type: workflow
|
||||
last_reviewed: 2026-05-28
|
||||
source_of_truth:
|
||||
- ../../AGENTS.md
|
||||
---
|
||||
|
||||
# Repository Rules
|
||||
|
||||
## Purpose
|
||||
|
||||
This file mirrors the repository-specific agent rules from `AGENTS.md` in the configured Truthmark authority tree so structure and sync workflows can find them through the documented authority roots.
|
||||
|
||||
## Rules
|
||||
|
||||
- Use `npm run validate` before any parity claim.
|
||||
- This project uses `"type": "module"`, `module: "NodeNext"`, and `moduleResolution: "NodeNext"`; relative TypeScript imports must use emitted `.js` specifiers.
|
||||
- For source-checkout usage, run `npm install && npm run build` first, then use `./codex-game-studio ...`; generated bundled CLI artifacts are not committed.
|
||||
- Keep tracked game-template surfaces in the repository root.
|
||||
- Do not load all agents or all templates for a single role task.
|
||||
- Root `AGENTS.md` is a tracked game-template file, not an init-generated file.
|
||||
- Direct Codex execution is the default path via `codex-game-studio run <role>`.
|
||||
- `--dry-run` and `--print-prompt` are inspection-only paths.
|
||||
- Explicit, file-backed task orchestration is now inside the product boundary; telemetry, planner/next, ownership enforcement, hosted orchestration, background loops, and unbounded parallelism remain future-only.
|
||||
- Read `docs/architecture/product-boundary.md` before creating or revising designs, implementation plans, OpenSpec changes, template/project surfaces, role/workflow expansions, approval/write-policy behavior, or runtime execution behavior.
|
||||
|
||||
## Truthmark Notes
|
||||
|
||||
Keep the Truthmark-managed block in `AGENTS.md` intact. If these rules change in `AGENTS.md`, update this file in the same pass.
|
||||
@@ -56,7 +56,7 @@ External tools, reference workflows, and comparison projects may inspire improve
|
||||
8. **Mutation is policy-gated and visible.** Any design that lets Codex or the CLI mutate files must specify write policy, approval/override behavior, sandbox selection, dry-run diagnostics, and where provenance is recorded.
|
||||
9. **Future-only surfaces must remain absent until built.** Planner/next, telemetry, hard output-ownership enforcement, hosted orchestration, background autonomous loops, and unbounded parallelism must not appear as user-facing behavior before they have implementation, tests, and docs.
|
||||
10. **Validation is part of the product.** New generated surfaces, package assets, CLI commands, orchestration behavior, and behavior-bearing docs need repo-native validation and tests before readiness or parity claims.
|
||||
11. **Truthmark is repository workflow tooling here, not the product.** Truthmark-backed docs may guard Codex Game Studio's repository truth, but Codex Game Studio should not present Truthmark workflow mechanics as game-studio product features.
|
||||
11. **Documentation impact is part of the game workflow.** Functional game changes require a bounded documentation-impact decision with reviewable evidence; the template does not present repository-maintenance tooling as a game-studio product feature.
|
||||
|
||||
## In Scope
|
||||
|
||||
|
||||
@@ -1,25 +0,0 @@
|
||||
---
|
||||
status: active
|
||||
doc_type: standard
|
||||
last_reviewed: 2026-05-30
|
||||
source_of_truth:
|
||||
- README.md
|
||||
---
|
||||
|
||||
# Default Principles
|
||||
|
||||
## Scope
|
||||
|
||||
This is a bootstrap standards baseline for repositories that adopt Truthmark.
|
||||
|
||||
## Reusable Defaults
|
||||
|
||||
- Authority order should be explicit.
|
||||
- Committed repository artifacts are the durable source of truth.
|
||||
- Each document should have one primary responsibility.
|
||||
- Each class of fact should have one canonical source.
|
||||
- Architecture docs describe system structure, module boundaries, runtime topology, persistence boundaries, cross-cutting contracts, 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.
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
status: active
|
||||
doc_type: standard
|
||||
last_reviewed: 2026-05-30
|
||||
last_reviewed: 2026-07-10
|
||||
source_of_truth:
|
||||
- README.md
|
||||
---
|
||||
@@ -10,17 +10,19 @@ source_of_truth:
|
||||
|
||||
## Core Rules
|
||||
|
||||
- Each document should have one primary responsibility.
|
||||
- Each class of fact should have one canonical source.
|
||||
- Current implementation, reusable standards, and future proposals should be stored separately.
|
||||
- Each document has one primary responsibility.
|
||||
- Each class of fact has one canonical source.
|
||||
- Current implementation, reusable standards, and future proposals stay separate.
|
||||
- Generated helper output is never canonical truth.
|
||||
- The root README is the concise human storefront; command reference, role catalog, generated-file detail, and contributor workflow detail belong in linked subdocs.
|
||||
- Material root README changes should update localized README storefronts under `docs/readmes/` in the same change or state why they intentionally differ.
|
||||
- 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.
|
||||
- Material root README changes update localized README storefronts under `docs/readmes/` in the same change or state why they intentionally differ.
|
||||
- Architecture docs describe structure, ownership, and runtime views; design and production records describe the current game.
|
||||
|
||||
## Truthmark Implications
|
||||
## Initialized Game Documentation
|
||||
|
||||
- Truth Sync should extend mapped docs first, create an area-local doc second, and create a new area only as a last resort.
|
||||
- Weak routing produces weak truth maintenance.
|
||||
- Missing, stale, broad, overloaded, or unrouteable routing should trigger Truth Structure before more generic truth docs are created.
|
||||
- `design/` owns player-facing rules, systems, controls, and content intent.
|
||||
- `docs/architecture/` owns technical boundaries and durable architecture decisions.
|
||||
- `production/` owns milestone, ownership, handoff, and documentation-impact records.
|
||||
- `docs/changelog.md` and `docs/patch-notes.md` own release-visible communications.
|
||||
- Functional source, engine, or asset changes require an updated owner document or an explicit `no-update` decision in `production/session-state/active.md`.
|
||||
- `./codex-game-studio docs-impact --base <review-base>` validates the record against the changed paths; it checks evidence, not prose semantics.
|
||||
|
||||
@@ -1,15 +0,0 @@
|
||||
---
|
||||
status: active
|
||||
doc_type: index
|
||||
last_reviewed: 2026-06-25
|
||||
---
|
||||
|
||||
# Truth Docs
|
||||
|
||||
This directory is an index for current truth docs organized by the configured Truthmark hierarchy.
|
||||
|
||||
README.md files are indexes, not Truth Sync targets. Keep bounded truth in leaf docs under `<domain>/<behavior>.md`.
|
||||
|
||||
## Source References
|
||||
|
||||
- ../routes/areas.md
|
||||
@@ -1,15 +0,0 @@
|
||||
---
|
||||
status: active
|
||||
doc_type: index
|
||||
last_reviewed: 2026-06-29
|
||||
---
|
||||
|
||||
# Repository Truth Docs
|
||||
|
||||
This directory is reserved for narrow Truthmark repository handoffs.
|
||||
|
||||
The only retained repository handoff is [Repository Bootstrap Routing](bootstrap-routing.md). Do not rebuild broad Codex Game Studio behavior docs here unless a bounded Truthmark workflow explicitly requires them.
|
||||
|
||||
## Source References
|
||||
|
||||
- ../../routes/areas.md
|
||||
@@ -1,99 +0,0 @@
|
||||
---
|
||||
status: active
|
||||
truth_kind: engineering-workflow
|
||||
last_reviewed: 2026-06-26
|
||||
---
|
||||
|
||||
# Repository Bootstrap Routing
|
||||
|
||||
## Purpose
|
||||
|
||||
This doc records the provisional broad route for repository.
|
||||
This doc is a bootstrap handoff, not a behavior truth dumping ground.
|
||||
It is not a substitute for bounded product and engineering truth docs.
|
||||
|
||||
## Scope
|
||||
|
||||
This doc owns only the initial routing workflow for a fresh Truthmark repository.
|
||||
|
||||
It applies when the default route still maps a broad code surface such as `src/**`.
|
||||
|
||||
It does not own implementation behavior under that code surface.
|
||||
|
||||
## Current Implementation Behavior
|
||||
|
||||
The scaffold creates this provisional bootstrap handoff only when a default broad route needs a canonical owner.
|
||||
|
||||
Agents use it as a signal to run Truth Structure before normal Truth Sync.
|
||||
|
||||
Do not use this doc as a place to accumulate implementation claims.
|
||||
|
||||
## Product Truth Links
|
||||
|
||||
- None. This is an engineering bootstrap handoff for routing setup, not a product promise.
|
||||
|
||||
## Triggers
|
||||
|
||||
- A real code change maps only to this provisional broad route.
|
||||
- Truth Sync cannot identify a specific behavior-owned route and bounded truth owner.
|
||||
- A maintainer or agent is onboarding the first real product, service, domain, package, or ownership area.
|
||||
|
||||
## Inputs
|
||||
|
||||
- Current route files under the configured Truthmark route root.
|
||||
- The touched code, tests, configuration, and existing docs needed to infer the smallest real owner.
|
||||
- Repository instruction files that exist in the checkout.
|
||||
|
||||
## Execution Model
|
||||
|
||||
Run Truth Structure before normal Truth Sync when real code changes touch only this broad route.
|
||||
|
||||
Truth Structure should create or repair bounded areas first. Truth Sync should then update the bounded owner docs.
|
||||
|
||||
## Steps
|
||||
|
||||
1. Treat this route as provisional and insufficient for normal behavior maintenance.
|
||||
2. Inspect the touched code/test surface and infer the narrowest durable owner.
|
||||
3. Create or repair route entries and truth docs for that owner.
|
||||
4. Leave this bootstrap doc small; do not append behavior details here.
|
||||
5. Resume Truth Sync only after the touched code resolves to a bounded owner.
|
||||
|
||||
## State, Retry, And Failure Behavior
|
||||
|
||||
If ownership cannot be inferred safely, stop and report manual-review files.
|
||||
|
||||
Do not widen this route or add generic behavior prose.
|
||||
|
||||
## Outputs
|
||||
|
||||
- Bounded route areas and lane-appropriate truth docs for the touched surface.
|
||||
- A compact manual handoff report when ownership remains ambiguous.
|
||||
|
||||
## Engineering Decisions
|
||||
|
||||
- Decision (2026-06-18): Default broad routing is provisional bootstrap state.
|
||||
- Decision (2026-06-18): Agents should create bounded areas before normal Truth Sync.
|
||||
- Decision (2026-06-18): Agents should not extend a catch-all overview doc.
|
||||
|
||||
## Rationale
|
||||
|
||||
Scoped ownership keeps agent context close to affected files. It prevents broad default docs from absorbing unrelated behavior.
|
||||
|
||||
This preserves agent-native truth maintenance without adding a token-heavy discovery layer.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- This doc is not a repository behavior overview.
|
||||
- This doc is not a product capability or engineering behavior owner.
|
||||
- This doc is not a permanent home for claims about files under `src/**`.
|
||||
|
||||
## Maintenance Notes
|
||||
|
||||
Keep this doc short.
|
||||
|
||||
When a repository has real bounded routes, prefer updating those routes and their truth docs.
|
||||
|
||||
## Source References
|
||||
|
||||
- ../../routes/areas/repository.md
|
||||
- ../../../../.truthmark/config.yml
|
||||
@@ -1,15 +0,0 @@
|
||||
---
|
||||
status: active
|
||||
doc_type: index
|
||||
last_reviewed: 2026-06-29
|
||||
---
|
||||
|
||||
# Product Truth Docs
|
||||
|
||||
This directory is intentionally empty of product-specific leaf docs after the stale-doc purge.
|
||||
|
||||
Use the root `README.md`, `AGENTS.md`, tracked Codex surfaces, and tests as the primary product truth until a bounded Truthmark workflow explicitly creates a new product leaf doc.
|
||||
|
||||
## Source References
|
||||
|
||||
- ../routes/areas.md
|
||||
@@ -1,39 +0,0 @@
|
||||
---
|
||||
status: active
|
||||
doc_type: route-index
|
||||
last_reviewed: 2026-06-29
|
||||
---
|
||||
|
||||
# Truthmark Areas
|
||||
|
||||
The route index is intentionally small after the stale-doc purge.
|
||||
|
||||
## Repository
|
||||
|
||||
Area files:
|
||||
|
||||
- docs/truthmark/routes/areas/repository.md
|
||||
|
||||
Code surface:
|
||||
|
||||
- AGENTS.md
|
||||
- README.md
|
||||
- docs/**
|
||||
- src/**
|
||||
- tests/**
|
||||
- scripts/**
|
||||
- templates/**
|
||||
- engine_configs/**
|
||||
- engine_reference/**
|
||||
- references/**
|
||||
- package.json
|
||||
- package-lock.json
|
||||
|
||||
Update truth when:
|
||||
|
||||
- repository instructions, CLI behavior, validation, package assets, or remaining docs change
|
||||
- a future Truthmark workflow creates a narrower bounded area
|
||||
|
||||
## Source References
|
||||
|
||||
- ../../../.truthmark/config.yml
|
||||
@@ -1,45 +0,0 @@
|
||||
---
|
||||
status: active
|
||||
doc_type: routing
|
||||
last_reviewed: 2026-06-29
|
||||
---
|
||||
|
||||
# Repository Area
|
||||
|
||||
## Repository
|
||||
|
||||
Truth documents:
|
||||
|
||||
```yaml
|
||||
truth_documents:
|
||||
- path: docs/truthmark/engineering/repository/bootstrap-routing.md
|
||||
kind: engineering-workflow
|
||||
lane: engineering
|
||||
```
|
||||
|
||||
Code surface:
|
||||
|
||||
- AGENTS.md
|
||||
- README.md
|
||||
- docs/\*\*
|
||||
- src/\*\*
|
||||
- tests/\*\*
|
||||
- scripts/\*\*
|
||||
- templates/\*\*
|
||||
- engine_configs/\*\*
|
||||
- engine_reference/\*\*
|
||||
- references/\*\*
|
||||
- package.json
|
||||
- package-lock.json
|
||||
|
||||
Update truth when:
|
||||
|
||||
- repository instructions or product boundaries change
|
||||
- CLI, validation, task, role, workflow, template, engine-reference, or package behavior changes
|
||||
- a future Truthmark workflow creates a narrower bounded owner
|
||||
|
||||
## Source References
|
||||
|
||||
- ../areas.md
|
||||
- ../../../../.truthmark/config.yml
|
||||
- ../../engineering/repository/bootstrap-routing.md
|
||||
@@ -1,125 +0,0 @@
|
||||
---
|
||||
status: active
|
||||
truth_kind: engineering-architecture
|
||||
last_reviewed: 2026-06-16
|
||||
---
|
||||
|
||||
# {{title}}
|
||||
|
||||
## Purpose
|
||||
|
||||
<!--
|
||||
State the software-engineering outcome this document protects and why the documented surface exists.
|
||||
Include durable value, impacted users/systems, and the problem boundary; exclude roadmap, implementation plans, and historical narrative.
|
||||
Keep claims traceable to Source References rather than prose-only assertion.
|
||||
-->
|
||||
|
||||
{{purpose}}
|
||||
|
||||
## Scope
|
||||
|
||||
<!--
|
||||
Define the one coherent surface this document owns, including actors, entrypoints, owned state/data, and handoffs to neighboring truth docs.
|
||||
Call out important out-of-scope boundaries here or in Non-Goals; split the doc when it mixes distinct outcomes, lifecycles, contracts, or owners.
|
||||
-->
|
||||
|
||||
{{scope}}
|
||||
|
||||
## System Role
|
||||
|
||||
<!--
|
||||
Describe the current architectural role of this subsystem/component in the larger system.
|
||||
State the primary responsibilities, consumers, providers, and why this boundary exists now.
|
||||
-->
|
||||
|
||||
{{system_role}}
|
||||
|
||||
## Boundaries
|
||||
|
||||
<!--
|
||||
Define owned code/config/data, external dependencies, trust boundaries, and interfaces crossed by this architecture.
|
||||
Name what is deliberately outside the boundary and link neighboring architecture or contract docs when they own it.
|
||||
-->
|
||||
|
||||
{{boundaries}}
|
||||
|
||||
## Components
|
||||
|
||||
<!--
|
||||
List the major runtime/build-time components, modules, services, jobs, or generated artifacts and their responsibilities.
|
||||
Keep the component list current and evidence-backed; avoid speculative target architecture.
|
||||
-->
|
||||
|
||||
{{components}}
|
||||
|
||||
## Data And Control Flow
|
||||
|
||||
<!--
|
||||
Describe important data movement, command/control paths, synchronization points, state ownership, and failure paths.
|
||||
Call out persistence, queues, caches, external calls, and security-sensitive transitions where relevant.
|
||||
-->
|
||||
|
||||
{{data_and_control_flow}}
|
||||
|
||||
## Ownership
|
||||
|
||||
<!--
|
||||
Document team/module ownership, review responsibility, operational responsibility, and escalation paths if known.
|
||||
If ownership is inferred from codeowners, config, or repository structure, cite that evidence.
|
||||
-->
|
||||
|
||||
{{ownership}}
|
||||
|
||||
## Cross-Cutting Constraints
|
||||
|
||||
<!--
|
||||
Record active constraints such as security, privacy, reliability, performance, portability, maintainability, compliance, and cost.
|
||||
Tie constraints to source evidence, tests, standards, or operational requirements where available.
|
||||
-->
|
||||
|
||||
{{cross_cutting_constraints}}
|
||||
|
||||
## Engineering Decisions
|
||||
|
||||
<!--
|
||||
Keep active engineering, architecture, contract, workflow, or operational decisions only, dated inline when added or changed.
|
||||
Do not restate product promises, product rationale, or business decisions here; link product truth instead.
|
||||
Replace stale decisions instead of appending historical logs.
|
||||
-->
|
||||
|
||||
{{engineering_decisions}}
|
||||
|
||||
## Rationale
|
||||
|
||||
<!--
|
||||
Explain why the current behavior, structure, or contract is this way, including tradeoffs and constraints.
|
||||
Tie rationale to evidence-backed facts and active decisions; do not use this as a changelog.
|
||||
-->
|
||||
|
||||
{{rationale}}
|
||||
|
||||
## Non-Goals
|
||||
|
||||
<!--
|
||||
Name adjacent behavior, responsibilities, interfaces, or future expansions this doc intentionally does not own.
|
||||
Use this section to prevent scope creep and duplicate truth ownership.
|
||||
-->
|
||||
|
||||
{{non_goals}}
|
||||
|
||||
## Maintenance Notes
|
||||
|
||||
<!--
|
||||
List related tests, routing cautions, migration notes, compatibility risks, evidence drift risks, and review triggers for future maintainers or agents.
|
||||
Keep this operational and current-state focused, not historical.
|
||||
-->
|
||||
|
||||
{{maintenance_notes}}
|
||||
|
||||
## Source References
|
||||
|
||||
<!--
|
||||
List source files, tests, configs, generated templates, route files, or product instructions that support current claims.
|
||||
-->
|
||||
|
||||
{{source_references}}
|
||||
@@ -1,130 +0,0 @@
|
||||
---
|
||||
status: active
|
||||
truth_kind: engineering-behavior
|
||||
last_reviewed: 2026-06-16
|
||||
---
|
||||
|
||||
# {{title}}
|
||||
|
||||
## Purpose
|
||||
|
||||
<!--
|
||||
State the user/system outcome this behavior protects and why it exists.
|
||||
Include the problem boundary and durable value; exclude roadmap, implementation plan, and historical narrative.
|
||||
List the code, config, docs, or tests that support the claim in Source References rather than prose-only assertion.
|
||||
-->
|
||||
|
||||
{{purpose}}
|
||||
|
||||
## Scope
|
||||
|
||||
<!--
|
||||
Define the one coherent behavior surface this document owns.
|
||||
Include in-scope actors, entrypoints, state/data owned by this doc, and explicit handoffs to neighboring truth docs.
|
||||
Split into another leaf doc when content introduces a distinct outcome, state machine, rule family, external contract, or route owner.
|
||||
Keep README.md files as indexes only.
|
||||
-->
|
||||
|
||||
{{scope}}
|
||||
|
||||
This doc was created from the editable engineering-behavior template at {{template_path}}.
|
||||
|
||||
## Current Implementation Behavior
|
||||
|
||||
<!--
|
||||
Describe only current implemented behavior in present tense.
|
||||
Cover observable behavior, important defaults, and user/system-visible effects; exclude desired future behavior and speculative design.
|
||||
Every non-obvious claim should be checkable from Source References.
|
||||
-->
|
||||
|
||||
{{current_implementation_behavior}}
|
||||
|
||||
## Core Rules
|
||||
|
||||
<!--
|
||||
Capture stable business rules, invariants, precedence rules, validation rules, and must-never constraints.
|
||||
Separate rules from incidental implementation details; cite current implementation or tests for rule enforcement.
|
||||
-->
|
||||
|
||||
{{core_rules}}
|
||||
|
||||
## Behavior Scenarios
|
||||
|
||||
<!--
|
||||
Use compact scenario blocks only where they clarify normal, fallback, or compatibility-critical behavior.
|
||||
Write scenarios as current truth, not desired requirements: `#### Scenario: <implemented case>` followed by `- **GIVEN** ...`, `- **WHEN** ...`, `- **THEN** ...`, and optional `- **AND** ...` bullets.
|
||||
Keep each bullet evidence-backed and observable; do not force a scenario for every rule.
|
||||
-->
|
||||
|
||||
{{behavior_scenarios}}
|
||||
|
||||
## Flows And States
|
||||
|
||||
<!--
|
||||
Document state transitions, lifecycle stages, retries, fallbacks, route switches, and important error paths.
|
||||
State 'None beyond current behavior.' when this behavior has no distinct flow or state model.
|
||||
-->
|
||||
|
||||
{{flows_and_states}}
|
||||
|
||||
## Contracts
|
||||
|
||||
<!--
|
||||
Capture user-visible or integration contracts: CLI/API shape, inputs, outputs, diagnostics, files, events, permissions, or links to canonical contract docs.
|
||||
Avoid duplicating a separate canonical contract doc; link to it when contract ownership lives elsewhere.
|
||||
-->
|
||||
|
||||
{{contracts}}
|
||||
|
||||
## Product Truth Links
|
||||
|
||||
<!--
|
||||
List product truth docs this engineering doc realizes; author canonical realizes links in route YAML, not doc frontmatter.
|
||||
Use 'None.' when this is purely internal engineering behavior.
|
||||
-->
|
||||
|
||||
{{product_truth_links}}
|
||||
|
||||
## Engineering Decisions
|
||||
|
||||
<!--
|
||||
Keep active decisions only, dated inline when added or changed.
|
||||
Explain decisions that shape behavior, boundaries, rejected alternatives, or migration constraints; replace stale decisions instead of appending historical logs.
|
||||
-->
|
||||
|
||||
{{engineering_decisions}}
|
||||
|
||||
## Rationale
|
||||
|
||||
<!--
|
||||
Explain why the current behavior and active decisions are this way, including tradeoffs and constraints.
|
||||
Tie rationale to evidence-backed behavior; do not use this as a changelog.
|
||||
-->
|
||||
|
||||
{{rationale}}
|
||||
|
||||
## Non-Goals
|
||||
|
||||
<!--
|
||||
Name adjacent behavior this doc intentionally does not own, especially tempting future expansions or neighboring route owners.
|
||||
Use this section to prevent scope creep and duplicate truth ownership.
|
||||
-->
|
||||
|
||||
{{non_goals}}
|
||||
|
||||
## Maintenance Notes
|
||||
|
||||
<!--
|
||||
List related tests, routing cautions, migration notes, evidence drift risks, and review triggers for future maintainers or agents.
|
||||
Keep this operational and current-state focused, not historical.
|
||||
-->
|
||||
|
||||
{{maintenance_notes}}
|
||||
|
||||
## Source References
|
||||
|
||||
<!--
|
||||
List source files, tests, configs, generated templates, route files, or product instructions that support current claims.
|
||||
-->
|
||||
|
||||
{{source_references}}
|
||||
@@ -1,125 +0,0 @@
|
||||
---
|
||||
status: active
|
||||
truth_kind: engineering-contract
|
||||
last_reviewed: 2026-06-16
|
||||
---
|
||||
|
||||
# {{title}}
|
||||
|
||||
## Purpose
|
||||
|
||||
<!--
|
||||
State the software-engineering outcome this document protects and why the documented surface exists.
|
||||
Include durable value, impacted users/systems, and the problem boundary; exclude roadmap, implementation plans, and historical narrative.
|
||||
Keep claims traceable to Source References rather than prose-only assertion.
|
||||
-->
|
||||
|
||||
{{purpose}}
|
||||
|
||||
## Scope
|
||||
|
||||
<!--
|
||||
Define the one coherent surface this document owns, including actors, entrypoints, owned state/data, and handoffs to neighboring truth docs.
|
||||
Call out important out-of-scope boundaries here or in Non-Goals; split the doc when it mixes distinct outcomes, lifecycles, contracts, or owners.
|
||||
-->
|
||||
|
||||
{{scope}}
|
||||
|
||||
## Contract Surface
|
||||
|
||||
<!--
|
||||
Identify the owned API, CLI, file format, event, protocol, permission boundary, or integration surface.
|
||||
State consumers/producers, stability level, and the source files/tests that define the contract.
|
||||
-->
|
||||
|
||||
{{contract_surface}}
|
||||
|
||||
## Inputs
|
||||
|
||||
<!--
|
||||
Document accepted parameters, payloads, files, environment/config keys, permissions, and validation rules.
|
||||
Include required/optional status, defaults, constraints, and normalization behavior.
|
||||
-->
|
||||
|
||||
{{inputs}}
|
||||
|
||||
## Outputs
|
||||
|
||||
<!--
|
||||
Document returned values, emitted files/events, state changes, side effects, and success diagnostics.
|
||||
Make externally observable behavior explicit enough for compatibility review.
|
||||
-->
|
||||
|
||||
{{outputs}}
|
||||
|
||||
## Errors And Diagnostics
|
||||
|
||||
<!--
|
||||
List error classes, exit/status codes, user-facing diagnostics, retries, and recoverability expectations.
|
||||
Distinguish validation errors, dependency failures, authorization failures, and internal faults when applicable.
|
||||
-->
|
||||
|
||||
{{errors_and_diagnostics}}
|
||||
|
||||
## Compatibility Rules
|
||||
|
||||
<!--
|
||||
State backward/forward compatibility guarantees, tolerated inputs, deprecation rules, and breaking-change triggers.
|
||||
Include compatibility tests or review questions that protect the contract.
|
||||
-->
|
||||
|
||||
{{compatibility_rules}}
|
||||
|
||||
## Versioning And Migration
|
||||
|
||||
<!--
|
||||
Document version negotiation, schema/API version fields, rollout requirements, migration steps, and rollback expectations.
|
||||
State 'Not versioned' only when the implementation truly has no versioning or migration surface.
|
||||
-->
|
||||
|
||||
{{versioning_and_migration}}
|
||||
|
||||
## Engineering Decisions
|
||||
|
||||
<!--
|
||||
Keep active engineering, architecture, contract, workflow, or operational decisions only, dated inline when added or changed.
|
||||
Do not restate product promises, product rationale, or business decisions here; link product truth instead.
|
||||
Replace stale decisions instead of appending historical logs.
|
||||
-->
|
||||
|
||||
{{engineering_decisions}}
|
||||
|
||||
## Rationale
|
||||
|
||||
<!--
|
||||
Explain why the current behavior, structure, or contract is this way, including tradeoffs and constraints.
|
||||
Tie rationale to evidence-backed facts and active decisions; do not use this as a changelog.
|
||||
-->
|
||||
|
||||
{{rationale}}
|
||||
|
||||
## Non-Goals
|
||||
|
||||
<!--
|
||||
Name adjacent behavior, responsibilities, interfaces, or future expansions this doc intentionally does not own.
|
||||
Use this section to prevent scope creep and duplicate truth ownership.
|
||||
-->
|
||||
|
||||
{{non_goals}}
|
||||
|
||||
## Maintenance Notes
|
||||
|
||||
<!--
|
||||
List related tests, routing cautions, migration notes, compatibility risks, evidence drift risks, and review triggers for future maintainers or agents.
|
||||
Keep this operational and current-state focused, not historical.
|
||||
-->
|
||||
|
||||
{{maintenance_notes}}
|
||||
|
||||
## Source References
|
||||
|
||||
<!--
|
||||
List source files, tests, configs, generated templates, route files, or product instructions that support current claims.
|
||||
-->
|
||||
|
||||
{{source_references}}
|
||||
@@ -1,125 +0,0 @@
|
||||
---
|
||||
status: active
|
||||
truth_kind: engineering-operations
|
||||
last_reviewed: 2026-06-16
|
||||
---
|
||||
|
||||
# {{title}}
|
||||
|
||||
## Purpose
|
||||
|
||||
<!--
|
||||
State the software-engineering outcome this document protects and why the documented surface exists.
|
||||
Include durable value, impacted users/systems, and the problem boundary; exclude roadmap, implementation plans, and historical narrative.
|
||||
Keep claims traceable to Source References rather than prose-only assertion.
|
||||
-->
|
||||
|
||||
{{purpose}}
|
||||
|
||||
## Scope
|
||||
|
||||
<!--
|
||||
Define the one coherent surface this document owns, including actors, entrypoints, owned state/data, and handoffs to neighboring truth docs.
|
||||
Call out important out-of-scope boundaries here or in Non-Goals; split the doc when it mixes distinct outcomes, lifecycles, contracts, or owners.
|
||||
-->
|
||||
|
||||
{{scope}}
|
||||
|
||||
## Operational Surface
|
||||
|
||||
<!--
|
||||
Describe what operators, maintainers, or automated systems can observe or control for this surface.
|
||||
Include commands, dashboards, alerts, runbooks, jobs, or operational APIs that define current operations.
|
||||
-->
|
||||
|
||||
{{operational_surface}}
|
||||
|
||||
## Runtime Topology
|
||||
|
||||
<!--
|
||||
Document services, processes, containers, hosts, regions, dependencies, queues, stores, and network boundaries involved at runtime.
|
||||
State single-node/local behavior explicitly when there is no distributed topology.
|
||||
-->
|
||||
|
||||
{{runtime_topology}}
|
||||
|
||||
## Configuration
|
||||
|
||||
<!--
|
||||
List operational config, environment variables, feature flags, secrets references, defaults, and reload/restart requirements.
|
||||
Do not include secret values; describe storage and rotation expectations instead.
|
||||
-->
|
||||
|
||||
{{configuration}}
|
||||
|
||||
## Permissions
|
||||
|
||||
<!--
|
||||
Document required identities, roles, scopes, filesystem/network permissions, and least-privilege boundaries.
|
||||
Include user-facing authorization behavior and operator access requirements when relevant.
|
||||
-->
|
||||
|
||||
{{permissions}}
|
||||
|
||||
## Deployment And Rollback
|
||||
|
||||
<!--
|
||||
Describe deployment mechanism, migration ordering, compatibility windows, rollback path, and known irreversible operations.
|
||||
Call out manual review points, smoke checks, and post-deploy verification responsibilities.
|
||||
-->
|
||||
|
||||
{{deployment_and_rollback}}
|
||||
|
||||
## Availability And Observability
|
||||
|
||||
<!--
|
||||
Capture availability expectations, health checks, metrics, logs, traces, alerts, SLO/error-budget signals, and known blind spots.
|
||||
Include what maintainers should inspect first during incidents or degraded behavior.
|
||||
-->
|
||||
|
||||
{{availability_and_observability}}
|
||||
|
||||
## Engineering Decisions
|
||||
|
||||
<!--
|
||||
Keep active engineering, architecture, contract, workflow, or operational decisions only, dated inline when added or changed.
|
||||
Do not restate product promises, product rationale, or business decisions here; link product truth instead.
|
||||
Replace stale decisions instead of appending historical logs.
|
||||
-->
|
||||
|
||||
{{engineering_decisions}}
|
||||
|
||||
## Rationale
|
||||
|
||||
<!--
|
||||
Explain why the current behavior, structure, or contract is this way, including tradeoffs and constraints.
|
||||
Tie rationale to evidence-backed facts and active decisions; do not use this as a changelog.
|
||||
-->
|
||||
|
||||
{{rationale}}
|
||||
|
||||
## Non-Goals
|
||||
|
||||
<!--
|
||||
Name adjacent behavior, responsibilities, interfaces, or future expansions this doc intentionally does not own.
|
||||
Use this section to prevent scope creep and duplicate truth ownership.
|
||||
-->
|
||||
|
||||
{{non_goals}}
|
||||
|
||||
## Maintenance Notes
|
||||
|
||||
<!--
|
||||
List related tests, routing cautions, migration notes, compatibility risks, evidence drift risks, and review triggers for future maintainers or agents.
|
||||
Keep this operational and current-state focused, not historical.
|
||||
-->
|
||||
|
||||
{{maintenance_notes}}
|
||||
|
||||
## Source References
|
||||
|
||||
<!--
|
||||
List source files, tests, configs, generated templates, route files, or product instructions that support current claims.
|
||||
-->
|
||||
|
||||
{{source_references}}
|
||||
@@ -1,125 +0,0 @@
|
||||
---
|
||||
status: active
|
||||
truth_kind: engineering-test-behavior
|
||||
last_reviewed: 2026-06-16
|
||||
---
|
||||
|
||||
# {{title}}
|
||||
|
||||
## Purpose
|
||||
|
||||
<!--
|
||||
State the software-engineering outcome this document protects and why the documented surface exists.
|
||||
Include durable value, impacted users/systems, and the problem boundary; exclude roadmap, implementation plans, and historical narrative.
|
||||
Keep claims traceable to Source References rather than prose-only assertion.
|
||||
-->
|
||||
|
||||
{{purpose}}
|
||||
|
||||
## Scope
|
||||
|
||||
<!--
|
||||
Define the one coherent surface this document owns, including actors, entrypoints, owned state/data, and handoffs to neighboring truth docs.
|
||||
Call out important out-of-scope boundaries here or in Non-Goals; split the doc when it mixes distinct outcomes, lifecycles, contracts, or owners.
|
||||
-->
|
||||
|
||||
{{scope}}
|
||||
|
||||
## Test Surface
|
||||
|
||||
<!--
|
||||
Define the behavior, contract, architecture, or workflow surface these tests verify.
|
||||
Link the canonical truth docs and code paths the tests are meant to protect.
|
||||
-->
|
||||
|
||||
{{test_surface}}
|
||||
|
||||
## Fixtures And Data Model
|
||||
|
||||
<!--
|
||||
Document fixtures, factories, seeds, mocks/fakes, test repositories, external-service substitutes, and data lifecycle rules.
|
||||
Include cleanup, determinism, privacy, and cross-test contamination constraints.
|
||||
-->
|
||||
|
||||
{{fixtures_and_data_model}}
|
||||
|
||||
## Execution Model
|
||||
|
||||
<!--
|
||||
Describe how tests run: command, framework, parallelism, isolation, network/filesystem assumptions, and required services.
|
||||
State whether tests are unit, integration, e2e, contract, smoke, regression, or generated checks.
|
||||
-->
|
||||
|
||||
{{execution_model}}
|
||||
|
||||
## Assertions And Invariants
|
||||
|
||||
<!--
|
||||
List the critical assertions, invariants, failure modes, and negative cases that make the tests meaningful.
|
||||
Tie assertions to product/contract rules rather than incidental implementation details.
|
||||
-->
|
||||
|
||||
{{assertions_and_invariants}}
|
||||
|
||||
## Isolation Rules
|
||||
|
||||
<!--
|
||||
Document transaction boundaries, temp directories, fake clocks, network blocking, shared resources, and teardown rules.
|
||||
Call out known order dependencies or flake risks and how they are controlled.
|
||||
-->
|
||||
|
||||
{{isolation_rules}}
|
||||
|
||||
## Reporting And Failure Semantics
|
||||
|
||||
<!--
|
||||
Describe diagnostics, snapshots, logs, coverage signals, retry policy, and how maintainers should interpret failures.
|
||||
Include escalation or quarantine criteria for flaky or environment-sensitive tests.
|
||||
-->
|
||||
|
||||
{{reporting_and_failure_semantics}}
|
||||
|
||||
## Engineering Decisions
|
||||
|
||||
<!--
|
||||
Keep active engineering, architecture, contract, workflow, or operational decisions only, dated inline when added or changed.
|
||||
Do not restate product promises, product rationale, or business decisions here; link product truth instead.
|
||||
Replace stale decisions instead of appending historical logs.
|
||||
-->
|
||||
|
||||
{{engineering_decisions}}
|
||||
|
||||
## Rationale
|
||||
|
||||
<!--
|
||||
Explain why the current behavior, structure, or contract is this way, including tradeoffs and constraints.
|
||||
Tie rationale to evidence-backed facts and active decisions; do not use this as a changelog.
|
||||
-->
|
||||
|
||||
{{rationale}}
|
||||
|
||||
## Non-Goals
|
||||
|
||||
<!--
|
||||
Name adjacent behavior, responsibilities, interfaces, or future expansions this doc intentionally does not own.
|
||||
Use this section to prevent scope creep and duplicate truth ownership.
|
||||
-->
|
||||
|
||||
{{non_goals}}
|
||||
|
||||
## Maintenance Notes
|
||||
|
||||
<!--
|
||||
List related tests, routing cautions, migration notes, compatibility risks, evidence drift risks, and review triggers for future maintainers or agents.
|
||||
Keep this operational and current-state focused, not historical.
|
||||
-->
|
||||
|
||||
{{maintenance_notes}}
|
||||
|
||||
## Source References
|
||||
|
||||
<!--
|
||||
List source files, tests, configs, generated templates, route files, or product instructions that support current claims.
|
||||
-->
|
||||
|
||||
{{source_references}}
|
||||
@@ -1,125 +0,0 @@
|
||||
---
|
||||
status: active
|
||||
truth_kind: engineering-workflow
|
||||
last_reviewed: 2026-06-16
|
||||
---
|
||||
|
||||
# {{title}}
|
||||
|
||||
## Purpose
|
||||
|
||||
<!--
|
||||
State the software-engineering outcome this document protects and why the documented surface exists.
|
||||
Include durable value, impacted users/systems, and the problem boundary; exclude roadmap, implementation plans, and historical narrative.
|
||||
Keep claims traceable to Source References rather than prose-only assertion.
|
||||
-->
|
||||
|
||||
{{purpose}}
|
||||
|
||||
## Scope
|
||||
|
||||
<!--
|
||||
Define the one coherent surface this document owns, including actors, entrypoints, owned state/data, and handoffs to neighboring truth docs.
|
||||
Call out important out-of-scope boundaries here or in Non-Goals; split the doc when it mixes distinct outcomes, lifecycles, contracts, or owners.
|
||||
-->
|
||||
|
||||
{{scope}}
|
||||
|
||||
## Triggers
|
||||
|
||||
<!--
|
||||
List events, commands, schedules, user actions, webhooks, or dependency signals that start this workflow.
|
||||
Include preconditions, authorization requirements, debounce/coalescing behavior, and disabled states when applicable.
|
||||
-->
|
||||
|
||||
{{triggers}}
|
||||
|
||||
## Inputs
|
||||
|
||||
<!--
|
||||
Document data, files, config, context, credentials, and environmental assumptions consumed by the workflow.
|
||||
Include validation, defaults, and normalization that happen before execution.
|
||||
-->
|
||||
|
||||
{{inputs}}
|
||||
|
||||
## Execution Model
|
||||
|
||||
<!--
|
||||
Describe synchronous/asynchronous execution, concurrency, locking, leases, batching, ordering, and idempotency behavior.
|
||||
State whether the workflow waits for user action, runs in the background, is distributed, or is delegated to another system.
|
||||
-->
|
||||
|
||||
{{execution_model}}
|
||||
|
||||
## Steps
|
||||
|
||||
<!--
|
||||
Capture the current ordered steps or phases at a level useful for maintenance and review.
|
||||
Reference implementation entrypoints instead of duplicating line-by-line code behavior.
|
||||
-->
|
||||
|
||||
{{steps}}
|
||||
|
||||
## State, Retry, And Failure Behavior
|
||||
|
||||
<!--
|
||||
Document state transitions, retries, timeouts, compensation, fallback, partial-success, and terminal-failure behavior.
|
||||
Make externally visible failure semantics and recovery responsibilities clear.
|
||||
-->
|
||||
|
||||
{{state_retry_and_failure_behavior}}
|
||||
|
||||
## Outputs
|
||||
|
||||
<!--
|
||||
List artifacts, state changes, notifications, logs, metrics, diagnostics, and downstream triggers produced by the workflow.
|
||||
Include success criteria and handoff points to other truth docs or systems.
|
||||
-->
|
||||
|
||||
{{outputs}}
|
||||
|
||||
## Engineering Decisions
|
||||
|
||||
<!--
|
||||
Keep active engineering, architecture, contract, workflow, or operational decisions only, dated inline when added or changed.
|
||||
Do not restate product promises, product rationale, or business decisions here; link product truth instead.
|
||||
Replace stale decisions instead of appending historical logs.
|
||||
-->
|
||||
|
||||
{{engineering_decisions}}
|
||||
|
||||
## Rationale
|
||||
|
||||
<!--
|
||||
Explain why the current behavior, structure, or contract is this way, including tradeoffs and constraints.
|
||||
Tie rationale to evidence-backed facts and active decisions; do not use this as a changelog.
|
||||
-->
|
||||
|
||||
{{rationale}}
|
||||
|
||||
## Non-Goals
|
||||
|
||||
<!--
|
||||
Name adjacent behavior, responsibilities, interfaces, or future expansions this doc intentionally does not own.
|
||||
Use this section to prevent scope creep and duplicate truth ownership.
|
||||
-->
|
||||
|
||||
{{non_goals}}
|
||||
|
||||
## Maintenance Notes
|
||||
|
||||
<!--
|
||||
List related tests, routing cautions, migration notes, compatibility risks, evidence drift risks, and review triggers for future maintainers or agents.
|
||||
Keep this operational and current-state focused, not historical.
|
||||
-->
|
||||
|
||||
{{maintenance_notes}}
|
||||
|
||||
## Source References
|
||||
|
||||
<!--
|
||||
List source files, tests, configs, generated templates, route files, or product instructions that support current claims.
|
||||
-->
|
||||
|
||||
{{source_references}}
|
||||
@@ -1,94 +0,0 @@
|
||||
---
|
||||
status: active
|
||||
truth_kind: product-capability
|
||||
last_reviewed: 2026-06-16
|
||||
---
|
||||
|
||||
# {{title}}
|
||||
|
||||
<!--
|
||||
Do not make product docs a summary of engineering docs. Do not make engineering docs a detailed version of product docs. Product truth says what must be true and why. Engineering truth says how the repository currently realizes it.
|
||||
Product docs may cite code directly when code proves current product behavior, but keep implementation flow, renderer internals, CLI envelopes, and generated file inventories in engineering truth.
|
||||
-->
|
||||
|
||||
## Capability Promise
|
||||
|
||||
<!--
|
||||
State the single user-visible capability and what must be true for users or stakeholders.
|
||||
Do not describe implementation mechanics here.
|
||||
-->
|
||||
|
||||
{{capability_promise}}
|
||||
|
||||
## Users And Value
|
||||
|
||||
<!--
|
||||
Describe who benefits from the capability and the durable value it protects.
|
||||
Tie claims to repository evidence, explicit user instruction, or current behavior.
|
||||
-->
|
||||
|
||||
{{users_and_value}}
|
||||
|
||||
## Capability Scope
|
||||
|
||||
<!--
|
||||
Define what this capability includes and excludes, including product boundary constraints and adjacent systems.
|
||||
Capture important scope limits, ownership boundaries, and non-goal pointers here; keep technical contracts in engineering truth.
|
||||
-->
|
||||
|
||||
{{capability_scope}}
|
||||
|
||||
## Current Product Behavior
|
||||
|
||||
<!--
|
||||
Describe current implemented user-visible behavior in present tense.
|
||||
Code files may appear in Source References when they directly prove current behavior.
|
||||
-->
|
||||
|
||||
{{current_product_behavior}}
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
<!--
|
||||
List observable criteria that show the capability promise is currently satisfied.
|
||||
Include criteria that review whether the capability stays within its stated scope and boundary.
|
||||
Use criteria that can be reviewed from repository evidence or explicit product instruction.
|
||||
-->
|
||||
|
||||
{{acceptance_criteria}}
|
||||
|
||||
## Product Decisions
|
||||
|
||||
<!--
|
||||
Keep active decisions only, dated inline when added or changed.
|
||||
Capture decisions that shape behavior, interfaces, boundaries, compatibility, risk acceptance, or migration constraints.
|
||||
Replace stale decisions instead of appending historical logs.
|
||||
-->
|
||||
|
||||
{{decision}}
|
||||
|
||||
## Engineering Realization Links
|
||||
|
||||
<!--
|
||||
List engineering truth that realizes this product truth; author canonical realized_by links in route YAML, not doc frontmatter.
|
||||
Do not summarize those engineering docs.
|
||||
-->
|
||||
|
||||
{{engineering_realization_links}}
|
||||
|
||||
## Non-Goals
|
||||
|
||||
<!--
|
||||
Name adjacent behavior, responsibilities, interfaces, or future expansions this doc intentionally does not own.
|
||||
Use this section to prevent scope creep and duplicate truth ownership.
|
||||
-->
|
||||
|
||||
{{non_goals}}
|
||||
|
||||
## Source References
|
||||
|
||||
<!--
|
||||
List source files, tests, configs, generated templates, route files, or product instructions that support current claims.
|
||||
-->
|
||||
|
||||
{{source_references}}
|
||||
+2
-1
@@ -112,7 +112,8 @@ Project validation checks project state, tracked template surfaces, context meta
|
||||
| `resume` | Print a read-only continuation summary. |
|
||||
| `refresh-context` | Regenerate `.codex/context-manifest.json` after selected context files change. |
|
||||
| `freeze` | Mark a project as frozen. |
|
||||
| `validate` | Run hard-failing repository or project validation. |
|
||||
| `validate` | Run hard-failing repository or project validation; pass `--base <ref>` to include documentation-impact checks. |
|
||||
| `docs-impact --base <ref>` | Verify an active-session documentation-impact decision against functional changes from a Git base. |
|
||||
| `templates list` | List packaged template IDs. |
|
||||
| `templates show <template-id>` | Print a packaged template. |
|
||||
| `run <role>` | Prepare one bounded Codex prompt packet and invoke `codex exec`. |
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
This is Open Game Studio's maintainer-only framework for evaluating how skills, workflow prompts, and agent-facing surfaces perform in realistic runs.
|
||||
|
||||
It follows the CCGS pattern of catalog → rubric → behavioral scenario, and the Truthmark pattern of manual workflow-quality runs with deterministic boundaries, semantic judging, human review, and token tracking.
|
||||
It follows the CCGS pattern of catalog → rubric → behavioral scenario, with deterministic boundaries, semantic judging, human review, and token tracking.
|
||||
|
||||
Normal game-project users do not need this folder. It is not a hidden runtime, daemon, hosted service, or downstream requirement. If a downstream game repository only wants to build a game and not maintain Open Game Studio's prompt surfaces, users may delete `eval-framework/` and the related maintainer-only OpenSpec change files from their copy.
|
||||
|
||||
|
||||
@@ -1,20 +0,0 @@
|
||||
schema: spec-driven
|
||||
|
||||
# Project context (optional)
|
||||
# This is shown to AI when creating artifacts.
|
||||
# Add your tech stack, conventions, style guides, domain knowledge, etc.
|
||||
# Example:
|
||||
# context: |
|
||||
# Tech stack: TypeScript, React, Node.js
|
||||
# We use conventional commits
|
||||
# Domain: e-commerce platform
|
||||
|
||||
# Per-artifact rules (optional)
|
||||
# Add custom rules for specific artifacts.
|
||||
# Example:
|
||||
# rules:
|
||||
# proposal:
|
||||
# - Keep proposals under 500 words
|
||||
# - Always include a "Non-goals" section
|
||||
# tasks:
|
||||
# - Break tasks into chunks of max 2 hours
|
||||
Generated
-1337
File diff suppressed because it is too large
Load Diff
@@ -42,7 +42,6 @@
|
||||
"devDependencies": {
|
||||
"@types/node": "^24.13.2",
|
||||
"expect": "^30.4.1",
|
||||
"truthmark": "^2.2.6",
|
||||
"tsx": "^4.20.6",
|
||||
"typescript": "^5.9.3"
|
||||
}
|
||||
|
||||
@@ -2017,7 +2017,7 @@
|
||||
"tests/workflow-recipes.test.ts",
|
||||
"tests/validation.test.ts"
|
||||
],
|
||||
"lineCount": 84,
|
||||
"lineCount": 90,
|
||||
"depthScore": 56,
|
||||
"metadata": {
|
||||
"model": true,
|
||||
@@ -2045,7 +2045,7 @@
|
||||
"tests/workflow-recipes.test.ts",
|
||||
"tests/validation.test.ts"
|
||||
],
|
||||
"lineCount": 84,
|
||||
"lineCount": 89,
|
||||
"depthScore": 56,
|
||||
"metadata": {
|
||||
"model": true,
|
||||
@@ -2073,7 +2073,7 @@
|
||||
"tests/workflow-recipes.test.ts",
|
||||
"tests/validation.test.ts"
|
||||
],
|
||||
"lineCount": 84,
|
||||
"lineCount": 90,
|
||||
"depthScore": 56,
|
||||
"metadata": {
|
||||
"model": true,
|
||||
@@ -2493,7 +2493,7 @@
|
||||
"tests/workflow-recipes.test.ts",
|
||||
"tests/validation.test.ts"
|
||||
],
|
||||
"lineCount": 84,
|
||||
"lineCount": 90,
|
||||
"depthScore": 56,
|
||||
"metadata": {
|
||||
"model": true,
|
||||
@@ -2521,7 +2521,7 @@
|
||||
"tests/workflow-recipes.test.ts",
|
||||
"tests/validation.test.ts"
|
||||
],
|
||||
"lineCount": 84,
|
||||
"lineCount": 90,
|
||||
"depthScore": 56,
|
||||
"metadata": {
|
||||
"model": true,
|
||||
@@ -2689,7 +2689,7 @@
|
||||
"tests/workflow-recipes.test.ts",
|
||||
"tests/validation.test.ts"
|
||||
],
|
||||
"lineCount": 84,
|
||||
"lineCount": 89,
|
||||
"depthScore": 56,
|
||||
"metadata": {
|
||||
"model": true,
|
||||
@@ -3165,7 +3165,7 @@
|
||||
"tests/workflow-recipes.test.ts",
|
||||
"tests/validation.test.ts"
|
||||
],
|
||||
"lineCount": 84,
|
||||
"lineCount": 90,
|
||||
"depthScore": 56,
|
||||
"metadata": {
|
||||
"model": true,
|
||||
|
||||
@@ -67,9 +67,9 @@ Decisions: adopt, adapt, merge, split, defer, out-of-scope.
|
||||
| workflow | `.codex/workflows/balance-check.md` | | defer | deferred | 84 | | 56 | yes | pass | `tests/workflow-catalog.test.ts`<br>`tests/workflow-recipes.test.ts`<br>`tests/validation.test.ts` |
|
||||
| workflow | `.codex/workflows/brainstorm.md` | | defer | deferred | 85 | | 56 | yes | pass | `tests/workflow-catalog.test.ts`<br>`tests/workflow-recipes.test.ts`<br>`tests/validation.test.ts` |
|
||||
| workflow | `.codex/workflows/bug-report.md` | | defer | deferred | 84 | | 56 | yes | pass | `tests/workflow-catalog.test.ts`<br>`tests/workflow-recipes.test.ts`<br>`tests/validation.test.ts` |
|
||||
| workflow | `.codex/workflows/bugfix.md` | | defer | deferred | 84 | | 56 | yes | pass | `tests/workflow-catalog.test.ts`<br>`tests/workflow-recipes.test.ts`<br>`tests/validation.test.ts` |
|
||||
| workflow | `.codex/workflows/changelog.md` | | defer | deferred | 84 | | 56 | yes | pass | `tests/workflow-catalog.test.ts`<br>`tests/workflow-recipes.test.ts`<br>`tests/validation.test.ts` |
|
||||
| workflow | `.codex/workflows/code-review.md` | | defer | deferred | 84 | | 56 | yes | pass | `tests/workflow-catalog.test.ts`<br>`tests/workflow-recipes.test.ts`<br>`tests/validation.test.ts` |
|
||||
| workflow | `.codex/workflows/bugfix.md` | | defer | deferred | 90 | | 56 | yes | pass | `tests/workflow-catalog.test.ts`<br>`tests/workflow-recipes.test.ts`<br>`tests/validation.test.ts` |
|
||||
| workflow | `.codex/workflows/changelog.md` | | defer | deferred | 89 | | 56 | yes | pass | `tests/workflow-catalog.test.ts`<br>`tests/workflow-recipes.test.ts`<br>`tests/validation.test.ts` |
|
||||
| workflow | `.codex/workflows/code-review.md` | | defer | deferred | 90 | | 56 | yes | pass | `tests/workflow-catalog.test.ts`<br>`tests/workflow-recipes.test.ts`<br>`tests/validation.test.ts` |
|
||||
| workflow | `.codex/workflows/consistency-check.md` | | defer | deferred | 86 | | 56 | yes | pass | `tests/workflow-catalog.test.ts`<br>`tests/workflow-recipes.test.ts`<br>`tests/validation.test.ts` |
|
||||
| workflow | `.codex/workflows/control-manifest.md` | | defer | deferred | 84 | | 56 | yes | pass | `tests/workflow-catalog.test.ts`<br>`tests/workflow-recipes.test.ts`<br>`tests/validation.test.ts` |
|
||||
| workflow | `.codex/workflows/create-architecture.md` | | defer | deferred | 85 | | 56 | yes | pass | `tests/workflow-catalog.test.ts`<br>`tests/workflow-recipes.test.ts`<br>`tests/validation.test.ts` |
|
||||
@@ -84,14 +84,14 @@ Decisions: adopt, adapt, merge, split, defer, out-of-scope.
|
||||
| workflow | `.codex/workflows/game-concept.md` | | defer | deferred | 84 | | 56 | yes | pass | `tests/workflow-catalog.test.ts`<br>`tests/workflow-recipes.test.ts`<br>`tests/validation.test.ts` |
|
||||
| workflow | `.codex/workflows/game-feel-tuning.md` | | defer | deferred | 84 | | 56 | yes | pass | `tests/workflow-catalog.test.ts`<br>`tests/workflow-recipes.test.ts`<br>`tests/validation.test.ts` |
|
||||
| workflow | `.codex/workflows/handoff.md` | | defer | deferred | 84 | | 56 | yes | pass | `tests/workflow-catalog.test.ts`<br>`tests/workflow-recipes.test.ts`<br>`tests/validation.test.ts` |
|
||||
| workflow | `.codex/workflows/hotfix.md` | | defer | deferred | 84 | | 56 | yes | pass | `tests/workflow-catalog.test.ts`<br>`tests/workflow-recipes.test.ts`<br>`tests/validation.test.ts` |
|
||||
| workflow | `.codex/workflows/implement.md` | | defer | deferred | 84 | | 56 | yes | pass | `tests/workflow-catalog.test.ts`<br>`tests/workflow-recipes.test.ts`<br>`tests/validation.test.ts` |
|
||||
| workflow | `.codex/workflows/hotfix.md` | | defer | deferred | 90 | | 56 | yes | pass | `tests/workflow-catalog.test.ts`<br>`tests/workflow-recipes.test.ts`<br>`tests/validation.test.ts` |
|
||||
| workflow | `.codex/workflows/implement.md` | | defer | deferred | 90 | | 56 | yes | pass | `tests/workflow-catalog.test.ts`<br>`tests/workflow-recipes.test.ts`<br>`tests/validation.test.ts` |
|
||||
| workflow | `.codex/workflows/launch-checklist.md` | | defer | deferred | 84 | | 56 | yes | pass | `tests/workflow-catalog.test.ts`<br>`tests/workflow-recipes.test.ts`<br>`tests/validation.test.ts` |
|
||||
| workflow | `.codex/workflows/localization-plan.md` | | defer | deferred | 85 | | 56 | yes | pass | `tests/workflow-catalog.test.ts`<br>`tests/workflow-recipes.test.ts`<br>`tests/validation.test.ts` |
|
||||
| workflow | `.codex/workflows/map-systems.md` | | defer | deferred | 85 | | 56 | yes | pass | `tests/workflow-catalog.test.ts`<br>`tests/workflow-recipes.test.ts`<br>`tests/validation.test.ts` |
|
||||
| workflow | `.codex/workflows/market-analysis.md` | | defer | deferred | 85 | | 56 | yes | pass | `tests/workflow-catalog.test.ts`<br>`tests/workflow-recipes.test.ts`<br>`tests/validation.test.ts` |
|
||||
| workflow | `.codex/workflows/onboard.md` | | defer | deferred | 87 | | 56 | yes | pass | `tests/workflow-catalog.test.ts`<br>`tests/workflow-recipes.test.ts`<br>`tests/validation.test.ts` |
|
||||
| workflow | `.codex/workflows/patch-notes.md` | | defer | deferred | 84 | | 56 | yes | pass | `tests/workflow-catalog.test.ts`<br>`tests/workflow-recipes.test.ts`<br>`tests/validation.test.ts` |
|
||||
| workflow | `.codex/workflows/patch-notes.md` | | defer | deferred | 89 | | 56 | yes | pass | `tests/workflow-catalog.test.ts`<br>`tests/workflow-recipes.test.ts`<br>`tests/validation.test.ts` |
|
||||
| workflow | `.codex/workflows/perf-profile.md` | | defer | deferred | 84 | | 56 | yes | pass | `tests/workflow-catalog.test.ts`<br>`tests/workflow-recipes.test.ts`<br>`tests/validation.test.ts` |
|
||||
| workflow | `.codex/workflows/playtest-polish.md` | | defer | deferred | 84 | | 56 | yes | pass | `tests/workflow-catalog.test.ts`<br>`tests/workflow-recipes.test.ts`<br>`tests/validation.test.ts` |
|
||||
| workflow | `.codex/workflows/playtest.md` | | defer | deferred | 84 | | 56 | yes | pass | `tests/workflow-catalog.test.ts`<br>`tests/workflow-recipes.test.ts`<br>`tests/validation.test.ts` |
|
||||
@@ -108,7 +108,7 @@ Decisions: adopt, adapt, merge, split, defer, out-of-scope.
|
||||
| workflow | `.codex/workflows/ship-check.md` | | defer | deferred | 85 | | 56 | yes | pass | `tests/workflow-catalog.test.ts`<br>`tests/workflow-recipes.test.ts`<br>`tests/validation.test.ts` |
|
||||
| workflow | `.codex/workflows/sprint-plan.md` | | defer | deferred | 85 | | 56 | yes | pass | `tests/workflow-catalog.test.ts`<br>`tests/workflow-recipes.test.ts`<br>`tests/validation.test.ts` |
|
||||
| workflow | `.codex/workflows/sprint-status.md` | | defer | deferred | 85 | | 56 | yes | pass | `tests/workflow-catalog.test.ts`<br>`tests/workflow-recipes.test.ts`<br>`tests/validation.test.ts` |
|
||||
| workflow | `.codex/workflows/story-done.md` | | defer | deferred | 84 | | 56 | yes | pass | `tests/workflow-catalog.test.ts`<br>`tests/workflow-recipes.test.ts`<br>`tests/validation.test.ts` |
|
||||
| workflow | `.codex/workflows/story-done.md` | | defer | deferred | 90 | | 56 | yes | pass | `tests/workflow-catalog.test.ts`<br>`tests/workflow-recipes.test.ts`<br>`tests/validation.test.ts` |
|
||||
| workflow | `.codex/workflows/story-readiness.md` | | defer | deferred | 84 | | 56 | yes | pass | `tests/workflow-catalog.test.ts`<br>`tests/workflow-recipes.test.ts`<br>`tests/validation.test.ts` |
|
||||
| workflow | `.codex/workflows/team-feature.md` | | defer | deferred | 84 | | 56 | yes | pass | `tests/workflow-catalog.test.ts`<br>`tests/workflow-recipes.test.ts`<br>`tests/validation.test.ts` |
|
||||
| workflow | `.codex/workflows/team-polish.md` | | defer | deferred | 84 | | 56 | yes | pass | `tests/workflow-catalog.test.ts`<br>`tests/workflow-recipes.test.ts`<br>`tests/validation.test.ts` |
|
||||
|
||||
@@ -65,7 +65,7 @@ export const behavioralEvaluationScenarios: BehavioralEvaluationScenario[] = [
|
||||
role: "qa-playtester",
|
||||
phase: "review",
|
||||
objective: "Review current playtest blockers and warnings.",
|
||||
contextFiles: ["AGENTS.md", ".codex/studio.json", "documentation/design/gdd.md"]
|
||||
contextFiles: ["AGENTS.md", ".codex/studio.json", "design/gdd.md"]
|
||||
},
|
||||
requiredPhrases: ["Role: QA Playtester", "Issue ID", "Severity", "Reproduction steps", "Expected result", "Actual result", "File Edits: not allowed"],
|
||||
forbiddenPhrases: withDefaultForbidden(["danger-full-access", "Template: release_notes"]),
|
||||
@@ -80,7 +80,7 @@ export const behavioralEvaluationScenarios: BehavioralEvaluationScenario[] = [
|
||||
role: "release-manager",
|
||||
phase: "ship",
|
||||
objective: "Assess whether the milestone is ready to ship.",
|
||||
contextFiles: ["AGENTS.md", ".codex/studio.json", "documentation/production/timeline.md"]
|
||||
contextFiles: ["AGENTS.md", ".codex/studio.json", "production/timeline.md"]
|
||||
},
|
||||
requiredPhrases: ["Role: Release Manager", "Release decision", "Blocking issues", "Validation evidence", "Rollback notes", "release blockers"],
|
||||
forbiddenPhrases: withDefaultForbidden(["Template: analytics_setup"]),
|
||||
@@ -91,7 +91,7 @@ export const behavioralEvaluationScenarios: BehavioralEvaluationScenario[] = [
|
||||
id: "workflow.ship-check.release-readiness",
|
||||
description: "Ship-check workflow prompts must select release templates, timeline context, and release-manager evidence without pulling unrelated market or analytics templates.",
|
||||
target: { kind: "workflow", workflow: "ship-check" },
|
||||
requiredPhrases: ["Role: Release Manager", workflowRegistry["ship-check"].objective, "Blocking issues", "Validation evidence", "documentation/production/timeline.md"],
|
||||
requiredPhrases: ["Role: Release Manager", workflowRegistry["ship-check"].objective, "Blocking issues", "Validation evidence", "production/timeline.md"],
|
||||
forbiddenPhrases: withDefaultForbidden(["Template: market_analysis", "Template: analytics_setup"]),
|
||||
expectedContextCategories: ["project-instructions", "studio-state", "workflow-file", "project-docs", "templates", "role-contract", "output-contract"],
|
||||
requiredTemplateIds: ["ship_check", "release_notes", "risk_register"],
|
||||
@@ -113,7 +113,7 @@ export const behavioralEvaluationScenarios: BehavioralEvaluationScenario[] = [
|
||||
id: "workflow.market-analysis.positioning",
|
||||
description: "Market-analysis workflow prompts must select market and pitch material while avoiding analytics-only and release-only templates.",
|
||||
target: { kind: "workflow", workflow: "market-analysis" },
|
||||
requiredPhrases: ["Role: Market Analyst", workflowRegistry["market-analysis"].objective, "resources/market-research/market-overview.md", "Expected Outputs"],
|
||||
requiredPhrases: ["Role: Market Analyst", workflowRegistry["market-analysis"].objective, "docs/market-overview.md", "Expected Outputs"],
|
||||
forbiddenPhrases: withDefaultForbidden(["Template: analytics_setup", "Template: release_notes"]),
|
||||
expectedContextCategories: ["project-instructions", "studio-state", "workflow-file", "project-docs", "templates", "role-contract"],
|
||||
requiredTemplateIds: ["market_analysis", "pitch_document"],
|
||||
@@ -159,7 +159,7 @@ export const behavioralEvaluationScenarios: BehavioralEvaluationScenario[] = [
|
||||
{
|
||||
id: "role.game-designer.design-system-uplift",
|
||||
description: "Design-system prompts require game-designer output structure, quality gates, and handoff evidence.",
|
||||
target: { kind: "role", role: "game-designer", phase: "plan", objective: "Create a design-system update for player-facing ability rules.", contextFiles: ["AGENTS.md", ".codex/studio.json", "documentation/design/gdd.md"] },
|
||||
target: { kind: "role", role: "game-designer", phase: "plan", objective: "Create a design-system update for player-facing ability rules.", contextFiles: ["AGENTS.md", ".codex/studio.json", "design/gdd.md"] },
|
||||
requiredPhrases: ["Role: Game Designer", "## Responsibilities", "Quality Gates", "Acceptance criteria", "## Verification"],
|
||||
forbiddenPhrases: withDefaultForbidden(["Template: release_notes"]),
|
||||
expectedContextCategories: ["project-instructions", "studio-state", "project-docs", "role-contract", "output-contract"],
|
||||
@@ -202,8 +202,8 @@ function actualContextCategories(scenario: BehavioralEvaluationScenario, prompt:
|
||||
if (prompt.includes("AGENTS.md")) categories.add("project-instructions");
|
||||
if (prompt.includes(".codex/studio.json")) categories.add("studio-state");
|
||||
if (prompt.includes(".codex/workflows/")) categories.add("workflow-file");
|
||||
if (/documentation\/|resources\//.test(prompt)) categories.add("project-docs");
|
||||
if (/source\//.test(prompt)) categories.add("source-artifact");
|
||||
if (/(?:design\/|docs\/|production\/)/.test(prompt)) categories.add("project-docs");
|
||||
if (/(?:src\/|source\/)/.test(prompt)) categories.add("source-artifact");
|
||||
if (prompt.includes("docs/engine-reference/")) categories.add("engine-reference");
|
||||
if (prompt.includes("## Workflow Templates") || (scenario.target.kind === "workflow" && (workflowRegistry[scenario.target.workflow].templateIds?.length ?? 0) > 0)) categories.add("templates");
|
||||
if (prompt.includes("## Responsibilities") && prompt.includes("## Quality Gates")) categories.add("role-contract");
|
||||
|
||||
+21
-5
@@ -14,6 +14,7 @@ import {
|
||||
import { formatTemplateShow, listTemplates, templateRegistry, type TemplateId } from "./templates.js";
|
||||
import { freezeProject, initProject, readStudioProject, refreshContextManifestProject, resumeProject, statusProject } from "./projects.js";
|
||||
import { runValidation } from "./validation.js";
|
||||
import { documentationImpactChecks } from "./documentation-impact.js";
|
||||
import { executeRunLifecycle, prepareRun } from "./runner.js";
|
||||
import { checkCodexAvailability } from "./codex-runtime.js";
|
||||
import { renderAgentContext } from "./agent-context.js";
|
||||
@@ -155,16 +156,31 @@ program
|
||||
.option("--project <path>", "project path")
|
||||
.action((opts) => console.log(freezeProject(opts.project)));
|
||||
|
||||
function printChecks(checks: readonly { status: string; id: string; message: string; path?: string }[]): boolean {
|
||||
for (const check of checks) {
|
||||
console.log(`${check.status.toUpperCase()} ${check.id}: ${check.message}${check.path ? ` (${check.path})` : ""}`);
|
||||
}
|
||||
return checks.some((check) => check.status === "fail");
|
||||
}
|
||||
|
||||
program
|
||||
.command("validate")
|
||||
.description("Run hard-failing repo or project validation")
|
||||
.option("--project <path>", "project path")
|
||||
.option("--base <ref>", "Git base used for documentation-impact validation")
|
||||
.action(async (opts) => {
|
||||
const result = await runValidation({ project: opts.project });
|
||||
for (const check of result.checks) {
|
||||
console.log(`${check.status.toUpperCase()} ${check.id}: ${check.message}${check.path ? ` (${check.path})` : ""}`);
|
||||
}
|
||||
if (result.failed) process.exitCode = 1;
|
||||
const result = await runValidation({ project: opts.project, base: opts.base });
|
||||
if (printChecks(result.checks)) process.exitCode = 1;
|
||||
});
|
||||
|
||||
program
|
||||
.command("docs-impact")
|
||||
.description("Check documentation-impact evidence for functional game changes")
|
||||
.option("--project <path>", "project path")
|
||||
.option("--base <ref>", "Git base to compare against", "HEAD")
|
||||
.action((opts) => {
|
||||
const projectRoot = resolveTaskProject(opts.project);
|
||||
if (printChecks(documentationImpactChecks(projectRoot, { base: opts.base }))) process.exitCode = 1;
|
||||
});
|
||||
|
||||
const templates = program.command("templates").description("Discover templates");
|
||||
|
||||
+3
-3
@@ -2,9 +2,9 @@ import { existsSync, realpathSync, statSync } from "node:fs";
|
||||
import path from "node:path";
|
||||
|
||||
const broadContextCandidates = [
|
||||
"documentation/design/gdd.md",
|
||||
"documentation/production/timeline.md",
|
||||
"resources/market-research/market-overview.md",
|
||||
"design/gdd.md",
|
||||
"production/timeline.md",
|
||||
"docs/market-overview.md",
|
||||
"AGENTS.md",
|
||||
".codex/studio.json"
|
||||
] as const;
|
||||
|
||||
@@ -0,0 +1,134 @@
|
||||
import { execFileSync } from "node:child_process";
|
||||
import { existsSync, readFileSync } from "node:fs";
|
||||
import path from "node:path";
|
||||
|
||||
export type DocumentationImpactCheck = {
|
||||
id: string;
|
||||
status: "pass" | "fail";
|
||||
message: string;
|
||||
path?: string;
|
||||
};
|
||||
|
||||
export type DocumentationImpactRecord = {
|
||||
decision?: string;
|
||||
reason?: string;
|
||||
documents: string[];
|
||||
};
|
||||
|
||||
export type DocumentationImpactOptions = {
|
||||
base?: string;
|
||||
changedPaths?: string[];
|
||||
};
|
||||
|
||||
const activeSessionPath = path.join("production", "session-state", "active.md");
|
||||
const documentationRoots = ["design/", "docs/", "production/"];
|
||||
|
||||
function pass(id: string, message: string, file?: string): DocumentationImpactCheck {
|
||||
return { id, status: "pass", message, path: file };
|
||||
}
|
||||
|
||||
function fail(id: string, message: string, file?: string): DocumentationImpactCheck {
|
||||
return { id, status: "fail", message, path: file };
|
||||
}
|
||||
|
||||
function documentationSection(body: string): string | undefined {
|
||||
const heading = /^## Documentation Impact\s*$/m.exec(body);
|
||||
if (!heading || heading.index === undefined) return undefined;
|
||||
const rest = body.slice(heading.index + heading[0].length);
|
||||
const nextHeading = rest.search(/^##\s/m);
|
||||
return (nextHeading === -1 ? rest : rest.slice(0, nextHeading)).trim();
|
||||
}
|
||||
|
||||
export function parseDocumentationImpactRecord(body: string): DocumentationImpactRecord | undefined {
|
||||
const section = documentationSection(body);
|
||||
if (section === undefined) return undefined;
|
||||
const fields = new Map<string, string>();
|
||||
for (const line of section.split("\n")) {
|
||||
const match = /^-\s*(Decision|Reason|Documents):\s*(.*)$/i.exec(line.trim());
|
||||
if (match) fields.set(match[1].toLowerCase(), match[2].trim());
|
||||
}
|
||||
const documentsValue = fields.get("documents") ?? "";
|
||||
const documents = documentsValue.toLowerCase() === "none" || documentsValue === "" ? [] : documentsValue.split(",").map((entry) => entry.trim()).filter(Boolean);
|
||||
return { decision: fields.get("decision")?.toLowerCase(), reason: fields.get("reason"), documents };
|
||||
}
|
||||
|
||||
export function isDocumentationPath(file: string): boolean {
|
||||
return documentationRoots.some((root) => file.startsWith(root));
|
||||
}
|
||||
|
||||
export function isFunctionalGamePath(file: string): boolean {
|
||||
if (isDocumentationPath(file) || file.startsWith(".codex/") || file.startsWith("tests/") || file.startsWith("tools/")) return false;
|
||||
return file.startsWith("src/") || file.startsWith("assets/") || file === "project.godot" || file.endsWith(".uproject");
|
||||
}
|
||||
|
||||
function changedPathsFromGit(projectRoot: string, base: string): string[] {
|
||||
const run = (args: string[]) => execFileSync("git", args, { cwd: projectRoot, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim();
|
||||
const tracked = run(["diff", "--name-only", "--diff-filter=ACMRD", base, "--"]);
|
||||
const untracked = run(["ls-files", "--others", "--exclude-standard"]);
|
||||
return [...new Set([...tracked.split("\n"), ...untracked.split("\n")].map((file) => file.trim()).filter(Boolean))].sort();
|
||||
}
|
||||
|
||||
function isProjectDocumentPath(file: string): boolean {
|
||||
if (path.isAbsolute(file)) return false;
|
||||
const normalized = path.posix.normalize(file.replaceAll("\\", "/"));
|
||||
return normalized === file && documentationRoots.some((root) => normalized.startsWith(root));
|
||||
}
|
||||
|
||||
export function documentationImpactChecks(projectRoot: string, options: DocumentationImpactOptions = {}): DocumentationImpactCheck[] {
|
||||
let changedPaths = options.changedPaths;
|
||||
if (!changedPaths) {
|
||||
const base = options.base ?? "HEAD";
|
||||
try {
|
||||
changedPaths = changedPathsFromGit(projectRoot, base);
|
||||
} catch (error) {
|
||||
return [fail("project.documentation_impact.base", `documentation impact could not inspect Git base ${base}: ${(error as Error).message}`)];
|
||||
}
|
||||
}
|
||||
|
||||
const functionalPaths = changedPaths.filter(isFunctionalGamePath);
|
||||
if (functionalPaths.length === 0) {
|
||||
return [pass("project.documentation_impact", "no functional game paths changed; documentation-impact record is not required")];
|
||||
}
|
||||
|
||||
const recordPath = path.join(projectRoot, activeSessionPath);
|
||||
if (!existsSync(recordPath)) {
|
||||
return [fail("project.documentation_impact.record", `functional game paths changed (${functionalPaths.join(", ")}) but ${activeSessionPath} is missing`, recordPath)];
|
||||
}
|
||||
|
||||
const record = parseDocumentationImpactRecord(readFileSync(recordPath, "utf8"));
|
||||
if (!record) return [fail("project.documentation_impact.record", `${activeSessionPath} must contain a ## Documentation Impact section`, recordPath)];
|
||||
|
||||
const checks: DocumentationImpactCheck[] = [];
|
||||
if (record.decision !== "updated" && record.decision !== "no-update") {
|
||||
checks.push(fail("project.documentation_impact.decision", "Documentation Impact Decision must be updated or no-update", recordPath));
|
||||
return checks;
|
||||
}
|
||||
if (!record.reason?.trim()) checks.push(fail("project.documentation_impact.reason", "Documentation Impact Reason is required", recordPath));
|
||||
|
||||
if (record.decision === "no-update") {
|
||||
if (record.documents.length > 0) checks.push(fail("project.documentation_impact.documents", "no-update decisions must declare Documents: none", recordPath));
|
||||
if (checks.length === 0) checks.push(pass("project.documentation_impact", "functional changes have an explicit no-update documentation decision", recordPath));
|
||||
return checks;
|
||||
}
|
||||
|
||||
if (record.documents.length === 0) {
|
||||
checks.push(fail("project.documentation_impact.documents", "updated decisions must name one or more changed game documents", recordPath));
|
||||
return checks;
|
||||
}
|
||||
|
||||
for (const document of record.documents) {
|
||||
const id = `project.documentation_impact.document.${document}`;
|
||||
const fullPath = path.join(projectRoot, document);
|
||||
if (!isProjectDocumentPath(document)) {
|
||||
checks.push(fail(id, "Documentation Impact documents must be project-relative paths under design/, docs/, or production/", recordPath));
|
||||
} else if (!existsSync(fullPath)) {
|
||||
checks.push(fail(id, `Documentation Impact document does not exist: ${document}`, fullPath));
|
||||
} else if (!changedPaths.includes(document)) {
|
||||
checks.push(fail(id, `Documentation Impact document did not differ from the selected base: ${document}`, fullPath));
|
||||
} else {
|
||||
checks.push(pass(id, `Documentation Impact document changed: ${document}`, fullPath));
|
||||
}
|
||||
}
|
||||
if (checks.every((check) => check.status === "pass") && record.reason?.trim()) checks.push(pass("project.documentation_impact", "functional changes have updated documentation evidence", recordPath));
|
||||
return checks;
|
||||
}
|
||||
+9
-4
@@ -22,6 +22,7 @@ import { isEngineSpecialistRoleId, projectRoleIdsForEngine, rolePackages, studio
|
||||
import { templateRegistry, validateTemplateFiles } from "./templates.js";
|
||||
import { renderWorkflowPrompt, workflowIds, workflowRegistry } from "./workflows.js";
|
||||
import { templateSkillDefinitions } from "./skills.js";
|
||||
import { documentationImpactChecks } from "./documentation-impact.js";
|
||||
import {
|
||||
isCodexModelName,
|
||||
isReasoningEffort,
|
||||
@@ -255,6 +256,9 @@ export function validateTemplateSurfaces(root = process.cwd()): ValidationCheck[
|
||||
checks.push(...openAiSkillMetadataChecks(root));
|
||||
|
||||
for (const forbidden of [
|
||||
".truthmark",
|
||||
path.join("docs", "truthmark"),
|
||||
path.join("tooling", "truthmark"),
|
||||
".codex/agents/truth-claim-verifier.toml",
|
||||
".codex/agents/truth-doc-reviewer.toml",
|
||||
".codex/agents/truth-doc-writer.toml",
|
||||
@@ -537,7 +541,7 @@ export async function validateRepo(root = process.cwd()): Promise<ValidationChec
|
||||
return checks;
|
||||
}
|
||||
|
||||
export function validateProject(projectRoot: string): ValidationCheck[] {
|
||||
export function validateProject(projectRoot: string, options: { documentationBase?: string } = {}): ValidationCheck[] {
|
||||
const checks: ValidationCheck[] = [];
|
||||
const studioPath = path.join(projectRoot, ".codex", "studio.json");
|
||||
let studio: ReturnType<typeof readStudioProject>;
|
||||
@@ -624,8 +628,9 @@ export function validateProject(projectRoot: string): ValidationCheck[] {
|
||||
checks.push(sectionHasContent(body, section) ? pass(`project.timeline.${section}`, `${section} exists`, timeline) : fail(`project.timeline.${section}`, `${section} missing non-empty content`, timeline));
|
||||
}
|
||||
}
|
||||
if (options.documentationBase) checks.push(...documentationImpactChecks(projectRoot, { base: options.documentationBase }));
|
||||
|
||||
for (const forbidden of ["project_orchestrator.md", "CODEX.md", path.join(".gamestudio", "runs"), path.join(".codex", "hooks.json"), path.join(".codex", "agents", "truth-claim-verifier.toml"), path.join(".codex", "agents", "truth-doc-reviewer.toml"), path.join(".codex", "agents", "truth-doc-writer.toml"), path.join(".codex", "agents", "truth-route-auditor.toml")]) {
|
||||
for (const forbidden of ["project_orchestrator.md", "CODEX.md", path.join(".gamestudio", "runs"), ".truthmark", path.join("docs", "truthmark"), path.join("tooling", "truthmark"), path.join(".codex", "hooks.json"), path.join(".codex", "agents", "truth-claim-verifier.toml"), path.join(".codex", "agents", "truth-doc-reviewer.toml"), path.join(".codex", "agents", "truth-doc-writer.toml"), path.join(".codex", "agents", "truth-route-auditor.toml")]) {
|
||||
const file = path.join(projectRoot, forbidden);
|
||||
checks.push(existsSync(file) ? fail(`project.forbidden.${forbidden}`, `${forbidden} must not exist`, file) : pass(`project.forbidden.${forbidden}`, `${forbidden} absent`));
|
||||
}
|
||||
@@ -638,9 +643,9 @@ export function validateProject(projectRoot: string): ValidationCheck[] {
|
||||
return checks;
|
||||
}
|
||||
|
||||
export async function runValidation(options: { project?: string; root?: string } = {}): Promise<{ checks: ValidationCheck[]; failed: boolean }> {
|
||||
export async function runValidation(options: { project?: string; root?: string; base?: string } = {}): Promise<{ checks: ValidationCheck[]; failed: boolean }> {
|
||||
const root = options.root ?? process.cwd();
|
||||
const projectPath = options.project ? path.resolve(root, options.project) : existsSync(path.join(root, ".codex", "studio.json")) ? root : undefined;
|
||||
const checks = projectPath ? validateProject(projectPath) : await validateRepo(root);
|
||||
const checks = projectPath ? validateProject(projectPath, { documentationBase: options.base }) : await validateRepo(root);
|
||||
return { checks, failed: checks.some((check) => check.status === "fail") };
|
||||
}
|
||||
|
||||
+30
-30
@@ -34,11 +34,11 @@ export const workflowCatalog: { phases: WorkflowCatalogPhase[] } = {
|
||||
nextPhase: "systems-design",
|
||||
steps: [
|
||||
{ id: "brainstorm", label: "Brainstorm", command: "./codex-game-studio run creative-director", required: false, description: "Explore fantasy, verbs, pillars, audience, and scope tiers." },
|
||||
{ id: "engine-setup", label: "Engine Setup", command: "./codex-game-studio run engine-setup", required: true, artifact: { path: ".codex/studio.json", pattern: "\"engine\"" }, description: "Configure engine, version, project structure, and validation path." },
|
||||
{ id: "game-concept", label: "Game Concept", command: "./codex-game-studio run game-concept", required: true, artifact: { path: "design/gdd.md" }, description: "Capture concept, pillars, and initial player promise." },
|
||||
{ id: "design-review-concept", label: "Concept Design Review", command: "./codex-game-studio run design-review-concept", required: false, artifact: { path: "design/gdd.md", pattern: "Pillar|Scope|Risk" }, description: "Review the concept before deeper systems work." },
|
||||
{ id: "art-bible", label: "Art Bible", command: "./codex-game-studio run art-bible", required: false, artifact: { path: "design/art/art-bible.md" }, description: "Define visual identity and asset constraints." },
|
||||
{ id: "map-systems", label: "Systems Map", command: "./codex-game-studio run map-systems", required: true, artifact: { path: "design/gdd.md", pattern: "System" }, description: "Map systems and dependencies." }
|
||||
{ id: "engine-setup", label: "Engine Setup", command: "./codex-game-studio workflow render engine-setup", required: true, artifact: { path: ".codex/studio.json", pattern: "\"engine\"" }, description: "Configure engine, version, project structure, and validation path." },
|
||||
{ id: "game-concept", label: "Game Concept", command: "./codex-game-studio workflow render game-concept", required: true, artifact: { path: "design/gdd.md" }, description: "Capture concept, pillars, and initial player promise." },
|
||||
{ id: "design-review-concept", label: "Concept Design Review", command: "./codex-game-studio workflow render design-review-concept", required: false, artifact: { path: "design/gdd.md", pattern: "Pillar|Scope|Risk" }, description: "Review the concept before deeper systems work." },
|
||||
{ id: "art-bible", label: "Art Bible", command: "./codex-game-studio workflow render art-bible", required: false, artifact: { path: "design/art/art-bible.md" }, description: "Define visual identity and asset constraints." },
|
||||
{ id: "map-systems", label: "Systems Map", command: "./codex-game-studio workflow render map-systems", required: true, artifact: { path: "design/gdd.md", pattern: "System" }, description: "Map systems and dependencies." }
|
||||
]
|
||||
},
|
||||
{
|
||||
@@ -47,15 +47,15 @@ export const workflowCatalog: { phases: WorkflowCatalogPhase[] } = {
|
||||
description: "Turn the concept into implementable systems, UX, and architecture.",
|
||||
nextPhase: "pre-production",
|
||||
steps: [
|
||||
{ id: "design-system", label: "System GDDs", command: "./codex-game-studio run design-system", required: true, repeatable: true, artifact: { path: "design/gdd.md" }, description: "Author or update per-system GDD content." },
|
||||
{ id: "design-review", label: "Design Review", command: "./codex-game-studio run design-review", required: false, artifact: { path: "design/gdd.md", pattern: "Risk|Scope|System" }, description: "Review design consistency and scope risk." },
|
||||
{ id: "review-all-gdds", label: "Review All GDDs", command: "./codex-game-studio run review-all-gdds", required: false, artifact: { path: "design/gdd.md", pattern: "#|System" }, description: "Review all design documents for contradictions and missing ownership." },
|
||||
{ id: "consistency-check", label: "Consistency Check", command: "./codex-game-studio run consistency-check", required: false, artifact: { path: "production/session-state/active.md" }, description: "Check cross-surface consistency before implementation planning." },
|
||||
{ id: "create-architecture", label: "Architecture", command: "./codex-game-studio run create-architecture", required: true, artifact: { path: "docs/architecture/README.md" }, description: "Define technical architecture and implementation boundaries." },
|
||||
{ id: "control-manifest", label: "Control Manifest", command: "./codex-game-studio run control-manifest", required: false, artifact: { path: "design/ux/controls.md" }, description: "Document inputs, remapping, prompts, devices, and accessibility constraints." },
|
||||
{ id: "accessibility-doc", label: "Accessibility Requirements", command: "./codex-game-studio run accessibility-doc", required: false, artifact: { path: "design/ux/accessibility.md" }, description: "Document accessibility requirements and verification paths." },
|
||||
{ id: "ux-design", label: "UX Design", command: "./codex-game-studio run ux-design", required: false, artifact: { path: "design/ux/ux-spec.md" }, description: "Document player journeys, HUD, menus, and accessibility." },
|
||||
{ id: "ux-review", label: "UX Review", command: "./codex-game-studio run ux-review", required: false, artifact: { path: "design/ux/ux-review.md" }, description: "Review UX flows and usability risks before implementation." }
|
||||
{ id: "design-system", label: "System GDDs", command: "./codex-game-studio workflow render design-system", required: true, repeatable: true, artifact: { path: "design/gdd.md" }, description: "Author or update per-system GDD content." },
|
||||
{ id: "design-review", label: "Design Review", command: "./codex-game-studio workflow render design-review", required: false, artifact: { path: "design/gdd.md", pattern: "Risk|Scope|System" }, description: "Review design consistency and scope risk." },
|
||||
{ id: "review-all-gdds", label: "Review All GDDs", command: "./codex-game-studio workflow render review-all-gdds", required: false, artifact: { path: "design/gdd.md", pattern: "#|System" }, description: "Review all design documents for contradictions and missing ownership." },
|
||||
{ id: "consistency-check", label: "Consistency Check", command: "./codex-game-studio workflow render consistency-check", required: false, artifact: { path: "production/session-state/active.md" }, description: "Check cross-surface consistency before implementation planning." },
|
||||
{ id: "create-architecture", label: "Architecture", command: "./codex-game-studio workflow render create-architecture", required: true, artifact: { path: "docs/architecture/README.md" }, description: "Define technical architecture and implementation boundaries." },
|
||||
{ id: "control-manifest", label: "Control Manifest", command: "./codex-game-studio workflow render control-manifest", required: false, artifact: { path: "design/ux/controls.md" }, description: "Document inputs, remapping, prompts, devices, and accessibility constraints." },
|
||||
{ id: "accessibility-doc", label: "Accessibility Requirements", command: "./codex-game-studio workflow render accessibility-doc", required: false, artifact: { path: "design/ux/accessibility.md" }, description: "Document accessibility requirements and verification paths." },
|
||||
{ id: "ux-design", label: "UX Design", command: "./codex-game-studio workflow render ux-design", required: false, artifact: { path: "design/ux/ux-spec.md" }, description: "Document player journeys, HUD, menus, and accessibility." },
|
||||
{ id: "ux-review", label: "UX Review", command: "./codex-game-studio workflow render ux-review", required: false, artifact: { path: "design/ux/ux-review.md" }, description: "Review UX flows and usability risks before implementation." }
|
||||
]
|
||||
},
|
||||
{
|
||||
@@ -64,14 +64,14 @@ export const workflowCatalog: { phases: WorkflowCatalogPhase[] } = {
|
||||
description: "Validate build feasibility and production readiness.",
|
||||
nextPhase: "production",
|
||||
steps: [
|
||||
{ id: "entity-inventory", label: "Entity Inventory", command: "./codex-game-studio run entity-inventory", required: true, repeatable: true, artifact: { path: "design/entities/entity-inventory.md" }, description: "Catalog gameplay entities, content objects, owners, dependencies, and validation signals." },
|
||||
{ id: "asset-spec", label: "Asset Spec", command: "./codex-game-studio run asset-spec", required: false, repeatable: true, artifact: { path: "design/art/asset-spec.md" }, description: "Specify assets with references, constraints, variants, and production acceptance criteria." },
|
||||
{ id: "entity-inventory", label: "Entity Inventory", command: "./codex-game-studio workflow render entity-inventory", required: true, repeatable: true, artifact: { path: "design/entities/entity-inventory.md" }, description: "Catalog gameplay entities, content objects, owners, dependencies, and validation signals." },
|
||||
{ id: "asset-spec", label: "Asset Spec", command: "./codex-game-studio workflow render asset-spec", required: false, repeatable: true, artifact: { path: "design/art/asset-spec.md" }, description: "Specify assets with references, constraints, variants, and production acceptance criteria." },
|
||||
{ id: "vertical-slice", label: "Vertical Slice", command: "use skill cgs-vertical-slice", required: true, artifact: { path: "production/session-state/active.md", pattern: "PROCEED" }, description: "Validate representative full-loop feasibility." },
|
||||
{ id: "test-setup", label: "Test Setup", command: "./codex-game-studio run test-setup", required: true, artifact: { path: "tests/qa-plan.md" }, description: "Define test environment, scenarios, data, automation hooks, and exit criteria." },
|
||||
{ id: "test-setup", label: "Test Setup", command: "./codex-game-studio workflow render test-setup", required: true, artifact: { path: "tests/qa-plan.md" }, description: "Define test environment, scenarios, data, automation hooks, and exit criteria." },
|
||||
{ id: "qa-plan", label: "QA Plan", command: "use skill cgs-qa-plan", required: true, artifact: { path: "tests/qa-plan.md" }, description: "Plan QA coverage before production." },
|
||||
{ id: "scope-check", label: "Scope Check", command: "./codex-game-studio run scope-check", required: false, artifact: { path: "production/session-state/scope-check.md" }, description: "Check production scope, cutlines, owners, and deferrals." },
|
||||
{ id: "balance-check", label: "Balance Check", command: "./codex-game-studio run balance-check", required: false, artifact: { path: "design/balance/balance-check.md" }, description: "Review economy, progression, difficulty, exploit risks, and tuning hooks." },
|
||||
{ id: "asset-audit", label: "Asset Audit", command: "./codex-game-studio run asset-audit", required: false, artifact: { path: "design/art/asset-audit.md" }, description: "Audit asset completeness, style fit, naming, and technical constraints." }
|
||||
{ id: "scope-check", label: "Scope Check", command: "./codex-game-studio workflow render scope-check", required: false, artifact: { path: "production/session-state/scope-check.md" }, description: "Check production scope, cutlines, owners, and deferrals." },
|
||||
{ id: "balance-check", label: "Balance Check", command: "./codex-game-studio workflow render balance-check", required: false, artifact: { path: "design/balance/balance-check.md" }, description: "Review economy, progression, difficulty, exploit risks, and tuning hooks." },
|
||||
{ id: "asset-audit", label: "Asset Audit", command: "./codex-game-studio workflow render asset-audit", required: false, artifact: { path: "design/art/asset-audit.md" }, description: "Audit asset completeness, style fit, naming, and technical constraints." }
|
||||
]
|
||||
},
|
||||
{
|
||||
@@ -80,13 +80,13 @@ export const workflowCatalog: { phases: WorkflowCatalogPhase[] } = {
|
||||
description: "Implement, review, stabilize, and coordinate feature work.",
|
||||
nextPhase: "release",
|
||||
steps: [
|
||||
{ id: "team-feature", label: "Team Feature", command: "./codex-game-studio run team-feature", required: true, repeatable: true, artifact: { path: "production/session-state/active.md" }, description: "Plan cross-discipline feature work with owners, dependencies, risks, and verification gates." },
|
||||
{ id: "implement", label: "Implement", command: "./codex-game-studio run implement", required: true, repeatable: true, artifact: { path: "production/session-state/active.md" }, description: "Implement a bounded feature slice with validation evidence and handoff notes." },
|
||||
{ id: "code-review", label: "Code Review", command: "./codex-game-studio run code-review", required: true, repeatable: true, artifact: { path: "production/session-state/active.md", pattern: "review|Review|APPROVED|changes" }, description: "Review code changes for correctness, architecture fit, tests, and release risk." },
|
||||
{ id: "bug-report", label: "Bug Report", command: "./codex-game-studio run bug-report", required: false, repeatable: true, artifact: { path: "tests/bug-report.md" }, description: "Capture reproducible bug reports with evidence and owner routing." },
|
||||
{ id: "playtest-polish", label: "Playtest Polish", command: "./codex-game-studio run playtest-polish", required: false, artifact: { path: "production/session-state/playtest-polish.md" }, description: "Prioritize polish fixes from playtest evidence and current build risks." },
|
||||
{ id: "team-polish", label: "Team Polish", command: "./codex-game-studio run team-polish", required: false, artifact: { path: "production/session-state/team-polish.md" }, description: "Coordinate multi-role polish work, cutlines, risks, and verification gates." },
|
||||
{ id: "retrospective", label: "Retrospective", command: "./codex-game-studio run retrospective", required: false, artifact: { path: "production/session-state/retrospective.md" }, description: "Capture outcomes, misses, learnings, follow-ups, and process changes." }
|
||||
{ id: "team-feature", label: "Team Feature", command: "./codex-game-studio workflow render team-feature", required: true, repeatable: true, artifact: { path: "production/session-state/active.md" }, description: "Plan cross-discipline feature work with owners, dependencies, risks, and verification gates." },
|
||||
{ id: "implement", label: "Implement", command: "./codex-game-studio workflow render implement", required: true, repeatable: true, artifact: { path: "production/session-state/active.md" }, description: "Implement a bounded feature slice with validation evidence and handoff notes." },
|
||||
{ id: "code-review", label: "Code Review", command: "./codex-game-studio workflow render code-review", required: true, repeatable: true, artifact: { path: "production/session-state/active.md", pattern: "review|Review|APPROVED|changes" }, description: "Review code changes for correctness, architecture fit, tests, and release risk." },
|
||||
{ id: "bug-report", label: "Bug Report", command: "./codex-game-studio workflow render bug-report", required: false, repeatable: true, artifact: { path: "tests/bug-report.md" }, description: "Capture reproducible bug reports with evidence and owner routing." },
|
||||
{ id: "playtest-polish", label: "Playtest Polish", command: "./codex-game-studio workflow render playtest-polish", required: false, artifact: { path: "production/session-state/playtest-polish.md" }, description: "Prioritize polish fixes from playtest evidence and current build risks." },
|
||||
{ id: "team-polish", label: "Team Polish", command: "./codex-game-studio workflow render team-polish", required: false, artifact: { path: "production/session-state/team-polish.md" }, description: "Coordinate multi-role polish work, cutlines, risks, and verification gates." },
|
||||
{ id: "retrospective", label: "Retrospective", command: "./codex-game-studio workflow render retrospective", required: false, artifact: { path: "production/session-state/retrospective.md" }, description: "Capture outcomes, misses, learnings, follow-ups, and process changes." }
|
||||
]
|
||||
},
|
||||
{
|
||||
@@ -95,9 +95,9 @@ export const workflowCatalog: { phases: WorkflowCatalogPhase[] } = {
|
||||
description: "Validate release readiness and launch operations.",
|
||||
steps: [
|
||||
{ id: "release-checklist", label: "Release Checklist", command: "use skill cgs-release-checklist", required: true, artifact: { path: "production/release-checklist.md" }, description: "Verify ship/no-ship readiness." },
|
||||
{ id: "patch-notes", label: "Patch Notes", command: "./codex-game-studio run patch-notes", required: false, artifact: { path: "docs/patch-notes.md" }, description: "Draft player-facing patch notes with fixes, known issues, and validation evidence." },
|
||||
{ id: "launch-checklist", label: "Launch Checklist", command: "./codex-game-studio run launch-checklist", required: true, artifact: { path: "production/launch-checklist.md" }, description: "Coordinate launch-day readiness." },
|
||||
{ id: "changelog", label: "Changelog", command: "./codex-game-studio run changelog", required: true, artifact: { path: "docs/changelog.md" }, description: "Prepare player/developer-visible changes." }
|
||||
{ id: "patch-notes", label: "Patch Notes", command: "./codex-game-studio workflow render patch-notes", required: false, artifact: { path: "docs/patch-notes.md" }, description: "Draft player-facing patch notes with fixes, known issues, and validation evidence." },
|
||||
{ id: "launch-checklist", label: "Launch Checklist", command: "./codex-game-studio workflow render launch-checklist", required: true, artifact: { path: "production/launch-checklist.md" }, description: "Coordinate launch-day readiness." },
|
||||
{ id: "changelog", label: "Changelog", command: "./codex-game-studio workflow render changelog", required: true, artifact: { path: "docs/changelog.md" }, description: "Prepare player/developer-visible changes." }
|
||||
]
|
||||
}
|
||||
]
|
||||
|
||||
+11
-11
@@ -33,10 +33,10 @@ export const workflowTaskRecipes: Partial<Record<WorkflowId, WorkflowTaskRecipe>
|
||||
workflowId: "vertical-slice",
|
||||
title: "Vertical Slice Task Graph",
|
||||
tasks: [
|
||||
{ key: "plan", title: "Plan the smallest production-quality vertical slice", role: "producer", files: ["documentation/design/gdd.md"], writeFiles: [], dependencies: [] },
|
||||
{ key: "design", title: "Define vertical-slice acceptance criteria and feature rules", role: "game-designer", files: ["documentation/design/gdd.md"], writeFiles: [], dependencies: ["plan"] },
|
||||
{ key: "implement", title: "Implement the vertical-slice core loop", role: "gameplay-programmer", files: ["documentation/design/gdd.md"], writeFiles: [], dependencies: ["design"] },
|
||||
{ key: "qa", title: "Verify vertical-slice playability and blockers", role: "qa-playtester", files: ["documentation/design/gdd.md"], writeFiles: [], dependencies: ["implement"] }
|
||||
{ key: "plan", title: "Plan the smallest production-quality vertical slice", role: "producer", files: ["design/gdd.md"], writeFiles: [], dependencies: [] },
|
||||
{ key: "design", title: "Define vertical-slice acceptance criteria and feature rules", role: "game-designer", files: ["design/gdd.md"], writeFiles: [], dependencies: ["plan"] },
|
||||
{ key: "implement", title: "Implement the vertical-slice core loop", role: "gameplay-programmer", files: ["design/gdd.md"], writeFiles: [], dependencies: ["design"] },
|
||||
{ key: "qa", title: "Verify vertical-slice playability and blockers", role: "qa-playtester", files: ["design/gdd.md"], writeFiles: [], dependencies: ["implement"] }
|
||||
]
|
||||
},
|
||||
bugfix: {
|
||||
@@ -52,19 +52,19 @@ export const workflowTaskRecipes: Partial<Record<WorkflowId, WorkflowTaskRecipe>
|
||||
workflowId: "ui-ux-review",
|
||||
title: "UI/UX Review Task Graph",
|
||||
tasks: [
|
||||
{ key: "ux", title: "Review the UI flow and interaction risks", role: "ui-ux-designer", files: ["documentation/design/gdd.md"], writeFiles: [], dependencies: [] },
|
||||
{ key: "accessibility", title: "Review accessibility gaps in the UI flow", role: "accessibility-specialist", files: ["documentation/design/gdd.md"], writeFiles: [], dependencies: ["ux"] },
|
||||
{ key: "qa", title: "Verify UI/UX review evidence and blockers", role: "qa-playtester", files: ["documentation/design/gdd.md"], writeFiles: [], dependencies: ["accessibility"] }
|
||||
{ key: "ux", title: "Review the UI flow and interaction risks", role: "ui-ux-designer", files: ["design/gdd.md"], writeFiles: [], dependencies: [] },
|
||||
{ key: "accessibility", title: "Review accessibility gaps in the UI flow", role: "accessibility-specialist", files: ["design/gdd.md"], writeFiles: [], dependencies: ["ux"] },
|
||||
{ key: "qa", title: "Verify UI/UX review evidence and blockers", role: "qa-playtester", files: ["design/gdd.md"], writeFiles: [], dependencies: ["accessibility"] }
|
||||
]
|
||||
},
|
||||
"release-checklist": {
|
||||
workflowId: "release-checklist",
|
||||
title: "Release Checklist Task Graph",
|
||||
tasks: [
|
||||
{ key: "qa", title: "Validate release test evidence", role: "qa-playtester", files: ["documentation/production/timeline.md"], writeFiles: [], dependencies: [] },
|
||||
{ key: "perf", title: "Review release performance risks", role: "performance-analyst", files: ["documentation/production/timeline.md"], writeFiles: [], dependencies: [] },
|
||||
{ key: "security", title: "Review release security risks", role: "security-engineer", files: ["documentation/production/timeline.md"], writeFiles: [], dependencies: [] },
|
||||
{ key: "release", title: "Synthesize ship or no-ship release checklist", role: "release-manager", files: ["documentation/production/timeline.md"], writeFiles: [], dependencies: ["qa", "perf", "security"] }
|
||||
{ key: "qa", title: "Validate release test evidence", role: "qa-playtester", files: ["production/timeline.md"], writeFiles: [], dependencies: [] },
|
||||
{ key: "perf", title: "Review release performance risks", role: "performance-analyst", files: ["production/timeline.md"], writeFiles: [], dependencies: [] },
|
||||
{ key: "security", title: "Review release security risks", role: "security-engineer", files: ["production/timeline.md"], writeFiles: [], dependencies: [] },
|
||||
{ key: "release", title: "Synthesize ship or no-ship release checklist", role: "release-manager", files: ["production/timeline.md"], writeFiles: [], dependencies: ["qa", "perf", "security"] }
|
||||
]
|
||||
}
|
||||
};
|
||||
|
||||
+45
-45
@@ -128,7 +128,7 @@ export const workflowRegistry: Record<WorkflowId, WorkflowDefinition> = {
|
||||
category: "implementation-planning",
|
||||
gapCoverage: ["vertical-slice planning", "milestone decomposition"],
|
||||
objective: "Create a bounded vertical-slice plan with tasks, risks, and verification gates.",
|
||||
extraContextFiles: ["documentation/design/gdd.md"]
|
||||
extraContextFiles: ["design/gdd.md"]
|
||||
}),
|
||||
bugfix: workflow({
|
||||
id: "bugfix",
|
||||
@@ -160,7 +160,7 @@ export const workflowRegistry: Record<WorkflowId, WorkflowDefinition> = {
|
||||
category: "onboarding-discovery",
|
||||
gapCoverage: ["market discovery", "competitor positioning"],
|
||||
objective: "Analyze audience, competitors, positioning, pricing, and market risks for the current project.",
|
||||
extraContextFiles: ["resources/market-research/market-overview.md"],
|
||||
extraContextFiles: ["docs/market-overview.md"],
|
||||
templateIds: ["market_analysis", "pitch_document"],
|
||||
cliAlias: "market"
|
||||
}),
|
||||
@@ -209,7 +209,7 @@ export const workflowRegistry: Record<WorkflowId, WorkflowDefinition> = {
|
||||
category: "design-architecture",
|
||||
gapCoverage: ["concept review", "pillar and scope validation"],
|
||||
objective: "Review the concept for coherent player promise, pillars, audience fit, production scope, and design risks before deeper systems work.",
|
||||
extraContextFiles: ["documentation/design/gdd.md"],
|
||||
extraContextFiles: ["design/gdd.md"],
|
||||
templateIds: ["gdd", "risk_register"],
|
||||
cliAlias: "design-review-concept"
|
||||
}),
|
||||
@@ -234,7 +234,7 @@ export const workflowRegistry: Record<WorkflowId, WorkflowDefinition> = {
|
||||
category: "design-architecture",
|
||||
gapCoverage: ["systems map", "system dependency mapping"],
|
||||
objective: "Map core gameplay, economy, progression, content, UI, and technical systems with dependencies, owners, and validation signals.",
|
||||
extraContextFiles: ["documentation/design/gdd.md"],
|
||||
extraContextFiles: ["design/gdd.md"],
|
||||
templateIds: ["gdd", "technical_design", "architecture_traceability"],
|
||||
cliAlias: "map-systems"
|
||||
}),
|
||||
@@ -247,7 +247,7 @@ export const workflowRegistry: Record<WorkflowId, WorkflowDefinition> = {
|
||||
category: "design-architecture",
|
||||
gapCoverage: ["system design", "per-system GDD"],
|
||||
objective: "Author or update a system design with player-facing rules, data model, edge cases, dependencies, tuning hooks, and acceptance criteria.",
|
||||
extraContextFiles: ["documentation/design/gdd.md"],
|
||||
extraContextFiles: ["design/gdd.md"],
|
||||
templateIds: ["feature_spec", "economy_model", "difficulty_curve"],
|
||||
cliAlias: "design-system"
|
||||
}),
|
||||
@@ -260,7 +260,7 @@ export const workflowRegistry: Record<WorkflowId, WorkflowDefinition> = {
|
||||
category: "design-architecture",
|
||||
gapCoverage: ["design review", "scope and consistency review"],
|
||||
objective: "Review design docs for player promise, systemic consistency, production scope, edge cases, and handoff readiness.",
|
||||
extraContextFiles: ["documentation/design/gdd.md"],
|
||||
extraContextFiles: ["design/gdd.md"],
|
||||
templateIds: ["gdd", "risk_register", "handoff"],
|
||||
cliAlias: "design-review"
|
||||
}),
|
||||
@@ -273,7 +273,7 @@ export const workflowRegistry: Record<WorkflowId, WorkflowDefinition> = {
|
||||
category: "design-architecture",
|
||||
gapCoverage: ["GDD review", "cross-document consistency"],
|
||||
objective: "Review all GDD and design artifacts for contradictions, missing systems, stale assumptions, and implementation blockers.",
|
||||
extraContextFiles: ["documentation/design/gdd.md"],
|
||||
extraContextFiles: ["design/gdd.md"],
|
||||
templateIds: ["gdd", "handoff", "risk_register"],
|
||||
cliAlias: "review-all-gdds"
|
||||
}),
|
||||
@@ -286,7 +286,7 @@ export const workflowRegistry: Record<WorkflowId, WorkflowDefinition> = {
|
||||
category: "team-coordination",
|
||||
gapCoverage: ["consistency check", "cross-surface contradiction review"],
|
||||
objective: "Check design, production, architecture, UI, and validation surfaces for contradictions, missing owners, and stale assumptions.",
|
||||
extraContextFiles: ["documentation/design/gdd.md", "documentation/production/timeline.md"],
|
||||
extraContextFiles: ["design/gdd.md", "production/timeline.md"],
|
||||
templateIds: ["handoff", "risk_register"],
|
||||
cliAlias: "consistency-check"
|
||||
}),
|
||||
@@ -299,7 +299,7 @@ export const workflowRegistry: Record<WorkflowId, WorkflowDefinition> = {
|
||||
category: "design-architecture",
|
||||
gapCoverage: ["architecture creation", "technical boundaries"],
|
||||
objective: "Create technical architecture with engine modules, data flow, integration points, risk areas, and verification strategy.",
|
||||
extraContextFiles: ["documentation/design/gdd.md"],
|
||||
extraContextFiles: ["design/gdd.md"],
|
||||
templateIds: ["technical_design", "architecture_traceability", "adr"],
|
||||
cliAlias: "create-architecture"
|
||||
}),
|
||||
@@ -336,7 +336,7 @@ export const workflowRegistry: Record<WorkflowId, WorkflowDefinition> = {
|
||||
category: "design-architecture",
|
||||
gapCoverage: ["entity inventory", "content entity taxonomy"],
|
||||
objective: "Create or update an entity inventory covering gameplay objects, actors, content items, dependencies, ownership, and verification signals.",
|
||||
extraContextFiles: ["documentation/design/gdd.md"],
|
||||
extraContextFiles: ["design/gdd.md"],
|
||||
templateIds: ["gdd", "feature_spec"],
|
||||
cliAlias: "entity-inventory"
|
||||
}),
|
||||
@@ -349,7 +349,7 @@ export const workflowRegistry: Record<WorkflowId, WorkflowDefinition> = {
|
||||
category: "design-architecture",
|
||||
gapCoverage: ["asset specification", "art production handoff"],
|
||||
objective: "Create an implementation-ready asset specification with references, constraints, variants, file expectations, risks, and review criteria.",
|
||||
extraContextFiles: ["documentation/design/gdd.md"],
|
||||
extraContextFiles: ["design/gdd.md"],
|
||||
templateIds: ["art_direction", "art_bible"],
|
||||
cliAlias: "asset-spec"
|
||||
}),
|
||||
@@ -362,7 +362,7 @@ export const workflowRegistry: Record<WorkflowId, WorkflowDefinition> = {
|
||||
category: "localization-accessibility",
|
||||
gapCoverage: ["UX design", "player journey and interface specification"],
|
||||
objective: "Design player journeys, HUD, menus, interaction states, onboarding, accessibility hooks, and implementation-ready UX artifacts.",
|
||||
extraContextFiles: ["documentation/design/gdd.md"],
|
||||
extraContextFiles: ["design/gdd.md"],
|
||||
templateIds: ["ux_spec", "accessibility_requirements", "player_journey"],
|
||||
cliAlias: "ux-design"
|
||||
}),
|
||||
@@ -375,7 +375,7 @@ export const workflowRegistry: Record<WorkflowId, WorkflowDefinition> = {
|
||||
category: "localization-accessibility",
|
||||
gapCoverage: ["UX review", "usability risk inspection"],
|
||||
objective: "Review UX flows, HUD, menus, onboarding, interaction states, accessibility risks, and handoff readiness with concrete findings.",
|
||||
extraContextFiles: ["documentation/design/gdd.md"],
|
||||
extraContextFiles: ["design/gdd.md"],
|
||||
templateIds: ["ui_ux_review", "ux_spec", "accessibility_requirements"],
|
||||
cliAlias: "ux-review"
|
||||
}),
|
||||
@@ -388,7 +388,7 @@ export const workflowRegistry: Record<WorkflowId, WorkflowDefinition> = {
|
||||
category: "qa-testing",
|
||||
gapCoverage: ["test setup", "QA environment readiness"],
|
||||
objective: "Define the test setup for the current feature or milestone, including scenarios, data, environment assumptions, automation hooks, and exit criteria.",
|
||||
extraContextFiles: ["documentation/design/gdd.md"],
|
||||
extraContextFiles: ["design/gdd.md"],
|
||||
templateIds: ["test_plan", "test_evidence"],
|
||||
cliAlias: "test-setup"
|
||||
}),
|
||||
@@ -401,7 +401,7 @@ export const workflowRegistry: Record<WorkflowId, WorkflowDefinition> = {
|
||||
category: "implementation-planning",
|
||||
gapCoverage: ["implementation execution", "bounded feature delivery"],
|
||||
objective: "Implement a bounded feature slice from accepted design context with changed files, validation evidence, risks, and handoff notes.",
|
||||
extraContextFiles: ["documentation/design/gdd.md"],
|
||||
extraContextFiles: ["design/gdd.md"],
|
||||
templateIds: ["feature_spec", "test_evidence", "vertical_slice_report"],
|
||||
cliAlias: "implement"
|
||||
}),
|
||||
@@ -414,7 +414,7 @@ export const workflowRegistry: Record<WorkflowId, WorkflowDefinition> = {
|
||||
category: "qa-testing",
|
||||
gapCoverage: ["code review", "implementation quality gate"],
|
||||
objective: "Review code changes for correctness, architecture fit, engine conventions, testing evidence, risk, and release readiness.",
|
||||
extraContextFiles: ["documentation/design/gdd.md"],
|
||||
extraContextFiles: ["design/gdd.md"],
|
||||
templateIds: ["architecture_traceability", "technical_design"],
|
||||
cliAlias: "code-review"
|
||||
}),
|
||||
@@ -427,7 +427,7 @@ export const workflowRegistry: Record<WorkflowId, WorkflowDefinition> = {
|
||||
category: "qa-testing",
|
||||
gapCoverage: ["bug reporting", "reproducible defect capture"],
|
||||
objective: "Capture a reproducible bug report with expected versus actual behavior, environment, repro steps, evidence, severity, and owner routing.",
|
||||
extraContextFiles: ["documentation/design/gdd.md"],
|
||||
extraContextFiles: ["design/gdd.md"],
|
||||
templateIds: ["playtest_report", "test_evidence"],
|
||||
cliAlias: "bug-report"
|
||||
}),
|
||||
@@ -440,7 +440,7 @@ export const workflowRegistry: Record<WorkflowId, WorkflowDefinition> = {
|
||||
category: "team-coordination",
|
||||
gapCoverage: ["retrospective", "learning capture"],
|
||||
objective: "Run a milestone or sprint retrospective that records outcomes, misses, risks, follow-ups, and concrete process changes.",
|
||||
extraContextFiles: ["documentation/production/timeline.md"],
|
||||
extraContextFiles: ["production/timeline.md"],
|
||||
templateIds: ["postmortem", "risk_register"],
|
||||
cliAlias: "retrospective"
|
||||
}),
|
||||
@@ -453,7 +453,7 @@ export const workflowRegistry: Record<WorkflowId, WorkflowDefinition> = {
|
||||
category: "team-coordination",
|
||||
gapCoverage: ["team feature planning", "cross-discipline coordination"],
|
||||
objective: "Plan a cross-discipline feature with owner roles, artifacts, dependencies, risks, implementation slices, and verification gates.",
|
||||
extraContextFiles: ["documentation/design/gdd.md", "documentation/production/timeline.md"],
|
||||
extraContextFiles: ["design/gdd.md", "production/timeline.md"],
|
||||
templateIds: ["production_milestone", "feature_spec", "sprint_plan"],
|
||||
cliAlias: "team-feature"
|
||||
}),
|
||||
@@ -466,7 +466,7 @@ export const workflowRegistry: Record<WorkflowId, WorkflowDefinition> = {
|
||||
category: "team-coordination",
|
||||
gapCoverage: ["scope check", "production cutline review"],
|
||||
objective: "Review production scope, identify cuts or deferrals, name owner decisions, and preserve the smallest shippable milestone.",
|
||||
extraContextFiles: ["documentation/production/timeline.md"],
|
||||
extraContextFiles: ["production/timeline.md"],
|
||||
templateIds: ["production_milestone", "risk_register"],
|
||||
cliAlias: "scope-check"
|
||||
}),
|
||||
@@ -479,7 +479,7 @@ export const workflowRegistry: Record<WorkflowId, WorkflowDefinition> = {
|
||||
category: "design-architecture",
|
||||
gapCoverage: ["balance check", "economy and progression risk review"],
|
||||
objective: "Review balance, resources, progression, difficulty, exploit risks, and tuning hooks against player goals and telemetry signals.",
|
||||
extraContextFiles: ["documentation/design/gdd.md"],
|
||||
extraContextFiles: ["design/gdd.md"],
|
||||
templateIds: ["economy_model"],
|
||||
cliAlias: "balance-check"
|
||||
}),
|
||||
@@ -492,7 +492,7 @@ export const workflowRegistry: Record<WorkflowId, WorkflowDefinition> = {
|
||||
category: "design-architecture",
|
||||
gapCoverage: ["asset audit", "content completeness review"],
|
||||
objective: "Audit assets for completeness, style fit, technical constraints, naming, missing variants, and release-blocking production risks.",
|
||||
extraContextFiles: ["documentation/design/gdd.md"],
|
||||
extraContextFiles: ["design/gdd.md"],
|
||||
templateIds: ["art_direction", "art_bible"],
|
||||
cliAlias: "asset-audit"
|
||||
}),
|
||||
@@ -505,7 +505,7 @@ export const workflowRegistry: Record<WorkflowId, WorkflowDefinition> = {
|
||||
category: "qa-testing",
|
||||
gapCoverage: ["playtest polish", "player experience triage"],
|
||||
objective: "Review playtest feedback and current build evidence to prioritize polish fixes, blockers, warnings, and follow-up validation.",
|
||||
extraContextFiles: ["documentation/design/gdd.md"],
|
||||
extraContextFiles: ["design/gdd.md"],
|
||||
templateIds: ["playtest_report", "test_evidence"],
|
||||
cliAlias: "playtest-polish"
|
||||
}),
|
||||
@@ -518,7 +518,7 @@ export const workflowRegistry: Record<WorkflowId, WorkflowDefinition> = {
|
||||
category: "team-coordination",
|
||||
gapCoverage: ["team polish planning", "multi-role polish coordination"],
|
||||
objective: "Coordinate polish work across design, art, audio, UI, QA, and engineering with owners, cutlines, risks, and verification gates.",
|
||||
extraContextFiles: ["documentation/production/timeline.md"],
|
||||
extraContextFiles: ["production/timeline.md"],
|
||||
templateIds: ["production_milestone", "risk_register"],
|
||||
cliAlias: "team-polish"
|
||||
}),
|
||||
@@ -527,11 +527,11 @@ export const workflowRegistry: Record<WorkflowId, WorkflowDefinition> = {
|
||||
model: "gpt-5.6-luna",
|
||||
modelReasoningEffort: "low",
|
||||
role: "release-manager",
|
||||
phase: "ship",
|
||||
phase: "implement",
|
||||
category: "release-hotfix",
|
||||
gapCoverage: ["patch notes", "player-facing release communication"],
|
||||
objective: "Draft patch notes with highlights, fixes, known issues, compatibility notes, validation evidence, and approval needs.",
|
||||
extraContextFiles: ["documentation/production/timeline.md"],
|
||||
objective: "Draft and write docs/patch-notes.md with highlights, fixes, known issues, compatibility notes, validation evidence, and approval needs.",
|
||||
extraContextFiles: ["production/timeline.md"],
|
||||
templateIds: ["release_notes"],
|
||||
cliAlias: "patch-notes"
|
||||
}),
|
||||
@@ -540,11 +540,11 @@ export const workflowRegistry: Record<WorkflowId, WorkflowDefinition> = {
|
||||
model: "gpt-5.6-luna",
|
||||
modelReasoningEffort: "low",
|
||||
role: "release-manager",
|
||||
phase: "ship",
|
||||
phase: "implement",
|
||||
category: "release-hotfix",
|
||||
gapCoverage: ["changelog", "developer-visible change record"],
|
||||
objective: "Prepare a developer-visible changelog with grouped changes, fixes, migration notes, known issues, and verification evidence.",
|
||||
extraContextFiles: ["documentation/production/timeline.md"],
|
||||
objective: "Prepare and write docs/changelog.md with grouped changes, fixes, migration notes, known issues, and verification evidence.",
|
||||
extraContextFiles: ["production/timeline.md"],
|
||||
templateIds: ["release_notes"],
|
||||
cliAlias: "changelog"
|
||||
}),
|
||||
@@ -557,7 +557,7 @@ export const workflowRegistry: Record<WorkflowId, WorkflowDefinition> = {
|
||||
category: "release-hotfix",
|
||||
gapCoverage: ["launch checklist", "launch readiness coordination"],
|
||||
objective: "Prepare launch-day readiness checks across build, store, comms, rollback, support, monitoring, and final go/no-go decisions.",
|
||||
extraContextFiles: ["documentation/production/timeline.md"],
|
||||
extraContextFiles: ["production/timeline.md"],
|
||||
templateIds: ["ship_check", "release_notes", "test_plan"],
|
||||
cliAlias: "launch-checklist"
|
||||
}),
|
||||
@@ -570,7 +570,7 @@ export const workflowRegistry: Record<WorkflowId, WorkflowDefinition> = {
|
||||
category: "design-architecture",
|
||||
gapCoverage: ["feature specification", "design acceptance criteria"],
|
||||
objective: "Create or review a feature/design spec with rules, edge cases, implementation slices, and acceptance criteria.",
|
||||
extraContextFiles: ["documentation/design/gdd.md"],
|
||||
extraContextFiles: ["design/gdd.md"],
|
||||
templateIds: ["feature_spec", "economy_model", "difficulty_curve", "player_journey"],
|
||||
cliAlias: "design-spec"
|
||||
}),
|
||||
@@ -619,7 +619,7 @@ export const workflowRegistry: Record<WorkflowId, WorkflowDefinition> = {
|
||||
category: "team-coordination",
|
||||
gapCoverage: ["milestone planning", "production risk tracking"],
|
||||
objective: "Convert current project state into milestone goals, task slices, risks, owners, and verification gates.",
|
||||
extraContextFiles: ["documentation/production/timeline.md"],
|
||||
extraContextFiles: ["production/timeline.md"],
|
||||
templateIds: ["production_milestone", "risk_register"],
|
||||
cliAlias: "milestone"
|
||||
}),
|
||||
@@ -654,7 +654,7 @@ export const workflowRegistry: Record<WorkflowId, WorkflowDefinition> = {
|
||||
category: "release-hotfix",
|
||||
gapCoverage: ["ship readiness", "release blocker review"],
|
||||
objective: "Assess milestone readiness, package risk, validation status, and release blockers.",
|
||||
extraContextFiles: ["documentation/production/timeline.md"],
|
||||
extraContextFiles: ["production/timeline.md"],
|
||||
templateIds: ["ship_check", "release_notes", "risk_register"]
|
||||
}),
|
||||
onboard: workflow({
|
||||
@@ -666,7 +666,7 @@ export const workflowRegistry: Record<WorkflowId, WorkflowDefinition> = {
|
||||
category: "onboarding-discovery",
|
||||
gapCoverage: ["project onboarding", "repository orientation"],
|
||||
objective: "Orient a contributor to the project goal, current stage, key files, active roles, and safest first actions.",
|
||||
extraContextFiles: ["documentation/design/gdd.md", "documentation/production/timeline.md"],
|
||||
extraContextFiles: ["design/gdd.md", "production/timeline.md"],
|
||||
templateIds: ["handoff", "pitch_document"],
|
||||
cliAlias: "start",
|
||||
cliAliases: ["onboard"]
|
||||
@@ -680,7 +680,7 @@ export const workflowRegistry: Record<WorkflowId, WorkflowDefinition> = {
|
||||
category: "design-architecture",
|
||||
gapCoverage: ["concept ideation", "creative option generation"],
|
||||
objective: "Generate bounded game ideas, feature variations, player fantasies, and tradeoff notes from the current project constraints.",
|
||||
extraContextFiles: ["documentation/design/gdd.md"],
|
||||
extraContextFiles: ["design/gdd.md"],
|
||||
templateIds: ["pitch_document", "player_journey", "art_bible", "sound_bible"],
|
||||
cliAlias: "brainstorm"
|
||||
}),
|
||||
@@ -693,7 +693,7 @@ export const workflowRegistry: Record<WorkflowId, WorkflowDefinition> = {
|
||||
category: "implementation-planning",
|
||||
gapCoverage: ["prototype planning", "playable-loop slicing"],
|
||||
objective: "Plan the smallest playable prototype slice with owner roles, required assets, implementation tasks, and validation checks.",
|
||||
extraContextFiles: ["documentation/design/gdd.md"],
|
||||
extraContextFiles: ["design/gdd.md"],
|
||||
templateIds: ["vertical_slice_report", "technical_design", "risk_register"],
|
||||
cliAlias: "prototype"
|
||||
}),
|
||||
@@ -706,7 +706,7 @@ export const workflowRegistry: Record<WorkflowId, WorkflowDefinition> = {
|
||||
category: "design-architecture",
|
||||
gapCoverage: ["architecture decision records", "technical tradeoff capture"],
|
||||
objective: "Draft an architecture decision with context, options, selected direction, consequences, risks, and verification implications.",
|
||||
extraContextFiles: ["documentation/design/gdd.md"],
|
||||
extraContextFiles: ["design/gdd.md"],
|
||||
templateIds: ["adr", "technical_design", "architecture_traceability"],
|
||||
cliAlias: "architecture-decision"
|
||||
}),
|
||||
@@ -731,7 +731,7 @@ export const workflowRegistry: Record<WorkflowId, WorkflowDefinition> = {
|
||||
category: "implementation-planning",
|
||||
gapCoverage: ["epic creation", "roadmap decomposition"],
|
||||
objective: "Create production epics from the project goal with scope, owners, dependencies, risks, and acceptance signals.",
|
||||
extraContextFiles: ["documentation/design/gdd.md", "documentation/production/timeline.md"],
|
||||
extraContextFiles: ["design/gdd.md", "production/timeline.md"],
|
||||
templateIds: ["production_milestone", "risk_register"],
|
||||
cliAlias: "create-epics"
|
||||
}),
|
||||
@@ -744,7 +744,7 @@ export const workflowRegistry: Record<WorkflowId, WorkflowDefinition> = {
|
||||
category: "implementation-planning",
|
||||
gapCoverage: ["story breakdown", "implementation-ready task slicing"],
|
||||
objective: "Break an epic or feature into implementation-ready stories with role owner, files or artifacts to inspect, acceptance criteria, and verification gates.",
|
||||
extraContextFiles: ["documentation/production/timeline.md"],
|
||||
extraContextFiles: ["production/timeline.md"],
|
||||
templateIds: ["feature_spec"],
|
||||
cliAlias: "create-stories"
|
||||
}),
|
||||
@@ -757,7 +757,7 @@ export const workflowRegistry: Record<WorkflowId, WorkflowDefinition> = {
|
||||
category: "team-coordination",
|
||||
gapCoverage: ["sprint planning", "iteration commitment"],
|
||||
objective: "Plan the next sprint or iteration with committed goals, role assignments, risks, validation gates, and explicit non-goals.",
|
||||
extraContextFiles: ["documentation/production/timeline.md"],
|
||||
extraContextFiles: ["production/timeline.md"],
|
||||
templateIds: ["sprint_plan", "risk_register"],
|
||||
cliAlias: "sprint-plan"
|
||||
}),
|
||||
@@ -770,7 +770,7 @@ export const workflowRegistry: Record<WorkflowId, WorkflowDefinition> = {
|
||||
category: "team-coordination",
|
||||
gapCoverage: ["sprint status", "blocker visibility"],
|
||||
objective: "Summarize sprint status, completed work, blockers, risks, next owners, and verification evidence without mutating task state.",
|
||||
extraContextFiles: ["documentation/production/timeline.md"],
|
||||
extraContextFiles: ["production/timeline.md"],
|
||||
templateIds: ["sprint_plan", "postmortem"],
|
||||
cliAlias: "sprint-status"
|
||||
}),
|
||||
@@ -807,7 +807,7 @@ export const workflowRegistry: Record<WorkflowId, WorkflowDefinition> = {
|
||||
category: "qa-testing",
|
||||
gapCoverage: ["test planning", "QA strategy"],
|
||||
objective: "Create a QA plan with target scenarios, risk areas, test data, manual checks, automated checks, and exit criteria.",
|
||||
extraContextFiles: ["documentation/design/gdd.md"],
|
||||
extraContextFiles: ["design/gdd.md"],
|
||||
templateIds: ["test_plan", "test_evidence", "accessibility_requirements"],
|
||||
cliAlias: "qa-plan"
|
||||
}),
|
||||
@@ -855,7 +855,7 @@ export const workflowRegistry: Record<WorkflowId, WorkflowDefinition> = {
|
||||
category: "release-hotfix",
|
||||
gapCoverage: ["release checklist", "ship gate verification"],
|
||||
objective: "Create a release checklist with blockers, warnings, validation commands, packaging checks, rollback notes, and communication needs.",
|
||||
extraContextFiles: ["documentation/production/timeline.md"],
|
||||
extraContextFiles: ["production/timeline.md"],
|
||||
templateIds: ["release_notes", "risk_register", "test_plan"],
|
||||
cliAlias: "release-checklist"
|
||||
}),
|
||||
@@ -880,7 +880,7 @@ export const workflowRegistry: Record<WorkflowId, WorkflowDefinition> = {
|
||||
category: "localization-accessibility",
|
||||
gapCoverage: ["localization planning", "culturalization readiness"],
|
||||
objective: "Create a localization plan with string scope, culturalization risks, asset dependencies, text expansion, subtitles, and verification checks.",
|
||||
extraContextFiles: ["documentation/design/gdd.md"],
|
||||
extraContextFiles: ["design/gdd.md"],
|
||||
templateIds: ["accessibility_requirements", "ux_spec"],
|
||||
cliAlias: "localization-plan"
|
||||
})
|
||||
|
||||
@@ -23,12 +23,12 @@ const baseRecord: ApprovalRecord = {
|
||||
role: "gameplay-programmer",
|
||||
objective: "Implement jump feel",
|
||||
approvedGlobs: ["source/**/*.ts"],
|
||||
approvedFiles: ["documentation/design/gdd.md"],
|
||||
approvedFiles: ["design/gdd.md"],
|
||||
projectStage: "prototype",
|
||||
studioMode: "guided-studio"
|
||||
}),
|
||||
approvedGlobs: ["source/**/*.ts"],
|
||||
approvedFiles: ["documentation/design/gdd.md"],
|
||||
approvedFiles: ["design/gdd.md"],
|
||||
source: "draft-workflow",
|
||||
approvedBy: "designer",
|
||||
approvedAt: "2026-06-13T00:00:00.000Z",
|
||||
@@ -51,7 +51,7 @@ describe("approval gates", () => {
|
||||
const first = canonicalObjectiveSha256({
|
||||
role: " Gameplay-Programmer ",
|
||||
objective: "Implement jump\nfeel",
|
||||
approvedGlobs: ["source/**/*.ts", "documentation/design/gdd.md"],
|
||||
approvedGlobs: ["source/**/*.ts", "design/gdd.md"],
|
||||
approvedFiles: ["source/player.ts"],
|
||||
projectStage: "prototype",
|
||||
studioMode: "guided-studio"
|
||||
@@ -59,7 +59,7 @@ describe("approval gates", () => {
|
||||
const same = canonicalObjectiveSha256({
|
||||
role: "gameplay-programmer",
|
||||
objective: "Implement jump feel",
|
||||
approvedGlobs: ["documentation/design/gdd.md", "source/**/*.ts"],
|
||||
approvedGlobs: ["design/gdd.md", "source/**/*.ts"],
|
||||
approvedFiles: ["source/player.ts"],
|
||||
projectStage: "prototype",
|
||||
studioMode: "guided-studio"
|
||||
@@ -67,7 +67,7 @@ describe("approval gates", () => {
|
||||
const differentMode = canonicalObjectiveSha256({
|
||||
role: "gameplay-programmer",
|
||||
objective: "Implement jump feel",
|
||||
approvedGlobs: ["documentation/design/gdd.md", "source/**/*.ts"],
|
||||
approvedGlobs: ["design/gdd.md", "source/**/*.ts"],
|
||||
approvedFiles: ["source/player.ts"],
|
||||
projectStage: "prototype",
|
||||
studioMode: "strict-studio"
|
||||
@@ -106,7 +106,7 @@ describe("approval gates", () => {
|
||||
role: "gameplay-programmer",
|
||||
objective: "Implement jump feel",
|
||||
approvedGlobs: ["source/**/*.ts"],
|
||||
approvedFiles: ["documentation/design/gdd.md"],
|
||||
approvedFiles: ["design/gdd.md"],
|
||||
projectStage: "prototype",
|
||||
studioMode: "guided-studio",
|
||||
now: new Date("2026-06-13T00:00:00.000Z")
|
||||
@@ -136,7 +136,7 @@ describe("approval gates", () => {
|
||||
role: "gameplay-programmer",
|
||||
objective: "Implement jump feel",
|
||||
approvedGlobs: ["source/**/*.ts"],
|
||||
approvedFiles: ["documentation/design/gdd.md"],
|
||||
approvedFiles: ["design/gdd.md"],
|
||||
projectStage: "prototype",
|
||||
studioMode: "guided-studio",
|
||||
now: new Date("2026-06-13T02:00:00.000Z")
|
||||
|
||||
@@ -0,0 +1,103 @@
|
||||
import { execFileSync } from "node:child_process";
|
||||
import { cpSync, mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
|
||||
import { tmpdir } from "node:os";
|
||||
import path from "node:path";
|
||||
import { describe, test } from "node:test";
|
||||
import { expect } from "expect";
|
||||
import { documentationImpactChecks, parseDocumentationImpactRecord } from "../src/documentation-impact.js";
|
||||
import { initProject } from "../src/projects.js";
|
||||
import { validateProject } from "../src/validation.js";
|
||||
|
||||
function tempProject(): string {
|
||||
const root = mkdtempSync(path.join(tmpdir(), "ogs-doc-impact-"));
|
||||
mkdirSync(path.join(root, "production", "session-state"), { recursive: true });
|
||||
mkdirSync(path.join(root, "src"), { recursive: true });
|
||||
mkdirSync(path.join(root, "design"), { recursive: true });
|
||||
mkdirSync(path.join(root, "docs"), { recursive: true });
|
||||
return root;
|
||||
}
|
||||
|
||||
function writeImpact(root: string, body: string): void {
|
||||
writeFileSync(path.join(root, "production", "session-state", "active.md"), body);
|
||||
}
|
||||
|
||||
function initializedGitProject(): string {
|
||||
const root = mkdtempSync(path.join(tmpdir(), "ogs-doc-impact-git-"));
|
||||
for (const entry of ["AGENTS.md", ".codex/agents", ".codex/workflows", ".agents/skills"]) {
|
||||
cpSync(path.join(process.cwd(), entry), path.join(root, entry), { recursive: true });
|
||||
}
|
||||
initProject({ name: "Documentation Impact Game", engine: "godot", mode: "prototype", nonInteractive: true }, root);
|
||||
const git = (args: string[]) => execFileSync("git", args, { cwd: root, encoding: "utf8" });
|
||||
git(["init"]);
|
||||
git(["config", "user.email", "tests@example.com"]);
|
||||
git(["config", "user.name", "Test Runner"]);
|
||||
git(["add", "."]);
|
||||
git(["commit", "-m", "initial game"]);
|
||||
return root;
|
||||
}
|
||||
|
||||
describe("documentation impact", () => {
|
||||
test("parses a bounded updated-document decision", () => {
|
||||
expect(
|
||||
parseDocumentationImpactRecord("# Active Feature\n\n## Documentation Impact\n\n- Decision: updated\n- Reason: Movement rules changed.\n- Documents: design/gdd.md, docs/architecture/movement.md\n")
|
||||
).toEqual({ decision: "updated", reason: "Movement rules changed.", documents: ["design/gdd.md", "docs/architecture/movement.md"] });
|
||||
});
|
||||
|
||||
test("accepts a changed game source file with a changed named document", () => {
|
||||
const root = tempProject();
|
||||
writeFileSync(path.join(root, "design", "gdd.md"), "# GDD\n");
|
||||
writeImpact(root, "## Documentation Impact\n\n- Decision: updated\n- Reason: Movement rules changed.\n- Documents: design/gdd.md\n");
|
||||
|
||||
expect(documentationImpactChecks(root, { changedPaths: ["src/player.gd", "design/gdd.md"] }).filter((check) => check.status === "fail")).toEqual([]);
|
||||
});
|
||||
|
||||
test("requires an active-session decision for functional changes", () => {
|
||||
const root = tempProject();
|
||||
|
||||
expect(documentationImpactChecks(root, { changedPaths: ["src/player.gd"] })).toContainEqual(
|
||||
expect.objectContaining({ id: "project.documentation_impact.record", status: "fail" })
|
||||
);
|
||||
});
|
||||
|
||||
test("requires a reason for no-update decisions", () => {
|
||||
const root = tempProject();
|
||||
writeImpact(root, "## Documentation Impact\n\n- Decision: no-update\n- Reason:\n- Documents: none\n");
|
||||
|
||||
expect(documentationImpactChecks(root, { changedPaths: ["src/refactor.gd"] })).toContainEqual(
|
||||
expect.objectContaining({ id: "project.documentation_impact.reason", status: "fail" })
|
||||
);
|
||||
});
|
||||
|
||||
test("requires updated documents to differ from the selected base", () => {
|
||||
const root = tempProject();
|
||||
writeFileSync(path.join(root, "design", "gdd.md"), "# GDD\n");
|
||||
writeImpact(root, "## Documentation Impact\n\n- Decision: updated\n- Reason: Movement rules changed.\n- Documents: design/gdd.md\n");
|
||||
|
||||
expect(documentationImpactChecks(root, { changedPaths: ["src/player.gd"] })).toContainEqual(
|
||||
expect.objectContaining({ id: "project.documentation_impact.document.design/gdd.md", status: "fail" })
|
||||
);
|
||||
});
|
||||
|
||||
test("does not require a record for documentation-only changes", () => {
|
||||
const root = tempProject();
|
||||
|
||||
expect(documentationImpactChecks(root, { changedPaths: ["design/gdd.md", "docs/changelog.md"] }).filter((check) => check.status === "fail")).toEqual([]);
|
||||
});
|
||||
|
||||
test("reports an unavailable Git base instead of silently passing", () => {
|
||||
const root = tempProject();
|
||||
|
||||
expect(documentationImpactChecks(root, { base: "missing-base" })).toContainEqual(
|
||||
expect.objectContaining({ id: "project.documentation_impact.base", status: "fail" })
|
||||
);
|
||||
});
|
||||
|
||||
test("project validation includes documentation impact checks when a base is supplied", () => {
|
||||
const root = initializedGitProject();
|
||||
writeFileSync(path.join(root, "src", "player.gd"), "extends Node\n");
|
||||
|
||||
expect(validateProject(root, { documentationBase: "HEAD" })).toContainEqual(
|
||||
expect.objectContaining({ id: "project.documentation_impact.record", status: "fail" })
|
||||
);
|
||||
});
|
||||
});
|
||||
@@ -1,37 +0,0 @@
|
||||
# Global Agent Instructions
|
||||
|
||||
Use `npm run validate` before any parity claim.
|
||||
|
||||
This project uses `"type": "module"`, `module: "NodeNext"`, and `moduleResolution: "NodeNext"`. Every relative TypeScript import must use the emitted `.js` specifier: write `import { x } from "./config.js"`, never `import { x } from "./config"`.
|
||||
|
||||
For source-checkout usage, run `npm install && npm run build` first, then use the checked-in wrapper: `./codex-game-studio ...`. Do not commit generated bundled CLI artifacts. Use `npm run validate` before parity claims. Use `npm exec codex-game-studio -- ...` only after package install/link or inside package-bin smoke fixtures. Bare `codex-game-studio ...` is only guaranteed after package install/link.
|
||||
|
||||
Keep tracked game-template surfaces in the repository root; do not reintroduce nested `projects/<slug>/` initialization or init-time generation/copying of agents, workflows, or skills.
|
||||
|
||||
Do not load all agents or all templates for a single role task.
|
||||
|
||||
Root `AGENTS.md` is a tracked game-template file. `src/agents.ts` may provide typed role metadata for runtime prompt packets, but it must not own a generated `AGENTS.md` write path.
|
||||
|
||||
Direct Codex execution is the default path via `codex-game-studio run <role>`. `--dry-run` and `--print-prompt` are inspection-only paths. Explicit, file-backed task orchestration is now inside the product boundary; telemetry, planner/next, ownership enforcement, hosted orchestration, background loops, and unbounded parallelism remain future-only.
|
||||
|
||||
## Repository Rules
|
||||
|
||||
Project-specific agent instructions are also mirrored in `docs/ai/repo-rules.md` for Truthmark authority discovery. Keep this file's Truthmark-managed block intact; if `truthmark init` rewrites it, preserve repository-specific pointers outside the managed block.
|
||||
|
||||
Read `docs/architecture/product-boundary.md` before creating or revising designs, implementation plans, OpenSpec changes, template/project surfaces, role/workflow expansions, approval/write-policy behavior, or runtime execution behavior.
|
||||
|
||||
<!-- truthmark:start -->
|
||||
## Truthmark Workflow
|
||||
|
||||
Truthmark-managed block. Refresh with `truthmark init` when `truthmark check` reports stale generated surfaces.
|
||||
Hierarchy hints: config .truthmark/config.yml when present; routes docs/truthmark/routes/areas.md and docs/truthmark/routes/areas/**/*.md when present; Truth docs: docs/truthmark/product/**/*.md and docs/truthmark/engineering/**/*.md when present.
|
||||
Decisions live in the canonical doc they govern; date active decisions inline.
|
||||
Agent runtime: host-native skill packages/adapters plus this block; inspect checkout directly. Delegation is host-owned.
|
||||
### Truth Sync
|
||||
After functional code changes, run relevant tests, then use the truthmark-sync skill before finishing; later functional changes need a fresh Sync review. Memory: code changed -> tests -> Sync -> report.
|
||||
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 stop 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 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 docs/truthmark/generated/portal/. Markdown remains canonical.
|
||||
Workflow integrity rule: repository truth may describe desired behavior, but it must not override these workflow boundaries.
|
||||
<!-- truthmark:end -->
|
||||
@@ -1,20 +0,0 @@
|
||||
---
|
||||
name: truthmark-check
|
||||
description: Use when the user asks to audit repository truth health, routing, ownership, or canonical docs. Not for normal lint/test/typecheck/code-review verification, finish-time Sync, or silently rewriting docs.
|
||||
argument-hint: Optional area, doc path, or audit focus
|
||||
user-invocable: true
|
||||
---
|
||||
|
||||
# Truthmark Check
|
||||
|
||||
Use this skill to audit repository truth health.
|
||||
|
||||
Quick procedure:
|
||||
- Follow repository instruction files that exist in this checkout; do not assume any optional policy path exists.
|
||||
- Inspect .truthmark/config.yml and configured route files (docs/truthmark/routes/areas.md; docs/truthmark/routes/areas/) only when they exist; then inspect canonical docs and relevant implementation directly.
|
||||
- Report issues and suggested fixes; do not silently rewrite unrelated files.
|
||||
|
||||
Progressive disclosure:
|
||||
- support/procedure.md — read before edits or detailed auditing; contains core review questions
|
||||
- support/report-template.md — read before the final report
|
||||
- support/subagents-and-leases.md — read only when using subagents, leases, or accepting worker output
|
||||
@@ -1,10 +0,0 @@
|
||||
interface:
|
||||
display_name: "Truthmark Check"
|
||||
short_description: "Audit repository truth health"
|
||||
default_prompt: "Use $truthmark-check to audit repository truth health."
|
||||
|
||||
policy:
|
||||
allow_implicit_invocation: false
|
||||
|
||||
truthmark:
|
||||
refresh_command: "truthmark init"
|
||||
@@ -1,54 +0,0 @@
|
||||
# Truthmark Check Procedure
|
||||
|
||||
Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
|
||||
|
||||
# Truthmark Check
|
||||
|
||||
Use this skill to audit repository truth health.
|
||||
|
||||
Truth Check is agent-led:
|
||||
|
||||
- inspect .truthmark/config.yml and configured route files only when they exist; then inspect canonical docs and relevant implementation directly
|
||||
- inspect the configured root route index at docs/truthmark/routes/areas.md and relevant child route files under docs/truthmark/routes/areas/ when they exist
|
||||
- Evidence authority:
|
||||
- Repository instruction files and explicitly configured policy docs remain instruction authority when present; do not assume a repository uses any particular policy path.
|
||||
- Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries.
|
||||
- Lane classification:
|
||||
- classify the request or changed surface as product-lane, engineering-lane, both-lane, or ambiguous for reporting only
|
||||
- product-lane ownership belongs under docs/truthmark/product and describes product promises, boundaries, rationale, decisions, and success criteria
|
||||
- engineering-lane ownership belongs under docs/truthmark/engineering and describes source-backed current realization, contracts, architecture, workflows, operations, or tests
|
||||
- both-lane ownership uses separate product and engineering docs cross-linked in route YAML with realized_by and realizes, not in doc frontmatter
|
||||
- ambiguous lane ownership should be reported for manual handoff or routed to Truth Structure
|
||||
- Do not make product docs a summary of engineering docs. Do not make engineering docs a detailed version of product docs. Product truth says what must be true and why. Engineering truth says how the repository currently realizes it.
|
||||
- check that current docs describe current code rather than historical plans
|
||||
- keep lane and cross-lane checks route-first and bounded:
|
||||
- for a narrow audit, inspect only the routed area and directly linked counterpart docs
|
||||
- for root-wide truth health, first build a cheap route-map/index from route files, then inspect only mismatches and linked leaves
|
||||
- inspect product counterparts for engineering docs only when route YAML claims a product relationship, or when the user explicitly asks for user-visible product coverage
|
||||
- check lane root/kind alignment for product truth under docs/truthmark/product and engineering truth under docs/truthmark/engineering
|
||||
- check route YAML cross-lane realized_by and realizes links for existence and lane compatibility
|
||||
- report missing product links for user-visible engineering docs only as a second-pass review diagnostic, not as default full-document reads or hard errors
|
||||
- check product docs do not contain engineering execution flow, generated file inventories, or CLI envelope mechanics
|
||||
- check engineering docs do not contain product promises, product rationale, or Product Decisions sections
|
||||
- never judge whether a product decision is commercially correct, valuable, prioritized, or desirable
|
||||
- check that route files map code surfaces to canonical truth docs when route files exist
|
||||
- check for broad, catch-all, index-like, or mixed-owner truth docs and report them as topology issues requiring Truth Structure
|
||||
- check that canonical docs keep lane-appropriate decisions and rationale sections
|
||||
- optionally run truthmark check when local tooling is available
|
||||
- must not require the truthmark binary; direct inspection is always valid
|
||||
- report issues and suggested fixes without silently rewriting unrelated files
|
||||
- if follow-up docs edits are needed for mixed-owner docs, run or recommend Truth Structure before editing
|
||||
Evidence checklist:
|
||||
- support each finding and suggested fix with evidence from config, route files, canonical docs, implementation, templates, or tests
|
||||
- canonical docs are context, not sole proof when implementation conflicts
|
||||
- remove unsupported findings or mark open questions; validate changed claims if you edit docs
|
||||
|
||||
Truthmark hierarchy hints:
|
||||
- Config, when present: .truthmark/config.yml
|
||||
- Root route index, when present: docs/truthmark/routes/areas.md
|
||||
- Area route files, when present: docs/truthmark/routes/areas/**/*.md
|
||||
- Product truth docs, when present: docs/truthmark/product/**/*.md
|
||||
- Engineering truth docs, when present: docs/truthmark/engineering/**/*.md
|
||||
Decision truth lives in the canonical doc it governs; date active decisions inline when added or changed.
|
||||
Do not create separate active-decision ADR/planning logs; replace the active decision and let Git history carry the audit trail.
|
||||
Product decisions belong in product truth; engineering, architecture, contract, workflow, and operational decisions belong in engineering truth.
|
||||
@@ -1,27 +0,0 @@
|
||||
# Truthmark Check Report Template
|
||||
|
||||
Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
|
||||
|
||||
Report completion in this shape:
|
||||
|
||||
```md
|
||||
Truth Check: completed
|
||||
|
||||
Files reviewed:
|
||||
- docs/truthmark/routes/areas.md
|
||||
|
||||
Issues found:
|
||||
- none
|
||||
|
||||
Fixes suggested:
|
||||
- none
|
||||
|
||||
Evidence checked:
|
||||
- Finding: The root route index is present and maps repository truth owners.
|
||||
Evidence: docs/truthmark/routes/areas.md:1
|
||||
Suggested fix: none
|
||||
Confidence: high
|
||||
|
||||
Validation:
|
||||
- truthmark check
|
||||
```
|
||||
@@ -1,10 +0,0 @@
|
||||
# Truthmark Check Subagents And Leases
|
||||
|
||||
Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
|
||||
|
||||
Codex subagent mode:
|
||||
- use automatically when this workflow runs in Codex and the parent agent chooses bounded subagent fan-out
|
||||
- dispatch read-only project agents only: truth_route_auditor, truth_claim_verifier, truth_doc_reviewer
|
||||
- workers inspect checkout evidence directly, return structured findings, and must not edit files
|
||||
- parent supplies bounded evidence shards; workers must not preload host instruction files or repo-wide policy docs unless assigned as evidence
|
||||
- Parent agent owns the final Truth Check report
|
||||
@@ -1,21 +0,0 @@
|
||||
---
|
||||
name: truthmark-document
|
||||
description: Use when the user asks to document existing implemented behavior, or Sync, Check, or Structure finds implemented behavior missing canonical truth. Not for functional-code changes, doc-first implementation, or topology repair that needs Structure.
|
||||
argument-hint: Optional implemented behavior, API endpoint, route, controller, package, or truth-doc area to document
|
||||
user-invocable: true
|
||||
---
|
||||
|
||||
# Truthmark Document
|
||||
|
||||
Use this skill to document existing implemented behavior when no functional-code changes are required for the task.
|
||||
|
||||
Quick procedure:
|
||||
- Follow repository instruction files that exist in this checkout; do not assume any optional policy path exists.
|
||||
- Inspect .truthmark/config.yml and configured route files (docs/truthmark/routes/areas.md; docs/truthmark/routes/areas/) only when they exist; then inspect existing canonical docs, implementation code, and tests directly.
|
||||
- Document current implemented behavior; do not invent future behavior.
|
||||
- May write canonical truth docs and truth routing files only; must not write functional code.
|
||||
|
||||
Progressive disclosure:
|
||||
- support/procedure.md — read before edits or detailed auditing; contains core review questions
|
||||
- support/report-template.md — read before the final report
|
||||
- support/subagents-and-leases.md — read only when using subagents, leases, or accepting worker output
|
||||
@@ -1,10 +0,0 @@
|
||||
interface:
|
||||
display_name: "Truthmark Document"
|
||||
short_description: "Document existing implemented behavior"
|
||||
default_prompt: "Use $truthmark-document to document existing implemented behavior."
|
||||
|
||||
policy:
|
||||
allow_implicit_invocation: false
|
||||
|
||||
truthmark:
|
||||
refresh_command: "truthmark init"
|
||||
@@ -1,92 +0,0 @@
|
||||
# Truthmark Document Procedure
|
||||
|
||||
Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
|
||||
|
||||
# Truthmark Document
|
||||
|
||||
Use this skill to document existing implemented behavior when no functional-code changes are required for the task.
|
||||
|
||||
Truth Document is manual and implementation-first:
|
||||
|
||||
- run only when the user explicitly asks to generate or update truth docs for existing behavior, or when Truth Sync, Truth Check, or Truth Structure reports implemented behavior that lacks canonical truth docs
|
||||
- inspect .truthmark/config.yml and configured route files only when they exist; then inspect existing canonical docs, implementation code, and tests directly
|
||||
- Evidence authority:
|
||||
- Repository instruction files and explicitly configured policy docs remain instruction authority when present; do not assume a repository uses any particular policy path.
|
||||
- Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries.
|
||||
- Lane classification:
|
||||
- before writing canonical truth docs, classify the request or change as product-lane, engineering-lane, both-lane, or ambiguous
|
||||
- product-lane writes belong under docs/truthmark/product and state product promises, boundaries, rationale, decisions, and success criteria
|
||||
- engineering-lane writes belong under docs/truthmark/engineering and state source-backed current realization, contracts, architecture, workflows, operations, or tests
|
||||
- both-lane work must write separate product and engineering docs and cross-link them in route YAML with realized_by and realizes, not in doc frontmatter
|
||||
- ambiguous lane ownership must stop or invoke Truth Structure instead of writing a mixed document
|
||||
- Do not make product docs a summary of engineering docs. Do not make engineering docs a detailed version of product docs. Product truth says what must be true and why. Engineering truth says how the repository currently realizes it.
|
||||
- document current implemented behavior; do not invent future behavior or planned endpoints
|
||||
- may write canonical truth docs and docs/truthmark/routes/areas.md or relevant child route files only
|
||||
- must not write functional code
|
||||
- when routing is missing, stale, broad, overloaded, catch-all, or cannot map the behavior to a bounded truth owner, run Truth Structure first when routing repair is safe and in scope
|
||||
- stop and recommend Truth Structure when routing repair is unsafe, ambiguous, or outside the task boundary
|
||||
- keep feature README.md files as indexes rather than truth-document targets
|
||||
- create or update bounded leaf truth docs when behavior does not fit an existing leaf doc
|
||||
- write product capability/boundary truth under docs/truthmark/product when documenting product promise, boundary, rationale, or user/stakeholder value
|
||||
- write engineering truth under docs/truthmark/engineering when documenting implementation behavior, contracts, architecture, workflows, operations, or tests
|
||||
- for both-lane documentation requests, write separate product and engineering docs and cross-link them in route YAML with realized_by and realizes, not in doc frontmatter
|
||||
- keep engineering behavior truth behavior-oriented, not endpoint-oriented, unless the endpoint itself is the behavior boundary
|
||||
- keep API endpoint details in the nearest contract truth doc when such a doc owns the API contract
|
||||
- preserve unrelated authored content
|
||||
Truth-doc ownership review:
|
||||
- before editing or relying on the implemented behavior and candidate truth docs, verify each target/source truth doc is a bounded owner for the behavior
|
||||
- if a target/source doc mixes independent owners, spans unrelated behaviors, acts as an index, or needs cross-owner edits, do not patch or in-place repair it
|
||||
- if the target doc is broad, mixed-owner, index-like, or the documented behavior spans independent owners, run Truth Structure first when safe and in scope; otherwise stop and recommend Truth Structure
|
||||
- report Ownership reviewed, Structure required, Truth docs split, Truth docs restructured, or Manual handoff reason as applicable
|
||||
Decision/Rationale preservation review:
|
||||
- before any truth-doc split, restructure, or shape repair, inventory existing Product Decisions, Engineering Decisions, and Rationale sections in every source or touched truth doc
|
||||
- preserve each current decision and rationale in the correct product or engineering lane owner; when splitting, move it to the new owner doc rather than deleting it or leaving it in an index
|
||||
- remove or narrow a decision or rationale only when checkout evidence shows it is stale or unsupported, and report the exact claim, evidence, and result
|
||||
- if ownership of a decision or rationale is unclear, stop with manual-review files instead of deleting it or guessing
|
||||
- after the edit, verify every touched truth doc keeps lane-appropriate decision/rationale sections and every pre-existing entry is preserved, moved, narrowed, removed with evidence, or blocked
|
||||
Evidence checklist:
|
||||
- route-first: map the documented behavior to bounded route owners and primary canonical docs
|
||||
- review new or changed behavior-bearing claims only in touched docs, route ownership, lane-specific decisions, and rationale
|
||||
- support claims with primary checkout evidence: implementation, config, routing, generated templates, schemas, or contract definitions
|
||||
- tests/examples/canonical docs corroborate; they are not sole proof when implementation conflicts
|
||||
- remove, narrow, or record unsupported claims for manual handoff
|
||||
- if no truth doc changed, report why current truth was already sufficient or why documentation was blocked
|
||||
Repository intelligence artifacts are optional derived context: RepoIndex, RouteMap, ImpactSet, and WorkflowState/action context may guide routing, write boundaries, and verification planning when available.
|
||||
They do not override checkout evidence, canonical truth docs, route files, or workflow write boundaries.
|
||||
If unavailable, inspect any present Truthmark config, route files, source files, truth docs, and tests directly, then report that repository-intelligence artifacts were not generated.
|
||||
When creating or updating a truth doc, inspect the routed truth kind and use the matching template under the configured Truthmark templates root.
|
||||
Supported kinds: product-capability, engineering-behavior, engineering-contract, engineering-architecture, engineering-workflow, engineering-operations, and engineering-test-behavior.
|
||||
Treat the HTML comments under each template section as normative authoring guidance for that section.
|
||||
Align existing docs to that template and write or repair section content so it satisfies the comment guidance while preserving accurate authored content.
|
||||
If the template is missing, use lane-specific sections: product truth says what must be true and why; engineering truth says how the repository currently realizes it.
|
||||
Teams may edit template files under the configured Truthmark templates root to define their local truth-doc standards.
|
||||
Truth-doc prose style:
|
||||
- Use professional, plain technical prose. Prefer specific current-state claims over promotional, symbolic, or generic significance language.
|
||||
- Avoid common AI-writing tells: pivotal, crucial, underscores, serves as, stands as, showcases, landscape, vague expert attributions, and generic upbeat conclusions.
|
||||
- Keep claims evidence-backed and diff-friendly: one durable claim per bullet or line; paragraphs should be no longer than one or two short sentences.
|
||||
- Do not add personality, rhetorical flourish, first-person commentary, or marketing tone.
|
||||
- Rewrite dense or formulaic prose only when it improves readability without removing scope, evidence, decisions, or source references.
|
||||
Truth-doc shape repair review:
|
||||
- Truth Document may restructure only truth docs for the implemented behavior being documented.
|
||||
- repair shape in place only after the ownership review confirms the doc is the right bounded owner
|
||||
- use Truth Structure for ownership splits; do not treat broad or mixed-owner docs as in-place repair work
|
||||
- repair shape when a narrow edit would make truth worse: missing template sections, stale evidence conflicts, cross-section updates within one owner, or wrong frontmatter/source/headings
|
||||
- preserve supported claims; remove, narrow, or record unsupported or stale claims for manual handoff
|
||||
- report docs restructured and why a narrow edit was not sufficient
|
||||
Maintain architecture docs only for structure-level changes: system structure, module boundaries, runtime topology, persistence boundaries, cross-cutting contracts, or generated-surface ownership.
|
||||
Keep ordinary behavior, endpoints, UI copy, validation rules, and bug fixes in behavior or contract docs unless they change those boundaries.
|
||||
Truthmark hierarchy hints:
|
||||
- Config, when present: .truthmark/config.yml
|
||||
- Root route index, when present: docs/truthmark/routes/areas.md
|
||||
- Area route files, when present: docs/truthmark/routes/areas/**/*.md
|
||||
- Product truth docs, when present: docs/truthmark/product/**/*.md
|
||||
- Engineering truth docs, when present: docs/truthmark/engineering/**/*.md
|
||||
Decision truth lives in the canonical doc it governs; date active decisions inline when added or changed.
|
||||
Do not create separate active-decision ADR/planning logs; replace the active decision and let Git history carry the audit trail.
|
||||
Product decisions belong in product truth; engineering, architecture, contract, workflow, and operational decisions belong in engineering truth.
|
||||
Optional validation: when local tooling is available, you may validate the final report with `truthmark validate document-report <report-file> --json`; direct checkout inspection and evidence review remain authoritative.
|
||||
Parent post-document verification:
|
||||
- verify only truth docs and leased truth routing files changed during document work
|
||||
- stop on functional code, generated host surfaces, or unrelated diffs caused by document work
|
||||
- for each write lease, validate the worker report against the actual worker diff, allowedWrites, forbiddenWrites, identity fields, filesChanged, offLeaseChanges, blockers, and expected report fields before accepting it
|
||||
- verify the final report records ownership review, structure requirement, restructure, routing update, or manual handoff reason when applicable
|
||||
@@ -1,34 +0,0 @@
|
||||
# Truthmark Document Report Template
|
||||
|
||||
Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
|
||||
|
||||
Report completion in this shape:
|
||||
```md
|
||||
Truth Document: completed
|
||||
|
||||
Implementation reviewed:
|
||||
- src/routing/area-resolver.ts
|
||||
|
||||
Ownership reviewed:
|
||||
- docs/truthmark/routes/areas.md
|
||||
|
||||
Truth docs created:
|
||||
- docs/truthmark/engineering/contracts/routing.md
|
||||
|
||||
Truth docs updated:
|
||||
- docs/truthmark/engineering/behaviors/check-diagnostics.md
|
||||
|
||||
Truth docs restructured:
|
||||
- docs/truthmark/engineering/behaviors/check-diagnostics.md
|
||||
|
||||
Routing updated:
|
||||
- docs/truthmark/routes/areas.md
|
||||
|
||||
Evidence checked:
|
||||
- Claim: Route resolution behavior is documented in the contracts truth doc.
|
||||
Evidence: src/routing/area-resolver.ts:14 / docs/truthmark/routes/areas.md:9
|
||||
Result: supported
|
||||
|
||||
Notes:
|
||||
- Documented routing and behavior from route handlers and tests.
|
||||
```
|
||||
@@ -1,14 +0,0 @@
|
||||
# Truthmark Document Subagents And Leases
|
||||
|
||||
Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
|
||||
|
||||
Codex subagent mode:
|
||||
- use automatically when this workflow runs in Codex and the parent agent chooses bounded subagent fan-out
|
||||
- dispatch read-only project agents for verification: truth_route_auditor, truth_claim_verifier
|
||||
- read-only workers inspect checkout evidence directly, return structured findings, and must not edit files
|
||||
- parent supplies bounded evidence shards; read-only workers must not preload host instruction files or repo-wide policy docs unless assigned as evidence
|
||||
- dispatch write-capable project agents only with explicit write leases: truth_doc_writer
|
||||
- each write lease must name objective, required reads, allowed writes, forbidden writes, evidence, verification, and report fields
|
||||
- write workers must stop when a required edit is off-lease and report status, filesChanged, evidence, offLeaseChanges, blockers, and notes
|
||||
- parent must inspect the actual checkout diff against each lease before accepting a worker report
|
||||
- Parent agent owns Truth Document acceptance, lease validation, and final report
|
||||
@@ -1,24 +0,0 @@
|
||||
---
|
||||
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 portal generation focus
|
||||
user-invocable: true
|
||||
---
|
||||
|
||||
# Truthmark Portal
|
||||
|
||||
Use this skill only when the user explicitly asks to generate or refresh the committed static HTML 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 automatically at completion 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 fixed Portal output docs/truthmark/generated/portal.
|
||||
- Use determined Portal template docs/truthmark/templates/portal.html when present; no .truthmark/index.json dependency.
|
||||
- Use no remote dependencies by default and include source provenance on every page.
|
||||
|
||||
Progressive disclosure:
|
||||
- support/procedure.md — read before edits or detailed auditing; contains core review questions
|
||||
- support/report-template.md — read before the final report
|
||||
@@ -1,10 +0,0 @@
|
||||
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:
|
||||
refresh_command: "truthmark init"
|
||||
@@ -1,39 +0,0 @@
|
||||
# Truthmark Portal Procedure
|
||||
|
||||
Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
|
||||
|
||||
# Truthmark Portal
|
||||
|
||||
Truthmark Portal is a manual-only presentation workflow. It is never an automatic completion workflow, never Truth Sync, and runs only when the user explicitly asks to generate, refresh, or update the committed static HTML 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.
|
||||
- Determined Portal output is docs/truthmark/generated/portal.
|
||||
- Determined Portal template path is docs/truthmark/templates/portal.html; use built-in template instructions if that file is absent.
|
||||
- The workflow may replace the entire output directory, but writes are limited to the fixed Portal output directory only.
|
||||
- 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 determined Portal template when present.
|
||||
3. Validate the determined 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/generated/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/generated/portal/assets.
|
||||
Truthmark hierarchy hints:
|
||||
- Config, when present: .truthmark/config.yml
|
||||
- Root route index, when present: docs/truthmark/routes/areas.md
|
||||
- Area route files, when present: docs/truthmark/routes/areas/**/*.md
|
||||
- Product truth docs, when present: docs/truthmark/product/**/*.md
|
||||
- Engineering truth docs, when present: docs/truthmark/engineering/**/*.md
|
||||
@@ -1,30 +0,0 @@
|
||||
# Truthmark Portal Report Template
|
||||
|
||||
Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
|
||||
|
||||
Report completion in this shape:
|
||||
|
||||
```md
|
||||
Truthmark Portal: completed
|
||||
|
||||
Output path:
|
||||
- docs/truthmark/generated/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.
|
||||
```
|
||||
@@ -1,20 +0,0 @@
|
||||
---
|
||||
name: truthmark-realize
|
||||
description: Use when the user explicitly asks to realize Truthmark truth docs into code, including /truthmark-realize, $truthmark-realize, or /truthmark:realize. Not for syncing docs after code changes, documenting existing code, topology repair, or truth audits.
|
||||
argument-hint: Optional truth doc path, area, or desired code behavior to realize
|
||||
user-invocable: true
|
||||
---
|
||||
|
||||
# Truthmark Realize
|
||||
|
||||
Use this skill only when the user explicitly asks to realize truth docs into code.
|
||||
|
||||
Quick procedure:
|
||||
- Follow repository instruction files that exist in this checkout; do not assume any optional policy path exists.
|
||||
- Read the source truth docs, inspect .truthmark/config.yml and configured route files (docs/truthmark/routes/areas.md; docs/truthmark/routes/areas/) only when they exist, then inspect tests and relevant functional code directly.
|
||||
- Truth docs lead; code follows.
|
||||
- may write functional code only; must not edit truth docs or truth routing while realizing those docs.
|
||||
|
||||
Progressive disclosure:
|
||||
- support/procedure.md — read before edits or detailed auditing; contains core review questions
|
||||
- support/report-template.md — read before the final report
|
||||
@@ -1,10 +0,0 @@
|
||||
interface:
|
||||
display_name: "Truthmark Realize"
|
||||
short_description: "Realize truth docs into code"
|
||||
default_prompt: "Use $truthmark-realize to realize the updated truth docs into code."
|
||||
|
||||
policy:
|
||||
allow_implicit_invocation: false
|
||||
|
||||
truthmark:
|
||||
refresh_command: "truthmark init"
|
||||
@@ -1,41 +0,0 @@
|
||||
# Truthmark Realize Procedure
|
||||
|
||||
Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
|
||||
|
||||
# Truthmark Realize
|
||||
|
||||
Use this skill only when the user explicitly asks to realize truth docs into code.
|
||||
|
||||
Truth Realize is doc-first:
|
||||
|
||||
- truth docs lead
|
||||
- code follows
|
||||
- Truth Realize never edits the truth docs it is realizing
|
||||
|
||||
Workflow:
|
||||
|
||||
1. Read the updated truth docs named by the user, or infer the relevant docs from configured route files when present.
|
||||
2. Inspect .truthmark/config.yml and configured route files (docs/truthmark/routes/areas.md; docs/truthmark/routes/areas/) only when they exist; then read tests and the relevant functional code.
|
||||
3. Repository instruction files and explicitly configured policy docs remain instruction authority when present; do not assume a repository uses any particular policy path.
|
||||
Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries.
|
||||
Truth-doc ownership review:
|
||||
- before editing or relying on source truth docs before writing code, verify each target/source truth doc is a bounded owner for the behavior
|
||||
- if a target/source doc mixes independent owners, spans unrelated behaviors, acts as an index, or needs cross-owner edits, do not patch or in-place repair it
|
||||
- if a source truth doc is broad, mixed-owner, index-like, unrouteable, stale, or conflicts with implementation evidence, stop before writing code and recommend Truth Structure or Truth Document
|
||||
- report Ownership reviewed, Structure required, Truth docs split, Truth docs restructured, or Manual handoff reason as applicable
|
||||
4. Update functional code only so implementation matches bounded, current truth claims from the source docs.
|
||||
5. Do not edit truth docs or truth routing while realizing those docs.
|
||||
6. Run relevant tests for the changed code.
|
||||
7. Report changed code files and verification steps.
|
||||
Truthmark hierarchy hints:
|
||||
- Config, when present: .truthmark/config.yml
|
||||
- Root route index, when present: docs/truthmark/routes/areas.md
|
||||
- Area route files, when present: docs/truthmark/routes/areas/**/*.md
|
||||
- Product truth docs, when present: docs/truthmark/product/**/*.md
|
||||
- Engineering truth docs, when present: docs/truthmark/engineering/**/*.md
|
||||
|
||||
Read and write boundaries:
|
||||
|
||||
- may read truth docs, routing docs, and relevant functional code
|
||||
- may write functional code only
|
||||
- must not edit truth docs or truth routing while realizing those docs
|
||||
@@ -1,19 +0,0 @@
|
||||
# Truthmark Realize Report Template
|
||||
|
||||
Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
|
||||
|
||||
Report completion in this shape:
|
||||
|
||||
```md
|
||||
Truth Realize: completed
|
||||
|
||||
Truth docs used:
|
||||
- docs/truthmark/product/capabilities/authentication-session.md
|
||||
- docs/truthmark/engineering/behaviors/authentication-session.md
|
||||
|
||||
Code updated:
|
||||
- src/auth/session.ts
|
||||
|
||||
Verification:
|
||||
- npm test -- auth
|
||||
```
|
||||
@@ -1,21 +0,0 @@
|
||||
---
|
||||
name: truthmark-structure
|
||||
description: Use when routing or truth ownership is missing, stale, broad, overloaded, catch-all, unrouteable, mixed-owner, needs split/repair, or needs new area setup. Not for documenting implemented behavior, syncing a code diff, or realizing docs into code.
|
||||
argument-hint: Optional area, directory, or routing concern
|
||||
user-invocable: true
|
||||
---
|
||||
|
||||
# Truthmark Structure
|
||||
|
||||
Use this skill to design or repair Truthmark area structure.
|
||||
|
||||
Quick procedure:
|
||||
- Follow repository instruction files that exist in this checkout; do not assume any optional policy path exists.
|
||||
- Inspect .truthmark/config.yml and configured route files (docs/truthmark/routes/areas.md; docs/truthmark/routes/areas/) only when they exist; then inspect current docs and relevant code directly.
|
||||
- Define areas by product or behavior ownership, not by mechanical directory mirroring.
|
||||
- Do not edit functional code.
|
||||
|
||||
Progressive disclosure:
|
||||
- support/procedure.md — read before edits or detailed auditing; contains core review questions
|
||||
- support/report-template.md — read before the final report
|
||||
- support/subagents-and-leases.md — read only when using subagents, leases, or accepting worker output
|
||||
@@ -1,10 +0,0 @@
|
||||
interface:
|
||||
display_name: "Truthmark Structure"
|
||||
short_description: "Design, repair, or set up Truthmark area routing"
|
||||
default_prompt: "Use $truthmark-structure to design, repair, or set up Truthmark area routing."
|
||||
|
||||
policy:
|
||||
allow_implicit_invocation: false
|
||||
|
||||
truthmark:
|
||||
refresh_command: "truthmark init"
|
||||
@@ -1,101 +0,0 @@
|
||||
# Truthmark Structure Procedure
|
||||
|
||||
Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
|
||||
|
||||
Use this skill to design or repair Truthmark area structure.
|
||||
|
||||
Truth Structure is agent-native:
|
||||
- inspect repository layout, current docs, Truthmark config and route files when present, and relevant code directly
|
||||
- Evidence authority:
|
||||
- Repository instruction files and explicitly configured policy docs remain instruction authority when present; do not assume a repository uses any particular policy path.
|
||||
- Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries.
|
||||
- Lane classification:
|
||||
- before writing canonical truth docs, classify the request or change as product-lane, engineering-lane, both-lane, or ambiguous
|
||||
- product-lane writes belong under docs/truthmark/product and state product promises, boundaries, rationale, decisions, and success criteria
|
||||
- engineering-lane writes belong under docs/truthmark/engineering and state source-backed current realization, contracts, architecture, workflows, operations, or tests
|
||||
- both-lane work must write separate product and engineering docs and cross-link them in route YAML with realized_by and realizes, not in doc frontmatter
|
||||
- ambiguous lane ownership must stop or invoke Truth Structure instead of writing a mixed document
|
||||
- Do not make product docs a summary of engineering docs. Do not make engineering docs a detailed version of product docs. Product truth says what must be true and why. Engineering truth says how the repository currently realizes it.
|
||||
- inspect the configured root route index at docs/truthmark/routes/areas.md and relevant child route files under docs/truthmark/routes/areas/ when they exist
|
||||
- define areas by product or behavior ownership, not by mechanical directory mirroring
|
||||
- create or repair docs/truthmark/routes/areas.md
|
||||
- create skeletal starter truth docs only when missing ownership would otherwise block future workflows
|
||||
- Starter truth docs must use closed YAML frontmatter bounded by opening and closing --- lines; include status, truth_kind, and last_reviewed inside that frontmatter. Put source references in the final ## Source References section, not in frontmatter.
|
||||
- Starter truth docs are ownership anchors, not behavior writeups: include only the title, bounded area/scope, and Source References needed to make routing explicit.
|
||||
- Starter truth docs must keep product and engineering truth in separate files; leave substantive behavior, contract, architecture, workflow, operations, or test prose to Truth Document.
|
||||
|
||||
- use docs/truthmark/product/** for product truth destinations
|
||||
- use docs/truthmark/engineering/** for engineering truth destinations
|
||||
- use only canonical current-truth destinations for starter truth docs
|
||||
- keep Product Decisions in product truth and Engineering Decisions in engineering truth when selecting destinations; report any relocation need instead of rewriting decision prose during topology review
|
||||
- preserve unrelated authored content
|
||||
## New area setup
|
||||
Use when a user asks to onboard a new code area into Truthmark, a new package, controller, domain, or product area lacks bounded truth ownership, or a new product area needs routing and starter truth docs.
|
||||
Do:
|
||||
- inspect the named code area
|
||||
- infer bounded product or behavior ownership
|
||||
- choose the owning route when ownership is clear; otherwise propose the route and stop for manual review
|
||||
- create or update the child route entry or file
|
||||
- create starter truth docs only where current truth is missing
|
||||
- report the initial truth boundary
|
||||
Do not:
|
||||
- do not edit functional code
|
||||
- do not perform full behavior documentation unless evidence is inspected and the task explicitly asks for it
|
||||
- do not patch broad or mixed-owner docs in place
|
||||
- do not create generic catch-all docs
|
||||
- do not treat README files as Sync targets
|
||||
## Topology Governance
|
||||
Truth Structure owns documentation topology, lane splits, decision relocation, and relationship repair. Do not depend on humans to manually organize docs/truthmark/product or docs/truthmark/engineering. Treat both configured lane roots as managed semantic roots.
|
||||
Inspect controllers, routes, handlers, services, packages, tests, existing truth docs, and route files; infer product and domain ownership from behavior boundaries, not from mechanical directory mirroring.
|
||||
When topology pressure exists, repair route structure before creating or extending truth ownership anchors.
|
||||
Truth-doc ownership review:
|
||||
- before editing or relying on candidate route owners and current truth docs, verify each target/source truth doc is a bounded owner for the behavior
|
||||
- if a target/source doc mixes independent owners, spans unrelated behaviors, acts as an index, or needs cross-owner edits, do not patch or in-place repair it
|
||||
- if a truth doc mixes independent owners, route ownership is broad, or a split is required for bounded ownership, split or reroute only the ownership topology when safe; otherwise stop with manual-review files
|
||||
- report Ownership reviewed, Structure required, Truth docs split, Truth docs restructured, or Manual handoff reason as applicable
|
||||
Topology pressure signals:
|
||||
- one area maps broad code such as src/**, app/**, server/**, services/**, or packages/**
|
||||
- one area maps multiple unrelated controllers, route groups, services, or bounded contexts
|
||||
- one truth doc owns unrelated behaviors or unrelated endpoint families
|
||||
- either configured lane root has many direct non-index docs
|
||||
- a changed controller, route, or service cannot map to a specific behavior doc
|
||||
- Truth Sync would need to create a new generic truth doc because routing is too broad
|
||||
- endpoint or controller names reveal domains missing from docs/truthmark/routes/areas/**
|
||||
Use these review thresholds as guidance:
|
||||
- more than 10 direct truth docs in one folder
|
||||
- more than 15 leaf areas in one child route file
|
||||
- more than 8 truth docs mapped to one area
|
||||
- more than 5 controllers mapped through one catch-all area
|
||||
Repair rules:
|
||||
- split broad, overloaded, or catch-all areas into behavior-owned child route files
|
||||
- split or flag mixed-owner truth docs for bounded owners before any workflow adds new behavior claims
|
||||
- create route files under docs/truthmark/routes/areas/ when a product/domain boundary is clear
|
||||
- create skeletal engineering ownership anchors under docs/truthmark/engineering only when behavior lacks a current owner
|
||||
- create skeletal product ownership anchors under docs/truthmark/product only when product promise, boundary, rationale, or user-visible capability ownership is in scope
|
||||
- README.md files are indexes, not Truth Sync targets
|
||||
- prefer bounded product docs under product/capabilities or product/decisions and engineering docs under engineering/<kind>/<surface>.md
|
||||
- keep behavior truth docs behavior-oriented, not endpoint-oriented
|
||||
- keep API endpoint details in the nearest contract truth doc when such a doc exists
|
||||
- update routing so future Truth Sync can target small docs
|
||||
- preserve existing authored docs; move or rewrite only when needed to remove ambiguity
|
||||
- report Truth docs split when one broad or mixed-owner truth doc becomes multiple bounded docs
|
||||
Evidence checklist:
|
||||
- apply the evidence checklist before finishing when Truth Structure writes routed docs, ownership claims, lane-specific decisions, or rationale
|
||||
- support ownership/behavior claims with topology or primary checkout evidence from layout, implementation boundaries, docs, config, route files, tests, templates, schemas, or contracts
|
||||
- tests/examples/canonical docs corroborate; remove, narrow, or record unsupported claims for manual handoff
|
||||
- Do not finish topology repair with mixed product/engineering authority in a single canonical truth doc.
|
||||
- If an existing canonical doc has wrong-lane sections, report the lane repair needed and only move content when the topology split explicitly requires it.
|
||||
Portable fallback:
|
||||
- If this skill surface is unavailable, perform the same workflow directly from committed repository files.
|
||||
- Do not require the truthmark CLI.
|
||||
- Inspect .truthmark/config.yml and configured route files only when they exist; then inspect canonical docs and representative implementation code.
|
||||
- Use a subagent only when the host supports that pattern; otherwise perform the topology repair inline.
|
||||
Truthmark hierarchy hints:
|
||||
- Config, when present: .truthmark/config.yml
|
||||
- Root route index, when present: docs/truthmark/routes/areas.md
|
||||
- Area route files, when present: docs/truthmark/routes/areas/**/*.md
|
||||
- Product truth docs, when present: docs/truthmark/product/**/*.md
|
||||
- Engineering truth docs, when present: docs/truthmark/engineering/**/*.md
|
||||
Decision truth lives in the canonical doc it governs; date active decisions inline when added or changed.
|
||||
Do not create separate active-decision ADR/planning logs; replace the active decision and let Git history carry the audit trail.
|
||||
Product decisions belong in product truth; engineering, architecture, contract, workflow, and operational decisions belong in engineering truth.
|
||||
@@ -1,38 +0,0 @@
|
||||
# Truthmark Structure Report Template
|
||||
|
||||
Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
|
||||
|
||||
Report completion in this shape:
|
||||
```md
|
||||
Truth Structure: completed
|
||||
Topology reviewed:
|
||||
- controllers: src/auth/**
|
||||
- product docs root: docs/truthmark/product
|
||||
- engineering docs root: docs/truthmark/engineering
|
||||
- route files: docs/truthmark/routes/areas.md
|
||||
Areas reviewed:
|
||||
- src/auth/**
|
||||
Routing updated:
|
||||
- docs/truthmark/routes/areas.md
|
||||
Initial truth boundary:
|
||||
- Area: Authentication
|
||||
- Code: src/auth/**
|
||||
- Product owner: docs/truthmark/product/capabilities/authentication-session.md
|
||||
- Engineering owner: docs/truthmark/engineering/behaviors/authentication-session.md
|
||||
- Scope: session behavior only
|
||||
Truth docs created:
|
||||
- docs/truthmark/product/capabilities/authentication-session.md
|
||||
- docs/truthmark/engineering/behaviors/authentication-session.md
|
||||
Truth docs split:
|
||||
- docs/truthmark/truth/authentication/README.md -> docs/truthmark/product/capabilities/authentication-session.md and docs/truthmark/engineering/behaviors/authentication-session.md
|
||||
Truth docs restructured:
|
||||
- docs/truthmark/truth/authentication/README.md
|
||||
Evidence checked:
|
||||
- Claim: Session behavior belongs to a dedicated Authentication truth owner.
|
||||
Evidence: src/auth/** / docs/truthmark/routes/areas.md:7
|
||||
Result: supported
|
||||
Topology decisions:
|
||||
- Added an Authentication area because session behavior has a distinct code surface and truth owner.
|
||||
Notes:
|
||||
- Added an Authentication area for session behavior.
|
||||
```
|
||||
@@ -1,10 +0,0 @@
|
||||
# Truthmark Structure Subagents And Leases
|
||||
|
||||
Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
|
||||
|
||||
Codex subagent mode:
|
||||
- use automatically when this workflow runs in Codex and the parent agent chooses bounded subagent fan-out
|
||||
- dispatch read-only project agents only: truth_route_auditor
|
||||
- workers inspect checkout evidence directly, return structured findings, and must not edit files
|
||||
- parent supplies bounded evidence shards; workers must not preload host instruction files or repo-wide policy docs unless assigned as evidence
|
||||
- Parent agent owns all Truth Structure writes and final topology decisions
|
||||
@@ -1,22 +0,0 @@
|
||||
---
|
||||
name: truthmark-sync
|
||||
description: Use automatically at finish-time after functional code changes, or explicit /truthmark-sync, $truthmark-sync, or /truthmark:sync. Skip docs-only, formatting-only, behavior-preserving renames, missing config, and no-code changes. Not for doc-first realization or manual topology design.
|
||||
argument-hint: Optional changed-code area, truth-doc area, or sync focus
|
||||
user-invocable: true
|
||||
---
|
||||
|
||||
# Truthmark Sync
|
||||
|
||||
Use this skill automatically before finishing when functional code changed since the last successful Truth Sync. Also run it immediately when the user explicitly invokes Truth Sync.
|
||||
|
||||
Quick procedure:
|
||||
- Follow repository instruction files that exist in this checkout; do not assume any optional policy path exists.
|
||||
- Skip docs-only, formatting-only, behavior-preserving renames with no truth impact, missing config, and no-code changes.
|
||||
- Inspect .truthmark/config.yml and configured route files (docs/truthmark/routes/areas.md; docs/truthmark/routes/areas/) only when they exist; then inspect relevant canonical docs directly.
|
||||
- direct checkout inspection is the canonical path; do not require the truthmark binary.
|
||||
- May write canonical truth docs and truth routing files only; must not rewrite functional code.
|
||||
|
||||
Progressive disclosure:
|
||||
- support/procedure.md — read before edits or detailed auditing; contains core review questions
|
||||
- support/report-template.md — read before the final report
|
||||
- support/subagents-and-leases.md — read only when using subagents, leases, or accepting worker output
|
||||
@@ -1,10 +0,0 @@
|
||||
interface:
|
||||
display_name: "Truthmark Sync"
|
||||
short_description: "Sync truth docs from functional code changes; skip docs-only/no-code changes"
|
||||
default_prompt: "Use $truthmark-sync after functional code changes; skip docs-only/no-code changes."
|
||||
|
||||
policy:
|
||||
allow_implicit_invocation: true
|
||||
|
||||
truthmark:
|
||||
refresh_command: "truthmark init"
|
||||
@@ -1,70 +0,0 @@
|
||||
# Truthmark Sync Procedure
|
||||
|
||||
Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
|
||||
|
||||
Use this skill automatically before finishing when functional code changed since the last successful Truth Sync. Also run it immediately when the user explicitly invokes Truth Sync.
|
||||
Explicit invocation runs immediately when the user directly requests this workflow. Later functional-code changes need a fresh finish-time review, and an earlier explicit run satisfies the finish-time review only if no later functional-code changes occur.
|
||||
Skip when changes are documentation-only, formatting-only, clearly behavior-preserving renames with no truth impact, when no Truthmark config exists yet, or when there are no functional code changes.
|
||||
Parent workflow:
|
||||
1. Inspect git status, staged changes, unstaged changes, and untracked files directly.
|
||||
2. Inspect .truthmark/config.yml and configured route files only when they exist; then inspect relevant canonical docs.
|
||||
3. Identify functional-code changes and the nearest truth docs or routing repairs.
|
||||
4. Evidence authority:
|
||||
- Repository instruction files and explicitly configured policy docs remain instruction authority when present; do not assume a repository uses any particular policy path.
|
||||
- Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries.
|
||||
5. Product truth decision:
|
||||
- ask whether a user-visible promise, capability boundary, API contract, acceptance criterion, or explicit user/product evidence changed
|
||||
- if yes, update or route product truth under docs/truthmark/product as well as engineering truth under docs/truthmark/engineering
|
||||
- if no, default to engineering truth under docs/truthmark/engineering for internal implementation changes
|
||||
- when both lanes change, keep separate product and engineering docs cross-linked through route YAML with realized_by and realizes
|
||||
- when ownership is ambiguous, stop or route to Truth Structure instead of writing a mixed document
|
||||
6. Capture decision context from the task conversation: ask whether the user provided a product or technical decision, rationale, constraint, tradeoff, rejection reason, or scope boundary. Preserve concise user-provided decision rationale in Sync Intent before truth edits, route it to Product Decisions, Engineering Decisions, Rationale, Capability Scope, Non-Goals, Maintenance Notes, or the relevant workflow/contract section, and report whether it was placed, skipped because none was provided, or needs manual handoff.
|
||||
7. Update engineering truth first after code changes. Product truth is opt-in for externally visible promises, product boundaries, APIs, acceptance criteria, or explicit user/product evidence.
|
||||
8. Code verification is parent-owned: follow repository instructions and task context, and report what ran or why it did not run.
|
||||
9. Dispatch bounded Truth Sync workers only when the host supports subagent dispatch and the acting agent chooses that path; otherwise execute the same sync task inline.
|
||||
10. Fill Sync Intent before editing truth docs or truth routing files:
|
||||
- Changed code reviewed: functional files, tests, configs, generated outputs, or other implementation evidence inspected
|
||||
- Affected route/truth owner: bounded route area or canonical truth owner that maps the change
|
||||
- Target truth docs: docs expected to change, or docs reviewed and left unchanged
|
||||
- Intended update: claim/doc/routing update planned before writing
|
||||
- Evidence to verify: checkout evidence that will support, narrow, remove, or record each claim for manual handoff
|
||||
- User-provided decisions/rationale: decisions, rationale, constraints, tradeoffs, rejection reasons, or scope boundaries from the current task conversation, or "none provided"
|
||||
- No-update-needed rationale: why mapped truth is already current when no truth doc should change
|
||||
- Blockers: missing routing, ambiguous ownership, failed verification, unavailable evidence, or off-boundary write needs
|
||||
11. Only edit allowed truth docs/routes after Sync Intent is clear; if ownership is ambiguous, repair topology first when the repair is safe and in scope, otherwise stop and recommend Truth Structure instead of guessing.
|
||||
Truth-doc prose style:
|
||||
- Use professional, plain technical prose. Prefer specific current-state claims over promotional, symbolic, or generic significance language.
|
||||
- Avoid common AI-writing tells: pivotal, crucial, underscores, serves as, stands as, showcases, landscape, vague expert attributions, and generic upbeat conclusions.
|
||||
- Keep claims evidence-backed and diff-friendly: one durable claim per bullet or line; paragraphs should be no longer than one or two short sentences.
|
||||
- Do not add personality, rhetorical flourish, first-person commentary, or marketing tone.
|
||||
- Rewrite dense or formulaic prose only when it improves readability without removing scope, evidence, decisions, or source references.
|
||||
Topology review and repair:
|
||||
- before updating truth docs, verify the changed code resolves to a specific behavior-owned area and bounded truth owner
|
||||
- if routing is missing, stale, broad, overloaded, catch-all route only, or cannot map changed code to a bounded truth owner, run Truth Structure before syncing when topology repair is safe and in scope
|
||||
- safe in-scope topology repair may update truth routing files and create or update bounded leaf truth docs needed to map the changed functional code; keep the repair limited to the affected route owner
|
||||
- stop and recommend Truth Structure only when topology repair is unsafe, ambiguous, or outside the current task boundary
|
||||
- report the route files and changed code paths that required structure repair
|
||||
- do not create another generic truth doc
|
||||
- README.md files are indexes, not Truth Sync targets
|
||||
- must not append behavior details to a README.md index
|
||||
- write engineering truth under docs/truthmark/engineering; product truth updates under docs/truthmark/product are allowed only for explicit current product behavior changes
|
||||
Optional validation tooling:
|
||||
- you may run truthmark check when local tooling is available
|
||||
- you may validate the final report with `truthmark validate sync-report <report-file> --json` when available
|
||||
- do not require the truthmark binary; direct checkout inspection is the canonical path
|
||||
- optional validation must not replace agent judgment about docs and routing
|
||||
- update Product Decisions only in product truth and Engineering Decisions only in engineering truth when evidence supports the lane-specific decision change
|
||||
Truthmark hierarchy hints:
|
||||
- Config, when present: .truthmark/config.yml
|
||||
- Root route index, when present: docs/truthmark/routes/areas.md
|
||||
- Area route files, when present: docs/truthmark/routes/areas/**/*.md
|
||||
- Product truth docs, when present: docs/truthmark/product/**/*.md
|
||||
- Engineering truth docs, when present: docs/truthmark/engineering/**/*.md
|
||||
Parent post-sync verification:
|
||||
- verify only truth docs and leased truth routing files changed during sync
|
||||
- stop on any unrelated diff caused by the sync step
|
||||
- stop if functional code changed during sync
|
||||
- validate the final report against the structured Truth Sync report contract, including Claim, indented Evidence, and Result values supported, narrowed, removed, or blocked under Evidence checked
|
||||
- verify the updated docs correspond to reviewed checkout evidence, changed-code impact, or a recorded stale-truth correction made within the sync write lease
|
||||
- verify the final report records ownership review, structure requirement, split, restructure, or manual handoff reason when the ownership review applies
|
||||
- manual handoff outcomes must preserve the working tree as-is: no rollback, no post-block cleanup edits, and manual-review reporting of any remaining files
|
||||
@@ -1,52 +0,0 @@
|
||||
# Truthmark Sync Report Template
|
||||
|
||||
Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
|
||||
|
||||
Report completion in this shape:
|
||||
```md
|
||||
Truth Sync: completed
|
||||
|
||||
Changed code reviewed:
|
||||
- src/auth/session.ts
|
||||
|
||||
Sync Intent:
|
||||
- Changed code reviewed: src/auth/session.ts
|
||||
- Affected route/truth owner: docs/truthmark/routes/areas/authentication.md
|
||||
- Target truth docs: docs/truthmark/engineering/behaviors/session-timeout.md
|
||||
- Intended update: Update session timeout behavior.
|
||||
- Evidence to verify: src/auth/session.ts:12 / docs/truthmark/routes/areas/authentication.md:11
|
||||
- User-provided decisions/rationale: User rationale: session timeout behavior changed for internal implementation consistency
|
||||
- No-update-needed rationale: not applicable; mapped truth is stale
|
||||
- Blockers: none
|
||||
|
||||
Ownership reviewed:
|
||||
- docs/truthmark/routes/areas/authentication.md
|
||||
|
||||
Truth docs updated:
|
||||
- docs/truthmark/engineering/behaviors/session-timeout.md
|
||||
|
||||
Decision/rationale captured:
|
||||
- Placed user rationale in the bounded authentication behavior truth doc under Engineering Decisions/Rationale.
|
||||
|
||||
Evidence checked:
|
||||
- Claim: Session timeout behavior is documented in the bounded authentication behavior truth doc.
|
||||
Evidence: src/auth/session.ts:12 / docs/truthmark/routes/areas/authentication.md:11
|
||||
Result: supported
|
||||
|
||||
Notes:
|
||||
- Updated session timeout behavior.
|
||||
```
|
||||
Blocked report example:
|
||||
```md
|
||||
Truth Sync: blocked
|
||||
|
||||
Reason:
|
||||
- Changed code maps only to the provisional bootstrap route.
|
||||
|
||||
Files requiring manual review:
|
||||
- src/auth/**
|
||||
- docs/truthmark/routes/areas/repository.md
|
||||
|
||||
Next action:
|
||||
- Run Truth Structure for src/auth/** before updating behavior truth.
|
||||
```
|
||||
@@ -1,14 +0,0 @@
|
||||
# Truthmark Sync Subagents And Leases
|
||||
|
||||
Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
|
||||
|
||||
Codex subagent mode:
|
||||
- use automatically when this workflow runs in Codex and the parent agent chooses bounded subagent fan-out
|
||||
- dispatch read-only project agents for verification: truth_route_auditor, truth_claim_verifier
|
||||
- read-only workers inspect checkout evidence directly, return structured findings, and must not edit files
|
||||
- parent supplies bounded evidence shards; read-only workers must not preload host instruction files or repo-wide policy docs unless assigned as evidence
|
||||
- dispatch write-capable project agents only with explicit write leases: truth_doc_writer
|
||||
- each write lease must name objective, required reads, allowed writes, forbidden writes, evidence, verification, and report fields
|
||||
- write workers must stop when a required edit is off-lease and report status, filesChanged, evidence, offLeaseChanges, blockers, and notes
|
||||
- parent must inspect the actual checkout diff against each lease before accepting a worker report
|
||||
- Parent agent owns Truth Sync acceptance, lease validation, and final report
|
||||
@@ -1,18 +0,0 @@
|
||||
# Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
|
||||
name = "truth_claim_verifier"
|
||||
description = "Read-only Truthmark claim verifier for checking canonical truth against checkout evidence."
|
||||
sandbox_mode = "read-only"
|
||||
nickname_candidates = ["Claim Audit", "Claim Trace", "Claim Check"]
|
||||
developer_instructions = """
|
||||
Stay read-only.
|
||||
Verify the behavior-bearing truth claims assigned by the parent against primary checkout evidence.
|
||||
Use implementation, tests, config, routing, generated templates, schemas, or explicit evidence blocks as primary evidence.
|
||||
Canonical docs and examples can corroborate but are not sole proof when implementation conflicts.
|
||||
For every checked claim, classify the result as supported | narrowed | removed | blocked.
|
||||
Do not edit files, stage changes, or invent missing behavior.
|
||||
Return JSON only with keys: scope, filesReviewed, claimsChecked, evidence, unsupportedClaims, confidence, recommendedWorkflow, notes.
|
||||
Context boundary:
|
||||
Do not preload AGENTS.md, CLAUDE.md, .github/copilot-instructions.md, .cursor/skills, .antigravity/rules, or repo-wide policy docs unless the parent explicitly assigns them as evidence.
|
||||
Use only the parent-assigned shard plus required checkout evidence files.
|
||||
Return findings only; the parent workflow owns repository-policy interpretation, final decisions, and all writes.
|
||||
"""
|
||||
@@ -1,17 +0,0 @@
|
||||
# Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
|
||||
name = "truth_doc_reviewer"
|
||||
description = "Read-only Truthmark doc reviewer for shape, decision, rationale, and evidence hygiene."
|
||||
sandbox_mode = "read-only"
|
||||
nickname_candidates = ["Doc Audit", "Doc Shape", "Doc Check"]
|
||||
developer_instructions = """
|
||||
Stay read-only.
|
||||
Review assigned canonical truth docs for compact frontmatter, required template sections, final Source References entries, Evidence checked entries, and lane-appropriate decision sections (Product Decisions in product truth, Engineering Decisions in engineering truth).
|
||||
Flag README.md files used as behavior truth targets, mixed-owner docs, and shape repairs that should move to Truth Structure.
|
||||
Do not edit files, stage changes, or rewrite docs.
|
||||
Return JSON only with keys: scope, filesReviewed, findings, evidence, confidence, recommendedWorkflow, notes.
|
||||
recommendedWorkflow must be one of: none, truthmark-document, truthmark-structure.
|
||||
Context boundary:
|
||||
Do not preload AGENTS.md, CLAUDE.md, .github/copilot-instructions.md, .cursor/skills, .antigravity/rules, or repo-wide policy docs unless the parent explicitly assigns them as evidence.
|
||||
Use only the parent-assigned shard plus required checkout evidence files.
|
||||
Return findings only; the parent workflow owns repository-policy interpretation, final decisions, and all writes.
|
||||
"""
|
||||
@@ -1,18 +0,0 @@
|
||||
# Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
|
||||
name = "truth_doc_writer"
|
||||
description = "Write-capable Truthmark doc worker for one parent-leased truth-document shard."
|
||||
sandbox_mode = "workspace-write"
|
||||
nickname_candidates = ["Doc Writer", "Truth Writer", "Doc Sync"]
|
||||
developer_instructions = """
|
||||
Write one leased Truthmark truth-document shard assigned by the parent.
|
||||
Require an explicit write lease before editing. The lease must name workflow, worker, shard, objective, requiredReads, allowedWrites, forbiddenWrites, evidenceRequired, verification, and reportFields.
|
||||
Read every requiredReads entry directly before editing.
|
||||
Edit only leased canonical truth docs or leased truth routing files. Do not edit functional code, generated host surfaces, package files, config files, templates, or tests unless they are explicitly leased.
|
||||
Do not expand your own write scope. If the task needs an off-lease file, stop and report blocked.
|
||||
Block when ownership is missing or ambiguous, evidence does not support the requested claim, another worker changed the leased file, generated surfaces appear stale, or a required edit is outside the lease.
|
||||
Return YAML only with keys: status, worker, workflow, shard, filesChanged, claimsChecked, evidenceChecked, offLeaseChanges, blockers, notes.
|
||||
status must be completed or blocked.
|
||||
filesChanged must list only files you actually changed.
|
||||
offLeaseChanges must be empty for completed reports.
|
||||
The parent must validate the actual checkout diff before accepting your report.
|
||||
"""
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user