HNC
Hecate Need Creator Specification
1. Purpose
Hecate Need Creator is the canonical engineering-intake and implementation-orchestration preparation engine for ZAYAZ.
Hecate transforms human product, architecture, governance, compliance, operational or engineering intent into governed implementation work. It resolves each Need against canonical ZAYAZ architecture before delivery and produces machine-readable context that can be consumed by Jira, AI engineering agents, validation tooling and implementation repositories.
Hecate exists to prevent free-text tickets from becoming de facto architecture.
The v1.1 objective is to evolve the existing Jira Need model into a machine-readable Implementation Packet while preserving the authority chain established by CIAS:
Humans define intent. ZAYAZ Docs defines truth. Jira defines work. AI builds and verifies. ZAYAZ Platform contains the implementation. AWS executes it.
And the human/machine boundary:
Humans govern intent and approve outcomes. Machines prove as much implementation conformance as can be deterministically proven. AI handles interpretation, generation, coverage expansion, diagnosis and remediation.
2. Hecate's Responsibility Boundary
Hecate is a compiler/orchestrator between canonical architecture and implementation work.
Human Need
↓
Canonical ZAYAZ Docs resolution
↓
Hecate impact + contract resolution
↓
Machine-readable Implementation Packet
↓
Jira
↓
AI / human engineering
↓
ZAYAZ Platform
↓
CI/CD evidence
↓
AWS runtime
Hecate SHALL:
- resolve canonical sources;
- derive affected modules/components/interfaces/contracts/schemas/registries/rulesets;
- calculate impact and blast radius;
- derive implementation target(s);
- derive acceptance and validation requirements;
- establish forbidden-change boundaries;
- produce test and rollback references;
- establish agent autonomy limits;
- create or update Jira work;
- preserve requirements-to-runtime trace identifiers;
- collect implementation evidence references when work is completed.
Hecate SHALL NOT:
- redefine canonical architecture;
- silently invent missing contracts when authoritative metadata should exist;
- treat Jira descriptions as architectural truth;
- declare software fully correct merely because an AI review says so;
- allow implementation agents to bypass required deterministic gates;
- write production tenant business state into ZAYAZ Docs.
3. Core Principle — Architecture Before Work
Every engineering Need SHALL resolve against canonical architecture before it becomes agent-ready implementation work.
Human intent
→ canonical resolution
→ impact analysis
→ implementation packet
→ Jira work
→ implementation
If canonical architecture is missing or contradictory, Hecate SHALL route the Need to architecture resolution instead of asking an implementation agent to guess.
Jira remains a delivery system, not the architecture source of truth.
4. Need Input Model
Human input SHOULD remain intentionally small. Hecate derives technical context where canonical metadata exists.
Minimum logical input:
need:
title:
description:
requested_by:
source:
type: manual | zara | jira | github | audit | telemetry | regulation | incident
ref:
target:
spec_id:
section_id:
component_id:
interface_id:
change_intent:
type: feature | bugfix | ruleset | schema | contract | integration | refactor | docs | security | compliance
priority: low | medium | high | critical
acceptance_criteria:
-
Only title, description, and enough source/target context to resolve canonical scope need be directly supplied by a human. The UI MAY obtain scope implicitly from the Docusaurus heading currently being viewed.
Optional human input:
optional:
business_outcome:
unacceptable_outcomes: []
proposed_acceptance_criteria: []
deadline:
regulatory_driver:
desired_assignee:
desired_agent_usage:
Technical implementation detail SHOULD be derived rather than demanded from the requester whenever canonical metadata can provide it.
5. Canonical Source Binding
Every resolved Need SHALL bind to the canonical source state used to generate the implementation work.
Minimum binding:
canonical_source:
repository: viroway-ltd/zayaz-docs
commit_sha:
document_ids: []
source_files: []
section_ids: []
A human-friendly Docusaurus URL MAY be included, but a mutable URL alone is insufficient for implementation provenance.
The canonical source commit allows Hecate and downstream tooling to answer:
Which exact architectural truth was this implementation packet generated from?
If canonical source files change materially after packet generation, Hecate SHOULD detect staleness and require packet regeneration or compatibility review before implementation/merge.
6. Canonical Resolution Pipeline
Hecate v1.1 SHALL conceptually resolve:
Need Submitted
↓
Canonical Source Binding
↓
Module / Component Lookup
↓
Section Lookup
↓
ZIR Interface Lookup
↓
ZCT Contract Lookup
↓
Payload / Event Contract Lookup
↓
Schema Registry Lookup
↓
Controlled Registry Lookup
↓
Ruleset Registry Lookup
↓
Dependency Graph Traversal
↓
Implementation Target Resolution
↓
Blast Radius Calculation
↓
Validation Plan Generation
↓
Rollback Plan Generation
↓
Autonomy Boundary Resolution
↓
Implementation Packet Generation
↓
Jira Creation / Update
↓
Agent Context Pack Generation
↓
ALTD Audit Event
The v1.1 pipeline extends the v1.0 pipeline by treating implementation target, registries, payload/event contracts, forbidden changes, validation evidence and source commit binding as first-class outputs.
7. Component and Section Resolution
Hecate SHALL resolve, where applicable:
component:
module_ids: []
component_id:
semantic_id:
short_id:
canonical_name:
source_file:
section_ids: []
jira_epic:
owners: []
security_level:
classification: []
frameworks: []
If the target cannot be unambiguously resolved, Hecate SHALL stop agent-ready progression and return candidate resolution to a human.
Section resolution SHOULD be preferred to whole-component scope where the source document provides stable section identifiers.
8. Interface and Contract Resolution
Hecate SHALL resolve affected ZIR interfaces and ZCT contracts.
Representative output:
interfaces:
- zir_id:
interface_id:
producer_component:
consumers: []
schemas: []
contracts: []
rulesets: []
affected_contracts:
- zct_id:
contract_id:
contract_type:
producer:
consumers: []
schemas: []
compatibility:
governance:
Contract change classification:
contract_change_type:
- none
- patch
- minor
- major
- unknown
Major or breaking contract changes require architecture review and SHALL NOT be silently implemented by an agent.
9. Schema, Payload, Event, Registry and Ruleset Resolution
Hecate v1.1 SHALL distinguish canonical artifact classes rather than reporting everything merely as a generic schema.
canonical_artifacts:
schemas: []
payload_contracts: []
event_contracts: []
registries: []
rulesets: []
For each artifact Hecate SHOULD retain:
artifact:
id:
type:
source_ref:
version:
authority:
change_expected: false
Where registry data exists, implementation agents SHALL consume registered vocabulary rather than inventing values from prose.
Schema changes trigger structural/compatibility gates. Registry/ruleset changes trigger semantic/governance gates. Payload/event contract changes trigger producer/consumer compatibility analysis.
10. Dependency Graph and Blast Radius
Hecate SHALL traverse dependency relationships such as:
Module
→ Component
→ Interface
→ Contract
→ Schema / Payload / Event
→ Registry / Ruleset
→ Producer / Consumer
→ Workflow
→ Implementation target
Representative impact output:
dependency_impact:
upstream_components: []
direct_components: []
downstream_components: []
affected_workflows: []
affected_reports: []
affected_agents: []
affected_repositories: []
Blast radius SHALL be computed from deterministic metadata where possible.
blast_radius:
score: 0-100
level: minimal | low | medium | high | critical
reasons: []
required_reviewers: []
The blast radius influences validation depth, reviewer routing, rollout strategy and agent autonomy.
11. Implementation Target Resolution
Hecate SHALL explicitly state where implementation belongs.
Representative target:
implementation_target:
repository: viroway-ltd/zayaz-platform
layer: runtime | infrastructure | integration | migration | test
module_ids: []
component_ids: []
suggested_paths: []
zayaz-docs is the Governance & Contract Plane and SHALL NOT be selected as the runtime implementation target merely because the Need originates from Docusaurus.
Documentation-only or canonical-contract work MAY target zayaz-docs explicitly.
AWS is a runtime environment, not a source-code repository; infrastructure implementation should target the governed implementation/IaC repository and subsequently deploy to AWS through CI/CD.
12. Forbidden-Change Boundary
Each implementation packet SHOULD state what an implementation agent must not change while fulfilling the Need.
Example:
forbidden_changes:
- do_not_change_canonical_epu_identity_semantics
- do_not_add_unregistered_predicates
- do_not_relax_schema_validation
- do_not_modify_unrelated_modules
- do_not_bypass_trustgate
Forbidden changes may be derived from constitutions, registry defaults, affected-contract boundaries and explicit human decisions.
An agent encountering a forbidden-change conflict SHALL stop or route remediation to the appropriate higher authority layer.
13. Acceptance Criteria Derivation
Acceptance criteria have two sources:
Human outcome criteria
+
Machine-derived conformance criteria
Human criteria state what successful functionality means.
Machine-derived criteria may include:
- payload validates against canonical schema;
- only registered vocabulary is emitted;
- operation is replay/idempotency safe;
- required lineage is persisted;
- breaking consumer behavior is prohibited;
- security/authorization boundary is preserved;
- specified negative behavior is rejected.
Hecate SHALL distinguish human-authored from machine-derived acceptance criteria rather than presenting inferred criteria as human statements.
14. Validation Plan
Hecate v1.1 SHALL generate a machine-readable validation plan rather than a generic checklist.
validation_plan:
validation_plan_id:
generated_from:
need_id:
canonical_source_commit:
components: []
interfaces: []
contracts: []
schemas: []
registries: []
rulesets: []
required_gates:
- gate_id:
type: schema | registry | static | unit | negative | property | contract | compatibility | integration | workflow | replay | security | compliance | migration | infrastructure | staging
required: true
blocking: true
evidence_type:
AI may generate or expand tests, but deterministic execution results constitute evidence.
No generic AI statement such as looks correct satisfies a blocking validation gate.
15. Rollback Plan
Hecate SHALL generate or reference a rollback/remediation plan appropriate to the change.
rollback_plan:
rollback_plan_id:
rollback_plan_ref:
strategies:
- feature_flag_revert
- deployment_revert
- ruleset_ref_rollback
- schema_compatibility_shim
- event_replay
- data_forward_fix
validation:
- run_validation_plan
- verify_downstream_consumers
- check_dlq
Rollback capability SHALL reflect data/migration irreversibility rather than assuming every deployment can simply be reverted.
16. AI Autonomy Boundary
Hecate SHALL derive an explicit autonomy boundary instead of a single ambiguous agent_allowed boolean.
Recommended levels:
autonomy_level:
- blocked
- analyze_only
- draft_only
- implement_and_test
- open_pr
- merge_eligible
- deployment_eligible
The initial v1.1 implementation MAY map these levels onto current binary agent controls until the canonical autonomy registry is implemented.
Representative constraints:
blocked_when:
- unresolved canonical target
- contract conflict
- schema version conflict
- critical architecture ambiguity
merge_not_eligible_when:
- breaking contract change
- critical blast radius without required review
- governed ruleset approval outstanding
- compliance filing behavior affected without approval
AI may still be permitted to analyze or draft a high-risk change while being prohibited from merge or deployment.
17. Machine-Readable Implementation Packet
The principal HNC v1.1 output is the Implementation Packet.
implementation_packet:
schema_version:
packet_id:
need_id:
generated_at:
canonical_source:
repository: viroway-ltd/zayaz-docs
commit_sha:
document_ids: []
source_files: []
section_ids: []
intent:
title:
description:
requested_by:
change_type:
priority:
business_outcome:
target:
module_ids: []
component_ids: []
interface_ids: []
implementation_repository:
implementation_layers: []
canonical_artifacts:
contracts: []
schemas: []
payload_contracts: []
event_contracts: []
registries: []
rulesets: []
dependencies:
upstream: []
downstream: []
workflows: []
blast_radius:
score:
level:
reasons: []
acceptance:
human: []
derived: []
forbidden_changes: []
validation:
validation_plan_ref:
required_gates: []
rollback:
rollback_plan_ref:
agent:
autonomy_level:
context_pack_ref:
required_reviewers: []
traceability:
jira_ref:
implementation_commit_refs: []
ci_run_refs: []
deployment_refs: []
The final field layout SHALL be governed by a canonical JSON Schema in a subsequent HNC contract increment. Until that schema is approved, this structure is normative conceptually but not yet a production API promise.
18. Jira Output Model
Jira SHALL store implementation work and its delivery lifecycle, not duplicate the full architecture database.
A Jira work item SHOULD surface human-readable information and retain structured references to the canonical packet.
Recommended logical Jira payload:
jira_payload:
epic:
summary:
description:
need_id:
implementation_packet_ref:
canonical_source_commit:
canonical_source_urls: []
module_ids: []
component_ids: []
interface_ids: []
affected_contracts: []
affected_schemas: []
affected_registries: []
affected_rulesets: []
implementation_repository:
blast_radius:
validation_plan_ref:
rollback_plan_ref:
autonomy_level:
required_reviewers: []
governance_status:
Large structured data SHOULD be stored in a governed artifact and referenced from Jira rather than flattened into an unreadable issue description.
The Jira ticket SHALL make the canonical source link obvious to humans.
19. Agent Context Pack
Agents SHALL receive a context pack derived from the Implementation Packet.
agent_context_pack:
packet_ref:
canonical_source_commit:
target:
interfaces: []
contracts: []
schemas: []
payload_contracts: []
event_contracts: []
registries: []
rulesets: []
acceptance_criteria: []
forbidden_changes: []
required_validation_gates: []
rollback_plan_ref:
blast_radius:
autonomy_level:
Agents SHALL NOT infer canonical values directly from prose when authoritative registry/schema data exists.
20. Implementation Evidence Packet
Completion SHALL produce or reference machine-readable implementation evidence.
implementation_evidence:
schema_version:
evidence_id:
need_id:
implementation_packet_ref:
canonical_source_commit:
implementation:
repository:
commit_sha:
pull_request_ref:
contract_versions: []
schema_versions: []
registry_versions: []
ruleset_versions: []
validation_results:
- gate_id:
result: passed | failed | waived
evidence_ref:
executed_at:
ci_run_refs: []
deployment_refs: []
reviewer_approvals: []
A human can therefore approve an outcome based on inspectable implementation evidence without manually reproducing every deterministic test.
21. Requirements-to-Runtime Provenance
Hecate SHALL preserve traceability through the software delivery chain:
Human intent
↓
Canonical ZAYAZ Docs commit
↓
Hecate Need
↓
Implementation Packet
↓
Jira work item
↓
ZAYAZ Platform commit / PR
↓
CI evidence
↓
AWS deployment
↓
Runtime telemetry
The reverse lookup SHOULD also be possible:
AWS deployment
↑
implementation commit
↑
Jira key
↑
Implementation Packet / Hecate Need
↑
canonical ZAYAZ Docs commit
↑
human-approved intent
This is the software-engineering equivalent of ZAYAZ evidence/calculation lineage.
22. Authority-Aware Remediation Routing
Hecate SHALL classify discovered problems by the layer that owns the truth.
remediation_route:
implementation_defect: zayaz-platform
incomplete_jira_instruction: hecate_or_jira_packet
missing_canonical_contract: zayaz-docs
contradictory_canonical_contract: zayaz-docs_architecture_review
runtime_environment_defect: platform_or_aws
human_intent_ambiguity: human_decision
An implementation agent SHALL NOT resolve a missing canonical contract by silently inventing a local application rule.
A runtime observation may create a new Need, but it does not become canonical architecture until governed through ZAYAZ Docs.
23. Human Review Routing
Reviewer routing SHALL be derived from impact and artifact authority.
Representative reviewers:
reviewers:
architecture_owner:
security_owner:
compliance_owner:
assurance_owner:
component_owner:
data_owner:
cto:
Examples:
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]
Human approval is focused on intent, architecture decisions, risk and outcome rather than manually repeating machine-verifiable checks.
24. ALTD Audit Events
Hecate SHALL emit audit events for material transitions.
v1.1 event families SHOULD include:
events:
- NeedCreated
- NeedResolved
- CanonicalSourceBound
- ImpactAnalysisGenerated
- ValidationPlanGenerated
- RollbackPlanGenerated
- ImplementationPacketGenerated
- JiraTicketCreated
- AgentContextPackGenerated
- AgentReadyDeclared
- ImplementationEvidenceReceived
- ImplementationValidated
- NeedBlocked
- NeedCompleted
Every event SHALL carry appropriate correlation/need identifiers, actor, timestamp and governed artifact hashes/references.
25. Error and Warning Semantics
Hecate SHALL block agent-ready status on errors including:
blocking_errors:
- CANONICAL_SOURCE_UNRESOLVED
- COMPONENT_NOT_FOUND
- TARGET_AMBIGUOUS
- INTERFACE_UNRESOLVED
- CONTRACT_CONFLICT
- SCHEMA_VERSION_CONFLICT
- REGISTRY_REFERENCE_INVALID
- RULESET_STATUS_INVALID
- IMPLEMENTATION_TARGET_UNRESOLVED
- BLAST_RADIUS_UNCOMPUTABLE
- VALIDATION_PLAN_UNRESOLVED
- AUTONOMY_BOUNDARY_UNRESOLVED
Warnings may permit draft Jira creation but SHALL prevent false representation as agent-ready where they affect required context.
warnings:
- NO_DOWNSTREAM_CONSUMERS_FOUND
- VALIDATION_PLAN_PARTIAL
- ROLLBACK_PROFILE_INFERRED
- RULESET_LINKAGE_MISSING
- IMPLEMENTATION_PATH_INFERRED
Draft issues with unresolved governance SHALL be marked:
governance_status: needs-resolution
26. Status Lifecycle
The logical HNC lifecycle becomes:
status:
- draft
- submitted
- resolving
- needs-resolution
- resolved
- packet-generated
- jira-created
- agent-context-ready
- agent-ready
- implementing
- validating
- remediation-required
- implementation-ready-for-review
- completed
- blocked
- cancelled
Not every integration must expose every state directly in Jira; mappings may collapse internal states while preserving machine-readable lifecycle internally.
27. Hecate API Direction
The canonical public/internal contract SHALL be defined by schemas in a later v1.1 implementation increment.
Conceptual endpoint:
POST /api/hecate/needs
Conceptual response:
{
"need_id": "HNC-2026-000001",
"status": "packet-generated",
"canonical_source_commit": "<sha>",
"implementation_packet_ref": "HNC:packet:HNC-2026-000001@sha256...",
"jira_issue": "ZYZ-123",
"blast_radius": {
"level": "high",
"score": 72
},
"validation_plan_ref": "HNC:validation:HNC-2026-000001@sha256...",
"rollback_plan_ref": "HNC:rollback:HNC-2026-000001@sha256...",
"autonomy_level": "implement_and_test"
}
The current Hecate modal/workflow API remains operationally compatible until the v1.1 payload schemas are implemented and migration-tested.
28. Persistence Model Direction
Suggested logical persistence:
hecate_needs:
need_id:
title:
description:
requested_by:
status:
created_at:
hecate_canonical_resolution:
need_id:
canonical_source_commit:
component_refs: []
interface_refs: []
contract_refs: []
schema_refs: []
registry_refs: []
ruleset_refs: []
graph_hash:
blast_radius:
hecate_packets:
packet_id:
need_id:
packet_hash:
packet_ref:
generated_at:
hecate_outputs:
need_id:
jira_ref:
agent_context_pack_ref:
validation_plan_ref:
rollback_plan_ref:
evidence_ref:
hecate_audit_events:
event_id:
need_id:
event_type:
payload_hash:
created_at:
Implementation technology remains outside this specification until separately governed.
29. Existing Operational Compatibility
As of HNC v1.1 specification publication, the repository already contains an operational Hecate flow based on Docusaurus context selection, <JiraNeed/> insertion, Jira synchronization and write-back.
Key operational artifacts include:
content/architecture/hecate-need-creator.mdx
content/system/needs.mdx
docusaurus/src/theme/NavbarItem/CustomHecateNeedCreator.tsx
docusaurus/src/components/HecateNeedCreator/HecateNeedCreatorModal.tsx
.github/workflows/hecate-create-need.yml
.github/workflows/jira-epics-sync.yml
scripts/hecate/*
Jira sync scripts referenced by package commands
The v1.1 specification does not require these existing workflows to be broken or replaced in one step.
Migration SHALL be additive and contract-first:
v1.1 specification
↓
canonical schemas + registries
↓
validators + fixtures
↓
Hecate resolver/packet generation
↓
Jira field/reference mapping
↓
modal/workflow integration
↓
AI engineering handoff
↓
implementation evidence ingestion
Until the new schemas are approved, existing Jira Need creation remains the compatibility path.
30. Jira Epic and Docusaurus Authority
HNC implementation is tracked by Jira Epic ZYZ-904.
The Docusaurus HNC specification is authoritative. Jira tracks delivery against the specification and SHALL not supersede its architectural semantics.
Hecate should eventually write the canonical source commit and Implementation Packet reference into derived Jira work so each issue is explicitly bound to the architecture it implements.
31. HNC v1.1 Implementation Increments
The recommended implementation sequence is:
HNC-1.1-A Canonical payload schemas
Need
ImplementationPacket
AgentContextPack
ValidationPlan
ImplementationEvidence
HNC-1.1-B Controlled registries
validation gate types
autonomy levels
remediation routes
implementation targets
evidence types
HNC-1.1-C Schema validators + positive/negative fixtures
HNC-1.1-D Hecate canonical resolver extensions
source commit binding
payload/event/registry resolution
implementation target resolution
HNC-1.1-E Jira mapping contract + migration
HNC-1.1-F Modal/workflow migration
HNC-1.1-G AI engineering handoff + evidence return
HNC-1.1-H End-to-end reference test
ZAYAZ Docs → Hecate → Jira → AI → zayaz-platform → CI evidence
The hardened EPU Phase 1 architecture SHOULD be used as the initial end-to-end reference case because it already contains canonical registries, schemas, payload contracts, fixtures and deterministic tests.
32. Relationship to CIAS, ZIR and ZCT
CIAS = governance and software-delivery authority model
ZIR = interface identity and dependency mapping
ZCT = interoperability promises
HNC = canonical compilation of human/canonical intent into governed implementation work
Jira = implementation orchestration and delivery state
HNC operationalizes CIAS but does not replace CIAS as the higher-level delivery-governance authority.
33. Normative Statement
Hecate Need Creator is the authoritative intake and implementation-packet generation mechanism for governed ZAYAZ engineering work.
Before implementation work becomes agent-ready, Hecate SHALL provide or resolve at minimum:
required_before_agent_ready:
- canonical source binding
- target component/module resolution
- affected interfaces/contracts
- affected schemas/payloads/events
- affected registries/rulesets
- dependency impact
- blast radius
- implementation target
- acceptance criteria
- forbidden changes
- validation plan
- rollback plan
- autonomy boundary
- agent context pack
Before implementation is represented as complete, the delivery system SHALL provide machine-verifiable evidence for the blocking validation gates required by the Implementation Packet and any required human approvals.
Hecate SHALL preserve this authority chain:
Humans define intent. ZAYAZ Docs defines truth. Jira defines work. AI builds and verifies. ZAYAZ Platform contains the implementation. AWS executes it.
APPENDIX A — v1.1 Operational Migration Targets
The following existing artifacts are known HNC operational migration targets and SHALL be reviewed during implementation of v1.1:
content/system/needs.mdxdocusaurus/src/theme/NavbarItem/CustomHecateNeedCreator.tsxdocusaurus/src/components/HecateNeedCreator/HecateNeedCreatorModal.tsx.github/workflows/hecate-create-need.yml.github/workflows/jira-epics-sync.ymlscripts/hecate/create-need-mutation.ts- Jira Need synchronization scripts/package commands
- Hecate API implementation configured by Docusaurus
These targets SHALL be migrated only after their v1.1 machine-readable contracts exist and have positive/negative validation fixtures.