HNC
Hecate Need Creator Specification
1. Purpose
Hecate Need Creator is the canonical engineering-intake engine for ZAYAZ.
It transforms human product, architecture, governance, compliance, or engineering needs into structured Jira tickets, GitHub issues, agent context packs, workflow test plans, rollback plans, and audit events.
Hecate ensures that no ticket is created as isolated free text. Every Need is resolved against canonical ZAYAZ architecture metadata before it enters delivery.
2. Core Principle
Humans define intent.
Hecate derives impact.
Agents execute only after governed context is assembled.
Human Need
→ Canonical Resolution
→ Impact Analysis
→ Jira Ticket
→ GitHub Issue
→ Agent Context Pack
→ Governed Delivery
3. Need Input Model
Minimum input:
need:
title:
description:
requested_by:
source:
type: manual | zara | jira | github | audit | telemetry | regulation | incident
ref:
target:
component_id:
section_id:
interface_id:
change_intent:
type: feature | bugfix | ruleset | schema | contract | integration | refactor | docs | security | compliance
priority: low | medium | high | critical
acceptance_criteria:
-
Optional input:
optional:
proposed_rulesets:
proposed_schemas:
proposed_contracts:
proposed_tests:
proposed_rollback:
deadline:
regulatory_driver:
agent_allowed:
4. Canonical Resolution Pipeline
Need Submitted
↓
Component Lookup
↓
Section Lookup
↓
ZIR Interface Lookup
↓
ZCT Contract Lookup
↓
Schema Registry Lookup
↓
Ruleset Registry Lookup
↓
Dependency Graph Traversal
↓
Blast Radius Calculation
↓
Workflow Test Plan Generation
↓
Rollback Plan Generation
↓
Jira Ticket Creation
↓
GitHub Issue Creation
↓
Agent Context Pack Creation
↓
ALTD Audit Event
5. Component Resolution
Hecate SHALL resolve:
component:
component_id:
semantic_id:
short_id:
canonical_name:
source_file:
jira_epic:
owners:
security_level:
classification:
frameworks:
If component_id is missing, Hecate may infer candidates, but ticket creation must pause until a human confirms the target component.
6. Section Resolution
Component MDX sections MAY be linked to Jira work items.
Recommended section metadata:
sections:
- section_id: TG-CSI.sec.trust-score-generation
heading: Trust Score Generation
jira_refs:
- ZYZ-123
interface_refs:
- TG-CSI.trust-score-generation.v1
Hecate SHALL use section_id to scope impact more precisely than component-level analysis.
7. ZIR Interface Resolution
Hecate SHALL query ZIR to resolve:
interfaces:
- zir_id:
interface_id:
producer_component:
consumes:
produces:
schemas:
contracts:
rulesets:
workflow_profiles:
rollback_profiles:
If a Need affects a component but not a declared interface, Hecate SHALL classify it as one of:
interface_resolution:
- existing_interface
- new_interface_required
- component_internal_only
- documentation_only
- unresolved
8. ZCT Contract Resolution
Hecate SHALL resolve all affected contracts.
affected_contracts:
- zct_id:
contract_id:
contract_type:
producer:
consumers:
schemas:
rulesets:
compatibility:
governance:
Hecate SHALL classify contract change type:
contract_change_type:
- none
- patch
- minor
- major
- unknown
Major contract changes require architecture review.
9. Schema Resolution
Hecate SHALL derive affected schemas from:
Component frontmatter
ZIR records
ZCT contracts
Ruleset metadata
Schema metadata
Output:
affected_schemas:
consumes:
- schema.trust_signals@1.0.0
produces:
- schema.trust_scores@1.0.0
Schema changes SHALL trigger:
required_gates:
- schema_validation
- compatibility_check
- downstream_consumer_check
10. Ruleset Resolution
Hecate SHALL derive affected rulesets from ZRR and ruleset metadata.
Output:
affected_rulesets:
- ruleset.trustgate.csi.trust-score-calculation@1.0.0
Ruleset changes SHALL trigger:
required_gates:
- ruleset_registration_validation
- semantic_rule_validation
- ruleset_approval_check
- supersession_check
Prod deployment requires approved or frozen rulesets.
11. Dependency Graph Traversal
Hecate SHALL traverse the graph:
Component
→ Interface
→ Contract
→ Schema
→ Ruleset
→ Consumer
→ Workflow
Output:
dependency_impact:
direct_components:
downstream_components:
upstream_components:
affected_workflows:
affected_reports:
affected_agents:
Consumers are graph-derived, not manually authored.
12. Blast Radius Calculation
Hecate SHALL compute blast radius automatically.
Inputs:
blast_inputs:
security_level:
compliance_relevant:
assurance_relevant:
public_output:
downstream_consumer_count:
affected_contract_count:
affected_schema_count:
affected_ruleset_count:
change_intent:
reversibility:
Output:
blast_radius:
score: 0-100
level: minimal | low | medium | high | critical
reasons:
-
required_reviewers:
-
Suggested classification:
minimal: 0-19
low: 20-39
medium: 40-59
high: 60-79
critical: 80-100
13. Workflow Test Plan Generation
Hecate SHALL generate a machine-readable test plan.
test_plan:
test_plan_id:
test_plan_ref:
generated_from:
component_id:
interface_ids:
contract_ids:
schema_refs:
ruleset_refs:
required_tests:
- test_id:
type: unit | contract | integration | workflow | regression | replay | security
required: true
gate: blocking
Jira should store test_plan_ref, not a long manual checklist.
14. Rollback Plan Generation
Hecate SHALL generate or attach a rollback plan.
rollback_plan:
rollback_plan_id:
rollback_plan_ref:
strategy:
- feature_flag_revert
- deployment_revert
- ruleset_ref_rollback
- schema_compatibility_shim
- event_replay
- data_forward_fix
validation:
- run_test_plan_ref
- verify_downstream_consumers
- check_dlq
Jira should store:
rollback_plan_ref:
not free-text rollback instructions.
15. Jira Ticket Output Model
Derived Jira fields:
jira_payload:
epic:
summary:
description:
component_id:
semantic_id:
section_id:
interface_ids:
affected_contracts:
affected_rulesets:
affected_schemas:
consumes:
produces:
downstream_consumers:
blast_radius:
test_plan_ref:
rollback_plan_ref:
agent_allowed:
required_reviewers:
governance_status:
Jira remains a delivery system, not the architecture source of truth.
16. GitHub Issue Output Model
GitHub issue body should include:
github_issue:
linked_jira:
component_id:
interface_ids:
affected_contracts:
affected_schemas:
affected_rulesets:
agent_context_pack_ref:
test_plan_ref:
rollback_plan_ref:
Recommended labels:
labels:
- zayaz
- hecate-generated
- component:<component_id>
- blast:<level>
- change:<type>
- agent:allowed | agent:blocked
17. Agent Context Pack
Agents SHALL receive a generated context pack.
agent_context_pack:
component:
interfaces:
contracts:
schemas:
rulesets:
acceptance_criteria:
forbidden_changes:
required_tests:
rollback_plan_ref:
blast_radius:
Agents SHALL NOT infer architecture directly from prose when registry data exists.
18. Agent Eligibility Rules
agent_allowed:
true_when:
- blast_radius <= medium
- no frozen contract change
- no prod ruleset approval required
- no critical assurance output affected
false_when:
- blast_radius = critical
- security_level = critical and contract_change_type = major
- ruleset status change required
- schema breaking change required
- compliance filing output affected
Critical changes may still allow agents to draft code, but not merge or update governed artifacts autonomously.
19. Human Review Routing
Reviewer routing SHALL be derived.
reviewers:
architecture_owner:
security_owner:
compliance_owner:
assurance_owner:
component_owner:
data_owner:
Rules:
schema_change:
requires:
- architecture_owner
- data_owner
ruleset_change:
requires:
- governance_owner
- assurance_owner
contract_major_change:
requires:
- architecture_owner
- affected_component_owners
critical_blast_radius:
requires:
- cto
20. ALTD Audit Events
Hecate SHALL emit audit events.
events:
- NeedCreated
- NeedResolved
- ImpactAnalysisGenerated
- TestPlanGenerated
- RollbackPlanGenerated
- JiraTicketCreated
- GitHubIssueCreated
- AgentContextPackGenerated
Each event SHALL include:
event_payload:
need_id:
actor:
timestamp:
component_id:
derived_artifacts:
hash:
21. Error Handling
Hecate SHALL block ticket creation on:
blocking_errors:
- COMPONENT_NOT_FOUND
- INTERFACE_UNRESOLVED
- CONTRACT_CONFLICT
- SCHEMA_VERSION_CONFLICT
- RULESET_STATUS_INVALID
- BLAST_RADIUS_UNCOMPUTABLE
Hecate MAY create draft tickets on:
warnings:
- NO_DOWNSTREAM_CONSUMERS_FOUND
- TEST_PLAN_PARTIAL
- ROLLBACK_PROFILE_INFERRED
- RULESET_LINKAGE_MISSING
Draft tickets must be marked:
governance_status: needs-resolution
22. Hecate API
Suggested endpoint:
POST /api/hecate/needs
Request:
{
"title": "Add trust score replay validation",
"description": "Need replay validation for trust score generation.",
"target": {
"component_id": "TG-CSI",
"section_id": "TG-CSI.sec.trust-score-generation"
},
"change_intent": {
"type": "feature",
"priority": "high"
},
"acceptance_criteria": [
"Replay output must match original trust score within approved tolerance.",
"Replay artifacts must be emitted to DAL candidate queue."
]
}
Response:
{
"need_id": "HNC-2026-000001",
"status": "resolved",
"jira_issue": "ZYZ-123",
"github_issue": "Viroway/zayaz-core#456",
"blast_radius": {
"level": "high",
"score": 72
},
"test_plan_ref": "ZAR:test-plan:TG-CSI:2026-06-18@sha256...",
"rollback_plan_ref": "ZAR:rollback-plan:TG-CSI:standard@1.0.0"
}
23. Data Tables
Suggested core tables:
hecate_needs:
need_id:
title:
description:
requested_by:
status:
component_id:
section_id:
created_at:
hecate_resolution:
need_id:
component_ref:
interface_refs:
contract_refs:
schema_refs:
ruleset_refs:
graph_hash:
blast_radius:
hecate_outputs:
need_id:
jira_ref:
github_ref:
test_plan_ref:
rollback_plan_ref:
agent_context_pack_ref:
hecate_audit_events:
event_id:
need_id:
event_type:
payload_hash:
created_at:
24. Status Lifecycle
status:
- draft
- submitted
- resolving
- needs-resolution
- resolved
- jira-created
- github-created
- agent-ready
- blocked
- cancelled
25. Relationship to CIAS, ZIR, and ZCT
CIAS defines the governance framework.
ZIR defines interface mapping.
ZCT defines contract promises.
Hecate operationalizes all three.
CIAS = Why and governance model
ZIR = What capability is affected
ZCT = What promise is affected
Hecate = How the Need becomes governed delivery
26. Normative Statement
Hecate Need Creator is the authoritative intake mechanism for governed ZAYAZ engineering work.
No autonomous coding agent should receive a task unless Hecate has produced:
required_before_agent:
- component resolution
- impact analysis
- affected contracts
- affected schemas
- affected rulesets
- blast radius
- test plan
- rollback plan
- agent context pack
This ensures that agentic development scales without sacrificing ZAYAZ architecture integrity, auditability, or compliance trust.
APPENDIX A - Implementation
- Update component frontmatter schema
- Update ruleset generator requirements
- Add schema/ruleset/contract/interface registries
- Build Hecate impact resolver
- Generate test_plan.yaml and rollback_plan.yaml
- Map derived fields into Jira
- Feed GitHub/Codex/agents only through Hecate output