HNC
Hecate Jira Mapping Contract
1. Purpose
This contract defines how HNC v1.1 projects a governed Implementation Packet into Jira without turning Jira into a duplicate architecture database.
The governing boundary is:
ZAYAZ Docs defines truth. Jira defines work.
Jira SHALL remain readable to humans while retaining enough machine references for AI engineering, validation and requirements-to-runtime traceability.
2. Storage strategy
HNC SHALL use four Jira surfaces for different purposes:
| Jira surface | Purpose |
|---|---|
| Visible fields | Human work management: summary, issue type, parent, assignee, labels and rendered instructions |
| Existing custom fields | Stable navigation/identity: Need ID, Spec ID and Spec URL |
| Issue properties | Compact machine metadata and hashes; not human prose |
| Web links | Clickable canonical Docusaurus navigation |
The full Implementation Packet, Validation Plan and Agent Context Pack SHALL remain governed HNC artifacts and SHALL NOT be copied wholesale into Jira fields or Description.
3. Existing Jira compatibility
The existing Hecate sync already resolves Jira fields by name and uses Need ID, Spec ID and Spec URL. HNC v1.1 reuses these before introducing any new custom fields.
The existing ZARA issue property zara.instructions.meta remains owned by ZARA. HNC adds a separate property:
hnc.delivery.meta
The two properties SHALL NOT overwrite each other.
4. Description contract
Jira Description is a human implementation surface, not a machine payload store.
The rendered ZARA/Hecate instruction body SHALL contain:
Objective
Context
Scope of Work
Functional Requirements
Constraints (Non-Functional)
Acceptance Criteria
Out of Scope
Needs Clarification # only when present
The Description SHALL NOT contain:
- raw Implementation Packet JSON;
- raw Validation Plan JSON;
- raw Agent Context Pack JSON;
- canonical Docusaurus URLs embedded in generated instruction prose;
- invented implementation details not supported by canonical scope.
Canonical URLs belong in Jira web links and existing navigation fields.
5. Issue-type compatibility mapping
The current Hecate Need types map to Jira as follows:
| Hecate Need type | Jira issue type |
|---|---|
| Task | Task |
| Story | Story |
| Bug | Bug |
| Spike | Task |
| Validation | Task |
| Epic | Epic |
Spike and Validation retain their semantic distinction through labels (need:spike, need:validation) even where Jira uses the generic Task issue type.
6. HNC delivery property
hnc.delivery.meta stores compact machine metadata only:
schema_version:
need_id:
implementation_packet_ref:
implementation_packet_hash:
canonical_source_commit:
source_scope_hash:
validation_plan_ref:
validation_plan_hash:
agent_context_pack_ref:
agent_context_pack_hash:
implementation_repository:
autonomy_level:
blast_radius_level:
blocking_clarifications:
This enables deterministic correlation without making Jira authoritative for packet content.
7. Labels
HNC v1.1 SHOULD derive low-cardinality labels such as:
need
need:<type>
spec
hecate
hnc-v1-1
module:<module-id>
component:<component-id>
blast:<level>
agent:<autonomy-level>
Labels are routing/search hints, not contract authorities.
8. Parent/Epic mapping
Where the selected canonical specification contains a Jira Epic reference, HNC SHOULD use that Epic as the parent for implementation work when Jira hierarchy permits it.
If no parent can be resolved, Hecate may create draft work but SHALL retain the unresolved relationship as a clarification when parentage is required by governance.
9. Field discovery
HNC SHALL prefer field-name discovery with optional deployment-specific ID overrides.
This preserves portability across Jira configurations while allowing stable overrides where Jira field IDs are known.
The canonical field names currently reused are:
Need ID
Spec ID
Spec URL
10. Migration boundary
HNC-1.1-E establishes and tests the mapping contract. It does not yet replace the existing modal or sync:jira-needs workflow.
The next increment, HNC-1.1-F, SHALL integrate this mapping into the operational Hecate flow while maintaining backward compatibility and validating the resulting Jira issue/property updates before removing legacy behavior.
11. Constitutional invariants
- Jira is the implementation-orchestration plane, not architectural truth.
- Canonical source commit and source-scope hash must survive the Jira projection.
- Machine payloads are referenced and hashed, not pasted into Description.
- Existing Jira custom fields are reused before new custom fields are introduced.
- Blocking clarifications can never be represented as agent-ready.
- ZARA and HNC properties have separate ownership.
- Jira rendering remains human-readable and implementation-oriented.
- Jira navigation must point back to canonical ZAYAZ Docs scope.
12. Canonical machine contract
The machine-readable mapping is defined by:
config/system/hnc.jira-mapping.json
schemas/hnc/jira-mapping.schema.v1.json
The deterministic projection implementation is provided by:
tools/viroway-tools/src/viroway_tools/hnc_jira_mapping.py