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/config.toml b/.codex/config.toml index dfcec0a0..ec0d2986 100644 --- a/.codex/config.toml +++ b/.codex/config.toml @@ -1,6 +1,8 @@ # 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" @@ -8,7 +10,7 @@ sandbox_mode = "workspace-write" [features] goals = true -[agents] -max_threads = 4 -max_depth = 1 -job_max_runtime_seconds = 1800 +# Subagent policy guidance, not enforced by this config parser: +# max_threads = 4 +# max_depth = 1 +# job_max_runtime_seconds = 1800 diff --git a/AGENTS.md b/AGENTS.md index 732f0c7a..6d740bc3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -4,7 +4,7 @@ This repository is part of the Coregentis MPLP / Cognitive OS / SoloCrew / Valid ## Repository Layer -MPLP owns protocol objects, schemas, invariants, conformance vocabulary, and protocol documentation. Protocol core must stay product-neutral, runtime-neutral, vendor-neutral, and free of commercial validation claims. +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 @@ -18,12 +18,19 @@ Before implementation, inspect repository truth: 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. -- Do not modify release tags, release seals, package versions, publish plans, public website copy, schemas/v2 protocol objects, core package implementation logic, product source code, Validation Lab runtime/evidence logic, or public legal/compliance claims unless the owner explicitly approves that scope. -- Do not run `npm publish`, `npm deprecate`, PyPI upload, PyPI yank/delete, `git tag`, release seal creation, package version bump, or protocol schema primitive intake without owner approval. -- Do not make public legal, compliance, certification, regulator-approval, vendor-ranking, or official-standard claims without owner approval. +- 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. +- Do not run `npm publish`, `npm deprecate`, npm dist-tag mutation, PyPI upload, PyPI yank/delete, `git tag`, release seal creation, package version bump, or protocol schema primitive intake without an explicit owner-approved wave. +- Do not make public certification, regulator-approval, vendor-ranking, official-standard, or legal-compliance proof claims without owner approval. ## MPLP Schema v2 Discipline @@ -45,6 +52,14 @@ v1.0 module references to v2 objects must be pointer-only. Do not inline v2 obje - 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: diff --git a/governance/codex-goals/CODEX-GOAL-TEMPLATE.md b/governance/codex-goals/CODEX-GOAL-TEMPLATE.md index a0603c67..86bf864c 100644 --- a/governance/codex-goals/CODEX-GOAL-TEMPLATE.md +++ b/governance/codex-goals/CODEX-GOAL-TEMPLATE.md @@ -1,6 +1,6 @@ # Codex Goal Template -Use this template for bounded Goal Mode tasks in this repository family. +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 @@ -8,27 +8,56 @@ State the concrete objective and the verifiable stopping condition. ## Repository -Name the exact repository path and current branch. Do not assume cloud threads or app-only features. +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. +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 `.codex/skills/*/SKILL.md` workflows. +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: -## Required Subagents +- `package_surface_auditor` +- `release_governance_reviewer` +- `protocol_schema_reviewer` +- `product_boundary_reviewer` +- `runtime_binding_reviewer` +- `publication_claim_reviewer` -List any required `.codex/agents/*.toml` reviewers and the lane each must cover. +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, tag, seal, package-version, schema-intake, public-claim, or broad-rewrite 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 @@ -36,11 +65,36 @@ Define the exact evidence that proves the goal is complete. ## Owner Approval Boundary -Stop before any action requiring owner approval, including release mutation, public legal/compliance claim changes, schema primitive intake, or package version changes. +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. -## Commands To Run +## Merge Boundary -Include repo truth, existing-script inspection, and relevant non-mutating verification commands. +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 @@ -50,10 +104,19 @@ completion_report: repository: branch: starting_head: - final_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: - reused_existing_assets: - new_files_created_and_why: + required_skills: + required_subagents: + skill_discovery_resolution: config_added_or_updated: custom_agents_added_or_updated: skills_added_or_updated: @@ -61,6 +124,8 @@ completion_report: 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: @@ -69,11 +134,18 @@ completion_report: ## Allowed Final Verdicts -- `_READY_FOR_REVIEW` +- `_READY_FOR_REMOTE_REVIEW` +- `_NOT_READY_WITH_BLOCKERS` - `_BLOCKED` ## Sample Goal Mode Invocation ```text -/goal Complete until . Stop before publish, upload, deprecate, tag, seal, version bump, or public legal/compliance claim change. +/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 index 94464da3..978795cb 100755 --- a/scripts/codex/repo-truth-first.sh +++ b/scripts/codex/repo-truth-first.sh @@ -17,13 +17,37 @@ git rev-parse HEAD || true echo echo "[origin/main HEAD]" -git rev-parse --verify origin/main || true +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/*' \