trace

/trace — Requirement ↔ Design ↔ Code ↔ Test Link Graph

Role: Traceability Engineer Inputs: requirement IDs, file paths, test paths Outputs: .magneto/trace.db (SQLite) + trace.json artifact Audit actions: trace.link_added, trace.impact_queried, trace.coverage_reported

---

Why This Skill Exists — The Moat

gstack has no notion of requirements. Magneto tracks every code change back to the requirement that drove it, every test back to the code it covers, and every design decision back to the business rule that justified it.

This is the single most valuable enterprise feature: when your CISO asks "prove nothing unauthorized shipped," you have the log.

Subcommands

Initialize

magneto trace init     # creates .magneto/trace.db

Add a requirement

magneto trace req add "REQ-042" --title "Password reset must expire in 1h" \
  --source "policy/password.md#section-2"

Link requirement to design

magneto trace link REQ-042 --design .magneto/sprints/<id>/design.md#password-reset

Link requirement to code (AST-based, not line-based)

magneto trace link REQ-042 \
  --code-symbol "src/auth/reset.ts:PasswordReset.expire" \
  --commit <sha>

Link requirement to test

magneto trace link REQ-042 --test tests/auth/reset.spec.ts:"expires after 1h"

Query

magneto trace show REQ-042          # show all links for a requirement
magneto trace impact src/auth/reset.ts   # which requirements does this file affect?
magneto trace coverage              # % of requirements with code + tests

Example Output

REQ-042: Password reset must expire in 1h
├── Design: sprints/s-20260512/design.md#password-reset
├── Code:
│   ├── src/auth/reset.ts:PasswordReset.expire (commit abc123)
│   └── src/auth/reset.ts:PasswordReset.isValid (commit abc123)
├── Tests:
│   ├── tests/auth/reset.spec.ts:"expires after 1h"
│   └── tests/auth/reset.spec.ts:"rejects after expiry"
└── Coverage: 100% (design ✓, code ✓, tests ✓)