specsail 0.0.0-stage → 0.2.0

package/templates/.specsail/docs/workflow.md

@@ -0,0 +1,56 @@
+# SpecSail workflow reference
+
+SpecSail uses durable Markdown artifacts to carry intent between stages. The Captain is the human who owns the approval and merge gates. The First Mate (`manage`) runs the workflow conversationally; the other stages are role lenses it adopts.
+
+## Stages and crew
+
+| # | Skill | Development role — crew alias | Reads | Writes |
+|---|---|---|---|---|
+| 0 | manage | Orchestrator — First Mate | project docs, Makefile, feature state | bootstrap docs, sequencing, gate records |
+| 1 | understand | Product Owner — Scout | project, architecture, request | `request.md` |
+| 2a | plan (spec mode) | Tech Lead — Navigator | project, architecture, request | `spec.md` |
+| 2b | plan (plan mode) | Tech Lead — Navigator | approved spec, module docs | `plan.md`, `tasks.md` |
+| 3 | acceptance-tests | QA — Quartermaster | approved spec, glossary, public interfaces | `tests/acceptance/<feature>/**` |
+| 4 | implement | Developer — Hands | spec, plan, tasks, review, module docs | code, unit tests, task status |
+| 5 | review | Reviewer — Bosun | spec, plan, tasks, diff, invariants | review report, task status |
+| 6 | ship | Release — Clerk | spec, plan, tasks, diff | docs, changelog, PR |
+
+The human Captain is not an agent role. Agents may prepare work for a gate, but only the Captain approves `spec.md`, approves each phase's acceptance tests, and merges.
+
+## Conversational operation
+
+The Captain starts with a normal request ("let's add user authentication"). The First Mate checks project context, bootstraps missing docs/Makefile settings with the Captain's answers, scaffolds the feature, then runs the stages in order. The Captain answers questions and approves artifacts in chat; commands are optional.
+
+**Recording approvals:** on explicit approval, the agent records `Status: APPROVED — Captain (chat), YYYY-MM-DD` in the artifact. The Captain's decision is the approval; the file is the evidence. Silence is not approval.
+
+**Review independence:** the First Mate asks the Captain whether to review in a second session/model. If the Captain accepts a same-model review, the caveat is recorded in `review.md`.
+
+## Change paths
+
+| Type | Path |
+|---|---|
+| FIX | understand → spec with a reproduction criterion → acceptance test → implement → review → ship. Skip architecture planning unless needed. |
+| FEATURE UPDATE | full flow; plan skips architecture decisions if `Architecture affected: NO`. |
+| NEW FEATURE | full flow. |
+| Trivial (typo, config, dependency bump) | Normal PR and `make verify`; no feature artifacts. |
+
+## Human gates
+
+1. Confirm the request and resolve or explicitly defer open questions.
+2. Review and approve `spec.md` before planning.
+3. Review and approve acceptance tests for the current phase before implementation.
+4. Merge only after CI is green, review is done, protected paths are clean, and docs are current.
+
+Architecture decisions require Captain approval when the plan says architecture is affected. Merge is always a human decision.
+
+## Task states and done
+
+`TODO → IN_PROGRESS → DEV_DONE → DONE`; rework uses `CHANGES_REQUESTED`; an unresolved issue uses `BLOCKED` plus `blocked.md`. After three review iterations, stop and escalate to the Captain.
+
+A task is done when `make verify` is green, linked acceptance criteria pass, required docs are updated, and the Bosun marks it `DONE`.
+
+## Parallel work and review
+
+- Define API contracts before parallel multi-app work; independent tasks may use separate worktrees.
+- Do not parallelize tasks that touch the same module or shared task-status rows.
+- CI is deterministic verification; Bosun review checks behavior and invariants; the Captain merges.

package/templates/Makefile

@@ -0,0 +1,19 @@
+# SPECSAIL_UNCONFIGURED_TEMPLATE: replace these recipes with your project's real checks.
+.PHONY: setup lint typecheck test accept verify check-protected
+
+# Configure these commands for your project before using the workflow.
+setup:
+	@echo "Configure setup for this project's stack"; exit 1
+lint:
+	@echo "Configure lint for this project's stack"; exit 1
+typecheck:
+	@echo "Configure typecheck for this project's stack (or use a no-op if not applicable)"; exit 1
+test:
+	@echo "Configure unit/integration tests; exclude tests/acceptance/**"; exit 1
+accept:
+	@echo "Configure acceptance tests from tests/acceptance/**"; exit 1
+
+verify: lint typecheck test accept
+
+check-protected:
+	@.specsail/scripts/check-protected-paths.sh $${BASE:-origin/main}

package/templates/docs/architecture.md

@@ -0,0 +1,15 @@
+# Architecture
+
+<!-- Complete for the consuming project. Keep the overview short; use docs/architecture/<module>.md for module detail. -->
+
+## System context
+
+## Module boundaries and allowed dependencies
+
+## Critical data flows
+
+## Cross-cutting concerns
+
+## Invariants
+
+## Key decisions

package/templates/docs/project.md

@@ -0,0 +1,19 @@
+# Project
+
+<!-- Complete this file for the consuming project. Keep details that agents cannot reliably infer from the code. -->
+
+## What it is / who uses it
+
+## Non-goals
+
+## Glossary
+| Term | Meaning |
+|---|---|
+
+## Tech stack
+
+## Repo map
+
+## Invariants and gotchas
+
+## Pointers

package/test/acceptance/cli.acceptance.test.js

@@ -0,0 +1,129 @@
+import assert from "node:assert/strict";
+import { mkdtemp, mkdir, readFile, rm, symlink, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { test } from "node:test";
+import { runCli } from "../../src/cli.js";
+
+const packageRoot = new URL("../../", import.meta.url).pathname;
+const manifest = JSON.parse(await readFile(new URL("../../package.json", import.meta.url), "utf8"));
+
+async function temporaryProject() {
+  return mkdtemp(path.join(os.tmpdir(), "specsail-test-"));
+}
+
+function streams() {
+  let stdout = "";
+  let stderr = "";
+  return {
+    options: {
+      packageRoot,
+      stdout: (text) => { stdout += text; },
+      stderr: (text) => { stderr += text; },
+    },
+    stdout: () => stdout,
+    stderr: () => stderr,
+  };
+}
+
+test("init preserves project-owned files, installs the crew, and is repeatable", async (context) => {
+  const cwd = await temporaryProject();
+  context.after(() => rm(cwd, { recursive: true, force: true }));
+  await mkdir(path.join(cwd, "docs"), { recursive: true });
+  await writeFile(path.join(cwd, "AGENTS.md"), "# Existing project rules\n", "utf8");
+  await writeFile(path.join(cwd, "Makefile"), "verify:\n\t@echo project checks\n", "utf8");
+  await writeFile(path.join(cwd, "docs/project.md"), "# My existing project\n", "utf8");
+  await writeFile(path.join(cwd, ".specsail.json"), JSON.stringify({ version: "old", localSetting: true }), "utf8");
+  const first = streams();
+
+  assert.equal(await runCli(["init"], { cwd, ...first.options }), 0);
+  assert.equal(await readFile(path.join(cwd, "Makefile"), "utf8"), "verify:\n\t@echo project checks\n");
+  assert.equal(await readFile(path.join(cwd, "docs/project.md"), "utf8"), "# My existing project\n");
+  assert.match(await readFile(path.join(cwd, "AGENTS.md"), "utf8"), /<!-- specsail:start -->/);
+  assert.match(await readFile(path.join(cwd, ".specsail/skills/understand/SKILL.md"), "utf8"), /Scout/);
+  assert.match(await readFile(path.join(cwd, ".specsail/skills/manage/SKILL.md"), "utf8"), /First Mate/);
+  assert.match(await readFile(path.join(cwd, ".specsail/skills/review/SKILL.md"), "utf8"), /Bosun/);
+  assert.match(await readFile(path.join(cwd, ".specsail/skills/ship/SKILL.md"), "utf8"), /Clerk/);
+  assert.match(await readFile(path.join(cwd, "AGENTS.md"), "utf8"), /skills\/manage\/SKILL\.md/);
+  assert.match(await readFile(path.join(cwd, ".gitignore"), "utf8"), /\.specsail\/agents\.env/);
+  assert.deepEqual(JSON.parse(await readFile(path.join(cwd, ".specsail.json"), "utf8")), { version: manifest.version, localSetting: true });
+
+  const second = streams();
+  assert.equal(await runCli(["init"], { cwd, ...second.options }), 0);
+  const agents = await readFile(path.join(cwd, "AGENTS.md"), "utf8");
+  assert.equal(agents.split("<!-- specsail:start -->").length - 1, 1);
+  assert.equal(agents.split("<!-- specsail:end -->").length - 1, 1);
+  const gitignore = await readFile(path.join(cwd, ".gitignore"), "utf8");
+  assert.equal(gitignore.split("# >>> SpecSail >>>").length - 1, 1);
+  assert.equal(gitignore.split("# <<< SpecSail <<<").length - 1, 1);
+  assert.match(second.stdout(), /left \d+ existing file\(s\) unchanged/);
+});
+
+test("new scaffolds only the four feature artifacts and rejects unsafe or duplicate slugs", async (context) => {
+  const cwd = await temporaryProject();
+  context.after(() => rm(cwd, { recursive: true, force: true }));
+  const initStreams = streams();
+  assert.equal(await runCli(["init"], { cwd, ...initStreams.options }), 0);
+
+  const created = streams();
+  assert.equal(await runCli(["new", "password-reset", "new"], { cwd, ...created.options }), 0);
+  const spec = await readFile(path.join(cwd, "specs/password-reset/spec.md"), "utf8");
+  assert.match(spec, /^# Spec: password-reset/m);
+  assert.match(await readFile(path.join(cwd, "specs/password-reset/request.md"), "utf8"), /Type: NEW FEATURE/);
+  assert.deepEqual((await (await import("node:fs/promises")).readdir(path.join(cwd, "specs/password-reset"))).sort(), ["plan.md", "request.md", "spec.md", "tasks.md"]);
+
+  const invalid = streams();
+  assert.equal(await runCli(["new", "../escape", "fix"], { cwd, ...invalid.options }), 1);
+  assert.match(invalid.stderr(), /Usage: specsail new/);
+  const duplicate = streams();
+  assert.equal(await runCli(["new", "password-reset", "fix"], { cwd, ...duplicate.options }), 1);
+  assert.match(duplicate.stderr(), /refusing to overwrite/);
+});
+
+test("doctor verifies the kit and the project's verify command", async (context) => {
+  const cwd = await temporaryProject();
+  context.after(() => rm(cwd, { recursive: true, force: true }));
+  const initialized = streams();
+  assert.equal(await runCli(["init"], { cwd, ...initialized.options }), 0);
+
+  const beforeConfig = streams();
+  assert.equal(await runCli(["doctor"], { cwd, ...beforeConfig.options }), 1);
+  assert.match(beforeConfig.stderr(), /Makefile still contains the SpecSail starter template/);
+
+  await writeFile(path.join(cwd, "Makefile"), "verify:\n\t@echo configured\n", "utf8");
+  const afterConfig = streams();
+  assert.equal(await runCli(["doctor"], { cwd, ...afterConfig.options }), 0);
+  assert.match(afterConfig.stdout(), /files and verify target are present/);
+});
+
+test("doctor flags an AGENTS.md that does not start the conversational workflow", async (context) => {
+  const cwd = await temporaryProject();
+  context.after(() => rm(cwd, { recursive: true, force: true }));
+  const initialized = streams();
+  assert.equal(await runCli(["init"], { cwd, ...initialized.options }), 0);
+  await writeFile(path.join(cwd, "Makefile"), "verify:\n\t@echo configured\n", "utf8");
+  const agentsPath = path.join(cwd, "AGENTS.md");
+  await writeFile(agentsPath, (await readFile(agentsPath, "utf8")).replace("skills/manage/SKILL.md", "AGENTS.md"), "utf8");
+  const result = streams();
+  assert.equal(await runCli(["doctor"], { cwd, ...result.options }), 1);
+  assert.match(result.stderr(), /does not start the conversational workflow/);
+});
+
+test("init refuses to write through a symlinked SpecSail directory", async (context) => {
+  const cwd = await temporaryProject();
+  const outside = await temporaryProject();
+  context.after(async () => {
+    await rm(cwd, { recursive: true, force: true });
+    await rm(outside, { recursive: true, force: true });
+  });
+  try {
+    await symlink(outside, path.join(cwd, ".specsail"), "dir");
+  } catch (failure) {
+    context.skip(`symlink creation unavailable: ${failure.message}`);
+    return;
+  }
+  const result = streams();
+  assert.equal(await runCli(["init"], { cwd, ...result.options }), 1);
+  assert.match(result.stderr(), /Refusing to write through a symlink/);
+  await assert.rejects(readFile(path.join(outside, "skills/understand/SKILL.md")), { code: "ENOENT" });
+});

package/test/cli.test.js

@@ -0,0 +1,26 @@
+import assert from "node:assert/strict";
+import { readFile } from "node:fs/promises";
+import { test } from "node:test";
+import { runCli } from "../src/cli.js";
+
+const root = new URL("../", import.meta.url).pathname;
+const manifest = JSON.parse(await readFile(new URL("../package.json", import.meta.url), "utf8"));
+
+test("help and version are available without initializing a project", async () => {
+  let stdout = "";
+  let stderr = "";
+  const options = { packageRoot: root, stdout: (text) => { stdout += text; }, stderr: (text) => { stderr += text; } };
+  assert.equal(await runCli(["--help"], options), 0);
+  assert.match(stdout, /Captain is always human/);
+  assert.equal(await runCli(["--version"], options), 0);
+  assert.match(stdout, new RegExp(manifest.version.replaceAll(".", "\\.")));
+  assert.equal(stderr, "");
+});
+
+test("unknown commands fail with a useful hint", async () => {
+  let stderr = "";
+  const status = await runCli(["sail"], { stderr: (text) => { stderr += text; } });
+  assert.equal(status, 1);
+  assert.match(stderr, /Unknown command: sail/);
+  assert.match(stderr, /specsail --help/);
+});

package/test/release.test.js

@@ -0,0 +1,17 @@
+import assert from "node:assert/strict";
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { test } from "node:test";
+
+const workflowPath = new URL("../.github/workflows/release.yml", import.meta.url);
+const shipped = existsSync(workflowPath);
+
+test("release workflow publishes with OIDC and provenance", { skip: !shipped && "release workflow is not included in the published tarball" }, async () => {
+  const workflow = await readFile(workflowPath, "utf8");
+  assert.match(workflow, /^on:\s*\n\s*push:\s*\n\s*tags:\s*\["v\*"\]/m);
+  assert.match(workflow, /^\s*id-token:\s*write$/m);
+  assert.match(workflow, /^\s*contents:\s*write$/m);
+  assert.match(workflow, /^\s*environment:\s*npm$/m);
+  assert.match(workflow, /npm publish --access public --provenance/);
+  assert.doesNotMatch(workflow, /NODE_AUTH_TOKEN|NPM_TOKEN|secrets\./);
+});