Plan-002 — semantic module contract (issue #78)
Contents of the Plan-002 bundle.
Open source Repository Open in the app JSON README (API)
About
# Plan-002 — semantic module contract (issue #78)
## Contents
* [Plan-002: semantic module contract (issue #78)](./plan.md) - Plan overview, DAG, tracks, gates, test plan.
* [Task-007: Toolchain: pinned TypeSpec package, semantic-core resolution, engine wheel, LF pin](./tasks/Task-007-toolchain-and-engine.md) - The enablement nothing else can start without.
* [Task-008: FR-009 — the projection generator, its preconditions and the drift gate](./tasks/Task-008-generator-and-drift-gate.md) - Source to shipped bytes, and the refusal when they disagree.
* [Task-009: FR-009 + FR-013 — one model per artifact type, with the definition/occurrence rule as an authoring gate](./tasks/Task-009-models-and-role-gate.md) - Twelve models, role-checked while written.
* [Task-010: GATE — SpecReview end to end](./tasks/Task-010-gate-specreview-slice.md) - One type proven through model, mapping, skeleton, golden record and negatives.
* [Task-011: FR-010 — the semantic block, reference-form data_schema, a
Details
- Kind
- OKF bundles
- Topic
- No topic detected
- Publisher
- agent-ix
- Origin
- okf_github
- Category
- dados
- Version
- 0.1
- Stars
- 1
- Open pull requests
- 3
- Last push
- 2026-09-06T22:25:22Z
- Repository state
- ativo
- Language
- Python
- License
- AGPL-3.0
- Added
- 2026-09-09 05:08:26
- Updated
- 2026-09-09 05:08:26
- Origin id
agent-ix/spec-artifacts-process:plan/Plan-002-semantic-module-contract/index.md
README
# spec-artifacts-process
> Filament Module: process artifact templates (ADR, Plan, Task, Review, Finding, TestMatrix, Standard) — Jinja .md.j2 templates
Agent-IX Filament module loaded by [`quire-cli`](https://github.com/agent-ix/quire-cli) and [`quoin`](https://github.com/agent-ix/quoin).
## Installing quire-cli
`@agent-ix` packages are published to public npm. Install the CLI globally:
```bash
npm install -g @agent-ix/quire-cli
```
See https://github.com/agent-ix/quire-cli#install for details.
## Install this module via npm
This module is also published as a config-only npm package: `@agent-ix/spec-artifacts-process`.
The package root **is** the Filament module (`manifest.yaml` + schemas/skeletons),
so it works directly as a `--module` target or via quoin's `package:` source.
```bash
npm install @agent-ix/spec-artifacts-process
```
```bash
# quoin — resolve the module from npm by name
quoin plugin install package:@agent-ix/spec-artifacts-process
# or point any tool at the installed package root
quire validate spec/**/*.md --module node_modules/@agent-ix/spec-artifacts-process
```
## Artifact types provided
| Kind | ID pattern | Description |
|------|------------|-------------|
| ADR | `ADR-{next:03d}` | Architecture Decision Record capturing a decision, its context and consequences; moves through `proposed → accepted → superseded → rejected` states and links via `supersedes`/`superseded_by`/`relates_to`/`depends_on`. |
| Plan | `Plan-{next:03d}` | An implementation plan that owns a set of member Tasks (expected artifact `Task`); links via `contains`/`depends_on`/`references`. |
| Task | `Task-{next:03d}` | A single unit of implementation work; links via `depends_on`/`verifies`/`references`. |
| Review | `Review-{next:03d}` | A review document that owns a set of member Findings (expected artifact `Finding`); top-level nav item, links via `reviews`/`references`. |
| Finding | `Finding-{next:03d}` | An individual review finding/issue; links via `found_in`/`blocks`/`references`. |
| TestMatrix | `TestMatrix-{next:03d}` | A requirement-to-test coverage matrix; links via `covers`/`references`. |
| Standard | `Standard-{next:03d}` | A normative standard definition with a stable `code` slug, description and application guidance; links via `references`. |
All artifacts share the `process-artifacts` grammar and require `id`, `title`, and `type` frontmatter; Standard additionally requires `code`.
### Object type: `standard`
The module also exposes a `standard` object type. It extracts a stable `code` slug (required), optional `name`/`link` frontmatter, a `description` from the **Description** section body, and a `guide` from the **Application Guidance** section body. These objects are referenced from spec frontmatter `standards_alignment[]`.
## How this module is used
### With quoin (recommended)
```bash
quoin plugin install path:../spec-artifacts-process
quoin catalog list
quoin catalog show ADR
quoin write . --types ADR,Plan
quoin review
```
See https://github.com/agent-ix/quoin.
### With quire-cli directly
```bash
quire schema ADR --module ./spec_artifacts_process
quire validate spec/**/*.md --module ./spec_artifacts_process
quire extract <DOC> --module ./spec_artifacts_process --archetype ADR
```
See https://github.com/agent-ix/quire-cli#usage-instructions.
## Development
- **Library:** `spec_artifacts_process` (flat layout, Python 3.13+, [Poetry](https://python-poetry.org/))
- **Build & CI:** GitHub Actions; dynamic Git-tag-based versioning; published to Google Artifact Registry via `twine upload -r internal-pypi`.
```bash
make install # install dependencies in Poetry venv
make test # run pytest
make lint # ruff + black check
make format # ruff + black format
make build # build wheel and sdist under dist/
make update-lock # update poetry.lock
make use-local p=<name> # switch dep to local pypi.ix
make use-upstream p=<name> # switch dep back to upstream
make local-publish # build and publish to local pypi.ix
```
Required CI secrets/variables: `GCP_SERVICE_ACCOUNT_KEY`, `GCP_REGION`, `GCP_PROJECT_NAME`, `GCP_PYPI`.