{"id":48060925,"url":"https://github.com/tslateman/spec-trace","last_synced_at":"2026-04-04T14:32:42.522Z","repository":{"id":334623679,"uuid":"1140067570","full_name":"tslateman/spec-trace","owner":"tslateman","description":"Requirements traceability for Python projects — connect specs to tests, see what's verified","archived":false,"fork":false,"pushed_at":"2026-03-21T00:00:48.000Z","size":1637,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-21T15:38:14.453Z","etag":null,"topics":["python","requirements","testing","traceability"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tslateman.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-01-22T19:34:07.000Z","updated_at":"2026-03-21T00:00:53.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/tslateman/spec-trace","commit_stats":null,"previous_names":["tslateman/spec-trace"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/tslateman/spec-trace","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tslateman%2Fspec-trace","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tslateman%2Fspec-trace/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tslateman%2Fspec-trace/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tslateman%2Fspec-trace/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tslateman","download_url":"https://codeload.github.com/tslateman/spec-trace/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tslateman%2Fspec-trace/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31402759,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-04T10:20:44.708Z","status":"ssl_error","status_checked_at":"2026-04-04T10:20:06.846Z","response_time":60,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["python","requirements","testing","traceability"],"created_at":"2026-04-04T14:32:41.902Z","updated_at":"2026-04-04T14:32:42.510Z","avatar_url":"https://github.com/tslateman.png","language":"Python","readme":"# SpecTrace\n\nRequirements traceability for Python projects. Connect specs to tests, see what's verified.\n\n## Prerequisites\n\nSpecTrace uses [uv](https://github.com/astral-sh/uv) for fast, reliable package management:\n\n```bash\n# Install uv (if not already installed)\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n# or: pip install uv\n```\n\n## Quick Start\n\n```bash\n# Install with uv (recommended)\nmake install\n# or: uv pip install -e .\n\n# Setup database\nmake migrate\n\n# Create admin user\nmake setup\n\n# Import your specs\npython spectrace/manage.py parse_specs specs/\n\n# Run development server\nmake run\n\n# Open http://localhost:8000/admin/\n```\n\n## Development Commands\n\nSpecTrace includes a Makefile for common development tasks (uses `uv` for package management):\n\n| Command | Description |\n|---------|-------------|\n| `make help` | Show all available commands |\n| `make install` | Install package in editable mode (uses `uv pip install`) |\n| `make install-dev` | Install with dev dependencies (uses `uv pip install`) |\n| `make test` | Run tests with pytest |\n| `make migrate` | Run Django migrations |\n| `make makemigrations` | Create new migrations |\n| `make shell` | Open Django shell |\n| `make run` | Start development server |\n| `make clean` | Remove caches and build artifacts |\n| `make setup` | Create admin user (admin/admin) |\n| `make demo` | Run the SpecTrace demo |\n\n**Note:** If you don't have `uv` installed, the Makefile commands will fail. Install it first: `pip install uv`\n\n## Workflow Example\n\n```bash\n# 1. Import requirements from specs\npython spectrace/manage.py parse_specs specs/\n\n# 2. Run tests with JUnit output\nmake test\n# or: pytest --junitxml=test_results.xml\n\n# 3. Extract test-requirement links\npython spectrace/manage.py extract_links --output links.json\n\n# 4. Import results and compute status\npython spectrace/manage.py import_results test_results.xml --links links.json\n\n# 5. View dashboard\nmake run\n# Open http://localhost:8000/admin/\n```\n\n## Examples\n\nSee the **[Document Pipeline Example](examples/document-pipeline/)** for a comprehensive demonstration of spec-trace features:\n\n- Nested requirement hierarchy (3 levels)\n- Multiple verification methods (test, inapp, both)\n- Passing, failing, and skipped tests\n- SLO integration with OpenSLO YAML\n- Various pytest patterns (parametrized, async, class-based, xfail)\n- CI/CD workflow example\n\nRun the demo:\n```bash\nmake demo\n# or: python scripts/demo_pipeline.py\n```\n\n## Writing Specs\n\nCreate markdown files in `specs/` with frontmatter:\n\n```markdown\n---\nid: REQ-AUTH-001\ntitle: User Login\npriority: high\ntags: [authentication, security]\nverification_method: test  # test, inapp, or both\n---\n\nUsers must be able to log in with email and password.\n```\n\n## Linking Tests\n\nUse the `@pytest.mark.requirement` decorator:\n\n```python\nimport pytest\n\n@pytest.mark.requirement(\"REQ-AUTH-001\")\ndef test_user_can_login():\n    # test implementation\n    pass\n\n@pytest.mark.requirement(\"REQ-AUTH-001\", \"REQ-AUTH-002\")\ndef test_login_creates_session():\n    # test can link to multiple requirements\n    pass\n```\n\n## Management Commands\n\nSpecTrace provides Django management commands for various operations:\n\n| Command | Description |\n|---------|-------------|\n| `parse_specs \u003cdir\u003e` | Import requirements from markdown specs |\n| `extract_links` | Extract test-requirement links from test files |\n| `import_results \u003cxml\u003e` | Import pytest JUnit XML and compute status |\n| `validate_links \u003cjson\u003e` | Validate links for drift detection (CI) |\n| `import_slos \u003cdir\u003e` | Import SLOs from OpenSLO YAML files |\n| `update_slo_status --from-json \u003cfile\u003e` | Update SLO status from observability data |\n| `import_inapp_validations \u003cjson\u003e` | Import in-app validation results |\n| `check_invariants` | Validate data consistency (INV-A through INV-K) |\n\n**Agent Task Commands** (see [docs/agent-tasks.md](docs/agent-tasks.md)):\n\n| Command | Description |\n|---------|-------------|\n| `agent_register` | Register an agent with role (planner/coder/reviewer) |\n| `agent_tasks` | List tasks with filtering |\n| `agent_claim` | Claim an unclaimed task with lease |\n| `agent_start` | Begin work on claimed task |\n| `agent_submit` | Submit work for review |\n| `agent_review` | Approve or request changes |\n| `agent_merge` | Mark approved task as merged |\n| `expire_leases` | Release stale task claims (cron) |\n\nAll commands are run via: `python spectrace/manage.py \u003ccommand\u003e`\n\n## Verification Status\n\n- **Passing** - All linked tests pass\n- **Failing** - Any linked test fails\n- **Untested** - No tests linked to requirement\n\n## Verification Methods\n\nRequirements can specify how they should be verified:\n\n- **test** - Verified by automated tests (default)\n- **inapp** - Verified by in-app validation buttons/endpoints\n- **both** - Must pass both test and in-app validation\n\n## SLO Integration\n\nLink requirements to Service Level Objectives using OpenSLO YAML:\n\n```yaml\napiVersion: openslo/v1\nkind: SLO\nmetadata:\n  name: api-availability\n  labels:\n    requirement: REQ-API-001\nspec:\n  service: api-gateway\n  objectives:\n    - target: 0.999\n      timeWindow:\n        duration: 30d\n```\n\nImport with: `python spectrace/manage.py import_slos slos/`\n\n## REST API\n\nExternal systems can push status updates:\n\n| Endpoint | Method | Description |\n|----------|--------|-------------|\n| `/api/slo/status/` | POST | Update SLO status from observability platforms |\n| `/api/validation/result/` | POST | Submit in-app validation results |\n| `/api/requirement/\u003cid\u003e/status/` | GET | Get requirement verification status |\n\n### Example: Update SLO Status\n\n```bash\ncurl -X POST http://localhost:8000/api/slo/status/ \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"slos\": [\n      {\"name\": \"api-availability\", \"status\": \"met\", \"current_value\": 0.9995}\n    ]\n  }'\n```\n\n### Example: Submit Validation Result\n\n```bash\ncurl -X POST http://localhost:8000/api/validation/result/ \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"source\": \"production-app\",\n    \"validations\": [\n      {\"requirement_id\": \"REQ-AUTH-001\", \"name\": \"Login Flow\", \"status\": \"success\"}\n    ]\n  }'\n```\n\n## CI Integration\n\nValidate test-requirement links in CI to catch drift:\n\n```bash\npython spectrace/manage.py validate_links links.json --strict\n```\n\n- `--strict` - Exit with error on warnings (missing coverage)\n- `--format json` - Output JSON for programmatic parsing\n\nExample in CI pipeline:\n```yaml\n# .github/workflows/test.yml\n- name: Run tests\n  run: make test\n\n- name: Validate requirements coverage\n  run: |\n    python spectrace/manage.py extract_links --output links.json\n    python spectrace/manage.py validate_links links.json --strict\n```\n\n## License\n\nMIT\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftslateman%2Fspec-trace","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftslateman%2Fspec-trace","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftslateman%2Fspec-trace/lists"}