merge-cooking

Imported from serpegon11710-byte/merge-cooking (AGENTS.md). Install upstream with npx skills add serpegon11710-byte/merge-cooking. Copyright stays with the author.

AI Agent Governance & Execution Framework (AGENTS.md)

This document constitutes the unbreachable behavioral framework for any AI Agent (Cursor, Claude Code, GitHub Copilot) operating within this repository. You must read and comply with these rules upon initialization.

COD Inheritance And Liability Boundary

• This file is a COD-inherited constitutional profile and must not be modified unilaterally in ways that alter inherited normative semantics.
• Any local modification not synchronized with the governing COD source invalidates COD conformance for this file until regularized.
• Such unsynchronized modifications are outside COD responsibility coverage.

1. Temporal & Runtime Anchor (The "System Truth" Protocol)

To prevent context drift and stale documentation caused by IDE metadata, you must follow this protocol:

• No Rely on Context Date: Never use Today's date provided in the IDE's system context; it is unreliable in long-running sessions.

• The "Get-Date" Mandate: Whenever you are instructed to document the current time of generation (e.g., Last updated: headers, sprint closure notes, or sync-logs), you must execute this command in the terminal before writing:

Get-Date -Format "yyyy-MM-dd"

• Strict Usage (Generation Timestamps Only): Use the exact output of the Get-Date command only for metadata fields representing the moment of document generation.

• Historical Data Preservation: Never alter dates referring to historical events (e.g., meeting dates, past sprint occurrences, or logs of finished tasks) based on the Get-Date command. Historical dates are immutable and must remain unchanged unless explicitly corrected for factual accuracy.

• Header Correction: You are authorized to correct a header date only if the header specifically claims to represent the "current" status or "last update" of the document.

2. Clean Onion Documentation (COD) Rules

You are operating inside a concentric, modular repository structure. You must strictly follow the dependency rules:

1. Outer Layers Dependency: Files in outer layers (4-sprints, 3-implementation) can reference inner layers (1-product-documentation). The authoritative layer dependency matrix and stack leakage rules live in 5-governance/clean-onion-documentation.md §4 — do not duplicate them here.

2. Inner Layer Agnosticism: Core business logic and use cases inside 1-product-documentation must remain entirely agnostic of technological stacks, deployment details, or sprint timelines.

3. Atomic Fractal Pattern: Every micro-feature folder should contain an independent ecosystem (README.md, index.md, history/, and doubts-and-decisions/). Never mix scopes.

4. Token Management: Do not read full directories recursively unless explicitly instructed. Lean on local index.md files at layer root to navigate the architecture efficiently.

3. Environment & Shell Safeguards (Windows PowerShell 5.x)

When writing automation scripts, scaffolding files, or updating documentation through terminal commands, you must comply with the following PowerShell restrictions:

• No Heredocs (<<): PowerShell 5.x does not support bash-style Heredocs. Never emit scripts using this syntax.

• File Write Prohibition (Default-Deny): Do not use OS-native PowerShell write cmdlets for persistent edits (Set-Content, Out-File, Add-Content, >/>>) because they can inject platform defaults (for example CRLF) and break repository integrity.

• Approved Editing Methods: Use IDE-native editing operations or apply_patch as primary methods. CLI fallback is allowed only when UTF-8 + LF normalization is explicitly enforced.

• Mandatory Post-Write Verification: After any automated write, verify UTF-8 + LF compliance and immediately normalize with approved methods if drift is detected.

• Temporary Files Safeguard: If complex string escaping is required, write the content to an atomic temporary file (*.tmp), execute the transfer, and delete the file immediately after confirmation.

Normative source: 5-governance/pre-commit-validation-rules.md §1.1.

4. Formatting & Syntax Enforcement

• Strict Markdown Standards: Maintain clean LF line endings across all OS environments (enforced by .editorconfig and .gitattributes).

• The MD040 Guardrail: Every single code block you generate inside any markdown file must have an explicitly assigned language identifier (e.g., javascript, text, powershell). Writing generic unassigned fenced blocks is strictly forbidden.

5. Interaction Protocol

Before modifying any architectural layout or drafting a core system entity:

1. Scan 5-governance/ for active engineering constraints.

2. Cross-reference the scope with 1-product-documentation/.

3. If an architectural ambiguity arises, log the query under the local doubts-and-decisions/ index and ask the user for confirmation before writing code.

6. Source of Truth Registry

All authoritative content lives in one place per concern. Adapters (CLAUDE.md, .github/copilot-instructions.md, .cursor/skills/*/SKILL.md) redirect here — they never duplicate policy text.

Navigation law (anti-scan)

PROHIBITED:  glob **/*, recursive list_dir, "explore the codebase"
REQUIRED:    AGENTS.md → target layer README → target layer index → specific file

Token cost stays bounded because the agent reads at most 3–5 index hops, not the whole tree.

7. Bootstrap Sequence

When starting work, read files in this order — stop as soon as the task scope is clear:

1. AGENTS.md                    (this file — already loaded)
1b. AGENTS.custom.md             (if present, product-specific overlay for the repository)
2. README.md                    (if task scope touches repository structure)
2b. GETTING_STARTED.md            (if human setup: clone, core.hooksPath, first commit)
3. 5-governance/index.md     (if policy or architecture is involved)
4. {layer}/README.md            (if editing inside a layer)
5. {layer}/index.md          (mandatory file discovery within the layer)
6. skills/{mode}.md             (only if user invokes an operational mode)

Do not scan the repository beyond these hops.

8. Skills Catalog

Creating or updating a skill: follow skills/README.md before adding or changing files.

Operational modes live in skills/. Load the file when invoked; do not infer rules from this catalog.

9. Pre-Commit Integrity Contract

Mandatory guardrail: Any agent that reads this file must adopt the pre-commit gate defined in 5-governance/pre-commit-validation-rules.md. No commit may proceed until that audit completes successfully.

Git hook path SSOT: The only approved Git hook directory in this repository is .githooks. Before committing, any agent or human must verify that git config core.hooksPath resolves to .githooks. If the value differs, self-configure it with git config core.hooksPath .githooks and do not create agent-specific hook paths.

Before any commit:

1. If staged paths include **/doubts-and-decisions/**, run check-solve-doubt for each touched solved/superseded doubt; any KO result blocks commit.
2. Invoke solid, which loads and executes all criteria in pre-commit-validation-rules.md (COD, SOLID, L4 ZC pseudocode mirror when applicable) and the skill-only propagation coherence check in that skill.
3. Regenerate ## Current audit in solid-principles-review-report.md per that document.
4. Abort the commit on **STATUS:** KO or any unresolved violation.
5. Anti-evasion (hard rule): It is forbidden to update only Audit completed, STATUS, or other report metadata to satisfy the hook without executing the required audits.
6. Source-of-truth discipline: Hook scripts are transport gates only; they never define validation scope. Validation scope is defined exclusively by pre-commit-validation-rules.md and skills/solid.md.
7. Bypass prohibition (absolute): It is forbidden to suggest or execute git commit --no-verify (or -n) under any circumstance.
8. Unsafe amend shortcut prohibition: It is forbidden to suggest git commit --amend --no-edit as a recovery path after hook/audit failures. Execution is allowed only under explicit user request and after required validations pass.
9. Automatic audit recovery: If a commit is blocked by audit/report freshness, the agent must execute the required validation workflow automatically and must not ask permission to run it.
10. Protected-file detection discipline: Protected/exempt decisions must be based on required git command outputs (git diff --cached --name-only; for amend also git show --name-only --pretty="" HEAD), never on repository text search.

Hook enforcement for the audit report artifact is documented in §8. L4 pseudocode mirror validation has no automated hook in this template — see §9.

10. Linguistic Policy

You must strictly comply with the Repository Language Standard.

• Reasoning: In the user's language.
• Persistence: English only.
• No redundancy: Single-language repository.