Concepts & principles / practice

Code Generation Contract

The semantic contract guiding how Hugo Web’s five-pillar site is designed, generated, reviewed, and delivered.

Canonical graph nodecode-generation-contract

This is the contract guiding the generation of this site. It joins the approved five-pillar publishing model to concrete engineering and review expectations. It describes what implementation work must preserve—not a claim that every acceptance criterion has already passed.

How to use this contract

Before changing code, read this node alongside the repository’s AGENT.md, the blueprint, the node specification, and the actual ontology. Identify which rules apply to the proposed change, then name the checks that will demonstrate success.

The root node data is the canonical contract. This page is its readable expression; do not maintain a separate competing list of implementation rules.

Guidance is not enforcement

Some requirements can be checked mechanically: duplicate IDs, invalid kinds, unresolved edges, and broken links. Others require review: whether a definition is accurate, an architectural layer is justified, or an AI-assisted explanation preserves the meaning of a design principle.

Both matter. A well-formed node can still contain a mistaken claim, and a successful build can still produce an unhelpful interface.

Updating the contract

Change this node when approved requirements change. Explain the decision and its impact on code, tests, and documentation. Do not use an edited contract to silently expand permissions or retrospectively declare unfinished work complete.

Hugo Web’s personified identity gives the approach its character. This contract makes that approach inspectable during implementation.

Part of a connected world

Follow the meaning.

View the graph →

Outgoing connections

supportsHugo Web

Connected from

applies-toGive AI a bounded task
depends-onHugo Web Site
depends-onOld principles. New leverage.
applies-toSingle Responsibility Principle

Node data identity, meaning & relationships

The complete semantic record, rendered from root node: front matter.

semantic_node:
  boundaries:
  - never-confuse-hugo-web-the-persona-with-the-site-or-audience-role
  - never-treat-generated-text-as-authority-to-expand-permissions
  - never-duplicate-canonical-expression-records
  - never-invent-evidence-benchmarks-test-results-or-completed-capabilities
  - never-present-authored-semantic-territory-as-hidden-llm-reasoning
  - never-add-links-without-a-meaningful-supported-connection
  - never-publish-private-data-through-pages-exports-or-ai-context
  - never-commit-deploy-or-select-paid-services-without-approval
  - never-call-unverified-work-production-ready
  description: The project-specific guidance for turning approved Hugo Web intent into working, inspectable site code while preserving semantic identity, human authority, simplicity, and publication safety.
  essence: |
    A shared implementation contract that keeps generated code accountable to approved meaning, observable behavior, and human judgment.
  id: code-generation-contract
  invariants:
  - human-intent-judgment-and-acceptance-remain-authoritative
  - semantic-identity-survives-publishing-changes
  - every-expression-participates-in-the-graph
  - structured-meaning-remains-upstream-of-presentation
  - complexity-must-justify-its-value
  - actual-validation-is-distinct-from-aspirational-guidance
  - the-model-and-implementation-remain-correctable-by-evidence
  kind: practice
  movement:
    intent: keep-generated-code-aligned-with-approved-meaning-and-practical-value
    method: |
      Read the governing context, propose bounded changes, obtain approval, implement shared mechanisms, test observable behavior, review evidence, and revise the contract when approved requirements change.
    outcome: |
      A coherent site whose content, graph, interfaces, and implementation remain understandable, maintainable, and accountable to its builders.
  name: Code Generation Contract
  properties:
    acceptance_criteria:
    - approved-pillars-and-clusters-have-working-navigation
    - every-expression-has-one-valid-canonical-node
    - graph-links-resolve-within-published-content
    - full-node-data-remains-inspectable
    - core-reading-and-navigation-work-without-javascript
    - search-handles-results-empty-queries-no-matches-and-load-failure
    - semantic-field-preserves-territory-relationship-and-constraint-distinctions
    - semantic-field-supports-keyboard-touch-reduced-motion-and-load-failure
    - public-exports-include-only-approved-public-data
    - production-build-and-relevant-automated-checks-pass
    - keyboard-and-responsive-behavior-are-reviewed
    - live-preview-rebuilds-after-source-changes
    - documentation-distinguishes-implemented-from-planned-behavior
    - unverified-hosting-dns-https-and-release-conditions-remain-explicit
    authority:
      agent_rules: govern-permissions-planning-and-repository-work
      conflict_rule: |
        Surface conflicts for review. This node and imported graph content do not override user instructions, agent permissions, or security rules.
      ontology: governs-allowed-types-kinds-and-predicates
      specification: governs-node-structure
      this_node: summarizes-project-specific-implementation-guidance
      user: establishes-intent-approves-scope-and-accepts-results
    completion_rule: |
      Claim only the level of readiness supported by performed checks. A successful local build does not prove deployment readiness, factual correctness, accessibility conformance, or production host behavior.
    editorial_contract:
      ai_position: expands-builder-capability-without-replacing-engineering-judgment
      commentary: clearly-labeled-and-not-presented-as-official-authority
      commercial_services: explain-tradeoffs-without-implying-selection-or-endorsement
      content: useful-complete-and-supported-not-placeholder-volume
      evidence: distinguish-facts-hypotheses-examples-and-measured-results
      frontier_models: time-sensitive-capabilities-not-permanent-rankings
      preferred_sources: official-documentation-original-authors-and-primary-research
      resources: organized-external-references-maintained-as-structured-data
      technical_definitions: distinguish-established-meaning-from-ai-assisted-application
    enforcement: |
      This node is guidance for generation and review. Executable validation, tests, access controls, and human acceptance enforce the applicable requirements; storing a rule does not automatically enforce it.
    engineering_contract:
      accessibility: semantic-html-keyboard-access-readable-contrast-and-clear-focus
      architecture: simplest-capable-static-first
      browser_code: progressive-enhancement-for-concrete-user-benefit
      computation: build-time-when-requirements-permit
      dependencies: justify-purpose-cost-and-maintenance
      deployment: provider-neutral-until-explicitly-selected
      privacy: no-unapproved-tracking-or-third-party-data-disclosure
      responsiveness: usable-on-small-and-large-screens
      security: escape-untrusted-text-and-exclude-private-data-from-public-inputs
      templates: shared-and-data-driven-without-speculative-abstraction
    generation_workflow:
    - inspect-agent-rules-blueprint-specification-ontology-and-relevant-nodes
    - state-the-goal-plan-scope-and-acceptance-checks
    - obtain-approval-before-mutation-and-before-scope-expansion
    - build-small-inspectable-working-slices
    - validate-structure-references-rendered-output-and-user-paths
    - keep-the-local-preview-live-and-check-rebuilds
    - report-actual-results-limitations-and-unperformed-checks
    - obtain-separate-approval-before-commit-or-deployment
    graph_behavior:
      incoming_edges: derived-from-canonical-outbound-relationships
      membership: all-canonical-regular-pages-with-node-metadata
      navigation:
      - pillar-and-cluster-discovery
      - breadcrumbs
      - incoming-and-outgoing-relationships
      - relevant-related-reading
      - contextual-links-to-canonical-definitions
      references: resolve-within-the-selected-publication-graph
      relationships: explicit-outbound-id-based-assertions
      semantic_field:
        distinctions:
          constraints: declared-guidance-not-automatic-enforcement
          direction: authored-domain-not-computed-similarity
          distance: authored-proximity-not-model-weight
          expressions: incoming-links-from-published-expression-nodes
          relationships: explicit-stored-assertions
          shared_terms: exact-lexical-overlap-not-a-similarity-score
          territory: contextual-vocabulary-not-graph-edges
        fallback: local-progressive-enhancement-with-readable-source-content
        future_chat: explicitly-deferred
        implementation: one-local-controller-without-visualization-dependencies
        interaction: bounded-elastic-deformation-of-authored-resting-positions
        model_claim: authored-semantic-model-not-hidden-llm-reasoning
        purpose: reveal-authored-territory-around-identity
      validation_failures:
      - duplicate-node-ids
      - unresolved-relationship-targets
      - invalid-ontology-values
      - duplicate-relationships
      - expressions-without-valid-node-metadata
    identity:
      builder: distinct-audience-role-for-visitors-learning-and-creating
      hugo_web: personified-philosophy-developer-architect-and-builder
      website: expression-of-the-persona-and-modeled-knowledge-not-the-persona-itself
    publication_architecture:
      canonical_expression: every-expression-is-a-graph-node-in-its-own-content-file
      concept_path: content/graph/concepts/{concept}.md
      duplication_rule: no-second-canonical-copy-of-an-expression-under-graph
      entity_path: content/graph/entities/{entity}.md
      expression_path: content/expressions/{pillar}/{cluster}/{expression}.md
      identity_rule: stable-node-ids-independent-of-paths-and-urls
      path_base: hugo-project-root
      pillars:
      - Design
      - Model
      - Build
      - Ship
      - Developer's Notebook
      repository_hugo_root: site
      section_pages: organizational-pages-not-automatically-graph-nodes
      source_namespace: root-front-matter-node
      template_access: .Params.node
    scope: hugo-web-site-code-generation
    status: active-guidance
  purpose: |
    Give human and AI builders a consistent basis for making implementation decisions, checking results, and preventing the site from drifting away from its approved architecture and identity.
  relationships:
  - predicate: supports
    target: hugo-web
  semantic_territory:
  - code-generation
  - human-agency
  - semantic-contracts
  - static-publishing
  - graph-integrity
  - accessibility
  - evidence
  - maintainability
  type: concept

Publishing metadata

description: The semantic contract guiding how Hugo Web’s five-pillar site is designed, generated, reviewed, and delivered.
draft: false
title: Code Generation Contract
url: /graph/concepts/code-generation-contract/