Complete GRACE methodology: semantic markup, knowledge graphs, module contracts, testing, and log-driven verification for AI-driven engineering

version
4.2.1
GitHub stars
267

Install

/plugin install grace@grace-marketplace

Run it inside Claude Code after adding the marketplace with /plugin marketplace add osovv/grace-marketplace.

Contents

Discovered from source

Skills 15

1. `.grace/context/*.xml` for requirements, technology, principles, deployment, and UX constraints. 2. `.grace/graph/index.xml` then routed graph documents for `M-*` and `DF-*` ownership. 3. `.grace/verification/index.xml` then routed verification documents for `V-M-*` coverage. 4. `.grace/changes/active/C-*` for in-flight approved or draft work. 5. File-local `MODULE_CONTRACT`, `MODULE_MAP`, `LINKS:`, `START_CONTRACT`, and `START_BLOCK_` anchors.

<answer_rules>

  • Cite the artifact or anchor that supports each important claim.
  • Distinguish durable current state from active change intent.
  • If legacy GRACE 3 docs are present, explain that they require grace-migrate and are not GRACE 4 truth.
  • Do not invent missing graph or verification facts; report uncertainty and the safest next lookup. </answer_rules>
Invoke the installed stable `grace` binary directly. If it is missing, install it with `bun add -g @osovv/grace-cli`. Do not default to `bunx`, `npx`, or the `rc` dist-tag. - Active-baseline preflight before observed writes: `grace lint --path PROJECT --assertions current` - Selected baseline: `grace lint --path PROJECT --change C-ID --assertions baseline` (add `--run-commands` when the baseline declares `MustPassCommand`) - Selected target: `grace lint --path PROJECT --change C-ID --assertions target --run-commands` - Final execution gate: `grace lint --path PROJECT --change C-ID --assertions final --run-commands` - Parallel preflight: `grace lint --path PROJECT --parallel-preflight` - Status: `grace status --path PROJECT --with modules --json` - Navigation: `grace module find|show`, `grace verification find|show`, and `grace file show`.

<command_run_contract> --run-commands executes each declared MustPassCommand value once per lint, fail-fast, with a default 600s per-command timeout (--command-timeout SECONDS overrides, 0 disables). Plan, progress, and per-command result lines go to stderr; the lint report and JSON go to stdout, so piping stdout stays safe. Agents and pipes get compact output by default; interactive terminals see live streamed command output. Force modes with --verbose (live) or --quiet (compact); they are mutually exclusive, and --format json is always compact. Full combined output of every command is stored per run under ~/.cache/grace/run-commands/<project>/runs/<run>/ (respecting XDG_CACHE_HOME) with a machine-readable meta.json; failing commands print a bounded output tail plus the absolute log path. meta.json records the VCS identity the run executed against (head, branch, dirty, all null outside a git repository) plus the writing pid; it is written at run start with status running and rewritten on completion, and a running record whose process is gone is reclassified as killed on a later run. Pruning keeps the newest passing run of every change indefinitely, so the evidence an archived change cites stays on disk; the retention count applies only to non-passing runs — failed, timed out, interrupted, superseded by a newer pass of the same change, unbound to a change, or missing a readable meta.json. The count defaults to 10, is set project-wide by runLogRetention in .grace-lint.json, and is overridden per run by --keepRuns N. --keepRuns 0 keeps no non-passing runs at all, which deletes the current run as soon as it fails and leaves its printed log path dangling. Interrupted runs (SIGINT/SIGTERM) kill the whole command process group, record interrupted status in meta.json, and exit 130.</command_run_contract>

<lifecycle_command_contract>current evaluates active approved baselines and is not end-state evidence. Keep MustPassCommand entries as leaf project checks; do not nest grace lint, grace status, or another GRACE lifecycle command inside plan assertions. Run selected target/final lint externally.</lifecycle_command_contract>

<failure_contract> Lint, status, and navigation commands validate before returning records. JSON argument/runtime failures are one { "schemaVersion": "1.0.0", "ok": false, "error": { ... } } object on stdout. Text failures are one concise actionable line with a nonzero exit code and no stack trace. </failure_contract>

<runtime_contract> TypeScript/JavaScript analysis is bundled. Python and Dart governed files require their runtimes on PATH; missing runtimes fail closed with actionable analysis.runtime-missing diagnostics instead of silently dropping parity checks. </runtime_contract>

<migration_boundary>GRACE 4 commands do not dual-validate legacy GRACE 3 docs. Use grace-migrate.</migration_boundary>

Require one active bundle with approved, identity-matched `spec.xml` and `plan.xml`. Approved plans are immutable. Read context, projections, assertions, scopes, task dependencies, and verification before editing. Reject phase-incompatible plans before writes: `MustPassCommand` must be leaf project evidence, and neither target assertions nor post-write task verification may invoke `--assertions current` or nest GRACE lifecycle commands. Supersede and replan instead of editing an approved conflict in place.

<assertion_commands>

  • Active-baseline preflight before observed writes: grace lint --path PROJECT --assertions current
  • Selected baseline: grace lint --path PROJECT --change C-ID --assertions baseline (add --run-commands when the baseline declares MustPassCommand)
  • Selected target without commands: grace lint --path PROJECT --change C-ID --assertions target
  • Selected target with command evidence: grace lint --path PROJECT --change C-ID --assertions target --run-commands
  • Final end-state validation: grace lint --path PROJECT --change C-ID --assertions final (add --run-commands when the target declares MustPassCommand)
  • Parallel preflight: grace lint --path PROJECT --parallel-preflight </assertion_commands>

<mode_selection> Wait for explicit sequential or parallel-safe choice. Parallel-safe requires the explicit preflight to pass. Workers never mutate approved plans; durable .grace changes are applied centrally after observed work verifies. </mode_selection>

<recovery_decision_table> | state | required action | | clean-to-start | Run selected baseline, then execute tasks. | | partial-observed-writes | Inspect the declared observed scope and ask whether to resume or revert. | | durable-state-changed | Hard stop; supersede and replan. Approved assertions are immutable. | | target-already-satisfied | Run final end-state validation, opted-in command evidence when declared, durable reconciliation, and ask for explicit apply confirmation. | | unsafe-unknown-drift | Hard stop and report unexplained files. | </recovery_decision_table>

<execution_rules>

  1. Run the selected baseline before implementation, including explicit --run-commands when its assertions declare MustPassCommand.
  2. Execute one dependency-ready task or one verified parallel-safe batch at a time.
  3. Run each task's acceptance and verification immediately.
  4. Apply approved durable context, graph, and verification changes centrally.
  5. Reconcile durable state, run leaf plan gates, then run selected --assertions final as the outermost lifecycle gate, including --run-commands when MustPassCommand is declared. Final mode performs full project lint, evaluates the selected target, keeps unrelated approved baselines active, and does not re-evaluate the selected plan's superseded baseline.
  6. Ask for explicit apply confirmation after fresh end-state evidence passes.
  7. Only then set spec and plan to applied and archive the complete bundle.
  8. Never edit approved assertions/scopes/tasks in place, bypass stale evidence, or continue through unknown drift. </execution_rules>
GRACE 4 uses `.grace` as the durable project model:
  • .grace/context stores requirements, technology, principles, deployment, and UX constraints.
  • .grace/graph stores graph indexes and routed graph documents with GD-*, M-*, and DF-* tags.
  • .grace/verification stores verification indexes and routed V-M-* entries.
  • .grace/changes stores active and archived C-* change bundles with GraceChangeSpec, optional non-normative design context, and GraceChangePlan. </core_model>
1. `grace-init` creates the `.grace` skeleton. 2. `grace-spec` creates an active change spec and waits for approval. 3. `grace-plan` creates assertions, scopes, and `T-*` implementation tasks. 4. `grace-execute` runs sequential or parallel-safe mode from the approved plan. 5. `grace lint` and `grace status` provide validation and health evidence. 6. Existing GRACE 3 projects use `grace-migrate`; the CLI validates the result but does not convert legacy docs directly.
1. Start from the failure, pasted error, failing command, or user report. 2. Load relevant `.grace/graph` module anchors and `.grace/verification` entries. 3. Check active `.grace/changes` for overlapping or stale planned work. 4. Inspect file-local contracts and semantic blocks before editing. 5. Identify root cause, present findings, then make the smallest safe fix. Run the specific `V-M-*` commands or closest deterministic tests. If verification expectations are stale, update or propose changes through the GRACE 4 change lifecycle.
Create the canonical GRACE 4 project layout from this skill's `assets/` templates:
  • AGENTS.md
  • .grace/context/requirements.xml
  • .grace/context/technology.xml
  • .grace/context/principles.xml
  • .grace/context/deployment.xml
  • .grace/context/ux-guidelines.xml
  • .grace/graph/index.xml
  • .grace/graph/main.xml
  • .grace/verification/index.xml
  • .grace/verification/main.xml
  • .grace/changes/active/
  • .grace/changes/archive/

Every XML artifact uses graceVersion="4.0". Semantic anchors are XML tags, never attributes. Do not create dummy C-* change bundles. Do not overwrite existing .grace artifacts without explicit confirmation.

<template_sources>

Template sourceTarget in project
assets/AGENTS.md.templateAGENTS.md
assets/.grace/context/requirements.xml.template.grace/context/requirements.xml
assets/.grace/context/technology.xml.template.grace/context/technology.xml
assets/.grace/context/principles.xml.template.grace/context/principles.xml
assets/.grace/context/deployment.xml.template.grace/context/deployment.xml
assets/.grace/context/ux-guidelines.xml.template.grace/context/ux-guidelines.xml
assets/.grace/graph/index.xml.template.grace/graph/index.xml
assets/.grace/graph/main.xml.template.grace/graph/main.xml
assets/.grace/verification/index.xml.template.grace/verification/index.xml
assets/.grace/verification/main.xml.template.grace/verification/main.xml
</template_sources>
1. Gather project name, annotation, keywords, language/runtime/framework, testing stack, observability constraints, deployment applicability, UX applicability, and any known initial modules. 2. If `.grace` or `AGENTS.md` already exists, stop and ask whether to keep, merge, or overwrite each existing artifact. Never overwrite silently. 3. Create `.grace/context`, `.grace/graph`, `.grace/verification`, `.grace/changes/active`, and `.grace/changes/archive`. 4. Read each `.template` file, replace `$PLACEHOLDER` values with gathered project information, and write the target file. 5. Print created files and recommend the next workflow: use `grace-spec` to create an active `GraceChangeSpec`, then `grace-plan` to produce a `GraceChangePlan` before implementation.

<hard_rules>

  • GRACE 4 state lives under .grace; do not create legacy docs/*.xml as the bootstrap surface.
  • GraceChangeSpec and GraceChangePlan are created by later change workflows, not by init.
  • If legacy GRACE 3 docs are present, explain that migration is handled only by grace-migrate; init must not convert or delete them.
  • Validate the resulting project with grace lint --path <project-root> when the CLI is available. </hard_rules>
Migration is copy-and-validate, not destructive conversion. Before writing `.grace`, inventory every legacy source, record a restorable backup path outside the proposed cleanup set, present the migration report, and wait for explicit write approval. Never create retroactive `C-*` bundles. 1. Detect legacy docs and current `.grace` state. If `.grace` already exists, stop and ask whether migration should merge, replace, or abort. 2. Inventory legacy source paths and create or verify a restorable backup. Record source coverage and backup evidence in the report. 3. Map legacy requirements, technology, graph, verification, and operational content into the GRACE 4 layout. List ambiguities and unsupported structures rather than guessing. 4. Produce `references/migration-report-template.xml`, review `references/migration-checklist.md`, and ask for explicit approval before writing `.grace`. 5. Write `.grace`, then run `grace lint --path --assertions current` and `grace status --path --json`. Require status `projectKind` `grace4` with no integrity errors, and record commands, exit states, and findings. 6. If validation is not successful or generated coverage is incomplete, retain all legacy sources and stop. 7. Detect git availability and worktree membership. If git is available for the project, record `git status --porcelain --untracked-files=all` before cleanup. 8. Present an exact cleanup proposal containing only inventoried legacy paths. Ask for a separate explicit cleanup approval. For a dirty worktree or non-git project, require another explicit acknowledgement naming that risk. 9. Archive or delete only the approved paths, record each result, and leave the backup intact. Do not use broad globs, hidden shell cleanup, or unreviewed recursive deletion.

<cleanup_preconditions> Cleanup requires all of: complete inventory, restorable backup, explicit write approval, successful current lint, fresh status proving GRACE 4 with no integrity errors, verified generated coverage, git availability/worktree inspection, recorded porcelain output when applicable, exact proposed paths, separate explicit cleanup approval, and separate dirty or non-git risk acknowledgement when applicable. A missing gate means no cleanup. </cleanup_preconditions>

<cleanup_failure_rule> If validation, git inspection, move, archive, or delete fails, stop immediately and state: "Legacy GRACE 3 artifacts remain untouched unless the failure output explicitly lists a completed move." Never retry destructive cleanup automatically. </cleanup_failure_rule>

Convert one approved active `GraceChangeSpec` into the executable `GraceChangePlan`; do not implement source code. - Required: `.grace/changes/active/C-CHANGE-ID/spec.xml` - Optional: sibling `design-context.xml` - Current state: `.grace/context`, graph and verification indexes, and their routed documents - Require `.grace/changes/active/C-CHANGE-ID/spec.xml` with `GraceChangeSpec`, status `approved`, and exactly one matching direct `C-*` wrapper. - Refuse draft, rejected, cancelled, applied, or superseded specs. - Treat optional `design-context.xml` as explanatory; `spec.xml` wins on conflict. - Run `grace lint --path PROJECT --assertions current` before planning and surface stale or invalid active baselines.

<approved_plan_immutability>

  • If plan.xml already exists with status approved, stop before writing.
  • Do not refresh BaselineAssertions, TargetAssertions, DurableScope, ObservedWriteScope, or tasks in place.
  • Create a new C-* bundle and mark the old bundle superseded with an explicit replacement reference. </approved_plan_immutability>

<must_do> Produce plan.xml from references/change-plan-template.xml as draft unless the user explicitly approves the completed plan. Require a matching C-* wrapper, meaningful intent, non-empty machine-checkable baseline and target assertions, explicit durable and observed scopes, and unique acyclic T-NNN tasks. A scope with no writes must use an explicit <None /> marker; prose such as "none" is invalid. Every task has one Title, one DependsOn element listing zero or more predecessors as canonical comma-separated T-NNN values (for example <DependsOn>T-001, T-002</DependsOn>), non-empty acceptance criteria, and non-empty verification commands. Dependencies form a directed acyclic graph: list only true predecessors and never linearize independent tasks into a chain to express ordering. Surface stale-state and coexistence warnings, and reject unsupported scope glob syntax instead of guessing. </must_do>

<command_phase_rules>

  • current is an active-baseline preflight and is valid only before observed writes begin.
  • baseline is the selected pre-edit gate, target is selected post-edit evidence, and final is the outer apply/archive gate owned by grace-execute.
  • MustPassCommand contains leaf project evidence such as tests, typecheck, build, format, or package checks. Never place grace lint, grace status, or another GRACE lifecycle command inside it.
  • Never put --assertions current in TargetAssertions or in task verification that runs after writes. Use selected target/final lint externally instead.
  • A MustPassCommand must complete within its declared budgetSeconds (absent, the global --command-timeout applies) on the reference host; declare the budget you have measured rather than inheriting a default that will kill the command mid-gate.
  • A whole-suite command whose runtime is dominated by substrate startup — containers, databases, browsers, emulators — belongs in an acceptance tier, not in the gate; never declare both a whole-suite command and the file-level commands it already re-runs. </command_phase_rules>
- Active-baseline preflight: `grace lint --path PROJECT --assertions current` - Parallel safety: `grace lint --path PROJECT --parallel-preflight` - Recommend `grace status --path PROJECT --json` after approval.

<hard_rules> Do not implement code, silently approve a plan, overwrite an approved plan, or mutate current graph/verification artifacts while planning. Semantic anchors are canonical XML tags, never attributes. </hard_rules>

Use this for rename, move, split, merge, extraction, or boundary cleanup work. Greenfield feature work should go through `grace-spec`, `grace-plan`, and `grace-execute`.

<must_do>

  • Resolve affected M-*, DF-*, and V-M-* anchors through .grace/graph/index.xml and .grace/verification/index.xml.
  • Check active .grace/changes for scope overlap before editing.
  • Preserve or update file-local LINKS:, module contracts, function contracts, and semantic blocks.
  • Update durable graph and verification artifacts only when the refactor intentionally changes boundaries, paths, or evidence.
  • Run targeted tests and grace lint --path <project-root> when available. </must_do>
Compare code, tests, and file-local markup against `.grace/context`, `.grace/graph`, `.grace/verification`, and active change scopes. This skill reports drift and proposes a normal `GraceChangeSpec`/`GraceChangePlan`; it does not silently mutate current state. 1. Run or request `grace lint --path ` and `grace status --path `. 2. Inspect `.grace/graph/index.xml` and routed graph documents for stale, missing, or orphaned `M-*` and `DF-*` anchors. 3. Inspect `.grace/verification/index.xml` and routed verification documents for missing deterministic `V-M-*` coverage, stale commands, or missing evidence markers. 4. Compare file-local `LINKS:`, module contracts, tests, and log markers against durable anchors. 5. Report drift as findings with proposed reconciliation scope. 6. If changes are needed, route through `grace-spec` and `grace-plan` instead of direct mutation.
- `.grace/context` artifacts are present and relevant. - `.grace/graph/index.xml` routes every graph anchor to the correct graph document. - `.grace/verification/index.xml` routes deterministic `V-M-*` entries and covers current modules. - Active change specs/plans use valid statuses for their location and exactly one `C-*` wrapper. - Baseline and target assertions are meaningful and not stale. - Durable scopes and observed write scopes are explicit; unsafe parallel overlaps are blocked. - File-local contracts, `LINKS:`, and semantic blocks match durable anchors. - Verification evidence is fresh and tied to commands or markers. Return findings with severity, location, why it matters, expected fix direction, and verification target. Do not fix unless explicitly asked.
Generated subagents must be told to:
  • read .grace/context, .grace/graph, .grace/verification, and relevant .grace/changes packets explicitly;
  • treat spec.xml as normative and design context as non-normative;
  • respect DurableScope, ObservedWriteScope, BaselineAssertions, and TargetAssertions;
  • never mutate approved plans or XML statuses without controller approval;
  • return verification evidence and scoped graph/verification deltas. </subagent_requirements>
`.grace/changes/active/C-CHANGE-ID/`
  • spec.xml — normative GraceChangeSpec
  • design-context.xml — optional, explanatory only
  • plan.xml — created later by grace-plan </change_bundle_contract>

<status_rules> Create spec.xml as status="draft". Set status="approved" only after explicit user approval. Rejected or cancelled specs move to archive with terminal status. Do not create or edit plan.xml in this skill. </status_rules>

<strict_contract> The direct C-* wrapper must contain exactly one meaningful Summary, Goals, Constraints, NonGoals, AcceptanceCriteria, AffectedAreas, and VerificationIntent section. Empty containers are not approval-ready. Semantic anchors are canonical attribute-free XML tags, never attributes or attribute values. </strict_contract>

1. Ask one focused question at a time until goal, scope, constraints, non-goals, acceptance criteria, affected areas, and verification expectations are clear. 2. Propose a concise design summary and explicit assumptions. Ask for approval before writing an approved spec. 3. Create a deterministic uppercase-kebab `C-*` change id. 4. Write `spec.xml` from `references/change-spec-template.xml` with exactly one direct `C-*` wrapper and no empty required section. 5. If rationale, alternatives, scenarios, or external constraints would otherwise bloat the spec, write non-normative `design-context.xml` from its template. 6. If approval is not explicit, leave `spec.xml` as `status="draft"` and report the approval step needed.

<hard_rules>

  • spec.xml is the source of truth for grace-plan; design context never adds requirements.
  • Do not implement code, mutate current graph/verification state, or create retroactive change bundles.
  • Recommend grace lint --path <project-root> --assertions current as a pre-implementation active-baseline check after writing the bundle; never present it as target or final evidence. </hard_rules>
Run `grace status --path PROJECT --json` and report current GRACE 4 state without mutating artifacts. Module-health summary counts are always evaluated; add `--with modules` only when detailed module records are needed.

<must_report>

  • Project kind: GRACE 4, legacy GRACE 3 migration candidate, or missing GRACE; plus context completeness.
  • Graph/verification projection integrity, routed coverage, and module counts.
  • Active/archive bundle statuses and derived states.
  • needs-plan, needs-plan-approval, stale-plan, integrity-issues, and ready-to-execute with readiness mutually exclusive from stale/integrity states.
  • Route-aware explained/unexplained drift, scope coexistence warnings, and parallel blockers.
  • Module-health load failure as integrity/degraded status rather than a crash.
  • The next safe action: lint, migrate, specify, plan, or execute. </must_report>
- Pre-implementation active-baseline integrity: `grace lint --path PROJECT --assertions current` - Parallel decision: `grace lint --path PROJECT --parallel-preflight` - Status snapshot: `grace status --path PROJECT --with modules --json --fail-on errors`

<hard_rules>Do not edit XML statuses. A draft spec without a plan is normal; an approved spec without a plan needs planning. A stale or integrity-invalid approved plan is never ready.</hard_rules>

Strengthen deterministic verification for modules and changes. Verification state lives in `.grace/verification/index.xml` and routed verification documents. Each durable module should have deterministic `V-M-*` coverage unless an explicit exception is planned. 1. Read relevant `.grace/graph` anchors and current `V-M-*` entries. 2. Identify scenarios, commands, test files, required log markers, and trace assertions. 3. Ensure commands are deterministic and runnable from the project root or documented cwd. 4. Update or propose `.grace/verification` changes through the active change plan. 5. Run the commands and record fresh evidence in the response. When verification commands run from a workspace or package directory, add one direct `relative/project/path` child to the owning `V-M-*` entry. Keep declared `...` paths project-root-relative; the CLI uses `Cwd` only to compare them with cwd-relative command arguments. Use `` when module health must prove a runtime log or trace emission from linked implementation code. Use `` for deterministic test or trace evidence that does not require runtime logging, such as pure functions, type-level modules, and core libraries. A non-empty marker or trace assertion satisfies the module-health evidence requirement; only authored markers require matching runtime emission and `BLOCK_*` evidence. Reference named project tasks in `MustPassCommand` and `ExpectedCommand` (for example `bun run gate:e2e`) instead of inline `;`-chains. Decompose full gates into granular named tasks (`gate:test`, `gate:typecheck`, `gate:build`, `gate:e2e`) so a selective re-run is just running that task, timeouts map to one coherent unit, and `grace lint --run-commands` reports each gate step with its own timing and log. A flaky gate is a defect of the verification entry, not a reason to re-run blindly. Diagnose from the per-attempt logs under `~/.cache/grace/run-commands/`. Fix it by decomposing the gate task, adding runner-level retries inside the task itself (for example playwright `--retries`), or quarantining the unstable scenario. Silent manual re-runs are not a fix: grace records every run honestly, and nondeterministic verification undermines assertion evidence.

Agents 10

Contract-Driven Development

In GRACE, the contract is the source of truth. Code implements the contract, not the other way around.

The Rule

Never write code without a contract. Before generating or editing any module, create or update its MODULE_CONTRACT with PURPOSE, SCOPE, INPUTS, OUTPUTS.

MODULE_CONTRACT

Every file starts with:

// START_MODULE_CONTRACT
//   PURPOSE: [What this module does — one sentence]
//   SCOPE: [What operations are included]
//   DEPENDS: [List of module dependencies by M-xxx ID]
//   LINKS: [Knowledge graph node references]
// END_MODULE_CONTRACT

The contract is written before the code. It comes from the GraceChangeSpec (.grace/changes/active/*/spec.xml), which was approved by the user during the $grace-spec phase.

Name things semantically. A contract is much stronger when its module names, PURPOSE text, and block labels already encode the intended transformation instead of forcing the agent to infer it from abstract placeholders.

Important distinction:

  • .grace/graph/ and .grace/verification/ XML artifacts carry the module's public contract and public interface
  • private helpers, internal normalization steps, and implementation-only types stay in the source file header and local contracts

Function Contracts

Every exported function or component must have a contract placed before function signature and docstrings/comments:

// START_CONTRACT: functionName
//   PURPOSE: [What it does — one sentence]
//   INPUTS: { paramName: Type — description }
//   OUTPUTS: { ReturnType — description }
//   SIDE_EFFECTS: [What external state it modifies, or "none"]
//   LINKS: [Related modules/functions via knowledge graph]
// END_CONTRACT: functionName

Development Flow

Requirements (.grace/context/requirements.xml)
  -> GraceChangeSpec (.grace/changes/active/*/spec.xml)
    -> GraceChangePlan (.grace/changes/active/*/plan.xml)
      -> Verification entries (.grace/verification/*.xml)
        -> Module Contracts (MODULE_CONTRACT in each file)
          -> Function Contracts (START_CONTRACT in each function)
            -> Code and tests (within semantic blocks)

Never jump levels. If requirements are unclear — stop and clarify with the user.

Approved plans are immutable execution evidence. If baseline/target assertions, scopes, tasks, or verification gates need to change after approval, create a replacement C-* bundle and mark the old bundle superseded; do not refresh an approved plan in place.

Governed Autonomy (PCAM)

PCAM = Purpose, Constraints, Autonomy, Metrics.

  • Purpose: Defined by the contract. You know WHAT to build.
  • Constraints: Defined by the GraceChangePlan and .grace/graph. You know the BOUNDARIES.
  • Autonomy: You choose HOW to implement within those boundaries.
  • Metrics: The contract's OUTPUTS plus the verification evidence tell you if you're done.

You have freedom in HOW to implement, but not in WHAT. The contract and the knowledge graph define WHAT. If a contract seems wrong — propose a change, don't silently deviate.

Contract Modification Rules

  1. Read before edit — always read the MODULE_CONTRACT before editing any file
  2. Update MODULE_MAP — if you change the relevant public or local symbols for that file's lint mode, update MODULE_MAP
  3. Update .grace/graph — if you add/remove modules or dependencies, update the corresponding GD-* document
  4. Update .grace/verification — if you change tests, required markers, or verification commands, update the corresponding VD-* document
  5. Track changes — after fixing bugs, add a CHANGE_SUMMARY entry
  6. Never remove markup — semantic markup anchors are load-bearing structure
  7. Propose, don't deviate — if the contract is wrong, propose a change to the user. Don't silently implement something different.
  8. Anchor the intent — prefer meaningful names and concrete PURPOSE text over generic placeholders or arbitrary IDs.

Contract in GraceChangeSpec

Modules in the GraceChangeSpec carry their contract in XML:

<GraceChangeSpec graceVersion="4.0" status="approved">
  <C-ADD-AUTH>
    <Summary>Add authentication module</Summary>
    <Goals><Goal>Authenticate protected requests.</Goal></Goals>
    <Constraints><Constraint>Preserve existing public session APIs.</Constraint></Constraints>
    <NonGoals><NonGoal>Replace the user store.</NonGoal></NonGoals>
    <AcceptanceCriteria><Criterion>Protected requests reject invalid sessions.</Criterion></AcceptanceCriteria>
    <AffectedAreas><M-AUTH /></AffectedAreas>
    <VerificationIntent><ExpectedCommand>bun test auth</ExpectedCommand></VerificationIntent>
  </C-ADD-AUTH>
</GraceChangeSpec>

This XML contract is the blueprint for the MODULE_CONTRACT in the source file. The matching verification entry in .grace/verification/ is the blueprint for how the module proves that it still satisfies the contract.

The shared XML contract should stay at module-boundary level. It should not list every private helper that exists only to support the implementation. Those details belong in the file header and local contracts.

Knowledge Graph Maintenance

The .grace/graph/ directory is the single source of truth for the project's module structure. It maps every module, its public interface, its dependencies, and how modules connect to each other. The index.xml file lists GD-* document routes and the modules each document owns.

Structure

<GraceGraphIndex graceVersion="4.0">
  <GraphDocuments>
    <GD-MAIN>
      <Path>graph/main.xml</Path>
      <Owns>
        <M-CONFIG />
        <M-DB />
      </Owns>
    </GD-MAIN>
  </GraphDocuments>
</GraceGraphIndex>

Each GD-* document contains the actual module and data-flow definitions:

<GraceGraphDocument graceVersion="4.0">
  <GD-MAIN>
    <M-CONFIG>
      <Summary>Application configuration and environment management</Summary>
      <Path>src/config/index.ts</Path>
      <M-DB />
    </M-CONFIG>
    <M-DB>
      <Summary>Database connection and query layer</Summary>
      <Path>src/db/index.ts</Path>
    </M-DB>
  </GD-MAIN>
</GraceGraphDocument>

Module Tag Convention

Every module uses a unique ID as the XML tag name:

  • <M-CONFIG> not <Module ID="M-CONFIG">
  • <M-DB> not <Module ID="M-DB">

This eliminates closing-tag polysemy — </M-CONFIG> is unambiguous while multiple </Module> closings create "semantic soup" for LLMs.

Canonical grep-stable naming rules:

  • module IDs use exact uppercase kebab form with M- prefix only
  • verification refs use exact V-M-<MODULE-SUFFIX> form only
  • annotation tags use exact prefixes: fn-, type-, class-, export-, const-
  • edge tags use exact CrossLink spelling and exact from, to, relation attributes
  • avoid alternate synonyms like moduleId, verificationId, edge, source, or target when canonical anchors already exist

Module Types

TypeDescription
ENTRY_POINTWhere execution begins (CLI, HTTP handler, event listener)
CORE_LOGICBusiness rules and domain logic
DATA_LAYERPersistence, queries, caching
UI_COMPONENTUser interface elements
UTILITYShared helpers, configuration, logging
INTEGRATIONExternal service adapters

Annotation Tags

TagPurpose
<fn-name>Public function in the module's external contract
<type-Name>Public type/interface exposed by the module
<class-Name>Public class in the module interface
<export-name>Public named export (constants, config objects)
<const-NAME>Public constant

Do not mirror every private helper from the source file into <annotations>. Private orchestration helpers, local-only utility functions, and implementation-only types stay in the module file header and local contracts.

Links

Links between modules are expressed as direct child tags:

<M-CONFIG>
  <Summary>Config management</Summary>
  <M-DB />   <!-- M-CONFIG links to M-DB -->
</M-CONFIG>

Verification References

The .grace/verification/ directory provides matching V-M-* entries. The verification reference is mechanically derivable from the module ID by replacing the leading M- with V-M-.

This keeps navigation and proof linked:

  • the graph answers where the module lives and what it depends on
  • the verification plan answers how the module proves correctness

Maintenance Rules

  1. Always current — when you add a module, add it to the graph. When you add a dependency, link it. Never let the graph drift from reality.
  2. Scan on doubt — if unsure whether the graph is current, run $grace-refresh to scan and sync.
  3. Version tracking — increment the graph index when the graph changes structurally (new modules, removed modules).
  4. Annotations match the public interface — if a module's public exports change, update its <annotations> section.
  5. Verification refs stay valid — if a module's verification entry changes ID, update its graph document.
  6. No orphans — if a module is deleted, remove its graph entry and all links referencing it.

Semantic Markup Convention

Semantic markup in GRACE serves dual purpose: navigation anchors for RAG agents and attention anchors for LLM context management. Markers are not comments - they are load-bearing structure.

Module Level (top of each file)

Every important source file must begin with:

// FILE: path/to/file.ext
// VERSION: 1.0.0
// START_MODULE_CONTRACT
//   PURPOSE: [What this module does - one sentence]
//   SCOPE: [What operations are included]
//   DEPENDS: [List of module dependencies]
//   LINKS: [References to knowledge graph nodes]
//   ROLE: [Optional: RUNTIME | TEST | BARREL | CONFIG | TYPES | SCRIPT]
//   MAP_MODE: [Optional: EXPORTS | LOCALS | SUMMARY | NONE]
// END_MODULE_CONTRACT
//
// START_MODULE_MAP
//   exportedSymbol - one-line description
// END_MODULE_MAP

Adapt comment syntax to the project language (# for Python, // for Dart/Go/TS/Java, -- for SQL). Marker grammar is strict: canonical marker tokens and field labels must appear at the start of the normalized comment payload, not inside prose, strings, or unrelated code.

The CLI bundles TypeScript/JavaScript analysis and can enforce exact compiler-derived export parity there. Governed Python and Dart files use runtime-backed adapters and therefore require python3/python or dart on PATH. Python exports are exact when the source declares a static __all__, including Unicode identifiers; otherwise Python analysis emits analysis.heuristic-confidence. A missing runtime fails closed with actionable analysis.runtime-missing; a present adapter that fails emits analysis.adapter-failed. Neither diagnostic can count as parity success.

Substantial test files should use the same structure when tests are the fastest way for future agents to understand behavior, fixtures, and expected evidence.

Optional lint-specific fields:

  • ROLE tells grace lint what kind of governed file this is.
  • MAP_MODE tells grace lint how to interpret MODULE_MAP.

Recommended defaults:

  • RUNTIME + EXPORTS for normal source modules
  • TEST + LOCALS for substantial test files
  • BARREL + SUMMARY for re-export aggregators
  • CONFIG + NONE for tool or build configuration files
  • TYPES + EXPORTS for pure type/interface modules
  • SCRIPT + LOCALS for CLI/bootstrap/smoke scripts

Shared-docs boundary rule:

  • .grace/graph/* and .grace/verification/* should describe only the module's public contract and public interface
  • internal helpers, private types, and implementation-only orchestration belong in the file header markup and local function contracts instead of shared XML artifacts

Canonical grep-stable naming rule:

  • keep module IDs in exact uppercase kebab form: M-AUTH, M-USER-STORE
  • keep verification IDs in exact derived form: V-M-AUTH, V-M-USER-STORE
  • keep field labels exact; do not rename PURPOSE, SCOPE, DEPENDS, LINKS, INPUTS, OUTPUTS, or SIDE_EFFECTS
  • keep block names uppercase snake after the prefix: START_BLOCK_VALIDATE_INPUT
  • prefer exact IDs and canonical annotation tags inside LINKS:: M-*, V-M-*, fn-*, type-*, class-*, export-*, const-*
  • avoid prose-only references when an exact anchor can be emitted instead

Function or Component Level

Every exported function or component must have a contract placed before function signature and docstrings/comments:

// START_CONTRACT: functionName
//   PURPOSE: [What it does]
//   INPUTS: { paramName: Type - description }
//   OUTPUTS: { ReturnType - description }
//   SIDE_EFFECTS: [What external state it modifies]
//   LINKS: [Related modules/functions via knowledge graph]
// END_CONTRACT: functionName

Code Block Level (inside functions)

// START_BLOCK_VALIDATE_INPUT
// ... code ...
// END_BLOCK_VALIDATE_INPUT

Change Tracking

// START_CHANGE_SUMMARY
//   LAST_CHANGE: [v1.2.0 - What changed and why]
// END_CHANGE_SUMMARY

Granularity Rules

  1. Around 500 tokens per block. Too large and the model loses locality. Too small and the markup becomes noise.
  2. Block names must be canonical uppercase snake identifiers and unique inside the file.
  3. Every START_BLOCK_X must have a matching exact END_BLOCK_X; orphan, crossed, malformed, or mismatched markers are integrity errors.
  4. Block names describe WHAT, not HOW.

Logging Convention

All important logs should reference semantic blocks for traceability:

logger.info(`[ModuleName][functionName][BLOCK_NAME] message`, {
  correlationId,
  stableField: value,
});

This creates a direct link from runtime logs to source code blocks.

Test and Trace Guidance

When a path is critical enough to verify, make the test and the logs meet in the middle:

  • production code emits stable [Module][function][BLOCK_NAME] markers
  • tests assert deterministic outcomes first
  • tests assert markers or trace order when trajectory matters
  • verification docs record which markers are required

Example:

expect(hasLogMarker("info", "[ChatDomain][createChat][BLOCK_INSERT_CHAT]")).toBe(true);

Rules

  1. Never remove semantic markup anchors casually.
  2. When editing code, preserve block boundaries unless the edit truly requires restructuring.
  3. If a block grows beyond the working window, split it into sub-blocks.
  4. If you rename a block, update all log references and related verification entries.
  5. MODULE_MAP must match the file's lint mode:
    • EXPORTS => reflect public exports
    • LOCALS => reflect important local helpers, fixtures, or entry points
    • SUMMARY => summarize grouped surfaces without enumerating every symbol
    • NONE => omit MODULE_MAP when the file role truly does not need one
  6. Shared XML artifacts should never mirror the whole file header mechanically. Only public module-facing contract and interface details belong there.
  7. Do not invent alternate field names or ID prefixes if an exact canonical GRACE anchor already exists.

Unique Tag Convention

In .grace/*.xml files, every repeated entity must use its unique ID as the XML tag name instead of a generic type tag with an ID attribute.

The Problem: Closing-Tag Polysemy

<!-- BAD: Multiple </Module> closings — LLM loses track of what's being closed -->
<Module ID="M-CONFIG">
  ...
</Module>
<Module ID="M-DB">
  ...
</Module>
<Module ID="M-AUTH">
  ...
</Module>

When an LLM sees </Module>, it has to backtrack to figure out WHICH module is being closed. With many modules, this causes attention errors.

The Solution: Semantic Accumulators

<!-- GOOD: Each closing tag carries the full identity of the entity -->
<M-CONFIG NAME="Config" TYPE="UTILITY">
  ...
</M-CONFIG>
<M-DB NAME="Database" TYPE="DATA_LAYER">
  ...
</M-DB>
<M-AUTH NAME="Authentication" TYPE="CORE_LOGIC">
  ...
</M-AUTH>

A tag with a unique name is a semantic anchor. </M-CONFIG> is unambiguous — the closing tag carries the full identity of the entity.

Tag Naming Conventions

Entity typeAnti-patternCorrect (unique tags)
Module<Module ID="M-CONFIG">...</Module><M-CONFIG NAME="Config" TYPE="UTILITY">...</M-CONFIG>
Phase<Phase number="1">...</Phase><Phase-1 name="Foundation">...</Phase-1>
Flow<Flow ID="DF-SEARCH">...</Flow><DF-SEARCH NAME="...">...</DF-SEARCH>
UseCase<UseCase ID="UC-001">...</UseCase><UC-001>...</UC-001>
Step<step order="1">...</step><step-1>...</step-1>
Group<group name="Database">...</group><group-Database>...</group-Database>
Export<export name="config" .../><export-config .../>
Function<function name="search" .../><fn-search .../>
Type<type name="SearchResult" .../><type-SearchResult .../>
Class<class name="Error" .../><class-Error .../>
Schema<schema name="Input" .../><schema-Input .../>
Table<table name="messages" .../><table-messages .../>
Index<index name="fts" .../><index-fts .../>
Column<column name="id" .../><col-id .../>
Command<command name="/start" .../><cmd-start .../>
Handler<handler name="doc" .../><handler-doc .../>
Constant<constant name="X" .../><const-X .../>
Route<route path="/api" .../><route-api .../>
File<file name="Dockerfile" .../><file-Dockerfile .../>
Rule<rule>text</rule><rule-errors>text</rule-errors>

What NOT to Change

  • CrossLinks — self-closing (<CrossLink ... />), no nesting, no polysemy problem
  • Structural wrappers that appear once per parent: <annotations>, <interface>, <contract>, <inputs>, <outputs>, <errors>, <notes>, <purpose>, <path>, <depends>
  • Code-level markup (// START_BLOCK_... / // END_BLOCK_...) — already uses unique names, stays as-is

Why This Works

Research on LLM attention patterns shows that unique tokens serve as "accumulators" — they collect and carry meaning through the context window. A unique closing tag like </M-CONFIG> doesn't just mark the end of a block; it re-activates all the semantic associations built up since <M-CONFIG> was opened. Generic </Module> tags force the LLM to resolve ambiguity, wasting attention capacity.

Verification-Driven Development

In GRACE, verification is not an afterthought. It is a maintained architectural artifact.

Core Idea

.grace/verification/ answers the question:

"How will another agent prove that this module or flow is still correct?"

That proof has three layers:

  1. deterministic assertions for exact outcomes
  2. trace or log assertions for execution trajectory
  3. phase-level or integration checks for merged surfaces

For longer autonomous runs, verification is also an autonomy gate. It must prove that another agent can continue or debug from the visible evidence instead of from hidden reasoning.

Verification Plan Structure

The .grace/verification/ directory holds one or more VD-* verification documents. Each VD-* document wraps V-M-* entries. The index.xml maps VD-* routes to their document paths.

Each V-M-* entry may contain:

  • <Cwd> - one contained project-relative command working directory
  • <TestFiles><File>...</File></TestFiles> - exact project-root-relative test paths
  • <Command> - module-local verification command
  • <Scenario> - named success or failure behavior
  • <Marker> - required log markers for trace assertions

Module Verification Entry

Example:

<V-M-CHATS>
  <Cwd>apps/server</Cwd>
  <TestFiles>
    <File>apps/server/src/chat/index.test.ts</File>
  </TestFiles>
  <Command>bun test src/chat/index.test.ts</Command>
  <Scenario>Generated title is assigned only when the chat is still untitled.</Scenario>
  <Scenario>Ownership failure rejects the mutation.</Scenario>
  <Marker>[ChatDomain][setGeneratedTitleIfEmpty][BLOCK_ASSIGN_GENERATED_TITLE]</Marker>
</V-M-CHATS>

Log-Driven Development

Logs are evidence, not decoration.

Good GRACE logs are:

  • tied to semantic blocks
  • structured with stable fields
  • safe to retain and inspect
  • precise enough that a future agent can navigate back to the source block or the failing scenario

Example:

logger.info("[ChatDomain][createChat][BLOCK_INSERT_CHAT] Chat created", {
  chatId,
  userId,
  correlationId,
});

Test Design Rules

  1. Deterministic assertions first.
  2. Add trace or log assertions when a plain return-value check is not enough.
  3. Keep module-local tests close to the module when practical.
  4. Use narrow fakes and stubs rather than giant opaque mocks.
  5. If a bug escaped, strengthen the nearby verification entry and tests before closing the loop.

Execution Levels

  • Module level: fast checks that a worker can run alone
  • Wave level: checks for only the merged surfaces touched in the wave
  • Phase level: broader regression and integrity gates

Execution packets in grace-execute should reuse these levels instead of inventing new checks ad hoc.

Plan assertions use distinct evidence moments: current is the active-baseline preflight and is expected only before observed writes, selected baseline must pass immediately before edits, selected target proves the post-edit state, and selected final is the outer apply/archive gate. MustPassCommand is deliberately opt-in through --run-commands and contains leaf project evidence only; nesting grace lint, grace status, or another GRACE lifecycle command inside it is invalid.

Autonomy Gate

Before sending a module to a longer autonomous run, check:

  1. a V-M-xxx entry exists for the module
  2. at least one module-local command exists
  3. success and failure scenarios are named
  4. required log markers or trace assertions make divergence observable
  5. wave-level or phase-level follow-up is named when module-local checks are not enough
  6. the GraceChangePlan scope defines DurableScope and ObservedWriteScope

Failure Packets

When verification fails, capture:

  • scenario that failed
  • expected evidence
  • observed evidence
  • first divergent function or block
  • next suggested action

This makes grace-fix faster and less lossy.

GRACE 4 Migration Checklist

Before Writing .grace

  • Every legacy source path is inventoried with its intended GRACE 4 destination or an explicit unsupported/omitted reason.
  • A restorable backup exists at a recorded path outside the cleanup set.
  • Backup verification evidence and timestamp are recorded.
  • Ambiguities and unsupported legacy structures are listed.
  • No retroactive C-* bundles are proposed.
  • The user explicitly approved writing the reviewed .grace artifacts.

After Writing .grace

  • Generated .grace/context artifacts and source coverage were reviewed.
  • Generated graph index, routed graph documents, and projection coverage were reviewed.
  • Generated verification index, routed verification documents, and projection coverage were reviewed.
  • grace lint --path <project-root> --assertions current passed and the exit state is recorded.
  • grace status --path <project-root> --json reports projectKind grace4, no integrity errors, and its exit state is recorded.
  • Any failed or incomplete gate stopped cleanup while preserving legacy sources.

Before Legacy Cleanup

  • The cleanup proposal lists exact inventoried paths and actions; it contains no broad glob or unreviewed recursive deletion.
  • The restorable backup remains available and is not included in cleanup.
  • Git availability and project worktree membership were recorded.
  • For a git worktree, git status --porcelain --untracked-files=all output was recorded before cleanup.
  • The user separately and explicitly approved the exact cleanup proposal.
  • A dirty worktree or non-git project has a second explicit acknowledgement naming that risk.
  • Each archive/delete action and result will be recorded in the migration report.
  • Any cleanup failure stops immediately, preserves remaining legacy files, and is never retried automatically.

You are a GRACE contract reviewer. Your job is to verify that one module implementation matches its approved contract and preserves GRACE structure.

Review mindset

Do not trust the implementer's summary. Read the actual files.

Default to a scoped gate review: inspect only the changed files, the execution packet, and the graph delta proposal unless wider drift is suspected.

What to check

  • MODULE_CONTRACT matches the contract in the execution packet or approved plan
  • MODULE_MAP matches real exports
  • Imports match DEPENDS
  • Function contracts match signatures and behavior
  • Semantic blocks are paired, unique, and purposeful
  • The implementation stayed inside the approved write scope
  • The graph delta proposal matches actual imports and exports
  • No architectural drift was introduced silently

Escalate to a full GRACE review when the local evidence suggests broader drift or shared-artifact inconsistency.

Output format

Either:

PASS - contract compliant, scope respected, and no escalation needed.

or:

FAIL - issues found:

  • Missing: [requirement] - [file:line]
  • Extra: [unrequested implementation] - [file:line]
  • Drift: [architectural or dependency mismatch] - [file:line]
  • Markup: [GRACE integrity issue] - [file:line]
  • Graph delta: [proposal mismatch] - [file:line]

Also include:

  • Escalation: no / yes - reason

Every issue must include a file and line reference.

You are a GRACE fixer. You take one failure packet and repair the assigned module without changing architecture silently.

Mission

  • Read the module contract or execution packet first
  • Read the failure packet
  • If the GraceChangePlan provides DurableScope and ObservedWriteScope, respect those boundaries
  • Navigate to the relevant function or semantic block
  • Apply the smallest correct fix inside the assigned write scope

Rules

  • Do not invent new modules
  • Do not rewrite the plan
  • Preserve semantic block boundaries unless the fix requires restructuring
  • Update CHANGE_SUMMARY after the fix
  • If behavior changed, update the local contract text that must stay in sync
  • If verification was weak, strengthen the related module-local tests or traces within scope
  • If test files, required markers, or commands changed, report the changes clearly
  • Rerun only the affected module-local verification unless the controller requests broader checks

If the real problem is architectural:

  • Stop
  • Report the contract mismatch
  • Ask the controller to revise the plan

If the local fix reveals broader drift:

  • say whether wave-level review or full GRACE review should be triggered

Report format

  1. Root cause addressed
  2. Files changed
  3. Module-local verification results
  4. Remaining risks or escalation needs

You are a GRACE module implementer. You implement exactly one planned module or one explicitly bounded module slice.

Mission

  • Accept the controller's execution packet as the primary source of truth
  • Read the assigned module contract, graph entry, dependency summaries, write scope, and verification excerpt from that packet
  • Read additional dependency contracts or local files only when the packet is insufficient
  • Generate or update code within the assigned write scope only
  • If the GraceChangePlan provides DurableScope and ObservedWriteScope, align your execution to those boundaries

Rules

Before starting:

  • If the contract, scope, or dependencies are unclear, stop and ask
  • Do not invent new modules or new architecture
  • Do not edit shared .grace artifacts directly
  • Do not reread the whole plan or graph if the execution packet already contains the required context

While implementing:

  • Preserve MODULE_CONTRACT, MODULE_MAP, CHANGE_SUMMARY, function contracts, and semantic blocks
  • Implement exactly what the module contract requires
  • Place START_CONTRACT/END_CONTRACT above both: function signature and docstrings/comments
  • Keep imports aligned with DEPENDS
  • Add or update module-local tests only
  • Keep logs traceable to [Module][function][BLOCK_NAME] where relevant
  • Preserve substantive test-file markup when present
  • Run module-local verification only unless the controller explicitly expands scope

If you discover architectural drift:

  • Stop
  • Report the gap clearly
  • Propose what the controller should revise

Before reporting back:

  • Self-review for completeness, discipline, and overbuilding
  • Run the required module-local verification commands
  • Prepare a scope delta proposal for the affected .grace/graph and .grace/verification changes
  • Note any integration assumptions that the controller must validate at wave level

When shared artifacts change, propose only public module-facing surface updates. Private helpers, internal types, and local orchestration details belong in the source file header and local contracts.

Report format

  1. Module implemented
  2. Files changed
  3. Module-local verification results
  4. Graph delta proposal
  5. Verification delta proposal
  6. Integration assumptions or blockers

You are a GRACE verification reviewer. Your job is to decide whether the module has strong enough automated verification for autonomous and multi-agent execution.

What to evaluate

  • Are the important module-local scenarios covered?
  • Are deterministic assertions used where they should be?
  • Are traces or logs checked when trajectory matters?
  • Do logs reference semantic blocks in a stable way?
  • Does the evidence match the module's verification-plan excerpt?
  • Are tests brittle, shallow, or overfit to one fixture?
  • Would another agent be able to debug a failure from the evidence left behind?
  • Which checks can stay module-local, and which must be deferred to wave-level or phase-level verification?

Review rules

  • Prefer deterministic asserts over fuzzy evaluation
  • Allow semantic trace checks only when exact equality is insufficient
  • Treat weak observability as a real verification defect
  • Do not accept verbose logs as a substitute for actionable traces
  • Default to gate decisions based on module-local evidence, then name any required wave-level or phase-level follow-up explicitly

Output format

Either:

PASS - module-local verification is acceptable for this gate.

or:

FAIL - verification gaps:

  • Missing scenario: [description] - [file:line]
  • Weak assertion: [description] - [file:line]
  • Weak telemetry: [description] - [file:line]
  • Debuggability gap: [description] - [file:line]

Also include:

  • required module-level follow-up tests
  • required wave-level follow-up checks
  • required phase-level follow-up checks
  • required telemetry or trace improvements

Sponsors

Details

Marketplace
osovv/grace-marketplace
Source
plugins/grace
Author
osovv
Category
Methodology
License
MIT
Keywords
grace, semantic-markup, knowledge-graph, contracts, ai-code-generation, log-driven-development, verification, llm-friendly