forgeguard-engineering · diff
git:20260801.8998c92 to git:20260811.774988d
48 added, 9 removed. Audit A to A.
---
name: forgeguard-engineering
- description: Enforce evidence-based engineering for backend, frontend, mobile, AI, scripts, infrastructure, APIs, components, queries, algorithms, and MCP work in any language or framework. Use whenever code or repository behavior changes.
+ description: Enforce minimal, surgical, evidence-based engineering for backend, frontend, mobile, LLM, machine learning, deep learning, scripts, APIs, components, queries, algorithms, and MCP work. Use whenever code or repository behavior changes.
---
# ForgeGuard Engineering
Follow: inspect → design → implement → test → review → verify.
- Inspect the affected code, callers, tests, contracts, and schemas before editing. Reuse only behavior with the same purpose and change reasons; inspect every caller before changing shared behavior. Define relevant bounds, failures, complexity, I/O, concurrency, and the smallest safe design.
+ ## Work surgically
- For every code change in strict mode, and every non-trivial code change in other modes, use the ForgeGuard session id injected by the lifecycle hook to register the exact objective, verifiable todos, and optional path prefixes with `forgeguard task start`. For abstract work, also state the metric, baseline, target, guardrails, and verification so progress is hill-climbable. Keep the declared scope honest; expand it only after repository evidence shows the objective requires another path. Use `--semantic` only when the host provides a native goal evaluator.
+ - Inspect the affected code, tests, contracts, schemas, direct callers, and compatibility surface before editing.
+ - Resolve missing facts with read-only inspection. When unresolved ambiguity materially changes behavior, data, security, scope, cost, or external or irreversible state, use the host's native structured user-input tool and wait; otherwise state the safest reversible assumption.
+ - Reuse an existing project pattern only when its purpose and change reasons match. Prefer the standard library and installed dependencies over new abstractions or packages.
+ - Make every changed line trace to the objective. Do not refactor adjacent code or remove pre-existing dead code; remove only orphans created by the change.
+ - Choose the smallest safe design. Define only the relevant bounds, failures, complexity, I/O, and concurrency risks.
- Implement focused changes and proportionate tests. Run `forgeguard gate --changed --output compact` plus relevant repository checks, review the complete diff, and report only executed checks and unresolved risk. Never weaken quality or security controls.
+ ## Register the goal
- Update completed todos with `forgeguard task todo`. Before stopping, run `forgeguard task ready --session <id> --confidence <0-100> --evidence <exact-check-result>` for an active task. Confidence is model-reported and advisory; it never replaces executed evidence. Never present a model-derived value, correction, or completion claim as fact: cite exact tool/check evidence or label the claim unverified.
+ Use the session id injected by the lifecycle hook. Run `forgeguard mode` to resolve policy: register every change in strict mode and every non-trivial change otherwise.
- Treat an auto-poke as a new bounded verification phase: perform the requested TODO, test, review, or contract check, then submit fresh evidence. Do not repeat an earlier completion claim.
+ Before editing, inspect existing state with `forgeguard task status --session <id>`. If no task exists, register the objective and verifiable steps:
- Read only the matching reference; do not read references for routine inspection, reuse, or testing:
+ ```sh
+ forgeguard task start --session <id> --objective "<outcome>" \
+ --todo "<step with observable completion>" \
+ --verification "<exact check>"
+ ```
+ Make every non-trivial goal hill-climbable: supply `--metric`, a measured `--baseline`, `--target`, at least one `--guardrail`, and `--verification`. For functional work, use an observable acceptance or regression count; never invent a baseline. Add `--scope <path>` when the affected paths are known. Use `--semantic` only when the host provides a native goal evaluator.
+
+ ## Prove the change
+
+ Implement the smallest focused change and the smallest test layer that can fail for the changed behavior. Match evidence to the claim:
+
+ - Bug fix: regression test exercising the reported failure.
+ - API or schema change: contract, migration, or compatibility check.
+ - Performance change: the same benchmark before and after, including the measured values.
+ - Security or authorization change: negative-path test showing rejection.
+ - Behavior-preserving refactor: relevant checks passing before and after.
+
+ Never weaken tests, quality gates, validation, authorization, or security controls to pass a check.
+
+ ## Finish with evidence
+
+ 1. Run relevant repository checks and `forgeguard gate --changed --output compact`.
+ 2. Review the complete diff for unrelated edits and new dead code.
+ 3. Mark completed work with `forgeguard task todo --session <id> --done <index>`.
+ 4. Recheck `forgeguard task status --session <id>`; do not claim completion with pending todos.
+ 5. Submit each exact result with `forgeguard task ready --session <id> --confidence <0-100> --evidence "<check: result>"`.
+
+ Report only executed evidence and unresolved risk. Confidence is advisory and never replaces deterministic evidence. Label unverified claims as unverified.
+
+ Treat an auto-poke as a new bounded verification phase: perform the requested TODO or check, then submit fresh evidence. Do not repeat an earlier completion claim.
+
+ Use progressive disclosure: read only the matching reference; do not read references for routine inspection, reuse, or testing. Role text is a reasoning frame, not permission to invent requirements, APIs, schemas, or evidence.
+
- UI, browser client, or accessibility work: [frontend.md](references/frontend.md)
- Native or cross-platform mobile work: [mobile.md](references/mobile.md)
- API, service, auth, or distributed-operation work: [backend.md](references/backend.md)
- - Schema, query, migration, ORM, or MCP data work: [database.md](references/database.md)
- - LLM, RAG, agent, or MCP tool work: [ai.md](references/ai.md)
+ - Schema, query, migration, ORM, or database MCP work: [database.md](references/database.md)
+ - LLM, RAG, agent, or tool-authorization work: [ai.md](references/ai.md)
+ - Classical machine-learning model or feature-pipeline work: [ml.md](references/ml.md)
+ - Neural-network or deep-learning training/inference work: [deep-learning.md](references/deep-learning.md)
+ - Model serving, deployment, registry, or drift-monitoring work: [mlops.md](references/mlops.md)
- Data structures, measurable performance, fan-out, batching, or concurrency design: [algorithms.md](references/algorithms.md)
- Complex, risky, or unfamiliar test design: [testing.md](references/testing.md)