Technical architecture

Doc type: Explanation · Applies to: POSE 5.x (current stable)

Status: Reference-grade, offline-first engineering operating standard
Updated: 2026-09-11 for the v5.0.2 release — mechanisms 2, 6, 7, 10, 11, 14 and 16 checked against the code of that release. The others were last verified 2026-08-17 against v1.4.3, after four consecutive real releases closed an 11-defect upgrade-path field audit against independently-owned repositories.

POSE is a repository-local governance system for human and AI-assisted software delivery. It combines a versioned operating contract, a native deterministic engine and an MCP adapter. It does not implement an IDE, an agent runtime or a hosted control plane; it governs how those systems may work inside a repository.

System context

flowchart LR
    H[Humans and reviewers]
    A[AI coding agents]
    CI[CI and Git hooks]
    P[pose native binary]
    I[Repository-owned POSE instance]
    V[Language toolchains]
    M[MCP clients]
    O[Optional OPA policy service]
    C[Optional Harne8 control plane]

    H --> I
    A --> I
    H --> P
    A --> P
    CI --> P
    P <--> I
    P --> V
    M <--> P
    P -. policy decision .-> O
    P -. run events .-> C

The repository remains the source of truth. POSE artifacts move through normal Git review, and the engine can operate without a network connection. External systems consume explicit contracts instead of owning the governance state.

Architectural principles

Keep governance with the code. Store specs, rules, workflows, evidence and operational knowledge in version control.
Separate deterministic decisions from semantic judgment. Let the CLI enforce syntax, lifecycle and repeatable gates; require humans or agents to decide intent, trade-offs and consequential follow-up disposition.
Close both sides of delivery. Gate entry with Definition of Ready and gate exit with evidence, completion metadata and follow-up triage.
Prefer adapters over duplicated engines. Reuse the same Go domain from the CLI and MCP server.
Fail closed at trust boundaries. Confine paths, reject legacy shell commands, deny policy failures and keep sensitive knowledge out of MCP.
Adopt incrementally. Start with visibility, promote stable checks to blocking gates and preserve existing repository content during upgrades.

Distribution and runtime

POSE ships as one CGO-free Go binary named pose. Release builds target Linux, macOS and Windows on amd64 and arm64. The binary contains:

the CLI dispatcher and native command implementations;
the embedded install scaffold for English and Brazilian Portuguese;
the POSE domain readers used by MCP;
the stdio and Streamable HTTP MCP transports;
the optional in-process policy and audit adapter.

The installed instance is data, not another runtime. pose install copies the contract and templates into the target repository, then runs init, index and check --strict. Reinstallation updates managed machinery while preserving specs, ADRs, roadmaps, knowledge and reports. .pose/schema-version allows the engine to apply ordered, idempotent migrations with pose update, verified against a populated instance (a real spec, knowledge note and hand-edited managed file) for dry-run non-mutation, schema-only apply and idempotent reapply. Releases publish through Homebrew and WinGet channels generated deterministically from the release's own checksums (pose release-package-manifests); pose doctor --fix turns a subset of diagnosable findings into confined, reversible, idempotent repairs.

Component model

Component	Responsibility	Primary implementation
Native CLI	Scaffold, validate, inspect, report, migrate and maintain	`pose-mcp/internal/cli/`
Governance domain	Read specs, roadmaps, knowledge, reports and insights	`pose-mcp/internal/pose/`
MCP server	Expose project-scoped governance tools	`pose-mcp/internal/mcpserver/`
Bootstrap	Resolve roots and wire transports, auth and policy	`pose-mcp/internal/bootstrap/`
Installer scaffold	Embed the repository contract and locales	`pose-mcp/internal/scaffold/`
Policy enforcement	Evaluate OPA decisions, identity and audit	`mcp-enforce/`
CI adapters	Run gates in GitHub Actions, pre-commit and Git hooks	`pose-action/`, `.pre-commit-hooks.yaml`
Documentation	Explain operation and public contracts	`docs-site/`, `AGENTS.md`, `POSE.md`

Installed contract

AGENTS.md                 short instruction and precedence contract
POSE.md                   operating manual
.agents/skills/           portable Agent Skills
.claude/skills/           Claude-compatible skill links
.pose/
  workflows/              task procedures
  rules/                  cumulative domain constraints
  templates/              governed artifact templates
  specs/                  living feature contracts
  roadmaps/               milestone dependency graphs
  adr/                    implementation decisions
  knowledge/              handoffs, notes and decision logs
  changelogs/             unreleased fragments and release notes
  indexes/                machine-readable projections and configuration
  reports/                evidence, history and retention archive
  policy/                 local policy data
  schema-version          instance/engine compatibility contract

Authoritative documents and generated projections are deliberately separated. Specs and roadmaps are authoritative; spec-graph.json and roadmaps.json are rebuildable indexes.

Mechanism 1: task routing

task-map.json maps a task type to its workflow, skill, cumulative rules, artifact obligations and validation command. pose suggest resolves that map and can add domain rules from an explicit domain or repository path.

This mechanism turns broad instructions such as “implement a feature” into a stable execution trail without embedding the trail in a prompt. It is also the boundary between generic POSE behavior and repository-specific policy.

Mechanism 2: spec lifecycle

Each spec carries flat, machine-readable frontmatter and seven narrative sections. The lifecycle is intentionally asymmetric:

stateDiagram-v2
    [*] --> draft
    draft --> in_progress: DoR gate passes
    draft --> abandoned
    in_progress --> blocked
    blocked --> in_progress
    in_progress --> done: closeout gate passes
    draft --> superseded
    in_progress --> superseded

lint-spec --ready-check requires intent, requirements with stable R<N> identifiers and a technical plan before execution. The Definition of Ready is opt-in: .pose/policy/dor.json ships with an empty adopted_at, and the gate applies to specs created on or after the date a project sets there.
lint-spec --strict requires completed_at and a disposition for every follow-up before done.
check validates status transitions and references at repository scope.

The spec remains a living contract: planning, decisions, validation strategy and final report stay together rather than becoming disconnected tickets. Each R<N> also carries a Requirement trace entry — [satisfied] with evidence refs, [waived: reason] or [withdrawn: reason] — projected bidirectionally through pose_requirement_trace, so a requirement's satisfying checks and commits are queryable, not just asserted. Material intent or acceptance-criteria changes after DoR are recorded as append-only, reviewed amendments (pose amend, amendments.jsonl) distinguished from editorial edits by a deterministic hash-based gate.

Mechanism 3: dependencies, readiness and roadmaps

depends_on accepts spec, milestone and roadmap references. priority orders eligible work without creating false dependencies. pose check verifies existence and acyclicity, while pose index builds the cached graph.

Roadmaps add milestone DAGs, target dates and exclusive membership of specs in active roadmaps. pose_spec_readiness resolves the graph for agents and control planes. This provides planning eligibility, not transactional task scheduling; fine-grained execution state belongs in an external control plane. pose portfolio-projection extends the same eligibility model across repositories through an additive xref: reference grammar, reusing the MCP server's own project-authorization boundary and surfacing explicit blocked/stale/unauthorized/unknown states rather than a silently outdated view.

Mechanism 4: workflows, rules and skills

Workflows define ordered procedures for feature, bugfix, review, refactor, documentation and recurrence escalation.
Rules accumulate constraints by domain. Security wins when rules conflict.
Skills package recurring agent behavior using the portable SKILL.md structure defined by the Agent Skills specification, continuously validated in CI (pose skills-check) with compatibility frontmatter (pose_schema_range, clients, capabilities).
AGENTS.md keeps precedence and mandatory obligations short enough for routine agent loading.
Extensions — skills, workflows, rules and import adapters not shipped in the base install — declare a versioned extension.json manifest (path confinement, permission whitelisting, provenance); pose extension install/list/remove/verify is dry-runnable, consent-gated and transactional. pose extension install <extension-id> also resolves the ID against the latest published GitHub release's signed assets, so a local directory is no longer required, and accepts a --locale flag for localized content.

The layers are independent so a team can change a security rule without forking every workflow or repeating the same instruction in every prompt.

Mechanism 5: repository discovery and indexes

pose index scans repository markers and materializes deterministic JSON:

repo-map.json: repository structure and detected modules;
services.json and packages.json: deployable and package views;
spec-graph.json: dependency projection;
roadmaps.json: roadmap projection;
task-map.json: routing configuration;
module-metadata.json: ownership, criticality, domain and validation profile.

Repository and module discovery share one stack detector across pose index, pose validate, pose install and pose init, recognizing Node.js, Go, Rust, Java, Python, .NET and Cloudflare Workers (wrangler.toml/ .json/.jsonc) modules.

pose init --wizard uses stack markers to seed validation configuration. Indexes are intentionally shallow and local; semantic code intelligence is a separate concern that Harne8 can supply through GraphForge.

Mechanism 6: deterministic validation

validation-matrix.json defines checks as structured program, args, env and optional file predicates. Legacy shell command strings are rejected. Checks are selected by stack and refined through module overrides.

flowchart LR
    T[Task type and affected path] --> S[pose suggest]
    S --> MM[Module metadata]
    MM --> VM[Validation matrix]
    VM --> R{required or optional}
    R -->|required failure| B[Blocking result]
    R -->|optional failure| W[Risk warning]
    R -->|pass| E[Evidence]

Supported baseline stacks are Node.js, Go, Rust, Java, Python (five package managers) and .NET; pose stacks reports detected stacks read-only. The matrix delegates to native project tools such as npm, go, cargo, Maven, Gradle, pip/poetry/pipenv/uv/conda and dotnet; POSE governs selection and evidence rather than replacing those ecosystems. --changed-from/--changed-to selects the minimum safe check set from declared dependency edges and policy widening, falling back to full execution for root-level or unmapped changes; --explain prints the selection trace. Per-check timeout and output-ceiling guardrails cancel by process group on Unix (documented Windows fallback); an isolation: "required" classification routes checks that must not run against untrusted local state to the Harness instead. Results emit through a canonical, versioned model with additive --json/--junit/--sarif projections alongside the native report; --report writes a report that lists the commands the run executed and derives its outcome from the run's own result.

Every check declares the evidenceClass it produces from one closed vocabulary — build, unit, integration, e2e, reachability, a11y, design-system, contrast, visual-regression, lint, typecheck, security-scan, contract — which is also the only vocabulary a review profile may demand. pose validate refuses a check outside it, and a profile that declares a class outside it fails to load. Static analysis is not reported as build: go vet emits lint.

Mechanism 7: evidence, history and insights

pose report persists a Markdown report and an append-only JSONL record. Each record includes task identity, workflow, validation profile, outcome, sequence and a stable-field hash. history-check prevents untracked history from being silently discarded.

pose stats aggregates outcomes by workflow, task or context. MCP exposes the same domain through pose_insights. pose stats governance is a separate read-only projection over report history, sealed review bundles and attestations: preparation, judgment, intervention, freshness, telemetry and coverage remain independent dimensions, with no aggregate quality score. MCP exposes that contract through pose_governance_stats; missing or invalid records remain visible rather than becoming zero. Reports can be archived by retention policy, but historical JSONL is preserved as the recurrence source. pose usage and MCP pose_usage read a separate best-effort journal outside the worktree. Recognized CLI commands and authorized project-backed MCP calls are observed automatically at their execution boundaries; the allowlisted schema keeps bounded outcomes, timing, counts and project-local HMAC fingerprints while excluding arguments, output, paths, source content and identity. Complete comparable finding sets support new/resolved/reopened transitions without agent-maintained counters. Human adjudication is not inferred; recording it is designed in the draft spec pose-usage-findings-adjudication.

pose record-deployment/record-incident capture quality-gated delivery events; pose dora-metrics derives all five current, production-scoped DORA metrics, including deployment rework rate and deployment-caused recovery, while pose adoption-metrics derives activation/time-to-first-gate/retention/task-success from the same local history — kept in separate reports so adoption is never blended into a DORA number as a false causal claim. events-housekeeping bounds retention.

POSE evidence is repository-auditable, not itself a cryptographic build attestation — but release artifacts it produces (Mechanism 10) do carry signed provenance and SBOMs; per-spec closeout evidence remains Git-history-integrity-protected rather than independently signed.

Mechanism 8: follow-ups and recurrence

Closeout dispositions form a controlled vocabulary: open, spawned, covered, duplicate, done or wont-do. pose followups aggregates the live backlog and suggests lexical near-duplicates. Semantic equivalence remains a reviewed decision. Open follow-ups end with ownership and a triage SLA in one trailing group, (owner:@alias crit:low|medium|high review:YYYY-MM-DD) — the only format read; pose followups --overdue and opt-in closeout blocking keep unowned or stale entries visible instead of silent.

recurrence-check scans historical failures by task slug and time window. The recurrence workflow converts repeated local fixes into a rule, workflow, spec or explicit exception. pose semantic-suggest adds advisory, cited, rationale-explained suggestions across knowledge, follow-ups and recurrence patterns (lexical similarity today, not an opaque score) with pose suggest-feedback recording accept/reject; an intervention registry (interventions.jsonl) feeds a deterministic before/after recurrence-effectiveness verdict once a systemic fix ships. This is the feedback edge that closes the governance loop.

Mechanism 9: operational knowledge

Knowledge artifacts have type, owner, sensitivity, creation/review dates and a bounded TTL. knowledge-check validates schema and overdue limits; housekeeping lists, archives and purges expired entries through explicit apply operations. Restricted entries are not returned by MCP. A stable knowledge:<slug> citation contract (dangling-reference gate) plus a derived knowledge-usage projection show when knowledge actually influenced work, not just that it was written; knowledge-suggest offers deterministic, sensitivity-filtered advisory retrieval.

Knowledge is not a vector database. Its purpose is small, reviewable operational memory that survives agent and session boundaries without becoming permanent, ownerless documentation.

Mechanism 10: change and release traceability

One changelog fragment is associated with each delivered spec. pose release prepare --apply consumes the selected queue exactly once and freezes canonical notes plus a candidate manifest; later tagged, published and verified records reconcile external facts against that immutable candidate rather than editing the tag or regenerating mutable notes. A release that introduces a governance contract carries a Compatibility section at the top of its notes, generated from the contract registry: what the contract requires and what adopting it costs an engine that does not know it. The pipeline builds six native platform targets through GoReleaser. GitHub Actions, pre-commit and native Git hooks provide progressively stronger adoption paths.

Every release archive is keyless-signed with Sigstore (offline-verifiable bundle, pinned issuer/identity policy), carries a per-archive CycloneDX SBOM (direct binary analysis, schema-validated) and a SLSA v1 provenance attestation (Build L2, with the L3 limitation stated explicitly rather than implied). An independent Verify release workflow re-derives trust from a clean environment — checksum, signature, SBOM and provenance, in that order — before ever executing the artifact; a versioned compatibility.json (engine/schema/upgrade pairs, support policy) backs a generated compatibility-report.md gate. The security workflow (CodeQL, govulncheck, gitleaks, dependency review) and an OpenSSF Scorecard workflow both publish results on every PR, push to main and weekly schedule.

Mechanism 11: MCP governance API

pose serve-mcp supports stdio and Streamable HTTP. The server advertises the full POSE governance surface — specs, readiness, roadmaps, changelogs, follow-ups, structural gates, task routing, workflows, rules, skills, knowledge, reports, insights and safe validation orchestration — frozen by a golden catalog fixture with an explicit risk class per tool. The catalog contains 47 POSE tools plus 3 optional Conductor reporters. Optional pose_validate_submit and conductor_run_* tools report external runs or submit to a Harness only when the corresponding Harne8 endpoints are configured.

MCP tools use JSON schemas and project-scoped root resolution. The server supports a default project plus explicit or directory-discovered roots. The MCP tools contract provides discovery and invocation; POSE keeps file mutations in the execution sandbox instead of exposing general-purpose write tools. Most tools answer by running the pose CLI: the server resolves that executable once, at start, so a server started before pose update keeps working with the binary installed at the same path. The stdio server exits on SIGTERM.

Mechanism 12: policy, identity and audit

HTTP mode can use bearer authentication. mcp-enforce adds:

principal and project extraction;
HMAC-bound execution identities with scopes, run ID and expiry;
OPA-backed per-call decisions;
default denial on policy transport, decode or undefined-path failures;
structured allow and deny audit events without payload content.

OPA remains the policy decision engine; POSE supplies scoped input and enforcement. Stdio mode inherits the security boundary of the spawning client. Production TLS, secret distribution and multi-replica coordination belong to the deployment environment.

Mechanism 13: interoperability and adoption

POSE imports Spec Kit and OpenSpec artifacts with a dry-run, bounded file and byte budgets, symlink rejection, batch preflight and a curation report. Import is intentionally one-way: POSE becomes the lifecycle authority after review. Three checked-in, executable adoption kits (examples/brownfield-kits/{direct-adoption,spec-kit-import,openspec-import}/) walk visibility→adoption→blocking-gate staged rollout against real, intentionally-imperfect fixtures, each verified end to end by a dedicated test. Monorepo adoption gets the same docs-as-tests treatment: three executed recipes (JS workspace, declared dependency graph, mixed-language with a shared high-criticality module) in docs-site/docs/monorepo-recipes.md.

Agents can consume the contract through repository files, Agent Skills or MCP. CI systems can call stable CLI commands. This keeps the core independent from one editor, model provider or hosted service.

Mechanism 14: localization, diagnostics and telemetry

The embedded distribution supports English and Brazilian Portuguese. Unknown locales fall back to English. pose doctor --json checks the binary, dependencies, instance, schema, skill links, MCP configuration and Git hooks, and diagnoses governance that would otherwise fail only downstream: a review profile demanding a class no check emits or no check produces, checks with no evidenceClass, a profile below the enforced schema, a contract with no adoption date, and keys in any of nine policies that the engine does not read — the way a misspelled setting silently does nothing. The full list is in the CLI reference.

Telemetry is disabled by default. Enabling it still sends nothing until an endpoint is explicitly configured. The payload is limited to anonymous ID, binary version and command name; repository names, paths and content are excluded by contract.

Mechanism 15: Harne8 control-plane composition

Five responsibilities compose without moving repository authority (spec pose-harne8-control-plane-integration):

Component	Responsibility	Consumes/exposes
POSE (this repository's engine)	Governs — owns specs, gates, evidence, policy input	CLI, MCP tools
Conductor	Orchestrates idempotent governed runs with approvals	`conductor_run_*`, `pose_validate_request/approve/submit/status/cancel`
Harness	Executes an approved, digest-pinned plan	`HarnessExecutor.Submit`, reconciled back via `pose reconcile-evidence`
GraphForge	Contextualizes (semantic code graph)	Consumes `pose portfolio-projection` and `pose semantic-suggest` output
Portal	Presents (portfolio, review UI)	Consumes policy-filtered projections; never a second lifecycle authority

Review follows the same ownership boundary. POSE prepares and seals a portable semantic ReviewBundle, verifies its separate attestation and remains the offline closeout authority. Conductor may assign reviewers, persist retries, manage findings and return a signed attestation envelope, but it cannot redefine the bundle or waive POSE policy. Recording the attestation, closing the scope and refreshing derived state never alter the approved bundle digest.

Every boundary already ships in the open core, testable without any Harne8 component present: pose_validate_submit returns a clear configuration error (not a crash) when no Harness is wired; pose reconcile-evidence rejects a second, silent record for an already-reconciled request unless --allow-supersede is passed explicitly, and even then appends a new, identity-bound record rather than editing the prior one; pose portfolio-projection and pose semantic-suggest are exactly the policy-filtered, tenant-scoped projections Portal/GraphForge would consume. pose_validate_submit's idempotent resubmit (same execution_id, no re-invocation) is the durable-state contract Conductor composes with, not replaces — the in-process registry is a local reference implementation; a real multi-replica deployment centralizes run state in Conductor itself.

Offline degradation is structural, not a fallback mode: no open-core command requires CONDUCTOR_URL, POSE_MCP_IDENTITY_SECRET, HARNE8_PROJECTS_DIR or any other Harne8-related environment variable — every one of them is optional, and their absence degrades a specific optional tool to a configuration error rather than blocking anything else. SLOs, backpressure, retry policy and disaster recovery for the hosted components (Conductor, Harness, GraphForge, Portal) are Harne8's own operational responsibility, out of this repository's scope by design (Non-goal: never move repository authority into a required hosted service).

Mechanism 16: component-aware review and sealed bundles

pose review-plan resolves, per component, which review profiles apply and which criteria and tools they demand; each criterion lists the evidence classes that satisfy it, any one of which is enough. pose review bundle --seal then freezes the review subject as an immutable rvb- bundle: the attributed change sets, the plan and the profiles it selected, the required evidence identities, the governance contracts in force, and the gates that decide it — reservations, accepted-risk severities and criterion reuse. Verification reads all of these from the bundle, never from the policy as it stands later; only the signing requirement is read live, so tightening it reaches old bundles.

Three governance contracts are registered — component-aware, review-bundles and evidence-vocabulary — each with the release that introduced it and an adoption date in the review policy. Adding one to the registry is what makes pose update stamp it, pose doctor report it and the release notes announce it.

An attestation binds to one bundle digest. A criterion recorded passed must cite evidence the bundle contains, of an accepted class, from the component the criterion is about — evidence from a directory inside a component does not answer for the component. Findings carry severity, action and a disposition; an accepted risk needs a severity the sealed gates accept, an owner, a rationale and a review date. pose review verify, review-check and closeout-check then decide freshness, completeness and closure.

flowchart LR
    P[review-plan per component] --> V[validate with evidence classes]
    V --> B[review bundle --seal]
    B --> A[attest: criteria, tools, findings]
    A --> C[review verify / closeout-check]

Primary data flows

Feature delivery

sequenceDiagram
    participant U as Human or agent
    participant P as pose CLI
    participant R as Repository
    participant T as Toolchains

    U->>P: new-spec / import
    P->>R: create draft spec
    U->>P: lint-spec --ready-check
    P-->>U: entry verdict
    U->>P: suggest feature
    P-->>U: workflow + skill + rules + check
    U->>P: validate
    P->>T: run structured checks
    T-->>P: results
    P->>R: report + history
    U->>P: lint-spec --strict
    P-->>U: closeout verdict

MCP read path

sequenceDiagram
    participant A as MCP client
    participant G as Policy gate
    participant S as POSE server
    participant R as Project root

    A->>S: tools/call(project_id, arguments)
    S->>G: principal + identity + project + tool
    G-->>S: allow or deny
    S->>R: confined read or deterministic gate
    R-->>S: structured result
    S-->>A: content + structuredContent

Extension boundaries

Extend POSE safely through repository data before changing the engine:

add task types to task-map.json;
add cumulative rules and workflows;
add Agent Skills;
add structured matrix checks and module overrides;
consume reports and indexes from external systems;
add narrow MCP tools with explicit schemas and risk classification.

Engine changes are appropriate when a deterministic invariant must be shared by every installation. Hosted orchestration, semantic code graphs, durable task state and visual portfolio management belong to Harne8 rather than the free repository engine.

Known architectural limits

POSE does not execute or schedule AI agents by itself.
Roadmaps model eligibility and ordering, not capacity or transactional work.
Cross-repository portfolio projections and DORA/adoption metrics never fabricate capacity, velocity or an ETA — only what was explicitly recorded or already governed locally.
Reports are auditable Git artifacts but are not signed attestations.
MCP is deliberately tool-only: list tools paginate with opaque cursors and the catalog is stable within a process lifetime, but resources and prompts are not implemented — a generic resources primitive would expose repository files wholesale, and prompts risk becoming policy outside .pose/workflows/, both explicitly out of scope (see MCP server).
The baseline validation matrix covers six stack families (Node.js, Go, Rust, Java, Python, .NET) and relies on repository overrides for other ecosystems.
Remote MCP deployment identity, secret management, TLS and rate limiting remain deployment-environment responsibilities — no roadmap in this portfolio targeted workload identity (SPIFFE) or a policy/audit-export layer beyond the existing OPA decision plus bounded, non-payload audit events.

Use the capability assessment for scored maturity, evidence and prioritized gaps.