Plan-001 — semantic data schemas and Markdown mappings
Contents of the Plan-001 bundle.
Open source Repository Open in the app JSON README (API)
About
# Plan-001 — semantic data schemas and Markdown mappings
## Contents
* [Plan-001: semantic data schemas and Markdown mappings](./plan.md) - Plan overview, dependency graph, tracks, gate, test plan.
* [Task-001: TypeSpec models realigned with the reviewed requirement](./tasks/Task-001-typespec-models.md) - main.tsp brought into line with FR-005 and regenerated.
* [Task-002: the schema-projection test suite](./tasks/Task-002-projection-suite.md) - bundle shape, offline refs, digest identity, drift gate.
* [Task-003: the manifest semantic block and digest references](./tasks/Task-003-manifest-semantic-block.md) - the FR-070 block, ten digest references, the invariants locator.
* [Task-004: Gate — a record built from a real skeleton validates](./tasks/Task-004-record-shape-gate.md) - measures whether the models describe what the locators extract.
* [Task-005: mappings.yaml, its schema, and the golden records](./tasks/Task-005-mappings-and-goldens.md) - the declared mapping and the ten go
Details
- Kind
- OKF bundles
- Topic
- Files & documents
- Publisher
- agent-ix
- Origin
- okf_github
- Category
- dados
- Version
- 0.1
- Stars
- 1
- Open pull requests
- 3
- Last push
- 2026-09-06T22:25:20Z
- 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-iso:plan/Plan-001-semantic-data-schemas/index.md
README
# spec-artifacts-iso
> Filament Module: ISO-style spec artifacts (FR, NFR, StR, US, IT, TC) — unified-shape archetypes (frontmatter schema + body_extraction asserts) validated by quire-rs; per-archetype authoring skeletons are the source of truth (no render templates); iso-spec-core grammar
An Agent-IX Filament module loaded by [`quire-cli`](https://github.com/agent-ix/quire-cli) and [`quoin`](https://github.com/agent-ix/quoin). The module path is `spec_artifacts_iso`: a `manifest.yaml`, per-kind authoring `skeletons/`, and frontmatter `schemas/`. It contributes doc-backed `archetypes` and `artifact_types` (ISO-style requirement artifacts) — no embedded `object_types`.
## 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-iso`.
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-iso
```
```bash
# quoin — resolve the module from npm by name
quoin plugin install package:@agent-ix/spec-artifacts-iso
# or point any tool at the installed package root
quire validate spec/**/*.md --module node_modules/@agent-ix/spec-artifacts-iso
```
## Artifact types provided
The `Spec` archetype (kind `spec`) is a doc-backed container that holds ISO-style requirement artifacts (its composition expects `StR`, `FR`, `NFR`, `US`, `IT`, `TC`). The artifact types below live inside it.
| Kind | ID pattern | Description |
|:-----|:-----------|:------------|
| `FR` | `FR-{next:03d}` | Functional Requirement (ISO/IEC/IEEE 29148): required `## Description` (normative shall/must language) + `## Acceptance Criteria` (`ID \| Criteria \| Verification` table, `{id}-AC-N`) + `## Dependencies`; optional `## Inputs`/`## Outputs`/`## Behavior` and a `## Constraints` table (`{id}-CON-N`). |
| `NFR` | `NFR-{next:03d}` | Non-Functional Requirement / quality constraint (ISO/IEC/IEEE 29148, attribute from ISO 25010): required `## Statement` + `## Measurement and Evaluation` (`Metric \| Target \| Threshold \| Method` table) + `## Verification`; `quality_attribute` is a frontmatter enum. |
| `StR` | `StR-{next:03d}` | Stakeholder Requirement (ISO/IEC/IEEE 29148 stakeholder triad): required `## Stakeholder Need` + `## Rationale` + `## Validation Criteria`; stakeholders, context, constraints, and traceability are optional. |
| `US` | `US-{next:03d}` | User Story (ISO/IEC/IEEE 29148): a single required `## Story` matching the "As a … / I want … / So that …" shape; all other sections are contextual and informative. |
| `IT` | `IT-{next:03d}` | Integration Test case (ISO/IEC/IEEE 29119): required six-section set — `## Objective`, `## Target Integration`, `## Preconditions`, `## Inputs`, `## Test Procedure`, `## Expected Results`. |
| `TC` | `TC-{next:03d}` | Test Case (ISO/IEC/IEEE 29119 essentials): required `## Description` + `## Test Procedure` + `## Expected Results`. |
| `master-requirements` | _(bundle root)_ | Master Requirements Specification: H1 fixed to "Master Requirements Specification"; required `## Purpose`, `## Scope`, `## System Overview`, `## Requirements Architecture`, `## References`; the repo-level `depends_on:` dependency manifest. |
| `index` | _(`index.md`)_ | OKF bundle directory index: required `## Contents` listing the artifacts in the directory via content-local relative links (not knowledge-graph edges). |
| `log` | _(`log.md`)_ | OKF bundle update log: required `## History` of dated, non-normative structural changes to the bundle. |
## How this module is used
### With quoin (recommended)
```bash
quoin plugin install path:../spec-artifacts-iso # bundled root module; shown for completeness
quoin catalog list # list available artifact kinds
quoin catalog show FR # inspect the FR skeleton + schema
quoin write . --types FR,NFR # scaffold new artifacts
quoin review # validate + review the spec
```
See https://github.com/agent-ix/quoin.
### With quire-cli directly
```bash
quire schema FR --module ./spec_artifacts_iso # show the FR authoring skeleton/schema
quire validate spec/**/*.md --module ./spec_artifacts_iso # validate Markdown artifacts
quire extract spec/functional/FR-001.md --module ./spec_artifacts_iso --archetype FR
```
See https://github.com/agent-ix/quire-cli#usage-instructions.
## Authoring conventions
- **FR body**: required = `## Description` + `## Acceptance Criteria` (table).
`## Inputs` / `## Outputs` / `## Behavior` / `## Constraints` /
`## Dependencies` are optional, all at **level 2** — there is no
`## Specification` umbrella. Object FRs carry their kind's anchor sections
instead of I/O.
- **`object:` frontmatter** is the canonical object-kind field (never
`object_type:`). It is optional for vanilla behavioral FRs and required for
object FRs — kind anchors and extraction hang off it.
- **NFR body**: required = `## Statement` + `## Measurement and Evaluation`
(`Metric|Target|Threshold|Method` table) + `## Verification`;
`quality_attribute` is a frontmatter enum (ISO 25010), not a section.
- **AC Verification cells** use the ISO 29148 methods — `Inspection`,
`Analysis`, `Demonstration`, `Test` — optionally annotated `Test (TC-035)`.
Checked by the module's `ac-verification-method` lint rule (`quire lint`).
- **Relationships**: author the explicit `relationships:` array (typed verbs,
incl. `specifies` for object FR → behavioral FR). Bare-ID sugar fields
(`depends_on:` etc.) are read-side ingestion tolerance only — except in
`spec.md` (master-requirements), where `depends_on:` is the repo-level
dependency manifest.
## Development
This is a flat-layout Python 3.13+ package (`spec_artifacts_iso`, no `src/`) managed with Poetry, built and published via GitHub Actions to Google Artifact Registry (PyPI-compatible). All work goes through the Makefile:
```bash
make install # install dependencies into the Poetry venv
make test # run pytest
make lint # ruff + black --check
make format # auto-format (black + ruff --fix)
make build # build wheel + sdist under dist/
make update-lock # update poetry.lock
make local-publish # build + publish to local pypi.ix
```
| Target | Description |
|:-------|:------------|
| `install` | Install dependencies in the Poetry venv |
| `test` | Run tests |
| `lint` | Run linting (Ruff + Black check) |
| `format` | Auto-format code (Black + Ruff --fix) |
| `build` | Build wheel and sdist artifacts |
| `clean` | Remove all build artifacts |
| `version` / `info` | Show version / Git info |
| `update-lock` | Update `poetry.lock` |
| `add-package p=<name>` | Add a runtime dependency |
| `add-dev-package p=<name>` | Add a dev dependency |
| `use-local p=<name>` / `use-upstream p=<name>` | Switch a dep to/from local `pypi.ix` |
| `local-publish` | Build and publish to local PyPI |
CI runs on `push`, `pull_request`, and `v*.*.*` tags: it runs tests and lint, builds with `poetry build`, and publishes to Artifact Registry via `twine upload -r internal-pypi`. Versioning is dynamic from the Git tag. Required CI config: secret `GCP_SERVICE_ACCOUNT_KEY`; variables `GCP_REGION`, `GCP_PROJECT_NAME`, `GCP_PYPI`.
For local install from the cluster PyPI proxy (after `make local-publish`):
```bash
pip install --index-url http://pypi.ix/root/dev/+simple/ spec_artifacts_iso
```