Established repo intent

This commit is contained in:
2026-05-16 00:29:39 +02:00
parent 9ad33efc08
commit bea7a0cf92
4 changed files with 1985 additions and 3 deletions

485
INTENT.md Normal file
View File

@@ -0,0 +1,485 @@
\---
project: helix-forge
product: HelixForge
status: draft
intent\_version: 0.1.0
date: 2026-05-15
standard: OrthogonalArchitectureStandard
standard\_version: 1.0.1
architecture\_framework: Viable Systems Model inspired Orthogonal Architecture Dimensions
---
# INTENT.md — helix-forge
> \*\*HelixForge envisions a world where software capabilities evolve with understanding, not guesswork.\*\*
## 1\. Repository intent
`helix-forge` exists to make **HelixForge** executable: a capability-first development ecosystem where real-world demands are discovered in natural language, shaped into reusable software capabilities, and delivered through validated architecture and implementation artifacts.
HelixForge treats software creation as a forge rather than a factory. A capability is not merely coded; it is refined through dialogue, structural modeling, validation, implementation, feedback, and reuse. The repository should therefore preserve both strands of the HelixForge double helix:
1. **Human understanding** — discovery, intent, problem framing, language, ownership, value, and fitness.
2. **Executable precision** — contracts, schemas, validators, services, tests, automation, governance, and runtime evidence.
The purpose of this repository is to turn intent into structure, structure into capability, and capability into lasting progress.
## 2\. Vision alignment
HelixForge empowers a global ecosystem of users, builders, and investors to collaboratively forge reusable software capabilities from real-world problems. It intertwines the natural-language art of discovery with the precise science of delivery, accumulating a battle-tested repository of composable intelligence that accelerates innovation for all.
This repository should advance that vision by ensuring that every meaningful contribution can answer the following questions:
* **What human or organizational intent does this serve?**
* **What reusable capability does it strengthen or create?**
* **Where does it belong in the Orthogonal Architecture Dimensions?**
* **Which Viable Systems Model function does it support?**
* **How is its correctness, safety, and usefulness validated?**
* **How does it improve the capability repository rather than merely add code?**
## 3\. Operating thesis
HelixForge is built on the belief that software capabilities evolve best when discovery and delivery are part of one continuous system.
Discovery without delivery produces insight that may never become useful. Delivery without discovery produces software that may work but may not matter. HelixForge connects them through an architecture-aware process where demands mature into capabilities, capabilities become contracts and realizations, and realizations are validated against both human intent and machine-checkable standards.
The repository should therefore prefer work that:
* explores problems before prescribing solutions;
* captures capability intent before implementation detail;
* expresses architecture using controlled vocabulary;
* keeps independent dimensions orthogonal instead of mixing concerns;
* uses executable schemas and semantic rules as truth-bearing artifacts;
* treats AI assistance as governed, observable, and architecturally placed;
* improves reuse, composability, and accumulated capability value.
## 4\. Primary outcomes
The repository is successful when it supports these outcomes:
### 4.1 Capability discovery
HelixForge must help users, builders, and investors describe problems, demands, constraints, and opportunities in natural language while progressively clarifying scope, ownership, value, and architectural fit.
### 4.2 Capability modeling
HelixForge must model capabilities as stable architectural units. A capability should have a purpose, boundary, contract, quality expectations, ownership, and relationship to other capabilities.
### 4.3 Capability realization
HelixForge must support implementation artifacts that realize capabilities through services, applications, platform services, integrations, automations, data stores, policies, and intelligence components.
### 4.4 Capability validation
HelixForge must validate architecture descriptions structurally and semantically using the Orthogonal Architecture Standard and its semantic rule profile.
### 4.5 Capability evolution
HelixForge must preserve feedback, learning, and architectural evidence so that capabilities improve through use rather than merely accumulate as static assets.
## 5\. Architectural foundation
HelixForge uses the **Orthogonal Architecture Standard** and an **OAS-compatible Orthogonal Architecture Dimensions information architecture**. The standard describes architectures as elements, placements, relations, principles, sources, and metadata.
The architectural foundation has three layers:
1. **Controlled vocabulary** — stable codes, names, verbs, and explanations for architecture dimensions and viable-system functions.
2. **Structural validation** — JSON Schema validation for the shape of architecture documents.
3. **Semantic validation** — architectural rules that check whether the model is meaningful, not merely syntactically valid.
The current standard reference is **Orthogonal Architecture Standard Schema v1.0.1**. Architecture documents should use:
```yaml
standard: OrthogonalArchitectureStandard
version: "1.0.1"
```
## 6\. Orthogonal Architecture Dimensions
HelixForge uses six independent dimensions. A single architectural element may be placed in multiple dimensions, but each placement must remain clear about which concern it expresses.
> Vocabulary note: the codes, short labels, verbs, and explanations are taken from the current OAD workbook. Minor obvious spelling is normalized in this prose, while the controlled codes remain unchanged.
### 6.1 Plane dimension
The Plane dimension describes operational responsibility.
|Code|Short|Name|Verb|Explanation|Examples|
|-|-|-|-|-|-|
|P|Plane|Plane Dimension|reign|Operational responsibility|—|
|P1|Workload|Workload Plane|operate|Contains operational services and applications|—|
|P2|Control|Control Plane|control|Maintains system state|Kubernetes control plane, GitOps controllers, policy engines, platform APIs|
|P3|Management|Management Plane|manage|Provides administrative interfaces|CLI tools, web portals, automation scripts, audit reporting|
### 6.2 Stack dimension
The Stack dimension describes the technical hosting substrate.
|Code|Short|Name|Verb|Explanation|Examples|
|-|-|-|-|-|-|
|S|Stack|Stack Dimension|implement|Technical hosting substrate|—|
|S1|Infrastructure|Infrastructure Substrate|carry|Defines the physical or cloud infrastructure|Cloud accounts, network foundations, compute nodes, operating systems, container runtimes|
|S2|Runtime|Cluster Runtime|run|Defines the orchestration runtime|Kubernetes scheduler, service discovery, ingress, admission controllers, service mesh, operators|
|S3|Services|Platform Services|service|Shared services supporting workloads|Databases, message brokers, caches, object storage, secret management, identity systems|
|S4|Enablement|Developer Enablement|enable|Tools that allow system evolution|CI/CD pipelines, developer portals, platform templates, SDKs, buildpacks|
|S5|Workloads|Workloads \& Experience Endpoints|apply|Functional applications delivering value|APIs, web frontends, workers, integration endpoints, administrative interfaces|
### 6.3 Quality dimension
The Quality dimension describes cross-cutting architectural qualities.
|Code|Short|Name|Verb|Explanation|Examples|
|-|-|-|-|-|-|
|Q|Quality|Quality Dimension|qualify|Defines cross-cutting architectural qualities|—|
|Q1|Compliance|Security \& Compliance|secure|Identity, access control, compliance|—|
|Q2|Observability|Observability|observe|Telemetry and monitoring|Metrics, logs, traces|
|Q3|Resilience|Resilience \& Operability|stabilize|Deployment, scaling, and disaster recovery|—|
|Q4|Isolation|Isolation \& Tenancy|isolate|Workload separation strategies|—|
|Q5|Performance|Performance \& Scalability|improve|Latency, throughput, and scaling|—|
|Q6|Efficiency|Cost \& Efficiency|optimize|Resource optimization|—|
|Q7|Governance|Governance \& Change|govern|Policies and architecture governance|—|
### 6.4 Logic dimension
The Logic dimension describes functional decomposition.
|Code|Short|Name|Verb|Explanation|Examples|
|-|-|-|-|-|-|
|L|Logic|Logic Dimension|structure|Functional decomposition|—|
|L1|Domain|Capability Domain|define|Defines stable functional areas|Billing, identity, catalog, order management|
|L2|Realization|Service Realization|realize|Implementation of capabilities|APIs, worker services, event processors, adapters|
|L3|Composition|Composition \& Integration|compose|Defines orchestration between services|Workflow engines, orchestration pipelines, API gateways, integration pipelines|
|L4|Solution|Solution Layer|solve|End-user solutions and applications|SaaS products, internal systems, partner solutions|
### 6.5 Intelligence dimension
The Intelligence dimension describes assisted system behavior.
|Code|Short|Name|Verb|Explanation|Examples|
|-|-|-|-|-|-|
|I|Intelligence|Intelligence Dimension|automate|Defines assisted system behavior|—|
|I1|Deterministic|Deterministic Automation|script|Scripts and rule engines|—|
|I2|Language|Language Interaction|prompt|Natural language interfaces|—|
|I3|Reasoning|Knowledge \& Reasoning|reason|Semantic processing and recommendation systems|—|
|I4|Fitting|Assisted Fitting \& Adaptation|fit|AI-assisted system configuration|—|
|I5|Agents|Agentic Delegation|delegate|Autonomous AI agents acting within governance policies|—|
### 6.6 Capability dimension
The Capability dimension describes capabilities as stable architectural units.
|Code|Short|Name|Verb|Explanation|Examples|
|-|-|-|-|-|-|
|C|Capability|Capability Dimension|define|Defines capabilities as stable architectural units|—|
|C1|Model|Capability Model|model|Defines purpose, scope, ownership|—|
|C2|Contract|Capability Contract|contract|Defines interfaces|APIs, events, SLOs|
|C3|Implementation|Capability Implementation|implement|Technical implementations|Services, databases, workflows|
|C4|Reusables|Shared Platform Capabilities|reuse|Platform-level services|Identity, messaging, observability|
|C5|Business|Business Capabilities|business|Business functionality|Billing, onboarding, support|
## 7\. Viable Systems Model inspired information architecture
HelixForge uses a Viable Systems Model inspired subsystem vocabulary to describe what each architectural element does for the living system. These VSM-inspired functions should be used to classify capabilities, elements, relations, validation rules, and repository concerns.
Code context matters: the Stack dimension uses `S1` through `S5` as placement levels, while VSM also uses `System 1` through `System 5` as viable-system tags. Use OAD codes inside dimensional `placements`; use VSM mappings inside OAS `vsm\_tags`. The workbook abbreviations such as `OPS`, `SYN`, and `CTL` are vocabulary labels; they do not replace the OAS `vsm\_tags` enum. `ENV` describes boundary/environment concerns and should be represented through metadata or an explicit extension if it is used outside the current OAS enum.
|Code|Short|Name|Verb|Explanation|VSM mapping|
|-|-|-|-|-|-|
|OPS|Operations|Operations \& Activities|does|Do the primary work|System 1|
|SYN|Synchronization|Synchronization \& Coordination|aligns|Prevent friction, oscillation, and local conflict|System 2|
|CTL|Control|Internal Control \& Regulation|governs|Manage current performance, resources, priorities, and constraints|System 3|
|AUD|Audit|Audit \& Monitoring|verifies|Check what is really happening|System 3\*|
|INT|Intelligence|Intelligence \& Adaptation|scans|Sense the environment and future|System 4|
|POL|Policy|Policy \& Identity|defines|Define identity, values, and ultimate direction|System 5|
|ENV|Environment|Boundary \& Surface|interacts|Provides interfaces, adapters, sensors, and actors|Environment|
### 7.1 VSM usage intent
* **OPS** marks the operational work of software capabilities and runtime value delivery.
* **SYN** marks coordination mechanisms that reduce friction between capabilities, services, teams, or workflows.
* **CTL** marks internal control, resource regulation, policy enforcement, and current-state management.
* **AUD** marks observability, monitoring, evidence collection, and independent checking.
* **INT** marks sensing, forecasting, learning, reasoning, adaptation, and future-state exploration.
* **POL** marks identity, direction, governance, values, and ultimate constraints.
* **ENV** marks the boundary between HelixForge and users, external systems, markets, investors, builders, and real-world problem contexts.
## 8\. OAS model commitments
Architecture descriptions in `helix-forge` should be compatible with the Orthogonal Architecture Standard.
### 8.1 Architecture documents
An OAS architecture document should contain:
* `standard` — the constant `OrthogonalArchitectureStandard`;
* `version` — a semantic version string;
* `architecture.id` — a stable identifier;
* `architecture.name` — a human-readable architecture name;
* `architecture.description` — an explanation of architectural purpose;
* `architecture.dimensions` — the six Orthogonal Architecture Dimensions;
* `architecture.elements` — capability, service, platform, policy, automation, and intelligence elements;
* `architecture.relations` — typed relationships between elements;
* `architecture.principles` — architectural principles relevant to the model;
* `architecture.sources` — source references when applicable;
* `architecture.metadata` — tool and repository metadata.
### 8.2 Element types
OAS-compatible element types are:
```text
Capability
Service
Application
PlatformService
DataStore
ControlComponent
ManagementInterface
Integration
Policy
Automation
IntelligenceComponent
```
Every element must have a stable `id`, `name`, `type`, and at least one dimensional `placement`.
### 8.3 Relation types
OAS-compatible relation types are:
```text
realizes
depends\_on
composes
exposes
governs
observes
hosted\_on
isolated\_by
augmented\_by
```
Relations should be used to explain architectural meaning, not merely technical adjacency. In particular:
* `realizes` connects an implementation to a capability;
* `depends\_on` expresses operational or architectural dependency;
* `composes` expresses higher-order assembly;
* `exposes` expresses an available surface or interface;
* `governs` expresses control, policy, or regulation;
* `observes` expresses audit, telemetry, or monitoring;
* `hosted\_on` connects runtime elements to stack substrate;
* `isolated\_by` explains tenancy or separation;
* `augmented\_by` connects an element to intelligence support.
### 8.4 Placement intent
Placements should answer: **where does this element belong by architectural concern?**
A `Service` might be placed at `Logic/L2`, `Plane/P1`, `Stack/S5`, and `Capability/C3`. A `Capability` might be placed at `Logic/L1` and `Capability/C5`. A `ControlComponent` should be placed in `Plane/P2`. An `IntelligenceComponent` should be placed in `Intelligence/I1` through `I5` and governed according to its autonomy.
## 9\. Semantic validation posture
HelixForge should treat semantic validation as architecture hygiene. A document can be structurally valid and still architecturally weak; semantic validation closes that gap.
The repository should support two validation profiles:
* **Draft profile** — suitable for exploration, discovery, and early modeling. Warnings are allowed when intent is still forming.
* **Production profile** — suitable for published or operational models. Key warnings become errors.
### 9.1 Normative semantic rules
The OAS semantic rule profile should be treated as the baseline for architecture validation:
|Rule|Intent|
|-|-|
|R1|Every `Service` must include `Logic/L2` and `Plane/P1` placements.|
|R2|Every `Capability` must include `Logic/L1` and one of `Capability/C1`, `Capability/C4`, or `Capability/C5`.|
|R3|Every `ControlComponent` must include `Plane/P2`.|
|R4|Every `ManagementInterface` must include `Plane/P3`.|
|R5|Every `IntelligenceComponent` must include an `Intelligence/I1` through `I5` placement.|
|R6|Every `Service` or `Application` should realize at least one `Capability`; production models should require this.|
|R7|Every `Intelligence/I5` element must be governed through a path to a `ControlComponent`.|
|R8|Every `Service`, `Application`, and `PlatformService` should reference `Q2` observability; production models should require this.|
|R9|Every `ControlComponent`, `ManagementInterface`, and `IntelligenceComponent` must reference `Q1` and `Q7`.|
|R10|Every hostable runtime element should have a `Stack` placement or `hosted\_on` relation; production models should require this.|
|R11|A `realizes` relation must connect a `Service` or `Application` to a `Capability`.|
|R12|A `governs` relation must originate from a `ControlComponent` or `Policy` and target a governed element.|
|R13|An `augmented\_by` relation must point to an `IntelligenceComponent`.|
|R14|Duplicate placements with the same dimension and level are forbidden.|
|R15|`Intelligence/I4` and `Intelligence/I5` elements should link to a control, management, or policy element; production models should require this.|
|R16|Only control, management, or policy elements should be placed directly in `Plane/P2` or `Plane/P3`.|
### 9.2 Validator behavior
A HelixForge validator should process models in four phases:
1. **Structural validation** against the OAS JSON Schema.
2. **Semantic indexing** of elements, placements, relations, sources, targets, and quality requirements.
3. **Semantic checks** using the rule profile.
4. **Report output** containing errors, warnings, and informational findings.
Production validation should upgrade R6, R8, R10, and R15 from warnings to errors.
## 10\. AI and intelligence governance
HelixForge may use deterministic automation, language interaction, reasoning systems, assisted fitting, and agentic delegation. These are architectural elements, not magic exceptions.
Any AI-assisted component must be placed in the Intelligence dimension and governed according to its autonomy:
* `I1` deterministic automation may execute scripted or rule-based actions.
* `I2` language interaction may translate between users and system models.
* `I3` knowledge and reasoning may infer, classify, recommend, or explain.
* `I4` assisted fitting may propose or configure system changes under governance.
* `I5` agentic delegation may act autonomously only within explicit policy, control-plane, and audit boundaries.
AI must not bypass the control plane. Agentic behavior must be observable, policy-bound, reversible where possible, and traceable to capability intent.
## 11\. Design principles
1. **Capability first.** Capabilities are stable intent; services and applications are realizations.
2. **Discovery and delivery co-evolve.** Natural language understanding and formal implementation must inform each other continuously.
3. **Dimensions stay orthogonal.** Plane, Stack, Quality, Logic, Intelligence, and Capability describe different concerns and must not be collapsed into one hierarchy.
4. **Validation is part of design.** Schemas and semantic rules are design instruments, not after-the-fact checks.
5. **Governance before autonomy.** Intelligence components must operate through control, management, policy, and audit structures.
6. **Reuse over accumulation.** The repository should grow by strengthening composable capabilities, not by collecting disconnected artifacts.
7. **Evidence over assertion.** Runtime behavior, telemetry, tests, contracts, and validation reports should back claims of readiness.
8. **Environment matters.** Users, builders, investors, external systems, markets, and real-world problems are part of the viable system boundary.
## 12\. Contribution intent
A contribution belongs in `helix-forge` when it strengthens at least one of these areas:
* capability discovery;
* capability modeling;
* OAS/OAD vocabulary or schema support;
* semantic validation;
* reusable capability contracts;
* reusable capability implementations;
* governed automation or intelligence;
* observability, audit, policy, or control;
* developer enablement;
* documentation that clarifies the forge process.
A contribution should be challenged when it:
* adds implementation without capability intent;
* introduces AI behavior without governance and observability;
* mixes architectural dimensions in a way that weakens model clarity;
* creates one-off assets that cannot be reused or composed;
* avoids validation despite being modelable;
* bypasses controlled vocabulary without proposing an explicit vocabulary change.
## 13\. Expected repository knowledge areas
The following knowledge areas should be represented in the repository or linked from the wiki once the supporting files are added:
|Area|Purpose|
|-|-|
|HelixForge vision|Defines why the project exists and what world it is trying to create.|
|Orthogonal Architecture Standard|Defines the structural schema for architecture descriptions.|
|OAS semantic validation|Defines the semantic rule profile and validation behavior.|
|Orthogonal Architecture Dimensions|Defines controlled architecture dimension vocabulary.|
|VSM-inspired information architecture|Defines viable-system functions and system roles.|
|Capability catalog|Captures reusable capabilities and their maturity.|
|Capability contracts|Defines interfaces, events, SLOs, ownership, and boundaries.|
|Validators|Turns architectural intent into executable checks.|
|Intelligence governance|Defines how automation, copilots, and agents are placed, governed, and audited.|
## 14\. Definition of done
A HelixForge artifact is done when it satisfies the appropriate level of intent, architecture, and validation for its maturity stage.
For a **draft** artifact:
* the problem or demand is understandable;
* the target capability is named;
* initial OAD placements are present;
* relevant VSM functions are identified;
* open questions and unresolved assumptions are explicit.
For a **production** artifact:
* capability intent, scope, ownership, and contract are documented;
* OAS structural validation passes;
* OAS semantic validation passes under the production profile;
* `Q1` security/compliance, `Q2` observability, and `Q7` governance/change are addressed where required;
* runtime or implementation artifacts realize the capability;
* relations to dependencies, hosting, governance, observation, and augmentation are explicit;
* AI or automation is governed and auditable;
* evidence exists through tests, telemetry, validation reports, or review records.
## 15\. Machine-readable intent anchor
```yaml
intent:
repository: helix-forge
product: HelixForge
purpose: >
Forge reusable software capabilities from real-world problems by uniting
human understanding with executable precision.
vision:
tagline: Evolving software capabilities
statement: >
Software capabilities should evolve with understanding, not guesswork.
architecture:
standard: OrthogonalArchitectureStandard
version: "1.0.1"
dimensions:
- Stack
- Logic
- Plane
- Quality
- Capability
- Intelligence
validation\_layers:
- structural\_schema
- semantic\_rules
validation\_profiles:
- draft
- production
oad\_codes:
plane: \[P1, P2, P3]
stack: \[S1, S2, S3, S4, S5]
quality: \[Q1, Q2, Q3, Q4, Q5, Q6, Q7]
logic: \[L1, L2, L3, L4]
intelligence: \[I1, I2, I3, I4, I5]
capability: \[C1, C2, C3, C4, C5]
vsm\_functions:
OPS: System 1 operations and activities
SYN: System 2 synchronization and coordination
CTL: System 3 internal control and regulation
AUD: System 3\* audit and monitoring
INT: System 4 intelligence and adaptation
POL: System 5 policy and identity
ENV: Environment boundary and surface
contribution\_test:
must\_strengthen\_one\_of:
- capability\_discovery
- capability\_modeling
- capability\_validation
- capability\_realization
- capability\_evolution
must\_not\_bypass:
- controlled\_vocabulary
- semantic\_validation
- governance\_for\_intelligence
- observability\_for\_runtime\_behavior
```
## 16\. Source inputs for this intent file
This file was drafted from the following project inputs:
* **HelixForgeVision** — project vision statement provided for this repository.
* **OrthogonalArchitectureSchema** — Orthogonal Architecture Standard Schema v1.0.1 and semantic validation profile.
* **260525-schema-orthogonalArchitecture.xlsx** — current OAD and VSM controlled vocabulary workbook.
When these materials are moved into the repository wiki, this file should be updated with stable wiki links.

View File

@@ -1,3 +1 @@
# repo-seed Evolving capabilities from intent to code
A git repository template to bootstrap coulomb projects from.

29
wiki/HelixForgeVision.md Normal file
View File

@@ -0,0 +1,29 @@
HelixForgeVision
*Evolving software capabilities*
## **HelixForge — Vision Statement**
**HelixForge envisions a world where software capabilities evolve with understanding, not guesswork.**
**HelixForge empowers a global ecosystem of users, builders, and investors to collaboratively forge reusable software capabilities from real-world problems—intertwining the natural-language art of discovery with the precise science of delivery in an evolving double helix, accumulating a battle-tested repository of composable intelligence that accelerates innovation for all.**
We believe the most powerful software is not merely built — it is *forged*:
through continuous dialogue between human meaning and machine precision.
HelixForge exists to unite **discovery and delivery** into a single evolutionary process, where natural-language understanding and formal implementation co-develop as two strands of the same helix. In this world, every demand can mature into a reusable capability, every capability can be assessed for both conceptual clarity and technical rigor, and every iteration strengthens the whole system.
Our vision is a capability-first development ecosystem where:
* problems are explored before they are solved,
* solutions are shaped for reuse from the start,
* implementation is guided by executable truth,
* and software assets grow in value through evolution, not accumulation.
HelixForge aims to become the forge where intent becomes structure,
structure becomes capability,
and capability becomes lasting progress.
**We evolve software capabilities by uniting human understanding and executable precision.**
xxx

File diff suppressed because it is too large Load Diff