rtmkit

A pluggable requirements traceability matrix for teams that keep their product documentation in the repo.

You describe your product once — the end-to-end flow, the rules, the backlog — and rtmkit gives you back a searchable matrix, a drift report against your issue tracker, and guardrails that fail the build when the document stops matching the code.

The engine is the package; the content is your data. Nothing in here knows about your product, your language, or your UI.

npm install @halilural/rtmkit

Why

Product docs rot silently. A file gets renamed, a rule is retired, an issue closes while the problem it was meant to fix survives — and the document keeps asserting things that stopped being true months ago. Reviews don't catch this, because nobody re-reads a 1,000-line document looking for stale line numbers.

rtmkit makes those claims resolvable. Every anchor the document makes is checked against the filesystem and the tracker, so rot becomes a failing check instead of a surprise in a planning meeting.

The three layers

Only the last one is a judgement call:

| Layer | Source | Editable | | --- | --- | --- | | Code coverage — which file/test implements this | rule ids + path anchors, resolved against the repo | ❌ computed | | Delivery state — is the work scheduled/done | issue tracker status | ❌ computed | | Coverage verdict — is this capability actually delivered? | a human | ✅ stored by the host |

Layers 1 and 2 are deliberately read-only. Letting someone override them would allow a document to claim things its own code contradicts — which is the failure mode this exists to prevent.

The third layer cannot be derived from anything. A step can be fully implemented, fully tested, its issue closed, and still not do the right thing for the user. rtkit models that verdict explicitly, including a partial state — built, but not doing the job. Most requirements tools collapse that into covered/not-covered, which is exactly where the interesting findings disappear.

Quick start

import { defineBlueprint, buildMatrix, computeCoverage } from '@halilural/rtmkit';

export const blueprint = defineBlueprint({
  meta: {
    title: 'Checkout — current state',
    owner: 'Product',
    verifiedAt: '2026-08-06',      // last time a human walked this against the code
    staleAfterDays: 90,
    adr: 'docs/decisions/checkout.md',
    ruleCatalog: 'docs/business-rules.md',
    linearTeam: 'ACME',
    linearProject: 'checkout',
  },
  labels: {
    status: { ready: 'works', todo: 'to build', gap: 'broken' },
    statusColor: { ready: 'teal', todo: 'indigo', gap: 'red' },
    lane: {
      customer: 'Customer actions',
      frontstage: 'Frontstage — visible',
      backstage: 'Backstage — invisible',
      support: 'Support processes',
    },
  },
  actors: [
    { name: 'Customer', desc: 'The person buying', lane: 'customer' },
    { name: 'App', desc: 'What they see', lane: 'frontstage' },
    { name: 'System', desc: 'Rules and persistence', lane: 'backstage' },
  ],
  phases: [
    {
      num: 'Phase 1',
      title: 'Cart',
      sub: 'From first add to checkout.',
      caption: 'Figure 1 — cart',
      chart: 'flowchart TD\n  A[Add item] --> B[Checkout]',
      steps: [
        {
          id: 'F1.1',
          who: 'Customer',
          what: 'Adds an item to the cart',
          rule: 'Stock is reserved for 15 minutes.',
          status: 'ready',
          trace: {
            br: ['BR-4'],
            code: ['src/cart/reserve.ts:42'],
            tests: ['test/cart.test.ts'],
          },
        },
      ],
    },
  ],
  rules: [{ rule: 'Stock hold', says: 'Reserved for 15 min', why: 'Avoids oversell', br: ['BR-4'] }],
  backlog: [
    { id: 'B-01', step: 'Guest checkout', status: 'todo', note: 'No account required', steps: ['F1.1'] },
  ],
  slices: [
    { id: 'S-1', title: 'Slice 1 — buy without an account', outcome: 'A guest can complete a purchase', items: ['B-01'], rationale: 'Smallest end-to-end outcome.' },
  ],
});

const rows = buildMatrix(blueprint);
console.log(computeCoverage(rows)); // { total, traced, tracedPct, byStatus, … }

Ids are stable and never reused

F<phase>.<n> for flow steps, B-<nn> for backlog items, S-<n> for release slices, R-<nn> derived for rules. Everything else — the matrix, the drift report, the coverage decisions — keys on these.

Guardrails

import { checkBlueprint } from '@halilural/rtmkit/checks';

const result = checkBlueprint({ blueprint, root: process.cwd() });
if (result.errors.length > 0) process.exit(1);

Five deterministic classes of rot, no network and no heuristics:

1. ids unique — an id is never reused
2. rule ids resolve — every trace.br exists in your rule catalog
3. code anchors resolve — every path exists; path:line is inside the file
4. cross-refs resolve — backlog→step and slice→backlog ids exist
5. freshness — verifiedAt is within staleAfterDays

Wire it into a pre-commit hook or CI. A renamed file then fails the commit instead of quietly rotting the document.

Issue-tracker drift

The engine compares the blueprint against scheduled work without knowing where that work lives. Everything speaks TrackerIssue; an adapter maps a vendor onto it, and core contains no vendor code at all.

import { computeDrift } from '@halilural/rtmkit';
import { createLinearAdapter } from '@halilural/rtmkit/adapters/linear';

const tracker = createLinearAdapter({ apiKey, teamKey: 'ACME' });
const drifts = computeDrift(blueprint, await tracker.fetchIssues());

Any source works, including one that is just a Map:

const issues = new Map([['ZZZ-1', { id: 'ZZZ-1', title: 'Ship it', status: 'done' }]]);
computeDrift(blueprint, issues);

Writing an adapter for Jira, GitHub Issues or a nightly CSV export means implementing one method and collapsing that vendor's workflow states into open | done | cancelled. No drift rule changes. Four classes:

| Kind | Meaning | | --- | --- | | STALE | the issue is closed but the doc still calls it a gap — either the doc is stale, or the issue closed early | | OPTIMISTIC | the doc says ready, the issue is still open | | BROKEN | the linked issue is gone or cancelled | | UNMAPPED | no link recorded — nobody wrote the mapping, not "no such issue exists" |

STALE is the finding that pays for the whole system: it means something shipped and the product problem survived.

For UNMAPPED, suggestIssues() proposes candidates by title overlap. Vocabulary is a property of your team, not of a library, so aliases, stopwords and stemming are all yours to supply:

import { TURKISH_PRODUCT_ALIASES } from '@halilural/rtmkit/adapters/linear';

suggestIssues(item.step, issues, { aliases: TURKISH_PRODUCT_ALIASES });

These are suggestions a human confirms, never written back automatically. A confident-looking wrong mapping is worse than no mapping, because it fabricates the exact traceability this is meant to guarantee.

Coverage verdicts

The human layer: a verdict, a required reason for anything other than covered, confirmed issue links, and dismissed suggestions (so a rejected candidate stops resurfacing on every sync).

import { createD1CoverageStore, coverageTableDdl } from '@halilural/rtmkit/adapters/sql';

// Paste the DDL into whatever migration tool you already use.
console.log(coverageTableDdl());

const store = createD1CoverageStore(env.DB);
await store.put('F1.1', { verdict: 'partial', note: 'ships, but skips the retry path' }, user.email);

The engine depends on the CoverageStore interface and owns no table, no column names and no SQL. A library that dictates your schema is a library you fight during your next migration.

A SQL implementation ships as an adapter (SQLite/D1/libSQL/Postgres, via a two-method runner you adapt in about ten lines) and an in-memory one for tests. Anything else is four methods.

HTTP surface

import { createRtmRouter } from '@halilural/rtmkit/api';

app.route('/admin/rtm', createRtmRouter({
  blueprint,
  store,
  operator: ({ req }) => sessionEmailFrom(req),   // null → 401, never an anonymous verdict
  tracker,                                        // optional; enables drift
}));

Hono is an optional peer dependency. GET / returns the joined view (matrix + decisions + drift), PUT /coverage/:id records a verdict, and a verdict for an id the blueprint never described is refused: a claim nothing can verify is worse than no claim.

React

import { useRtmFilters, useRtmView } from '@halilural/rtmkit/react';

const { filters, setQuery } = useRtmFilters();
const { rows, stats, totalStats } = useRtmView({ rows: matrix, decisions, drifts, filters });

Headless: state and merging only, no components and no styling. Every project has its own design system, and a library that ships buttons is a library you fight.

Design notes

No user-facing strings. Labels and colours come from the blueprint, so the package drops into any project and any language without a translation layer.

Derived, never duplicated. The matrix is projected from the blueprint on every call. There is no second copy to keep in sync, and therefore no way for the two to disagree.

Two boundaries, on purpose. The tracker is an interface because issue trackers are a choice teams make and change; storage is an interface because schemas are owned by the host. Everything else in core is pure functions over your data, which is why the same engine runs in a terminal, in a worker and in a browser.

Prior art worth reading: OpenFastTrace ([covers] markers in code), StrictDoc (requirements-as-code with source links), duvet (spec-to-code anchors). rtmkit borrows their model — coverage is computed from anchors, not asserted in prose — and adds the two things they leave out: issue-tracker drift, and a product verdict that isn't derivable from code.

License

MIT