Polyweave

Repositories

1

Projects Packages

@polyweave/sdlc-domain (1.0.6)

Published 2026-07-11 15:32:03 +00:00 by Dvorak

Installation

Set up this registry in your project .npmrc file:

@polyweave:registry=https://hub.kl1.tenere.ai/api/packages/Polyweave/npm/

To install the package using npm, run the following command:

npm install @polyweave/sdlc-domain@1.0.6

or add it to the package.json file:

"@polyweave/sdlc-domain": "1.0.6"

For more information on the npm registry, see the documentation.

About this package

@polyweave/sdlc-domain

Software Development Lifecycle domain model for htna-stream HGN/HTN/BT tripartite planning. Defines the full workflow from snow card requirements through TLA+ specification to red-green-refactor implementation, with staleness propagation and exception-driven replanning.

Synopsis

import {
  SDLC_DOMAIN,
  SDLC_TYPE_SYSTEM,
  SDLC_GOALS,
  SDLC_METHODS,
  SDLC_PRIMITIVES,
  SDLC_INVARIANTS,
  SDLC_ABORT_SCENARIOS,
  createSdlcHarness,
  createPlannerBridge
} from '@polyweave/sdlc-domain';

const harness = createSdlcHarness({
  evaluatorAdapter: myEvaluator,
  agentAdapter: myAgent
});

const bridge = createPlannerBridge({
  jjProvider: myJjProvider,
  stateStore: myStateStore
});

Install

npm install @polyweave/sdlc-domain

Why

HGN/HTN/BT planners need a structured domain model to decompose "build a software feature" into actionable primitives. This package provides the complete domain definition — goals, methods, types, invariants, abort scenarios — for modeling the full SDLC: requirements engineering (snow cards, question identification, coverage validation), TLA+ formal specification (modeling briefs, module scaffolding, SANY/TLC checking with counterexample explanation), architecture design (dependency analysis, task graphs), red-green-refactor implementation (code writing, testing, review, security scanning), and verification (trace bridging, staleness propagation, conflict resolution). It also includes bt-harness and planner-bridge adapters to wire the domain model into the Polyweave execution framework.

API

Domain Constants

SDLC_DOMAIN

The full SDLC domain definition object.

{
  name: 'sdlc',
  version: '1.0.0',
  description: 'Software Development Lifecycle domain — full workflow from snow cards to verification',
  typeSystem: SDLC_TYPE_SYSTEM,
  goals: SDLC_GOALS,
  methods: SDLC_METHODS,
  primitives: SDLC_PRIMITIVES,
  invariants: SDLC_INVARIANTS,
  abortScenarios: SDLC_ABORT_SCENARIOS,
  phases: { requirements, specification, design, implementation, verification },
  executorMap: { ... }  // Maps primitive executor names to descriptions
}

Each phase in phases specifies: order (1-5), goals (array of goal names), and methods (array of method names available for that phase).

The executorMap maps 26 executor names (e.g. 'tla-card-ingestor', 'polyweave-tla-tlc-runner', 'polyweave-code-writer') to deterministic, LLM, or stochastic activity descriptions.

SDLC_TYPE_SYSTEM

Type system defining SDLC entity types, value enums, type hierarchy, and predicate signatures.

{
  types: {
    Deliverable, Specification, SnowCard, AcceptanceCriteria, Worktree, TestSuite,
    ModelingBrief, TlaModule, TlaConfig, QuestionArtifact,
    DeliverableStatus: ['pending','in_progress','ready','failed','stale'],
    SpecificationStatus: ['draft','under_review','approved','stale','deprecated'],
    SnowCardStatus: ['open','clarified','resolved','deferred'],
    Priority: ['low','medium','high','critical'],
    ActivityType: ['llm','stochastic','deterministic'],
    Phase: ['requirements','specification','design','implementation','verification'],
    CheckFamily: ['tar_pit','api_design','hateoas','crash_only','tla_checks','tiger_style','nasa_power_of_ten','data_oriented_design'],
    RefinementLevel: ['L0','L1','L2','L3']
  },
  typeHierarchy: {
    CodeDeliverable → Deliverable, TestDeliverable → Deliverable,
    DocDeliverable → Deliverable, ConfigDeliverable → Deliverable,
    ServiceSpec → Specification, SubsystemSpec → Specification,
    ModuleSpec → Specification, InterfaceSpec → Specification
  },
  predicateSignatures: { deliverable_exists, spec_not_stale, tlc_passed, ... }
}

54 named predicates are defined with their argument types.

SDLC_GOALS

Hierarchical goal definitions across 5 phases:

Goal	Phase	Description
RequirementsCaptured	1	All snow cards ingested, ACs defined, questions resolved.
StakeholdersIdentified	1	Stakeholders, goals, constraints documented.
SpecApproved	2	Specification exists, approved, not stale.
TlaModulesGenerated	2	TLA+ modules exist and pass syntax checks.
SafetyInvariantsProven	2	All safety invariants hold under TLC.
LivenessConfirmed	2	All liveness properties confirmed.
SubsystemBoundariesDefined	1	Subsystem boundaries, actors, state variables, actions enumerated.
ArchitectureDefined	3	Module architecture, API surfaces, dependency graph mapped.
TaskGraphBuilt	3	Complete task graph with dependency ordering.
CodeReady	4	Code written, syntax-valid, tested, reviewed, secure.
CodeWritten	4	Source code exists and passes syntax check.
TestsPass	4	Tests exist and pass.
CodeReviewed	4	Code review completed.
SecurityScanned	4	Security scan passed.
DepsResolved	3	All dependencies resolved.
AllInvariantsSatisfied	5	All domain invariants satisfied.
SpecImplementationCoherence	5	Spec and implementation coherent.
FeatureComplete	5	All deliverables CodeReady, specs approved and coherent.

Each goal has params (typed parameter list with optional types like ?specId:Specification), clauses (conjunctive/disjunctive predicate conditions with optional quantifiers), precedence, and description.

SDLC_METHODS

Method specifications that decompose goals into subgoals, primitives, and ordering constraints:

Method	Decomposes	Strategy
AchieveRequirementsCaptured	RequirementsCaptured	Ingest → Identify → Resolve → Draft → Validate
AchieveSpecApproved_TLASynthesis	SpecApproved	Full TLA+ pipeline: brief → scaffold → SANY → TLC → classify → explain → document
AchieveSpecApproved_RefinementLadder	SpecApproved	L0 → L1 → L2+ refinement ladder with quality checks
AchieveTaskGraphBuilt	TaskGraphBuilt	Analyze → Interfaces → Stubs → Graph → Estimate
AchieveCodeReady_TDD	CodeReady	Test-first: WriteTest → RunTest → WriteCode → Validate → RunTests → EditCode → Review → Scan
AchieveCodeReady_Incremental	CodeReady	Write → Validate → Test → Edit (no review/scan)
AchieveCodeReady_Parallel	CodeReady	Parallel: [WriteCode, WriteTests, WriteDocs] → [RunTests, ValidateSyntax, CodeReview]
AchieveSpecImplementationCoherence	SpecImplementationCoherence	Trace → Validate → CheckStaleness → Report → Reconcile → Replan

Each method specifies: goal, params, description, precondition (array of predicate clauses), subgoals (goal/subgoal decomposition), primitives (action list), ordering (before/after constraints), priority (1-5, lower = preferred). Some methods include constants (invariant predicates that must hold) and parallel groups.

SDLC_PRIMITIVES

Primitive operation definitions — the leaf nodes executed as actual LLM/tool calls:

Primitive	Activity	Executor	Approx Cost
IngestSnowCards	deterministic	tla-card-ingestor	500ms
IdentifyQuestions	llm	polyweave-question-identifier	3000ms
ResolveQuestions	stochastic	polyweave-question-resolver	5000ms
DraftEnglishSpec	llm	polyweave-spec-writer	10000ms
ValidateCoverage	deterministic	polyweave-coverage-validator	200ms
GenerateModelingBrief	llm	polyweave-modeling-brief-generator	8000ms
ScaffoldTlaModule	llm	polyweave-tla-scaffolder	5000ms
RunSANYCheck	deterministic	polyweave-tla-sany-runner	2000ms
RunTLCCheck	deterministic	polyweave-tla-tlc-runner	10000ms
ClassifyFailure	llm	polyweave-failure-classifier	2000ms
ExplainCounterexample	llm	polyweave-counterexample-explainer	3000ms
StaleCheck	deterministic	polyweave-stale-checker	100ms
WriteCode	llm	polyweave-code-writer	30000ms
WriteTest	llm	polyweave-test-writer	15000ms
RunTests	stochastic	polyweave-test-runner	5000ms
ValidateSyntax	deterministic	polyweave-syntax-checker	100ms
EditCode	llm	polyweave-code-editor	10000ms
CodeReview	llm	polyweave-code-reviewer	8000ms
SecurityScan	stochastic	polyweave-security-scanner	3000ms
TraceBridge	deterministic	polyweave-trace-bridge	1000ms
ValidateAgainstSpec	deterministic	polyweave-spec-validator	2000ms
CheckStaleness	deterministic	polyweave-state-checker	50ms
ResolveConflicts	llm	polyweave-conflict-resolver	5000ms
TriggerReplan	deterministic	polyweave-replan-trigger	1ms
BounceBackCheck	deterministic	polyweave-bounceback-checker	200ms

Each primitive specifies name, description, activityType ('llm', 'stochastic', or 'deterministic'), executor (maps to SDLC_DOMAIN.executorMap), preconditions (predicate clauses), postconditions, effects (with optional conditional branches), constants, and approxCost.

SDLC_INVARIANTS

An array of invariant constraints that must hold across the SDLC workflow:

Invariant	Type	Description
deliverable_status_type	type	Status must be a valid DeliverableStatus value.
spec_status_type	type	Status must be a valid SpecificationStatus value.
snow_card_status_type	type	Status must be a valid SnowCardStatus value.
no_concurrent_status	exclusion	A deliverable cannot be both in_progress and failed.
no_stale_and_approved	exclusion	A spec cannot be both approved and stale.
single_critical_priority	cardinality	At most 1 deliverable with critical priority.
all_deliverables_have_status	forall	Every deliverable has a status.
all_specs_have_level	forall	Every specification has a refinement level.
all_deliverables_have_phase	forall	Every deliverable has a phase.
written_implies_exists	implication	code_written(d) → deliverable_exists(d).
tests_pass_implies_tests_exist	implication	tests_pass(d) → tests_exist(d).
code_reviewed_implies_written	implication	code_reviewed(d) → code_written(d).
approved_implies_not_stale	implication	spec_status(s, approved) → spec_not_stale(s).
tlc_passed_implies_module_valid	implication	tlc_passed(m) → tla_module_valid(m).
stale_spec_stales_dependents	implication	Stale spec → all implementing deliverables become stale.
no_self_dependency	exclusion	No depends_on(d, d).
implementation_requires_spec	implication	Deliverable in implementation phase requires an approved spec.

SDLC_ABORT_SCENARIOS

Exception scenarios that trigger replanning:

Scenario	Trigger	Actions
spec_staleness_aborts_write_code	spec_not_stale becomes false during WriteCode	Abort LLM call, mark deliverable stale, replan.
contradictory_requirements	Two acceptance criteria contradict each other	Emit contradiction diagnosis, stale affected specs, replan requirements.
tlc_counterexample_discovered	tlc_passed becomes false	Classify failure, explain counterexample, generate spec patch, rerun TLC.
dependency_merge_conflict	Parallel workspaces produce conflicting changes	Create conflict resolution workspace, LLM resolve, retry merge.
question_gate_unresolved	question_state is deferred	Emit operator gate blocked, stale affected specs, planner noop until resolved.

createSdlcHarness(options)

Creates a bt-harness-based SDLC execution tool. Delegates to createBtHarness from @polyweave/bt-harness.

Name	Type	Required	Default	Description
options.evaluatorAdapter	IFrameDuplex	no	undefined	Evaluator adapter for bt-harness.
options.agentAdapter	IFrameDuplex	no	undefined	Agent adapter for bt-harness.
options.jjProvider	object	no	null	JJ provider for workspace operations.
options.stateStore	object	no	null	State store for domain artifacts.
options.templates	object	no	{}	BT templates.
options.maxIterations	number	no	20	Maximum BT execution iterations.
options.onTxnBegin	function	no	undefined	Transaction begin callback.
options.onTxnCommit	function	no	undefined	Transaction commit callback.
options.onTxnAbort	function	no	undefined	Transaction abort callback.

Returns: { source, sink } — a bt-harness duplex from @polyweave/bt-harness.

Error conditions: None from this function directly. Errors from createBtHarness propagate.

createPlannerBridge(options)

Creates a frame duplex bridge between the SDLC domain and htna-stream planning. Handles plan actions, continuations, completions, and failures.

Name	Type	Required	Default	Description
options.enricher	object	no	createBtEnricher(options)	BT enricher instance.
options.jjProvider	object	no	null	JJ provider for workspace operations.
options.stateStore	object	no	null	State store for domain artifacts.
options.autoCommit	boolean	no	true	Automatically start BT execution on plan:actions.
options.btHarnessFactory	function(context): IFrameDuplex	no	null	Factory for creating bt-harness instances. Must be set before plan:actions frames arrive.
options.name	string	no	null	Name for the duplex.

Returns: IFrameDuplex — frame duplex with source and sink.

Frame Protocol (Input → Output)

Input Frame Type	Content	Output Frame Type	Content
START	(any)	START	{ phase: 'planner-bridge-ready' }
END	(any)	END	{ phase: 'planner-bridge-shutdown' }
(any)	{ type: 'plan:actions', actions, composition, continuation, contextId, requestId }	DATA	{ type: 'bt:execution_started', executionId, actionCount, ... }
(any)	(bt-harness emits) bt:node_completed	PROGRESS	{ type: 'bt:node_completed', nodeId, completed, total }
(any)	(bt-harness emits) bt:node_failed	PROGRESS	{ type: 'bt:node_failed', nodeId, evidence }
(any)	(bt-harness emits) bt:tree_complete	DATA	{ type: 'bt:tree_complete', actions, continuation }
(any)	(bt-harness emits) bt:symbolic_asserted	DATA	{ type: 'bt:symbolic_asserted', update }
(any)	(all complete)	DATA	{ type: 'execution:complete', stats: { completed, failed, total, duration } }
(any)	{ type: 'plan:continuation' }	DATA	{ type: 'plan:continuation_received' }
(any)	{ type: 'plan:complete' }	END	{ type: 'plan:complete', contextId }
(any)	{ type: 'plan:failure', reason }	ERROR	{ type: 'plan:failure', reason }
(any)	{ type: 'unknown' }	ERROR	{ error: 'Unknown data type: ...' }
(any)	{} (no type field)	ERROR	{ error: 'Missing type in frame content' }
(any)	(btHarnessFactory missing)	ERROR	{ error: 'btHarnessFactory not configured. Set options.btHarnessFactory.' }

Error conditions:

• btHarnessFactory not configured: Responds with ERROR frame without throwing.
• Missing type in frame content: Responds with ERROR frame without throwing.
• Unknown data.type: Responds with ERROR frame without throwing.

createDefaultBtHarnessFactory(options)

Default factory for creating bt-harness instances from SDLC method specs.

Name	Type	Required	Default	Description
options.evaluatorAdapter	IFrameDuplex	no	undefined	Evaluator adapter.
options.agentAdapter	IFrameDuplex	no	undefined	Agent adapter.
options.jjProvider	object	no	undefined	JJ provider.
options.stateStore	object	no	undefined	State store.
options.enricher	object	no	createBtEnricher()	BT enricher instance.
options.maxIterations	number	no	20	Maximum BT iterations.
options.workspaceDir	string	no	null	Workspace directory path.

Returns: function(context): IFrameDuplex — factory function that receives { executionId, actions, composition } and returns a createBtHarness duplex with an enriched BT tree.

createBtEnricher(options)

Creates a reusable BT enricher that augments BT nodes with SDLC-specific tool grants, task descriptions, and success criteria.

Name	Type	Required	Default	Description
options.domain	object	no	SDLC_DOMAIN	Domain definition with reactive layer and executorMap.

Returns: { enrichNode, enrichBatch, getToolMounts, reactiveLayer, executorMap }

Field	Type	Description
enrichNode(node, context)	function	Recursively enriches a BT tree node with taskDescription, successCriteria, constraints, example, toolGrants, timeoutMs, maxAttempts. Tool grants default to ['write_file', 'read_file', 'list_files', 'run_command', 'jj_status', 'jj_commit', 'jj_diff'].
enrichBatch(actions, composition, context)	function	Enriches an array of actions plus an optional composition.
getToolMounts(node, jjProvider, workspacePath)	function	Returns tool adapter mounts for a node based on its toolGrants. Classifies tools as JJ tools (jj_*), state tools (state_*, doc_*, tree_*, etc.), or generic tools.
reactiveLayer	object	The domain's reactive layer (BT tree definitions).
executorMap	object	Maps executor names to descriptions.

Tool grants are automatically inferred from node names:

• Write/Generate → write_file, read_file, list_files, edit, run_command, jj_*, state_query
• Read/Review/Analyze → read_file, list_files, doc_read, state_query, llm_reason
• Test/Run/Check → run_command, read_file, list_files, state_query, doc_read
• Search/Research → websearch, webfetch, webread, text_index, text_search, llm_summarize
• Commit/Merge/Resolve → jj_commit, jj_diff, jj_status, jj_resolve, jj_merge
• State/Verify/Validate → state_query, state_query_dsl, doc_read, doc_relate, tree_navigate

enrichBtTree(tree, domain, context)

Convenience function that creates a BT enricher and enriches a single tree.

Name	Type	Required	Default	Description
tree	object	yes	—	Raw BT tree to enrich.
domain	object	no	undefined	Domain object (defaults to SDLC_DOMAIN inside the enricher).
context	object	no	{}	Context passed to enrichNode.

Returns: Enriched BT tree (same structure with added fields).

Tests

npm test

Runs node --test test/*.test.js. Covers domain definition integrity, type system validation, goal hierarchy decomposition, method-to-BT-spec translation, harness creation, planner bridge integration, BT enrichment, and staleness propagation scenarios.

Requirements

Node.js 22 or later. ESM only.

Peer dependencies: @polyweave/bt-harness, @polyweave/state, @polyweave/tla-runner, @polyweave/core, @polyweave/jj-provider.

Caveats

• The SDLC domain is a planning/execution model, not a CI/CD system. It generates artifacts and tracks dependencies; actual code execution is delegated to tools.
• Method specifications define decompositions but do not guarantee optimal plans — the HTN planner selects the first applicable method.
• Staleness propagation handles dependency chains but requires accurate artifact versioning from the underlying state store.

Dependencies

Development Dependencies

ID	Version
@rigor/core	*

Peer Dependencies

ID	Version
@polyweave/bt-harness	*
@polyweave/core	*
@polyweave/jj-provider	*

Keywords

polyweave sdlc htna-stream hgn bt-harness software-development tla-plus

Details

npm

2026-07-11 15:32:03 +00:00

5

John Dvorak

SEE LICENSE IN LICENSE

latest

18 KiB

Assets (1)

sdlc-domain-1.0.6.tgz 18 KiB

Versions (3) View all

1.0.6 2026-07-11

1.0.3 2026-07-11

1.0.2 2026-07-10