5 · Knowledge Layer: Claims, Constraints, Decisions

This is the crux of AgentMark. Naive notes mix three different categories of statement: "Claude Code cannot be used because of usage rules" (constraint); "GLM is cheapest" (claim); "Claude Code is best for MCP" (claim). These are not the same thing and must be modeled differently. The three first-class knowledge types are constraint, claim, and decision — plus the supporting concepts of assertion, confidence, and source.

Constraint — something that limits the design. Uses RFC 2119 requirement levels (MUST, MUST_NOT, SHOULD, SHOULD_NOT, MAY):

constraint K-001:
  title: Claude Code backend usage restriction
  level: MUST_NOT
  applies_to: [harness#claude_code: Claude Code]
  action: use_as_backend_harness
  scope: Hermes
  basis: usage_rules
  source: user_interpretation
  confidence: medium
  as_of: 2026-06-02
  review_by: 2026-06-16

Claim — something believed true at a point in time. Carries kind, subjects, metric, scope, evidence, confidence, volatility, and review dates. It is the unit that expires.

claim C-001:
  text: Claude Code is strongest among tested harnesses for MCP-heavy coding workflow
  kind: comparative
  subjects: [Claude Code, Codex, GLM, Qwen Coder]
  metric: mcp_connection_reliability
  scope: Hermes coding-agent tests
  evidence: [test#MCP-SMOKE-2026-06]
  confidence: medium
  volatility: high
  as_of: 2026-06-02
  review_by: 2026-06-16

Claim kinds seen in practice: comparative, substitution, cost, capability, provider_market.

Decision — what you chose, given constraints and claims. Borrows the spirit of ADRs (context + consequences) but links directly to the claims and constraints that justify it — and to the conditions that would invalidate it.

decision D-001:
  title: Use Codex as Hermes cost-optimized coding harness
  status: accepted
  chosen: [harness#codex: Codex]
  alternatives: [Claude Code, GLM, Opus, Qwen Coder]
  drivers: [cost, coding_quality, backend_harness_allowed]
  constrained_by: [K-001]
  supported_by: [C-002, C-003]
  consequences:
    - weaker MCP ergonomics than Claude Code
    - better backend suitability under current constraints
  as_of: 2026-06-02
  review_by: 2026-06-16

Assertion, confidence, and sources. Never treat all claims equally. Every assertion carries a confidence level and its sources.

assert: Qwen weaker MCP compatibility
  confidence: medium
  sources: [internal testing]

assert: MCP introduced by Anthropic
  confidence: very_high
  sources: [Anthropic MCP announcement]

Confidence levels in use: low, medium, high, very_high.

Why the split matters: Separating the three lets the document answer questions a flat diagram cannot: Which decisions rest on which claims? Which claims are about to expire? If a constraint flips, which decisions fall? That dependency graph is what makes AgentMark a living contract rather than a snapshot.