Syntax

Dual-Layer Architecture with JSON-canonical (v1.7+)

Human-Facing Form (input)

Natural, semi-structured text. Written in the human's own language. Free-form but follows recommended patterns. Allows entry from any convenient block.

AI-Facing Form (canonical, source of truth)

Canonical JSON conforming to a registered JSON Schema. This is the source of truth for AI agents, validation tooling, and versioning systems. Human-facing rendering (texts, tables, diagrams) is auto-generated from JSON by viewers.

6 formal requirements for AI-facing form: canonicality, unambiguity, normalizability, validatability, typing, versionability.

8 sections of canonical AI-facing form (v1.8)

Core Definition - Intent, Object, Constraints, Expected Output

Supporting Context - Context, Value (structured list of items with priority), Actors, Evidence (may reference Knowledge Cards), Metrics

Development Layer - Conception, Vision, States, Transitions, Signals, Risks, Open Questions

Readiness Layer - Current Lifecycle State, Critical Gaps, Unknown Yet Items, Realization Decision

Composition (introduced in v1.8) - role, parent, contains, depth; hierarchical intenture structure

Knowledge Cards - External structured knowledge entities linked via informed_by

Linked Intenture - Inter-intenture relations (graph, separate from Composition)

Linked Artifacts - References to external documents

Intent Vocabulary (8 Verbs)

Not a rigid enum but guidance - each verb implies a different realization strategy.

Constraint Types (8 Types) with Inheritance Pattern (v1.8)

Rule: a conflict with a [safety] or [legal] Constraint is always resolved in favor of the Constraint. Conflicts with other types are resolved through dialogue with the human.

Inheritance Pattern governs constraint behavior under hierarchical intenture composition (see Composition Hierarchy chapter):

• Inherit & Restrict - constraint inherits as baseline; child may only tighten. Override (replacement) allowed only for [quality] and [coordination] with explicit rationale and approval.
• Pool & Allocate - constraint is a shared resource at parent; children get allocated shares via allocated_from. Sum(child allocations) ≤ parent total.

Structured Constraint Format

Constraint types [budget], [timeline], and [resource] support an optional structured format. The text description remains mandatory. Structured fields are added below the description with indentation.

Budget Constraint

- [budget] description of financial constraint
  amount: numeric value
  currency: currency code (USD, EUR, etc.)
  period: total | monthly | quarterly | yearly
  flexibility: none | +N% | negotiable

Timeline Constraint

- [timeline] description of time constraint
  deadline: YYYY-MM-DD
  type: hard | soft
  flexibility: none | +N days | +N weeks | negotiable

Resource Constraint

- [resource] description of resource constraint
  type: people | infrastructure | tools | licenses
  quantity: numeric value or description
  availability: description of availability

Rules

Structured fields are optional. The text format - [budget] total budget $5000 remains valid.

Types [safety], [legal], [quality], [coordination], [scope] remain text-only - they do not need structured format.

Vergil may suggest the human formalize budget and timeline constraints but is not required to demand it.

When structured fields are present, AI can automatically track budget spending and deadline compliance.

Evidence Markers

• [fact] - Verified information
• [to-collect] - Needs to be gathered
• [assumed] - AI or human assumption, needs confirmation

Information Source Tags (v1.6+)

Extended tag set for marking each significant JSON field. Applies in Canvas blocks and Knowledge Card fields alike.

Value Structure (v1.8)

Starting from v1.8 Value is represented as a list of structured items (previously a single string). Required for hierarchical parent-child Value comparison, prioritization, and coverage checking.

Value:
  - id: v1
    description: "Value description"
    priority: must-have | should-have | nice-to-have
    beneficiary:
      - actor:end-customer
      - "the user community"
    measurement: "How we know it's delivered"
    status: Answered | ...
    tags: [fact | hypothesis:human | ...]
    delivered_by: self | children
    contributes_to_parent_value:
      - parent_id: ai-agents
        parent_value_id: v1

Rules:

• Priority: 3-level schema (must-have / should-have / nice-to-have)
• Backward-compatibility: single string remains valid sugar (normalizes to one item with default priority)
• Child Value items must have at least one contributes_to_parent_value OR local_only: true with rationale
• Coverage gate: parent cannot reach Realizable if any must-have Value is uncovered
• delivered_by: self allows parent to have integrative Value that doesn't decompose to children

Signal Format

Signal: [type: severity] - description
  type = operational | quality | safety | feedback
  severity = info | warning | critical

JSON-canonical envelope (v1.7+, extended in v1.8)

Each JSON artifact must contain envelope fields:

$schema: URI of canonical JSON Schema
artifact_type: Intenture | Canvas | ObjectCard | KnowledgeCard | ExplicationRecord
schema_version: semver (language Schema version)
artifact_version: semver (content version)
uuid: UUIDv7 (immutable identity, v1.8)
id: slug within namespace (mutable, v1.8)
namespace: project scope (v1.8)
display_name: cosmetic label (v1.8)
metadata: { created, updated, author, last_updated_by, status, sources_used, change_log }

Three-tier Addressing (v1.8)

For cross-references between intentures:

Tier 1: UUID (immutable) - UUIDv7, generated at creation, never changes. Used by tooling for absolute identification. Tier 2: Slug (mutable) - lowercase alphanumeric + dash, max 64 chars, unique within namespace. Used in most references by default. Can be renamed with redirect history in namespace. Tier 3: Display name - cosmetic, no uniqueness constraints, only for UI.

Cross-references use slug + namespace + UUID as fallback during rename.

Identity Operations (v1.8)

Beyond content version bumps, intenture may undergo identity operations: