0286 — Vellum as the SDLC: spike bar, approvals, evidence, distribution and licence

​

Context

Vellum (figentra/vellum, a separate product) enforces spec lifecycles: approvals are signed, and task evidence is recorded in a hash-chained ledger in git. 0282 makes Vellum the SDLC only if spike STA-298 passes, and until then spec-kit stays. The owner’s decisions of 2026-10-22 answer the questions 0282 left open: how Vellum is distributed, who signs approvals, where task commands run, who owns the renderers, the licence and visibility, and the bar the spike must clear. Each decision below records its reasoning, so the page can be read without other documents.

​

Decision

​

Spike and adoption

1. Save the uncommitted Vellum work first (VL1). Each uncommitted working tree is committed as it is to a wip/<branch> branch, pushed to figentra/vellum, and then re-cloned. A local copy is deleted only after its pushes are verified. Nothing unpushed is deleted. Broken worktree links make an accidental prune likely, and committing as-is keeps each change reviewable.
2. The pass bar for STA-298 (VL3). STA-298 passes only if its written criteria hold and four further checks hold:
   • an agent session cannot produce a valid approval, because no signing key is reachable from it. Decided reading: this binds builder sessions, which cannot reach the reviewer key, and the reviewer identity of decision 4 is the only identity that signs;
   • evidence recorded on the box or the remote runner verifies on the owner’s machine;
   • the Quality Gate adds 60 seconds or less;
   • one full issue costs the lead no more than 15 extra minutes compared with spec-kit.
   The bar is set before the spike starts, so the spike cannot turn into adoption by default.
3. Adoption follows a pass. If STA-298 passes, a follow-up ADR supersedes 0067 and decision D15 of 0121, as decision 11 of 0282 says. If it fails, decision 14 of 0282 applies: spec-kit stays and Vellum is only the approval and evidence layer.

​

Approvals and lanes

4. Approvals are given by the reviewer identity (VL4). The separate reviewer identity approves Vellum tasks by default. Its signing key sits in an Infisical path that builder agents cannot read (STA-238). The owner approves only changes at change-risk R3, the top class of 0120, which includes auth, iam, tenancy, money, PII, secrets, webhooks, crypto, CI permissions and agent guards. Releases stay owner-approved under 0119 decision 5, which this ADR does not change. There is no hardware-key ceremony. This is not one of the three options that were weighed: the reviewer key is extended from low-risk lanes to every lane below R3. The reason is the owner’s stated aim of minimal human interaction, with the owner’s time kept for R3 and above. Builders never approve their own work (0230).
5. Lanes need different proof (VL5). The full and lite lanes need a signed approval and recorded evidence. The bug lane records evidence only, because its failing test is already the evidence. The trivial lane needs neither. The lanes are those of 0120.

​

Packages and distribution

6. The renderers belong to Stackra (VL6). The renderer layer moves into this repository as the published @stackra/renderers package in the developer category, and Vellum depends on it from npmjs. @vellum/renderers is no longer the shared package. The reason: Stackra is public, has release checks and a fixed version (0177), and is the larger consumer, while a public package should not depend on a product whose distribution is still open. The developer packages become four: @stackra/skills, @stackra/cli, @stackra/mcp and @stackra/renderers.
7. One public package (VL8). Vellum is distributed as one public package, @figentra/vellum, published to npmjs with provenance. It bundles the internal @vellum/* packages, which stay workspace-private. Vellum leaves the private registry.
8. Private until 1.0 (VL9). figentra/vellum stays private until version 1.0, then goes public. Its MIT licence text is already in place, so the later change costs nothing. The legal name on its licence follows 0291.
9. Free for now (VL10). Vellum is free and MIT-licensed as an adoption path into Stackra. Whether team features become paid is reviewed when the first team asks. No price is set.
10. Brand direction approved, nothing published (VL16). The Vellum brand direction is approved. Nothing is published until the repository is public (decision 8). The brand kit follows 0291.

​

Task commands, merge and specs

11. Task commands run on the remote runner (VL7). vellum task complete --command runs through the remote runner of 0287 (STA-255). Vellum records the runner job id, the git tree hash, the exit status and an output digest. Light commands may still run locally. Remote evidence is a Vellum feature, filed as an STA issue (decision 14).
12. pr:merge stays the only merger (VL13). vellum verify is a step inside the required Quality Gate, and Vellum’s automatedMergePermitted stays off in Stackra’s policy. 0119 and 0166 are unchanged.
13. Existing specs (VL14). If the spike passes, vellum adopt runs on open specs only. Done specs stay frozen as spec-kit history, with no retroactive approvals, because retroactive approvals would be fake evidence.

​

Toolchain, assistants and tracking

14. Tracking (VL/OP5, amends 0282 decision 16). Vellum work is tracked in Linear team STA with the vellum label. The code lives in figentra/vellum, and branches follow Linear’s naming, figentra/sta-<n>-<slug>, in that repository, so pnpm linear works unchanged. Gaps such as vellum sync are STA issues, not issues in figentra/vellum.
15. Preset split (VL2, amends 0282 decision 12). Vellum’s engine stays in figentra/vellum. The open Stackra preset, which holds the Impact questionnaire and the risk and lane rules, ships in @stackra/skills. Linear and the internal process rules stay in .agents/ in this repository. The preset is not a presets/stackra folder in figentra/vellum.
16. Assistants (VL12). Claude Code and OpenCode are supported and tested in the spike. The Kiro and Cursor renderers are kept and marked untested.
17. Toolchain (VL11). After the spike passes, Vellum moves to Node 24, pnpm 12, oxfmt (Prettier is dropped), tsdown, the published @stackra/*-config presets and the runway reusable workflows. The formatter-proof task parser must pass under oxfmt first. Until the spike has passed, Vellum keeps its own toolchain.
18. Repositories (VL15). Stackra is the first repository, for the spike, and Figentra OS follows once the spike passes. Academorix and the other product repositories stay out until someone asks.

​

Consequences

• Vellum gains a remote-evidence feature, a reviewer-identity approval path and the vellum label in Linear.
• Approvals depend on the reviewer key path (STA-238). Until that path exists, decision 4 cannot be met, and no task can be approved under it.
• The renderer layer has a second consumer in @stackra/renderers, so a change to it must keep Stackra and Vellum working.
• If STA-298 fails, decisions 3 (adoption), 13 (adopt specs) and 17 (toolchain) do not apply, and spec-kit stays.

​

Enforcement

planned — vellum verify inside the Quality Gate once STA-298 passes (decision 12). The four checks of decision 2 are the spike’s own tests, run on the box and the Mac. The lane rules of decision 5 move into tools/scripts/spec-gate.mjs when Vellum replaces spec-kit. No check yet enforces decision 4.

​

Dependencies

The reviewer key path (STA-238) is not built. Today both bot apps’ credentials sit in the same Infisical folder on one machine (0230). Decision 4 needs a path that builder agents cannot read, which is stricter than today, so decision 4 cannot be met until STA-238 delivers that path.

​

Supersedes and sources

Supersedes: none. Amends 0127 (the developer row) and 0282 (decisions 1, 2, 12 and 16; decisions 11 and 14 gain conditions). Related: 0067, 0120, 0177, 0230, 0287, 0291. Sources: owner decisions of 2026-10-22 (VL1 to VL16 and OP5); Linear STA-298, STA-238, STA-255 and STA-328.