HNC v1.3 — Bidirectional Delivery Traceability & ZARA Knowledge Integration

1. Purpose

HNC v1.3 extends Hecate from architecture-to-build governance into a permanent, bidirectionally navigable delivery provenance system.

The governing lifecycle is:

Canonical Docusaurus MDX
        ↓
<JiraNeed />
        ↓
HNC Need + Jira instructions
        ↓
Jira human build authorization
        ↓
ArtifactImpactPlan + EngineeringWorkOrder
        ↓
zayaz-platform implementation
        ↓
delivery/<jira-key>/manifest.json
        ↓
PR + CI + ImplementationEvidence
        ↓
human release authorization
        ↓
AWS/runtime evidence

ZARA may traverse this chain in either direction but MUST preserve source authority.

2. Constitutional source hierarchy

The v1.3 knowledge system MUST preserve the ZAYAZ authority hierarchy:

1. Canonical Docusaurus documentation
2. Approved ADRs, schemas, contracts, registries and rulesets
3. HNC/Jira implementation intent and instructions
4. zayaz-platform implementation
5. CI and implementation evidence
6. deployed runtime evidence

Implementation behavior MUST NOT silently overwrite canonical architecture. Divergence is an auditable condition requiring remediation or an approved canonical change.

3. Branch convention

New Hecate engineering branches MUST use:

hecate/<jira-key>

Example:

hecate/ZYZ-974

The branch name is a human-navigation aid, not a trusted provenance mechanism. Canonical document ID, slug, title, section, commit and scope hash are carried in governed payloads and the ImplementationManifest.

Retries MAY use an operational suffix when technically required, but the Jira key remains the delivery identity.

4. Permanent delivery record

Permanent implementation code MUST remain organized by Module → Component → capability. Jira ticket folders MUST NOT become the source-code architecture.

Every governed implementation SHOULD produce:

zayaz-platform/
  delivery/
    <jira-key>/
      manifest.json

The manifest is the implementation-side provenance index joining canonical documentation, HNC/Jira work, implementation artifacts, tests, migrations, rulesets, CI evidence and runtime deployments.

5. Existing JiraNeed contract

The existing <JiraNeed /> contract remains authoritative for the documentation-side edge.

Example:

<JiraNeed
  type="Story"
  needId="AIIL-CON#18-the-standards-registry-s-relationship-to-the-dataset-registry#1"
  jiraKey="ZYZ-730"
  hecateJobId="1f4a8ffa-2320-480a-8b35-a7a798ab8e4d"
  zaraInstructions="true"
  assigneeId="..."
  headingUrl="https://specs.zayaz.io/...#18-the-standards-registrys-relationship-to-the-dataset-registry"
  sectionHeading="1.8. The Standards Registry relationship to the Dataset Registry"
/>

HNC v1.3 MUST extract this tag into explicit graph edges. Volatile implementation metadata such as PR numbers, CI runs and deployments MUST NOT be appended to the MDX tag; those belong to the ImplementationManifest and derived delivery index.

6. Delivery lifecycle

Delivery state is machine-derived from authoritative evidence, not manually maintained prose.

Canonical states are:

NEED_CREATED
IMPACT_RESOLVED
WAITING_BUILD_APPROVAL
BUILD_APPROVED
BUILD_EXECUTED
CI_VERIFIED
WAITING_RELEASE_APPROVAL
RELEASE_AUTHORIZED
DEPLOYED
RUNTIME_VERIFIED
BLOCKED
REMEDIATION_REQUIRED

Human actions authorize boundaries. Machines observe factual execution state.

Build approval and release approval MUST remain separate.

7. Jira governance projection

Jira SHOULD expose controlled fields for:

• HNC Need ID
• canonical document ID
• canonical heading URL
• canonical commit
• source-scope hash
• build authorization state, actor and timestamp
• derived delivery state
• implementation repository
• implementation branch
• pull request
• delivery manifest link
• CI/evidence link
• release authorization state
• deployment/runtime evidence link

A human-readable approval comment MAY accompany the controlled authorization field, but agents MUST react to governed structured state rather than parsing arbitrary prose.

8. ZARA governed knowledge planes

ZARA MUST index the delivery graph as distinct knowledge planes:

8.1 Canonical Knowledge Plane

Sources include MDX sections, structured tables, examples, schemas, contracts, registries, rulesets and ADRs.

Authority: canonical.

8.2 Delivery Intent Plane

Sources include Jira descriptions, HNC/ZARA Jira instructions, acceptance criteria, ImplementationPackets, ArtifactImpactPlans and EngineeringWorkOrders.

Authority: delivery intent; subordinate to canonical architecture.

8.3 Implementation Plane

Sources include zayaz-platform source, migrations, tests, rulesets, infrastructure code and delivery manifests.

Authority: implementation evidence; never canonical by itself.

8.4 Evidence & Runtime Plane

Sources include PRs, CI runs, ImplementationEvidence, deployment evidence and runtime verification.

Authority: factual execution/evidence.

These planes MAY use separate vector indexes or equivalent retrieval partitions. They MUST retain authority metadata and explicit graph identity.

9. ZARA knowledge objects

A ZARA knowledge object is a typed, versioned, provenance-bearing retrievable unit. Object types include:

• canonical_document
• canonical_section
• requirement
• table
• code_example
• jira_need
• jira_description
• jira_instructions
• implementation_packet
• artifact_impact_plan
• engineering_work_order
• implementation_manifest
• source_file
• migration
• ruleset
• test
• pull_request
• ci_run
• implementation_evidence
• deployment
• runtime_verification

Every object MUST retain its source plane, authority, stable identifier, source locator and version/commit where applicable.

10. ZARA knowledge edges

Relationships MUST be explicit when authoritative identifiers exist. Canonical edge types include:

DECLARES_NEED
IMPLEMENTS_REQUIREMENT
DERIVED_FROM
INSTRUCTED_BY
REALIZED_BY
TESTED_BY
MIGRATED_BY
GOVERNED_BY_RULESET
VALIDATED_BY
EVIDENCED_BY
DEPLOYED_AS
VERIFIED_AT_RUNTIME
SUPERSEDES
RELATES_TO

ZARA MAY suggest inferred relationships, but inferred edges MUST remain distinguishable from governed edges.

11. MDX authoring profile for migrated manual content

New or migrated Docusaurus pages SHOULD be optimized simultaneously for humans, HNC and ZARA.

Each canonical page MUST have stable id, title and slug. Material actionable sections SHOULD have stable heading anchors and SHOULD clearly separate requirements, invariants, data semantics, rules, interfaces, examples, failure semantics and validation requirements where applicable.

Tables MUST retain parent section identity and table semantics during indexing. Code blocks MUST retain language, parent section, example/prescriptive classification and canonical authority metadata.

The authoring profile MUST NOT force artificial headings where they reduce human readability; semantic typing is the goal, not template uniformity.

12. Semantic architecture auditing

ZARA SHOULD perform cross-plane consistency analysis and emit structured audit findings rather than silently synchronizing lower-authority sources upward.

Canonical finding classes include:

• DOCUMENTATION_IMPLEMENTATION_DIVERGENCE
• IMPLEMENTATION_REQUIREMENT_GAP
• JIRA_INSTRUCTION_OMISSION
• TEST_COVERAGE_GAP
• RULESET_IMPLEMENTATION_DRIFT
• MIGRATION_PERSISTENCE_DRIFT
• EVIDENCE_COVERAGE_GAP
• RUNTIME_IMPLEMENTATION_DRIFT
• ORPHAN_IMPLEMENTATION
• ORPHAN_JIRA_NEED
• BROKEN_TRACEABILITY_EDGE

A finding MUST identify the compared objects, authority relationship, evidence and recommended remediation route.

If implementation appears superior to current documentation, ZARA MUST NOT update canonical architecture merely to match code. It SHOULD propose either implementation remediation or an explicit canonical architecture change.

13. Atlas delivery index

atlas.zayaz.io SHOULD expose a searchable administrative delivery index derived from governed manifests and synchronized Jira/HNC state.

Search SHOULD support Jira key, HNC Need ID, Hecate Job ID, canonical document ID, title, slug, section heading, Module, Component, source path, implementation path, schema, ruleset, migration, PR, commit and CI run.

The Atlas index is a projection, not the source of truth.

14. ImplementationManifest invariants

An ImplementationManifest MUST:

1. identify exactly one Jira delivery identity;
2. retain canonical document ID, slug, title, section/heading URL, commit and scope hash;
3. retain HNC Need and Hecate Job identity where available;
4. identify the implementation repository and branch;
5. enumerate implemented files by artifact role;
6. retain PR/commit and CI/evidence references;
7. preserve release/deployment attempts historically rather than overwriting them;
8. never assert runtime deployment without governed deployment evidence;
9. remain machine-validatable and indexable by ZARA/Atlas.

15. Requirements-to-runtime graph

HNC delivery lineage may originate from internal architecture, client requirements, methodology, standard or regulation. Where Pergamum Pulse supplies regulatory/framework lineage, the graph becomes:

Regulation / Standard
      ↓
Pergamum Pulse requirement
      ↓
Canonical ZAYAZ requirement
      ↓
MDX section
      ↓
JiraNeed
      ↓
HNC/Jira delivery
      ↓
ImplementationManifest
      ↓
source + migration + ruleset + tests
      ↓
CI / evidence
      ↓
runtime

Pergamum Pulse is not limited to regulation; it preserves authoritative requirement lineage. HNC preserves delivery lineage. ZARA traverses both.

16. v1.3 machine contracts

HNC v1.3 introduces:

• ImplementationManifest
• DeliveryLifecycle
• ZARAKnowledgeObject
• ZARAKnowledgeEdge
• SemanticArchitectureAudit
• DocusaurusAuthoringProfile
• AtlasDeliveryIndex

The first implementation reference is Jira ZYZ-974, the EPU ExternalAlias governed live smoke test.