@arjunkhera/atlas 0.0.0 → 0.2.1

package/shape/releases.json

@@ -0,0 +1,15 @@
+{
+  "note": "Every copy of shape/check.mjs a release of Atlas has shipped. The last row is the check this package ships. atlas status reads this list; git history is never read.",
+  "releases": [
+    {
+      "check_version": 1,
+      "sha256": "3dfd659a7533c51dce11bd0e2d7a9312f041c5955d45ac3cc67d3e29d328b5d2",
+      "first_package": "0.1.1"
+    },
+    {
+      "check_version": 2,
+      "sha256": "a4bc5ab8c75be8f216d460df9233670f5ba4ed9d853236f6b55a7f0d10dfe293",
+      "first_package": "0.2.0"
+    }
+  ]
+}

package/skills/sdlc-task/SKILL.md

@@ -0,0 +1,174 @@
+---
+name: sdlc-task
+description: >
+  The Atlas delivery lifecycle in a session — start / pause / resume / status / lock / done.
+  Trigger whenever the owner starts new software work in chat ("let's build X", "new
+  feature", "start a task"), pauses or resumes work ("park this", "pick up where we left
+  off"), asks where a task stands, or is ready to lock a design ("lock it down", "we're done
+  specifying"). Every write goes through the atlas-work verbs; this skill says when to call
+  which one.
+---
+
+# sdlc-task — the delivery lifecycle
+
+Atlas is the package that sets how a repo is worked on. This skill is its
+delivery lifecycle. It travels with the package, not with any one repo.
+
+The kernel is data, not prose. Read [`lifecycle.yaml`](lifecycle.yaml), beside
+this file, for the stages, tiers, tripwires and the lock contract before you
+act. A verb reads those lists; it never hard-codes them.
+
+## Where the state lives
+
+Every work item, question, decision and delivery mark is a record in the graph,
+written through the **atlas-work verbs** (the `atlas-work` MCP server). Do not
+write raw graph records for work. The verbs hold the write rules, the owner
+checks and the transition log; each verb's own description says what it needs.
+
+| You want to | Verb |
+|---|---|
+| Record new work, with the owner's words | `item_propose`, then `item_stage` as it moves |
+| Freeze the design | `item_lock` |
+| Park it, or pick it up again | `item_park`, `item_resume` |
+| Split it, or link it to other work | `item_split`, `item_link` |
+| Ask the owner something, or record the answer | `question_ask`, `question_answer` |
+| Record a decision in the owner's words | `decision_record` |
+| Mark it delivered, or reopen it | `item_done`, `item_reopen` |
+| Say where things stand | `where_are_we`, `in_flight`, `needs_me` |
+
+The repo's own facts come from `atlas.yaml` and `atlas/`. Its `kind` (`service`,
+`library`, `schema`) decides which procedures it has and what "delivered" means.
+Read it. Never assume a deployed service.
+
+A change to the process itself is not a task. It is an amendment to the
+frozen text, and the rule for one is short:
+
+1. Say so at once. Never build against a sentence you know is wrong.
+2. Write the amendment as its own dated file: what changes, why, the new
+   frozen text in full, one new hash over the whole frozen section, and the old
+   hash named as retired.
+3. Never edit frozen text in place. A reviewer's finding is a normal reason to
+   amend.
+
+(Source: the Atlas lock procedure, amendment A1.6, section 12.)
+
+## start
+
+1. **Tier** (`lifecycle.yaml` `tiers`): propose one — hotfix, standard or
+   initiative — with a one-line reason. The owner can override. The forced
+   escalators are `lifecycle.yaml` `tier_escalators`.
+2. **Record the work at once** with `item_propose`: the owner's goal
+   **verbatim**, and one line of interpretation that is clearly yours. Move its
+   stage with `item_stage` as the design conversation opens.
+3. **Worktree and branch.** Read the repo's `default_branch` from its record
+   (`registry_list`); it may be `main` or `master`. Branch from it, and never
+   commit to it. Local sessions use `feature/`, `fix/` or `chore/`; cloud
+   sessions use `claude/`. The pull request targets that branch.
+4. **Design doc** (standard and above): copy
+   [`templates/design-doc.md`](templates/design-doc.md) to
+   `docs/design-docs/<slug>.md`, fill Context and goal, and list it in
+   `docs/index.md` in the commit that first lands it. Hotfix tier skips the
+   doc: the acceptance criteria live on the work item, and a resume anchor
+   covers pauses.
+5. Enter the design loop.
+
+## The design loop (between start and lock)
+
+- **One voice.** The owner talks to one colleague. Crews run behind the
+  curtain as subagents and come back as digests — never as a committee
+  surfacing question lists.
+- **Guided elicitation** (the owner's words: *"one on one
+  conversation that flows… the purpose of agent is to do research and guide my
+  thoughts into useful features"*). Research first, then **one pointed question
+  at a time**, with a recommendation (the owner: *"Questions if posed
+  should be one by one. Just think, if you say 5 things in one go, how do I
+  respond."*). Keep the question queue in the design doc; surface only the
+  next one. Record each question with `question_ask` and each answer with
+  `question_answer`.
+- **Succinct chat; artifacts carry the content** (the owner's words:
+  *"the content is very verbose… I won't read that much"* · *"artefacts should
+  be the default method of communication… use as many diagrams and examples as
+  possible"*). Chat is a few short sentences: the outcome, the artifact link,
+  the one question.
+- **Lead with a worked example.** Real input, real process, real output, and a
+  sequence diagram where order matters. The owner cannot read dense prose.
+- **Read the reason, not only the rule.** Before you build to a done line, read
+  the owner's words behind it and ask whether the thing should exist at all. A
+  done line is a measure, not the goal.
+- **Research before opinions.** Fan out `atlas:code-explorer` for how the system
+  works today. Raw exploration never enters this session — digests only.
+- **When the task is a cluster of filed bugs, first ask whether the model
+  they presume was ever decided.** A bug report says the code surprised
+  someone; it does not say what the code should do.
+- **The doc accretes in real time.** Every resolved question, decision and
+  approach lands in the design doc as it happens. The doc is the pause and
+  resume state. Record each decision with `decision_record`.
+- **HTML is the owner's reading surface.** Any design, review or status the
+  owner reads is a styled artifact, rendered by the `atlas:artifact-renderer`
+  crew. Its treatment contract lives in that crew; do not restate it.
+- **No bare acronyms in front of the owner.** Spell a thing out on first
+  mention. Ids are for the machine; names are for the human.
+- **User stories before acceptance criteria** (the owner's words:
+  *"I need to see how a user would use the product, or like how the flow
+  works"*). Never draft criteria for a flow no story walks through.
+- **Adversarial review before lock.** Standard tier: at least one persona.
+  Initiative: the panel — `atlas:reviewer-pm`, `atlas:reviewer-architect`,
+  `atlas:reviewer-security` — each briefed with the doc path, in parallel. Brief each
+  one to ask whether the design is the right thing, not only whether it is
+  consistent. An unresolved finding goes into the doc's open questions, and
+  that blocks the lock.
+
+## lock
+
+Gate on `lifecycle.yaml` `lock.preconditions`, all four: the open questions
+are empty, the owner ratified the criteria, the approach is chosen, the tier
+is confirmed. Then:
+
+1. Stamp the design doc's lock block: date, ratifier, tier, the sha256 of the
+   acceptance criteria text, frozen interfaces, the work list. Commit.
+2. Call `item_lock` with the frozen scope and its hash.
+3. Build against the frozen text. **Tripwires** (`lifecycle.yaml`
+   `tripwires`): a discovery after lock that touches the criteria, security,
+   a schema or cost stops the build and goes back to the owner. If the frozen
+   text is wrong, say so at once and write an amendment. Never build against a
+   sentence you know is wrong.
+4. Test with the repo's own `test` procedure, which `atlas.yaml` names. Open a
+   pull request. Keep a separate acceptance reviewer, and close its findings
+   before acceptance.
+
+## pause
+
+1. Bring the resume state current: the design doc (standard and above), or a
+   resume anchor from [`templates/resume-anchor.md`](templates/resume-anchor.md)
+   (hotfix). The bar: a fresh session needs nothing else.
+2. Call `item_park` with the reason. A parked item keeps its stage.
+
+## resume
+
+1. Find it with `where_are_we` or `in_flight`, then read its design doc or its
+   newest resume anchor.
+2. **Check the world still matches.** Does the branch exist? Is the blocker
+   closed? Are the criteria still true? Write any change into the doc first.
+3. Call `item_resume` and continue at the recorded stage.
+
+## status
+
+Call `where_are_we` for the item, or `needs_me` for what waits on the owner.
+Report lifecycle, stage, open questions, what is blocked on the owner, and the
+next action. One short paragraph.
+
+## done
+
+1. Prove delivery the way the repo's `kind` requires, then call `item_done`. A
+   `library` or `schema` repo proves it by merged pull requests and a green
+   gate. A `service` repo also needs its live checks.
+2. If anything was a struggle, encode the fix where it stops a repeat — a lint,
+   then a tool, then a skill, then a doc — and say which.
+3. Design doc status: `SHIPPED <date>`.
+
+## Model tiering
+
+The design loop and the lock judgement run on the frontier model. Crews state
+their own tier in their own files, which ship with Atlas: `atlas:code-explorer`
+is Sonnet; the reviewer personas inherit the frontier model. Drafting from a
+locked spec goes to cheaper models through subagents.

package/skills/sdlc-task/lifecycle.yaml

@@ -0,0 +1,27 @@
+# The delivery lifecycle kernel, as data.
+#
+# Atlas is the package that sets how a repo is worked on, and this is its
+# lifecycle. It travels with the package, beside the skill that reads it, not
+# with any one repo. A verb reads these lists; it never hard-codes them.
+#
+# The values came from the old ops pack, unchanged. That pack and every script
+# that read it are deleted.
+version: 1
+authority: the Atlas lock procedure, amendment A1.9, section 5, slice L2 stage one.
+
+lifecycle_states: [proposed, active, paused, done, dropped, archived]
+stages: [capture, spec, build, verify, ship, learn]
+
+lock:
+  freezes: [acceptance_criteria, interfaces, approach]
+  preconditions: [open_questions_empty, ac_ratified, approach_chosen, tier_confirmed]
+
+tripwires: [acceptance_criteria, security, schema_migrations, money_cost]
+
+tiers: [hotfix, standard, initiative]
+tier_escalators: [migrations, auth_rls_surface, new_external_dependency, money_cost]
+
+# Both templates travel with the package, beside the kernel.
+templates:
+  design_doc: templates/design-doc.md
+  resume_anchor: templates/resume-anchor.md

package/skills/sdlc-task/templates/design-doc.md

@@ -0,0 +1,118 @@
+<!-- Living design document — template (lifecycle spec §7, LC-5).
+     Copy to docs/design-docs/<slug>.md at `sdlc-task start` (standard/initiative
+     tiers). Sections may be trimmed at standard tier; never at initiative.
+     The artifact projection republishes on change (D14: git is truth).
+     Structure rules that keep the doc easy to read by machine:
+     sections addressable by heading, decisions/questions as list items with
+     stable ids (D-n / OQ-n / RQ-n), no prose that depends on rendering.
+     Reference rule (the owner's directive): ids are for the machine,
+     names are for the human — every cross-reference to a stable id links to
+     its definition (markdown section link here; anchor + tooltip in the HTML
+     artifact, see the atlas:artifact-renderer crew) and spells out what
+     it is on first mention. Never leave a bare acronym for the reader to
+     decode. -->
+
+# <Feature name> — design
+
+> Status: DRAFT (in design loop) | LOCKED <date> | SHIPPED <date>
+> Work item: <work item id> · Tier: hotfix | standard | initiative
+> Artifact: <claude.ai artifact url once published>
+
+## Context & goal
+
+<One paragraph: the problem in the owner's words (verbatim where possible),
+and the one-line goal. Agent interpretation kept separate.>
+
+## Goals & non-goals
+
+<!-- From the owner's exemplar PRD shape. Bullets, testable
+     in spirit: what this change is FOR, and what it deliberately is not.
+     Success metrics where they exist — how we'd know it worked. -->
+
+- Goals: …
+- Non-goals: …
+- Success metrics: …
+
+## Flows
+
+<The user-visible flows this touches, before → after. Sequence diagrams
+(mermaid) where they earn their keep.>
+
+## User stories
+
+<!-- Mandatory at standard/initiative tier (the owner's words: "I need
+     to see how a user would use the product, or like how the flow works").
+     Concrete scenes with stable ids (US-n): who, the moment, what they do,
+     what the system does, what they see — written as narrative the owner can
+     react to, each tagged to the slice that ships it. Illustrative dialogue
+     is fine; mark invented values as illustrative. Draft these BEFORE
+     acceptance criteria — the AC formalize what the stories show. -->
+
+- **US-1 — <scene name>** *(slice)*: …
+
+## Architecture
+
+<High-level shape: components touched, data model changes, boundaries crossed.
+Initiative tier: current-state diagram + target-state diagram.>
+
+## Approaches considered
+
+<A/B with real depth at initiative tier — costs, risks, why the loser lost.
+Standard tier: may collapse to "approach + rejected alternative, one line".>
+
+- **Approach A — <name>**: …
+- **Approach B — <name>**: …
+- **Chosen**: <A/B> because <reason>.
+
+## Open questions
+
+<!-- The lock precondition: this checklist must be EMPTY (all items moved to
+     Resolved) before `sdlc-task lock` will stamp the lock block. -->
+
+- [ ] OQ-1 —
+
+## Resolved questions
+
+- RQ-1 — <question> → <resolution, owner-verbatim where it was an owner call> (<date>)
+
+## Decision log
+
+- D-1 — <decision> — <rationale> (<date>, <ratifier>)
+
+## Risks & failure modes
+
+<!-- What breaks, degrades, or bites later; per-risk mitigation or "accepted".
+     From the exemplar PRD shape; trimmable at standard tier. -->
+
+## Test & eval plan
+
+<!-- How each slice proves itself: suites, scenarios, eval questions, prod
+     verification. The red spec's table of contents. Trimmable at standard. -->
+
+## Acceptance criteria
+
+<!-- These freeze at lock (LC-6). Write them testable — the red spec derives
+     from this list. -->
+
+1. …
+
+## Lock block
+
+<!-- Stamped by `sdlc-task lock`; never hand-edited afterwards. -->
+
+```
+LOCKED: <date> by <ratifier>
+Tier: <tier>
+Frozen: AC (sha256 of the AC section), interfaces: <list>, approach: <chosen>
+Tripwires in force: AC / security / schema / cost (kernel defaults)
+Emitted: <child containers / issues created at lock>
+```
+
+## Deviation log (post-lock)
+
+<!-- Every post-lock divergence from this document. Review checks this list.
+     A deviation touching a tripwire (AC, security, schema, cost) must halt
+     and return to the owner instead of landing here. -->
+
+| # | What changed vs the doc | Why | Tripwire? | Reviewed |
+|---|---|---|---|---|

package/skills/sdlc-task/templates/resume-anchor.md

@@ -0,0 +1,25 @@
+<!-- Resume anchor — template (lifecycle spec §8).
+     For work BELOW the design-doc threshold: hotfix tier, bug investigations,
+     any interrupted queue work. Posted as a comment on the issue (queue lane)
+     or the container thread (conversation lane) at every pause AND at stage
+     transitions of long-running work.
+     The bar (and the eval): a fresh session given only this anchor proceeds
+     without asking the owner anything the anchor should have contained. -->
+
+## ⏸ Resume anchor — <date>
+
+**Goal:** <one line, owner-verbatim where possible>
+
+**State:** lifecycle `<active|paused>` · stage `<capture|spec|build|verify|ship|learn>`
+
+**Findings so far:** <POINTER to where they live — issue comment link, doc
+path, graph entity id. Never duplicate content inline.>
+
+**Open questions** (empty = resumable without the owner):
+
+- [ ] …
+
+**Next action:** <the single highest-leverage sentence for the resuming
+session — imperative, specific, no context required beyond this anchor>
+
+**Refs:** branch `<name>` · worktree `<path, if still live>` · PR/issue links

package/work/code-read.mjs

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+// Atlas M1 slice L4: resolve the citations of a code read.
+// The M1 acceptance criterion says "a reviewer resolves every citation". This
+// is how: each path and line is opened in the commit the digest names, read
+// with `git show`, and checked. Nothing is written, no branch moves, and no
+// working tree is touched, so the resolve is safe on a repo another session is
+// using. A never-read path is never opened. A never-quoted path gives back the
+// digest of its line, not its text.
+//
+//   atlas code-read resolve --digest <file.json> --repo <owner/repo> \
+//     --root <path to that repo> [--output report.json]
+//
+// The digest file may hold one digest, an array of digests, or the arguments
+// of a where_are_we call ({ code: [...] }).
+import { execFileSync } from 'node:child_process';
+import { childEnvironment } from './lib/child-env.mjs';
+import { readFile, writeFile } from 'node:fs/promises';
+import { resolve as resolvePath } from 'node:path';
+import { acceptCodeRead, resolveCitations } from './lib/code-read.mjs';
+
+const args = process.argv.slice(2);
+const command = args[0];
+const option = (name) => { const index = args.indexOf(`--${name}`); return index === -1 ? undefined : args[index + 1]; };
+const usage = 'usage: atlas code-read resolve --digest <file.json> --root <repo path> [--repo <owner/repo>] [--output <report.json>]';
+if (command !== 'resolve') { process.stderr.write(`${usage}\n`); process.exit(1); }
+
+const digestPath = option('digest'), rootOption = option('root');
+if (!digestPath || !rootOption) { process.stderr.write(`${usage}\n`); process.exit(1); }
+const roots = new Map();
+// --root may be given once, or once per repo as "owner/repo=/path".
+for (let index = 0; index < args.length; index += 1) {
+  if (args[index] !== '--root') continue;
+  const value = args[index + 1] ?? '';
+  const split = value.indexOf('=');
+  if (split > 0 && value.slice(0, split).includes('/') && value.slice(split + 1).startsWith('/')) roots.set(value.slice(0, split), value.slice(split + 1));
+  else roots.set('*', resolvePath(value));
+}
+
+const raw = JSON.parse(await readFile(resolvePath(digestPath), 'utf8'));
+const list = Array.isArray(raw) ? raw : (Array.isArray(raw?.code) ? raw.code : [raw]);
+const only = option('repo');
+const digests = list.map((entry, index) => acceptCodeRead(entry, { name: `code[${index}]` }).digest).filter((digest) => !only || digest.repo === only);
+if (!digests.length) { process.stderr.write('no digest to resolve\n'); process.exit(1); }
+
+const reports = [];
+for (const digest of digests) {
+  const root = roots.get(digest.repo) ?? roots.get('*');
+  if (!root) { process.stderr.write(`no --root for ${digest.repo}\n`); process.exit(1); }
+  // git show reads the commit, not the working tree. The checkout may sit on
+  // any branch with any uncommitted change; the answer is the same.
+  const readFileAt = async (commit, path) => execFileSync('git', ['-C', root, 'show', `${commit}:${path}`], { encoding: 'utf8', maxBuffer: 32 * 1024 * 1024, env: childEnvironment() });
+  const report = await resolveCitations({ digest, readFileAt });
+  reports.push({ ...report, root });
+  process.stderr.write(`${digest.repo}@${digest.commit.slice(0, 7)}: ${report.resolved}/${report.citations} citations resolved${report.failed ? `, ${report.failed} failed` : ''}${report.quote_mismatches ? `, ${report.quote_mismatches} quotes do not match` : ''}\n`);
+  for (const row of report.rows.filter((entry) => !entry.resolved || entry.quote_matches === false)) process.stderr.write(`  ${row.path}:${row.line} — ${row.reason ?? 'the quote is not on that line'}\n`);
+}
+
+const pass = reports.every((report) => report.pass);
+const output = option('output');
+if (output) {
+  await writeFile(resolvePath(output), `${JSON.stringify({ resolved_at: new Date().toISOString(), pass, reports }, null, 2)}\n`);
+  process.stderr.write(`wrote ${output}\n`);
+}
+process.stderr.write(pass ? 'every citation resolved\n' : 'some citations did not resolve\n');
+process.exitCode = pass ? 0 : 1;

package/work/lib/action-store.mjs

@@ -0,0 +1,84 @@
+import { mkdir, open, lstat, rename, rm, readdir } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { isAbsolute, join } from 'node:path';
+import { createHash, randomUUID } from 'node:crypto';
+
+// Local write-ahead records survive process exit. A stale lock is deliberately
+// held for operator reconciliation; a lost process must not start a second writer.
+export function createActionStore({ directory } = {}) {
+  if (typeof directory !== 'string' || !isAbsolute(directory)) throw new TypeError('absolute journal directory is required');
+  const key = (id) => createHash('sha256').update(id).digest('hex');
+  const path = (id) => join(directory, `${key(id)}.json`);
+  async function init() {
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+    const stat = await lstat(directory);
+    if (stat.isSymbolicLink() || !stat.isDirectory()) throw new Error('journal directory must not be a symlink');
+  }
+  async function assertRecord(id) {
+    try { const stat = await lstat(path(id)); if (stat.isSymbolicLink() || !stat.isFile()) throw new Error('journal record must be a regular file, not a symlink'); }
+    catch (error) { if (error.code !== 'ENOENT') throw error; }
+  }
+  async function get(id) {
+    await init();
+    await assertRecord(id);
+    try {
+      const file = await open(path(id), constants.O_RDONLY | constants.O_NOFOLLOW);
+      try { return JSON.parse(await file.readFile('utf8')); } finally { await file.close(); }
+    }
+    catch (error) { if (error.code === 'ENOENT') return null; throw error; }
+  }
+  async function put(id, value) {
+    await init();
+    await assertRecord(id);
+    const temp = `${path(id)}.${randomUUID()}.tmp`;
+    const handle = await open(temp, 'wx', 0o600);
+    try { await handle.writeFile(JSON.stringify(value)); await handle.sync(); }
+    finally { await handle.close(); }
+    await rename(temp, path(id));
+    const parent = await open(directory, 'r');
+    try { await parent.sync(); } finally { await parent.close(); }
+  }
+  async function withLock(id, operation) {
+    await init();
+    const lock = join(directory, `${key(id)}.lock`);
+    let handle;
+    try { handle = await open(lock, 'wx', 0o600); }
+    catch (error) { if (error.code === 'EEXIST') throw new Error('action journal is locked; reconcile its prior writer before retry'); throw error; }
+    try {
+      await handle.writeFile(JSON.stringify({ pid: process.pid, created_at: new Date().toISOString() }));
+      await handle.sync();
+      return await operation();
+    } finally { await handle.close(); await rm(lock); }
+  }
+  async function inspect() {
+    // Read-only inventory. Never create a journal or remove a writer lock.
+    let entries;
+    try {
+      const stat = await lstat(directory);
+      if (stat.isSymbolicLink() || !stat.isDirectory()) throw new Error('unsafe journal directory');
+      entries = await readdir(directory);
+    } catch (error) {
+      if (error.code === 'ENOENT') return { complete: false, records: [], locks: [] };
+      throw error;
+    }
+    if (entries.length > 10000) throw new Error('journal inventory exceeds inspection bound');
+    const records = [], locks = [];
+    let complete = true;
+    for (const name of entries.sort()) {
+      if (!/^[a-f0-9]{64}\.(json|lock)$/.test(name)) { complete = false; continue; }
+      try {
+        const full = join(directory, name), stat = await lstat(full);
+        if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 4 * 1024 * 1024) throw new Error('unsafe journal entry');
+        const handle = await open(full, constants.O_RDONLY | constants.O_NOFOLLOW);
+        let value;
+        try { value = JSON.parse(await handle.readFile('utf8')); } finally { await handle.close(); }
+        if (name.endsWith('.lock')) { locks.push({ name }); continue; }
+        const requestId = value.request?.requestId;
+        if (typeof requestId !== 'string' || name !== `${key(requestId)}.json` || typeof value.phase !== 'string') throw new Error('invalid journal identity');
+        records.push({ requestId, itemId: value.item_id ?? value.request?.itemId ?? null, phase: value.phase, kind: value.kind ?? 'work' });
+      } catch { complete = false; if (name.endsWith('.lock')) locks.push({ name }); }
+    }
+    return { complete, records, locks };
+  }
+  return Object.freeze({ get, put, withLock, inspect });
+}