diff --git a/.agents/skills/cross-repo-boundary-guard/SKILL.md b/.agents/skills/cross-repo-boundary-guard/SKILL.md new file mode 100644 index 00000000..bef500a7 --- /dev/null +++ b/.agents/skills/cross-repo-boundary-guard/SKILL.md @@ -0,0 +1,69 @@ +--- +name: cross-repo-boundary-guard +description: Use when a task touches MPLP, Cognitive OS, SoloCrew, Validation Lab, website, docs, runtime, protocol, evidence, publication, or brand surfaces. Prevents boundary drift. +--- + +# Cross-Repo Boundary Guard + +## Authority Map + +MPLP owns: + +- protocol objects +- schemas +- invariants +- conformance vocabulary +- protocol docs + +Cognitive OS owns: + +- runtime substrate +- execution semantics +- DTOs +- evidence pipeline +- protocol bindings + +SoloCrew owns: + +- product UX +- founder console +- secretary/cell interaction +- projection-safe workflow views + +Validation Lab owns: + +- evidence packs +- deterministic adjudication +- pointer resolution +- failure cases +- public validation UI + +JearonWong.com owns: + +- articles +- essays +- white papers +- brand narrative +- publication pages +- social distribution assets + +## Required Boundary Check + +Before implementation, classify every changed file: + +```yaml +boundary_check: + file: + repo_layer: + allowed_semantics: + forbidden_semantics: + risk: +``` + +## Forbidden Drift + +- MPLP must not contain product UI language. +- SoloCrew must not claim protocol authority. +- Cognitive OS must not redefine MPLP semantics. +- Validation Lab must not become certification authority. +- Website must not claim regulator approval or official standard status. diff --git a/.agents/skills/docs-minimalism-governance/SKILL.md b/.agents/skills/docs-minimalism-governance/SKILL.md new file mode 100644 index 00000000..30f4b203 --- /dev/null +++ b/.agents/skills/docs-minimalism-governance/SKILL.md @@ -0,0 +1,39 @@ +--- +name: docs-minimalism-governance +description: Use when creating, editing, or reviewing governance docs, release records, audit records, baselines, checklists, README files, or protocol documentation. Prevents document sprawl. +--- + +# Documentation Minimalism Governance + +## Rule + +Do not create new governance documents unless existing documents cannot be reused. + +## Required Before New Docs + +Codex must report: + +```yaml +doc_reuse_check: + existing_candidate_docs: + can_update_existing: + why_not_reuse: + new_doc_needed: + proposed_doc_path: + document_budget_impact: +``` + +## Preferred Actions + +1. Update existing baseline. +2. Append to existing audit record. +3. Add one index entry. +4. Only then create a new document. + +## Forbidden + +- Duplicate release records. +- Duplicate governance baselines. +- New checklist if an existing checklist can be extended. +- Marketing language in protocol docs. +- Certification, official standard, regulator approval, or vendor ranking claims. diff --git a/.agents/skills/mplp-schema-v2-invariant-intake/SKILL.md b/.agents/skills/mplp-schema-v2-invariant-intake/SKILL.md new file mode 100644 index 00000000..563044c6 --- /dev/null +++ b/.agents/skills/mplp-schema-v2-invariant-intake/SKILL.md @@ -0,0 +1,85 @@ +--- +name: mplp-schema-v2-invariant-intake +description: Use for MPLP schemas/v2 primitive intake, invariants, negative fixtures, object schemas, profiles, conformance manifests, and validator gates. +--- + +# MPLP Schema v2 Invariant Intake + +This skill governs schemas/v2 work. + +## Hard Order + +Codex must follow this order: + +1. Inspect existing schemas/v2 assets. +2. Inspect existing validators and fixtures. +3. Define or update invariants. +4. Add negative fixtures bound to invariant IDs. +5. Add kernel object schemas. +6. Add positive fixtures. +7. Add validator tests. +8. Update conformance manifest or inventory. +9. Update governance record only if necessary. + +## Required Principle + +Invariant -> Negative Fixture -> Object Schema -> Positive Fixture -> Validator -> Governance Record + +## v1.0 Frozen Boundary + +v1.0 module schemas may reference v2 objects only through pointer-only refs. + +Allowed: + +```yaml +active_context_version_ref: + ref_id: "ctxv-..." + ref_type: "ActiveContextVersion" + protocol_version: "2.0.0" + schema_version: "2.x" + profile_marker: "required" +``` + +Forbidden: + +```yaml +active_context_version: + context_id: "..." + validity_state: "active" + superseded_by: "..." +``` + +## Forbidden Imports Into Protocol Core + +Do not add these to MPLP protocol core: + +- RCCS-M +- ALCS +- AARM +- audit score +- insurance score +- procurement score +- certification +- legal compliance proof +- regulator approval +- vendor ranking +- SoloCrew UI objects +- Cognitive OS runtime internals +- Coregentis commercial validation service language + +## Required Output + +For every schema primitive, report: + +```yaml +primitive: + name: + module_mapping: + invariant_mapping: + positive_fixture: + negative_fixture: + validator_rule: + conformance_profile: + v1_pointer_refs_if_any: + files_changed: +``` diff --git a/.agents/skills/release-gate-and-seal-discipline/SKILL.md b/.agents/skills/release-gate-and-seal-discipline/SKILL.md new file mode 100644 index 00000000..d95b12d2 --- /dev/null +++ b/.agents/skills/release-gate-and-seal-discipline/SKILL.md @@ -0,0 +1,52 @@ +--- +name: release-gate-and-seal-discipline +description: Use before declaring any task, PR, release, RC, seal, deployment, or merge complete. Requires commands run, pass/fail evidence, remote truth, and remaining risk. +--- + +# Release Gate and Seal Discipline + +Codex must not declare completion without verification. + +## Required Report + +```yaml +completion_report: + branch: + starting_head: + final_head: + files_changed: + commands_run: + pass_fail_results: + tests_added_or_updated: + governance_records_changed: + remote_truth_checked: + final_git_status: + remaining_risks: + exact_verdict: +``` + +## Common Checks + +Use repo-specific commands if available. Otherwise inspect package scripts first: + +```bash +cat package.json | sed -n '1,160p' +``` + +Then run available gates: + +```bash +git diff --check +pnpm run build +pnpm run lint +pnpm run test +``` + +If commands differ, explain why. + +## Forbidden + +- Do not say "done" without command output summary. +- Do not tag release without owner approval. +- Do not create seal record without owner approval. +- Do not claim live deployment unless repo truth, build truth, remote truth, and live truth are checked. diff --git a/.agents/skills/repo-truth-first-audit/SKILL.md b/.agents/skills/repo-truth-first-audit/SKILL.md new file mode 100644 index 00000000..8fc00ba0 --- /dev/null +++ b/.agents/skills/repo-truth-first-audit/SKILL.md @@ -0,0 +1,57 @@ +--- +name: repo-truth-first-audit +description: Use before any implementation, refactor, release, schema, docs, or governance task. Inspect branch, HEAD, remote, dirty status, existing files, reusable assets, and why new files are needed. +--- + +# Repo Truth First Audit + +Before making changes, Codex must inspect repository truth. + +## Required Commands + +Run or equivalent: + +```bash +git branch --show-current +git status --short +git rev-parse HEAD +git rev-parse --verify origin/main || true +git log --oneline -5 +``` + +## Required Investigation + +Identify: + +- current branch +- current local HEAD +- remote HEAD if available +- dirty files +- relevant existing directories +- relevant existing tests +- reusable assets +- missing assets +- why new files are necessary + +## Output Format + +Before implementation, report: + +```yaml +repo_truth: + branch: + local_head: + origin_main_head: + dirty_status: + relevant_existing_files: + reusable_assets: + missing_assets: + why_new_files_needed: + proposed_change_surface: +``` + +## Rules + +- Do not create new files before this audit. +- Do not rewrite existing architecture without explaining why extension is insufficient. +- Prefer update over new document. diff --git a/.codex/agents/package_surface_auditor.toml b/.codex/agents/package_surface_auditor.toml new file mode 100644 index 00000000..c2c8a9ec --- /dev/null +++ b/.codex/agents/package_surface_auditor.toml @@ -0,0 +1,27 @@ +name = "package_surface_auditor" +description = "Audits npm/PyPI package publication surfaces, package metadata, README footers, LICENSE/NOTICE files, owner statements, and registry-readiness blockers." +model_reasoning_effort = "high" +sandbox_mode = "workspace-write" + +developer_instructions = """ +You are a package publication surface auditor. + +Inspect package-facing files only: +- packages/npm/** +- packages/pypi/** +- package.json +- README.md +- LICENSE +- NOTICE +- governance/release/** when package release readiness is relevant + +You must not publish, upload, deprecate, yank, tag, or bump versions. + +Return: +- files inspected +- exact problematic strings +- active publication surface vs historical record classification +- recommended replacement +- post-edit verification command +- blocker verdict +""" diff --git a/.codex/agents/product_boundary_reviewer.toml b/.codex/agents/product_boundary_reviewer.toml new file mode 100644 index 00000000..3e023f14 --- /dev/null +++ b/.codex/agents/product_boundary_reviewer.toml @@ -0,0 +1,28 @@ +name = "product_boundary_reviewer" +description = "Reviews SoloCrew product UX changes for user-facing clarity and prevents protocol/runtime jargon leaking into founder-facing UI." +model_reasoning_effort = "high" +sandbox_mode = "workspace-write" + +developer_instructions = """ +You are a SoloCrew product boundary reviewer. + +User-facing UI should express: +- what needs your decision +- company status +- secretary brief +- continue from here +- evidence behind this +- system details only when necessary + +Block: +- internal protocol jargon as primary UI copy +- direct approve/reject/dispatch/execute unless explicitly scoped +- runtime authority in product UI +- provider/channel send behavior unless explicitly authorized + +Return: +- UI files inspected +- copy issues +- authority boundary risks +- recommended user-facing wording +""" diff --git a/.codex/agents/protocol_schema_reviewer.toml b/.codex/agents/protocol_schema_reviewer.toml new file mode 100644 index 00000000..dd80d0e3 --- /dev/null +++ b/.codex/agents/protocol_schema_reviewer.toml @@ -0,0 +1,25 @@ +name = "protocol_schema_reviewer" +description = "Reviews MPLP schemas/v2 invariants, negative fixtures, object schemas, conformance profiles, and v1 pointer-only refs." +model_reasoning_effort = "xhigh" +sandbox_mode = "workspace-write" + +developer_instructions = """ +You are an MPLP protocol schema reviewer. + +Rules: +- invariant-first +- negative fixture second +- object schema third +- positive fixture fourth +- validator/conformance last +- v1 module refs must be pointer-only +- no RCCS-M, ALCS, AARM, certification, vendor ranking, product UI, runtime-private, or commercial validation service language in protocol core + +Return: +- schema files inspected +- invariant mapping +- fixture mapping +- missing negative tests +- v1/v2 boundary risks +- blocking findings +""" diff --git a/.codex/agents/publication_claim_reviewer.toml b/.codex/agents/publication_claim_reviewer.toml new file mode 100644 index 00000000..24bbbf07 --- /dev/null +++ b/.codex/agents/publication_claim_reviewer.toml @@ -0,0 +1,26 @@ +name = "publication_claim_reviewer" +description = "Reviews website, white paper, docs, metadata, and public writing surfaces for claim-boundary discipline." +model_reasoning_effort = "high" +sandbox_mode = "workspace-write" + +developer_instructions = """ +You are a public publication and claim-boundary reviewer. + +Review for: +- no certification claim +- no regulator approval claim +- no legal compliance proof claim +- no vendor ranking claim +- no unsupported world-first claim +- citation metadata consistency +- canonical URL consistency +- publication boundary language +- visible copy vs metadata consistency + +Return: +- files inspected +- unsafe claims found +- required boundary corrections +- metadata/canonical issues +- blocking findings +""" diff --git a/.codex/agents/release_governance_reviewer.toml b/.codex/agents/release_governance_reviewer.toml new file mode 100644 index 00000000..89be2f16 --- /dev/null +++ b/.codex/agents/release_governance_reviewer.toml @@ -0,0 +1,24 @@ +name = "release_governance_reviewer" +description = "Reviews release plans, owner approval records, seal boundaries, registry conflict status, and forbidden release mutations." +model_reasoning_effort = "high" +sandbox_mode = "workspace-write" + +developer_instructions = """ +You are a release governance reviewer. + +Your job is to prevent unsafe release readiness claims. + +Block if: +- exact package versions already exist in registry +- owner/copyright statements are unresolved +- publish/upload/deprecate/yank/tag actions are implied without owner approval +- final verdict uses READY_TO_PUBLISH prematurely +- release/seal claims are made without owner approval + +Return: +- release document reviewed +- unsafe language found +- required corrected verdict +- owner approval boundary +- no-mutation confirmation +""" diff --git a/.codex/agents/runtime_binding_reviewer.toml b/.codex/agents/runtime_binding_reviewer.toml new file mode 100644 index 00000000..b13c8c92 --- /dev/null +++ b/.codex/agents/runtime_binding_reviewer.toml @@ -0,0 +1,21 @@ +name = "runtime_binding_reviewer" +description = "Reviews Cognitive OS runtime binding changes for public/private boundary, DTO exposure, and MPLP semantic alignment." +model_reasoning_effort = "high" +sandbox_mode = "workspace-write" + +developer_instructions = """ +You are a Cognitive OS runtime binding reviewer. + +Rules: +- public DTOs may expose projection-safe lifecycle summaries +- runtime-private internals must not leak into public DTOs or SoloCrew +- Cognitive OS may bind to MPLP semantics but must not redefine MPLP protocol authority +- runtime implementation details must not become MPLP protocol claims + +Return: +- files inspected +- public/private boundary risks +- DTO exposure issues +- MPLP binding alignment +- blocking findings +""" diff --git a/.codex/config.toml b/.codex/config.toml new file mode 100644 index 00000000..ec0d2986 --- /dev/null +++ b/.codex/config.toml @@ -0,0 +1,16 @@ +# Codex operating foundation for this repository. +# This repository uses Codex through an API-key connected IDE workflow, +# so local repo configuration must not assume app-only/cloud-only features. +# Repository-scoped skills are mirrored under .agents/skills for Codex +# discovery. .codex/skills is retained as the project-internal ops source. + +approval_policy = "on-request" +sandbox_mode = "workspace-write" + +[features] +goals = true + +# Subagent policy guidance, not enforced by this config parser: +# max_threads = 4 +# max_depth = 1 +# job_max_runtime_seconds = 1800 diff --git a/.codex/skills/cross-repo-boundary-guard/SKILL.md b/.codex/skills/cross-repo-boundary-guard/SKILL.md new file mode 100644 index 00000000..bef500a7 --- /dev/null +++ b/.codex/skills/cross-repo-boundary-guard/SKILL.md @@ -0,0 +1,69 @@ +--- +name: cross-repo-boundary-guard +description: Use when a task touches MPLP, Cognitive OS, SoloCrew, Validation Lab, website, docs, runtime, protocol, evidence, publication, or brand surfaces. Prevents boundary drift. +--- + +# Cross-Repo Boundary Guard + +## Authority Map + +MPLP owns: + +- protocol objects +- schemas +- invariants +- conformance vocabulary +- protocol docs + +Cognitive OS owns: + +- runtime substrate +- execution semantics +- DTOs +- evidence pipeline +- protocol bindings + +SoloCrew owns: + +- product UX +- founder console +- secretary/cell interaction +- projection-safe workflow views + +Validation Lab owns: + +- evidence packs +- deterministic adjudication +- pointer resolution +- failure cases +- public validation UI + +JearonWong.com owns: + +- articles +- essays +- white papers +- brand narrative +- publication pages +- social distribution assets + +## Required Boundary Check + +Before implementation, classify every changed file: + +```yaml +boundary_check: + file: + repo_layer: + allowed_semantics: + forbidden_semantics: + risk: +``` + +## Forbidden Drift + +- MPLP must not contain product UI language. +- SoloCrew must not claim protocol authority. +- Cognitive OS must not redefine MPLP semantics. +- Validation Lab must not become certification authority. +- Website must not claim regulator approval or official standard status. diff --git a/.codex/skills/docs-minimalism-governance/SKILL.md b/.codex/skills/docs-minimalism-governance/SKILL.md new file mode 100644 index 00000000..30f4b203 --- /dev/null +++ b/.codex/skills/docs-minimalism-governance/SKILL.md @@ -0,0 +1,39 @@ +--- +name: docs-minimalism-governance +description: Use when creating, editing, or reviewing governance docs, release records, audit records, baselines, checklists, README files, or protocol documentation. Prevents document sprawl. +--- + +# Documentation Minimalism Governance + +## Rule + +Do not create new governance documents unless existing documents cannot be reused. + +## Required Before New Docs + +Codex must report: + +```yaml +doc_reuse_check: + existing_candidate_docs: + can_update_existing: + why_not_reuse: + new_doc_needed: + proposed_doc_path: + document_budget_impact: +``` + +## Preferred Actions + +1. Update existing baseline. +2. Append to existing audit record. +3. Add one index entry. +4. Only then create a new document. + +## Forbidden + +- Duplicate release records. +- Duplicate governance baselines. +- New checklist if an existing checklist can be extended. +- Marketing language in protocol docs. +- Certification, official standard, regulator approval, or vendor ranking claims. diff --git a/.codex/skills/mplp-schema-v2-invariant-intake/SKILL.md b/.codex/skills/mplp-schema-v2-invariant-intake/SKILL.md new file mode 100644 index 00000000..563044c6 --- /dev/null +++ b/.codex/skills/mplp-schema-v2-invariant-intake/SKILL.md @@ -0,0 +1,85 @@ +--- +name: mplp-schema-v2-invariant-intake +description: Use for MPLP schemas/v2 primitive intake, invariants, negative fixtures, object schemas, profiles, conformance manifests, and validator gates. +--- + +# MPLP Schema v2 Invariant Intake + +This skill governs schemas/v2 work. + +## Hard Order + +Codex must follow this order: + +1. Inspect existing schemas/v2 assets. +2. Inspect existing validators and fixtures. +3. Define or update invariants. +4. Add negative fixtures bound to invariant IDs. +5. Add kernel object schemas. +6. Add positive fixtures. +7. Add validator tests. +8. Update conformance manifest or inventory. +9. Update governance record only if necessary. + +## Required Principle + +Invariant -> Negative Fixture -> Object Schema -> Positive Fixture -> Validator -> Governance Record + +## v1.0 Frozen Boundary + +v1.0 module schemas may reference v2 objects only through pointer-only refs. + +Allowed: + +```yaml +active_context_version_ref: + ref_id: "ctxv-..." + ref_type: "ActiveContextVersion" + protocol_version: "2.0.0" + schema_version: "2.x" + profile_marker: "required" +``` + +Forbidden: + +```yaml +active_context_version: + context_id: "..." + validity_state: "active" + superseded_by: "..." +``` + +## Forbidden Imports Into Protocol Core + +Do not add these to MPLP protocol core: + +- RCCS-M +- ALCS +- AARM +- audit score +- insurance score +- procurement score +- certification +- legal compliance proof +- regulator approval +- vendor ranking +- SoloCrew UI objects +- Cognitive OS runtime internals +- Coregentis commercial validation service language + +## Required Output + +For every schema primitive, report: + +```yaml +primitive: + name: + module_mapping: + invariant_mapping: + positive_fixture: + negative_fixture: + validator_rule: + conformance_profile: + v1_pointer_refs_if_any: + files_changed: +``` diff --git a/.codex/skills/release-gate-and-seal-discipline/SKILL.md b/.codex/skills/release-gate-and-seal-discipline/SKILL.md new file mode 100644 index 00000000..d95b12d2 --- /dev/null +++ b/.codex/skills/release-gate-and-seal-discipline/SKILL.md @@ -0,0 +1,52 @@ +--- +name: release-gate-and-seal-discipline +description: Use before declaring any task, PR, release, RC, seal, deployment, or merge complete. Requires commands run, pass/fail evidence, remote truth, and remaining risk. +--- + +# Release Gate and Seal Discipline + +Codex must not declare completion without verification. + +## Required Report + +```yaml +completion_report: + branch: + starting_head: + final_head: + files_changed: + commands_run: + pass_fail_results: + tests_added_or_updated: + governance_records_changed: + remote_truth_checked: + final_git_status: + remaining_risks: + exact_verdict: +``` + +## Common Checks + +Use repo-specific commands if available. Otherwise inspect package scripts first: + +```bash +cat package.json | sed -n '1,160p' +``` + +Then run available gates: + +```bash +git diff --check +pnpm run build +pnpm run lint +pnpm run test +``` + +If commands differ, explain why. + +## Forbidden + +- Do not say "done" without command output summary. +- Do not tag release without owner approval. +- Do not create seal record without owner approval. +- Do not claim live deployment unless repo truth, build truth, remote truth, and live truth are checked. diff --git a/.codex/skills/repo-truth-first-audit/SKILL.md b/.codex/skills/repo-truth-first-audit/SKILL.md new file mode 100644 index 00000000..8fc00ba0 --- /dev/null +++ b/.codex/skills/repo-truth-first-audit/SKILL.md @@ -0,0 +1,57 @@ +--- +name: repo-truth-first-audit +description: Use before any implementation, refactor, release, schema, docs, or governance task. Inspect branch, HEAD, remote, dirty status, existing files, reusable assets, and why new files are needed. +--- + +# Repo Truth First Audit + +Before making changes, Codex must inspect repository truth. + +## Required Commands + +Run or equivalent: + +```bash +git branch --show-current +git status --short +git rev-parse HEAD +git rev-parse --verify origin/main || true +git log --oneline -5 +``` + +## Required Investigation + +Identify: + +- current branch +- current local HEAD +- remote HEAD if available +- dirty files +- relevant existing directories +- relevant existing tests +- reusable assets +- missing assets +- why new files are necessary + +## Output Format + +Before implementation, report: + +```yaml +repo_truth: + branch: + local_head: + origin_main_head: + dirty_status: + relevant_existing_files: + reusable_assets: + missing_assets: + why_new_files_needed: + proposed_change_surface: +``` + +## Rules + +- Do not create new files before this audit. +- Do not rewrite existing architecture without explaining why extension is insufficient. +- Prefer update over new document. diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000..40348af1 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,84 @@ +# Repository Operating Rules for Codex + +This repository is part of the Coregentis MPLP / Cognitive OS / SoloCrew / Validation Lab project family. Codex work here must preserve project boundaries and produce verifiable engineering evidence. + +## Repository Layer + +MPLP owns protocol objects, schemas, invariants, conformance vocabulary, and protocol documentation. The 10-module v1 baseline remains the protocol anchor. Protocol core must stay product-neutral, runtime-neutral, vendor-neutral, and free of product, commercial validation, certification, regulator-approval, legal-compliance proof, or vendor-ranking claims. v1 references to v2 objects must remain pointer-only; do not inline product, runtime, or commercial semantics into protocol core. + +## Repo Truth First + +Before implementation, inspect repository truth: + +- `git branch --show-current` +- `git status --short` +- `git rev-parse HEAD` +- `git rev-parse --verify origin/main || true` +- `git log --oneline -5` + +Reuse existing assets before creating new files. Prefer updating an existing rule, skill, script, audit, or governance record over creating a duplicate document. + +## Codex Skill Discovery + +- `.agents/skills/*/SKILL.md` is the repository-scoped Codex skill discovery path. +- `.codex/skills/*/SKILL.md` is retained as the project-internal ops source and compatibility copy. +- Keep mirrored skills same-named and content-equivalent; do not create divergent SOPs. + +## Hard Boundaries + +- Preserve protocol, runtime, product, validation, and publication boundaries. +- Normal task-authorized changes may modify files within the explicitly scoped repository layer, including low-risk code or docs that the current task asks for. +- Owner approval is required for high-risk or irreversible changes, including release mutation, registry mutation, public legal/compliance claims, package version changes, schema primitive intake, provider-send behavior, auth/payment/data-deletion flows, runtime authority changes, and merge/tag/seal actions. +- Forbidden without explicit owner approval: + - `npm publish` + - `npm deprecate` + - npm dist-tag add/remove + - PyPI upload + - PyPI yank/delete + - `git tag` + - release seal creation + - package version bump + - schema object intake + - external registry mutation +- Do not make public certification, regulator-approval, vendor-ranking, official-standard, or legal-compliance proof claims without owner approval. +- Do not over-block normal task-authorized development. + +## MPLP Schema v2 Discipline + +For MPLP `schemas/v2` work, use this order: + +1. Invariant first. +2. Negative fixture second. +3. Object schema third. +4. Positive fixture fourth. +5. Validator and conformance gates last. + +v1.0 module references to v2 objects must be pointer-only. Do not inline v2 object fields into v1 module schemas. + +## Boundary Language + +- No product, runtime, commercial, certification, legal-compliance, regulator-approval, or vendor-ranking language may leak into MPLP protocol core. +- No protocol authority may leak into product UI. +- Cognitive OS may bind to MPLP semantics but must not redefine MPLP protocol authority. +- Validation Lab may present deterministic evidence and adjudication but must not become a certification authority. +- SoloCrew UI must not expose internal protocol/runtime jargon as primary user-facing copy. + +## Standard Subagent Lanes + +Use `.codex/agents/*.toml` reviewers only when the parent task explicitly requests them. Relevant lanes include `package_surface_auditor`, `release_governance_reviewer`, `protocol_schema_reviewer`, `product_boundary_reviewer`, `runtime_binding_reviewer`, and `publication_claim_reviewer`. + +Default lane policy: use no subagent for trivial docs typos, one subagent for isolated repo-specific review, and multiple subagents for release, schema, runtime, publication, or cross-repo tasks. MPLP-Protocol defaults to `protocol_schema_reviewer`, with `release_governance_reviewer` and `package_surface_auditor` as secondary lanes when the task touches package surfaces, schema intake, conformance, or release planning. + +Subagents run review lanes only unless edits are explicitly authorized. They inherit sandbox and approval boundaries, must not publish, upload, tag, seal, bump versions, mutate registries, intake schema primitives, merge PRs, or change public claims, and must return P0/P1/P2 findings to the parent with files inspected and commands run. + +## Completion Discipline + +Do not declare completion without reporting: + +- files changed +- commands run +- pass/fail evidence +- final git status +- remaining risk + +If a verification command is unavailable or inappropriate, state why instead of silently skipping it. diff --git a/governance/codex-goals/CODEX-GOAL-TEMPLATE.md b/governance/codex-goals/CODEX-GOAL-TEMPLATE.md new file mode 100644 index 00000000..86bf864c --- /dev/null +++ b/governance/codex-goals/CODEX-GOAL-TEMPLATE.md @@ -0,0 +1,151 @@ +# Codex Goal Template + +Use this template for bounded Goal Mode tasks in this repository family. If `/goal` is not available in the current IDE surface, simulate Goal Mode by copying this template into the task prompt and keeping the same stopping condition, forbidden actions, and owner approval boundary. + +## Goal + +State the concrete objective and the verifiable stopping condition. + +## Repository + +Name the exact repository path and current branch. Do not assume cloud threads, marketplace features, app-only visibility, or cloud-only execution. + +## Branch + +Create or use a task branch from current `main` unless the owner instructs otherwise. Report whether the branch continues an existing Codex ops branch or is a follow-up branch. + +## PR Topology + +State the PR URL, base branch, base SHA, head branch, head SHA, whether the base is the default branch, and whether the PR is stacked. Stacked PRs must be declared. A final PR to `main` is required before merge unless the owner explicitly approves a stacked merge sequence. + +## Required Skills + +List any required `.agents/skills/*/SKILL.md` workflows. `.agents/skills` is the Codex discovery path; `.codex/skills` is retained as the project-internal ops source and compatibility copy. + +## Required Subagents Or Custom Agents + +List any required `.codex/agents/*.toml` reviewers and the lane each must cover. Standard lanes: + +- `package_surface_auditor` +- `release_governance_reviewer` +- `protocol_schema_reviewer` +- `product_boundary_reviewer` +- `runtime_binding_reviewer` +- `publication_claim_reviewer` + +Default lane policy: use no subagent for trivial docs typos, one subagent for isolated repo-specific review, and multiple subagents for release, schema, runtime, publication, or cross-repo tasks. Subagents return P0/P1/P2 findings to the parent. + +Prompt pattern: + +```text +Spawn one subagent per relevant review lane, wait for all results, then consolidate findings into a single parent report. Do not let subagents perform release mutation, version bump, schema intake, public-claim changes, or merge actions. +``` + +Subagents run review lanes only unless the task explicitly authorizes edits. They inherit sandbox and approval boundaries, must not publish, upload, tag, seal, bump versions, mutate registries, intake schema primitives, merge PRs, or change public claims, and must classify findings as P0/P1/P2 with files inspected and commands run. + +## Plan Mode Or Simulated Plan Mode + +For medium or high-risk work, write a short plan before edits. Include the intended files, commands, and stopping condition. Update the plan as gates pass or fail. + +## Scope + +Define allowed files, allowed semantics, and explicit non-goals. + +## Out-Of-Scope Surfaces + +List surfaces that must not change, including package versions, registries, tags, release seals, protocol schema primitives, product behavior, runtime behavior, Validation Lab evidence logic, public legal/compliance claims, and merge state. + +## Forbidden Actions + +State forbidden publish, upload, deprecate, yank, delete, dist-tag mutation, tag, seal, package-version, schema-intake, product-behavior, runtime-behavior, public-claim, or broad-rewrite actions. + +## Stopping Condition + +Define the exact evidence that proves the goal is complete. + +## Owner Approval Boundary + +Stop before any action requiring owner approval, including release mutation, registry mutation, public legal/compliance claim changes, schema primitive intake, package version changes, product behavior changes, runtime behavior changes, release seal creation, merge, or tag creation. + +## Merge Boundary + +Merge is forbidden by default. Merge is allowed only for an explicit `FINAL_MERGE` or `PR_FINALIZATION` task that names the PR URL, expected head SHA, passing gates, clean worktree, and owner instruction. + +## Package Release Rule + +External npm/PyPI registry validation is required before no-op closure or version-bump planning. Before publish, regenerate the publish plan, inspect dry-run artifacts, and require an explicit owner approval sentence. Do not mutate registry state from a planning task. + +## Instruction Size Guard + +Run `wc -c AGENTS.md`. Warn above 24000 bytes. Block if critical boundaries may be truncated. + +## Required Commands + +Include repo truth, existing-script inspection, and relevant non-mutating verification commands: + +```bash +git branch --show-current +git status --short +git rev-parse HEAD +git rev-parse --verify origin/main || true +git rev-parse --verify origin/codex/latest-ops-foundation-wave-01 || true +git log --oneline -5 +git diff --check +scripts/codex/repo-truth-first.sh +wc -c AGENTS.md +if [ -d .codex/skills ] && [ -d .agents/skills ]; then diff -qr .codex/skills .agents/skills; fi +``` + +## Final Report Format + +```yaml +completion_report: + task_id: + repository: + branch: + starting_head: + final_local_head: + final_origin_branch_head: + pr_url: + pr_base_branch: + pr_base_sha: + pr_head_branch: + pr_head_sha: + pr_is_stacked: + recommended_merge_topology: + files_changed: + required_skills: + required_subagents: + skill_discovery_resolution: + config_added_or_updated: + custom_agents_added_or_updated: + skills_added_or_updated: + goal_templates_added_or_updated: + scripts_added_or_updated: + commands_run: + pass_fail_results: + skill_mirror_drift_result: + agents_md_byte_size: + forbidden_actions_confirmation: + final_git_status: + remaining_risks: + exact_verdict: +``` + +## Allowed Final Verdicts + +- `_READY_FOR_REMOTE_REVIEW` +- `_NOT_READY_WITH_BLOCKERS` +- `_BLOCKED` + +## Sample Goal Mode Invocation + +```text +/goal Complete until . Stop before publish, upload, deprecate, yank, delete, dist-tag mutation, tag, release seal, version bump, schema primitive intake, product behavior change, runtime behavior change, or public legal/compliance claim change. +``` + +Package release governance example: + +```text +/goal Complete MPLP-PACKAGE-OWNER-APPROVED-VERSION-BUMP-PLANNING-WAVE-01 until a version-bump plan is ready for owner review. Stop before editing versions, publishing, uploading, tagging, deprecating, yanking, deleting, or mutating registry state. +``` diff --git a/scripts/codex/repo-truth-first.sh b/scripts/codex/repo-truth-first.sh new file mode 100755 index 00000000..978795cb --- /dev/null +++ b/scripts/codex/repo-truth-first.sh @@ -0,0 +1,63 @@ +#!/usr/bin/env bash +set -euo pipefail + +echo "== Repo Truth First ==" +echo + +echo "[branch]" +git branch --show-current || true +echo + +echo "[status]" +git status --short || true +echo + +echo "[local HEAD]" +git rev-parse HEAD || true +echo + +echo "[origin/main HEAD]" +git rev-parse --verify origin/main 2>/dev/null || echo "origin/main unavailable" +echo + +echo "[origin/codex/latest-ops-foundation-wave-01 HEAD]" +git rev-parse --verify origin/codex/latest-ops-foundation-wave-01 2>/dev/null || echo "origin/codex/latest-ops-foundation-wave-01 unavailable" +echo + +echo "[recent commits]" +git log --oneline -5 || true +echo + +echo "[AGENTS.md bytes]" +if [ -f AGENTS.md ]; then + wc -c AGENTS.md +else + echo "AGENTS.md missing" +fi +echo + +echo "[skill mirror drift]" +if [ -d .codex/skills ] && [ -d .agents/skills ]; then + if diff -qr .codex/skills .agents/skills; then + echo "SKILL_MIRROR_DRIFT=NO" + else + echo "SKILL_MIRROR_DRIFT=YES" + fi +else + echo "SKILL_MIRROR_DRIFT=NOT_APPLICABLE" +fi +echo + +echo "[top-level files]" +find . -maxdepth 2 \ + -not -path './.git/*' \ + -not -path './node_modules/*' \ + -not -path './.next/*' \ + -not -path './dist/*' \ + -type f | sort | head -200 +echo + +echo "[package scripts if package.json exists]" +if [ -f package.json ]; then + node -e "const p=require('./package.json'); console.log(JSON.stringify(p.scripts||{}, null, 2))" +fi