@outerlayer/cli 0.13.0 → 0.14.1

package/skill-pack/template/writing-specs/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: writing-specs
-description: How to write a feature spec: problem framing, goals and non-goals, assumptions, and acceptance criteria in Given/When/Then, before implementation begins. Use when asked to "write a spec", "spec this out", "write a PRD", "draft acceptance criteria", or when shaping the issue for a new feature.
+description: Describes how to write a feature spec before implementation begins - problem framing, goals and non-goals, assumptions, acceptance criteria in Given/When/Then, and the docs and structural verdicts. Use when asked to "write a spec", "spec this out", "write a PRD", "draft acceptance criteria", or when shaping the issue for a new feature.
 ---
 
 # Writing Specs
@@ -10,8 +10,9 @@ in the issue body: one clean spec, edited in place as the shape is agreed,
 never a trail of amendment comments. Its acceptance criteria sit under an
 `## Acceptance criteria` heading. Each criterion has an id, and an id is any
 stable label the team chooses, such as `LOGIN-01` or `AC-12-03`. Pick a scheme
-once and keep to it. Planning scratch is local and disposable. Nothing durable
-belongs there.
+once and keep to it. The body also records the docs and structural verdicts,
+each with a one-line reason. Planning scratch is local and disposable. Nothing
+durable belongs there.
 
 ## Lead with a summary block
 
@@ -104,6 +105,30 @@ implementing. Never write them by reading the finished implementation back.
   changes. The proof shows the running page, never a component render. The
   emitting-evidence skill covers capture.
 
+## The two verdicts
+
+Every feature spec declares two verdicts, each with a one-line reason. They
+are decided when the spec is written, and decided again from the finished
+change before the pull request opens.
+
+- **Docs.** `docs-required` when the change alters what a user sees or does.
+  Judge it against the repository's own docs: a `README.md`, a `docs/`
+  directory, a docs site. A new capability with no page yet is
+  `docs-required` too, and its criterion names the page to add. That no page
+  covers it is a reason to write one, not a reason to skip. Generated
+  reference, such as an API spec rendered as pages, is not a docs surface. A
+  new endpoint still needs a guide when using it takes a step the reference
+  cannot show, such as a credential to create or calls to make in order. When
+  required, the spec carries a criterion naming the page and its proof form.
+- **Structural.** `structural-required` when the change adds a package or an
+  app, introduces a seam between components, or moves data across a
+  boundary. When in doubt, say required: approval is where it gets argued
+  down. A structural change is worth planning before it is implemented.
+
+A verdict reversed when the change is finished is not a fault. The gap
+between the two calls is the useful signal, so state it rather than quietly
+adopting the later one.
+
 ## Honest limits
 
 A criterion may carry prose admitting what it does not cover. Useful idioms:
@@ -132,3 +157,11 @@ the one most often skipped. Re-reading your own spec does not satisfy it. Run it
 against the issue body as published, not the draft in the working tree. A spec
 whose design lives in links the reader cannot follow fails this test, and that
 failure is invisible to whoever wrote it.
+
+## Writing rules for the instructions file
+
+The reader test holds a spec to the rules in
+[references/agents-snippet.md](references/agents-snippet.md): write for a
+reader who was not in the session, and keep session history out of code
+comments. Paste that file into the repository's instructions file, such as
+`AGENTS.md`, to hold every agent's prose to the same rules.

package/skill-pack/template/writing-specs/references/agents-snippet.md

@@ -0,0 +1,57 @@
+<!-- outerlayer:writing-rules -->
+## Write for a reader who was not in the session
+
+This applies to anything a person reads: replies, commit messages, pull
+request titles and bodies, issue bodies, review comments, docs and code
+comments.
+
+The reader test: someone who knows this codebase but has never seen this
+session, the skill that ran it, or any label coined while working. If they
+would have to ask what a word means, explain it or cut it. Names made up
+during a session never appear in anything published: reviewer names, round
+labels, finding ids like C1 or N3, stage names, internal agent roles.
+Describe the thing instead.
+
+Lead with the outcome. One sentence: what changed, or what you found. Then
+only the detail that changes what the reader does next. Keep exact paths,
+numbers, identifiers and caveats. Cut the packaging around them.
+
+A sentence carries one idea and stays under about 20 words. A sentence with
+three clauses becomes three sentences. Break paragraphs often.
+
+Say what you mean. Use the literal phrase, not a metaphor or a flourish:
+"a parameter worth varying", not "a dial worth turning". Use everyday words:
+"use", not "leverage"; "start", not "initiate"; "so", not "thereby".
+
+Session telemetry, review-round tables, agent counts and raw command output
+belong in the report to the person who asked. They never go in a pull
+request or issue body.
+
+Before posting, read the text as that outsider. If they would stall on a
+term or a sentence, rewrite it.
+
+## Code comments
+
+A comment states a present-tense fact the code cannot express: a why, a
+constraint, a gotcha or an invariant. Everything else is noise that leaks
+the history of how the code was written.
+
+Never put these in a comment, a test title or a user-facing string:
+
+- Change narration: "previously…", "now uses…", "removed X", "renamed from
+  Y". Version control holds what changed. The comment says why the current
+  code is the way it is.
+- Issue, pull request or ticket numbers. They mean nothing to a reader
+  without access. If the context matters, restate its substance.
+- Project codenames, phase labels and spec section references. Describe
+  the behavior instead.
+- Labels from a working session: reviewer names, round labels, finding ids.
+
+One exception: an acceptance-criterion id may sit in a comment directly
+above the test that proves it, so a reader can find the test from the
+criterion. Never put it in the test's title.
+
+Keep comments that document constraints, invariants, footguns, security
+posture and real rationale, and do not weaken them when editing nearby. If
+a comment narrates a change but carries a real reason, rewrite it as
+present-tense rationale rather than deleting it.

package/skill-pack/template/writing-tests/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: writing-tests
+description: Writes and reviews tests that catch a specific bug - assertion strength, the seam each test binds at, binding a test to an acceptance-criterion id, and checking by mutation that a test would notice a break. Use when writing or changing any test, when binding a test to a criterion id, when reviewing whether a test proves anything, or when a mutation tool reports survivors.
+---
+
+# Writing tests
+
+A test earns its place by catching a specific bug. Before keeping one, ask:
+what is the smallest change to production code that would still pass this
+test? If the answer is "almost anything", the test checks wiring, not
+behavior. Strengthen it or delete it.
+
+The rules here hold in any language and any test framework. The examples
+use TypeScript with a Jest-style `expect`. Read each one as the equivalent
+assertion in the repository's own framework.
+
+## Assertion strength
+
+These pass for almost any implementation, so they are never the only proof
+in a test:
+
+- An "is defined" or "is not null" check passes for any value at all.
+- A truthy or falsy check. Assert the exact value instead.
+- "Was called" proves it ran, not what it ran with.
+- "Does not throw" on its own. Assert the return value too.
+
+Negative forms state a real expectation and are fine: "was never called",
+"is absent". Prefer:
+
+- Exact equality on the actual return value or the whole object shape.
+- "Called with" and the full argument shape.
+- Positional equality on lists. It catches reordering and off-by-one.
+- A negative assertion that pins an injection path shut, such as
+  `expect(query).not.toContain(rawUserValue)`.
+- On an error path, the message or status a user or operator sees, not only
+  that something failed.
+
+Do not pin brittle internals: exact log strings, incidental call counts, the
+order of unrelated calls. Those break on refactors without catching bugs.
+
+## Choose the seam
+
+Name the seam before writing the test: the boundary the test drives the code
+through.
+
+- Business behavior is proven below the user interface, in the service or
+  the pure function.
+- A user interface contract is proven at the component level, through what
+  the user sees and does.
+- Behavior that lives in the data store, such as an access rule, a trigger
+  or the real shape of a query, is proven against the real store.
+- A criterion that spans two seams gets two tests, one at each.
+
+Check two blind spots every time:
+
+- **Fake-seam blindness.** A fake that returns every field whatever the query
+  asked for proves nothing about the query. Pin the contract: assert the
+  request the code sent, make the fake honor what was asked for, or test
+  against the real dependency.
+- **Structural pinning.** "X is never called for Y" needs a spy that is
+  present and asserts zero calls. A missing fake skips silently, exactly like
+  the real skip.
+
+A field that crosses a module or package boundary needs an assertion at every
+hop: writer, relay, reader. Pinning only the ends leaves the middle free to
+drop it.
+
+## Bind a test to its criterion
+
+When a spec has acceptance criteria with ids, the test that proves a
+criterion carries the id in a comment directly above the test, never in its
+title:
+
+```ts
+// proves LOGIN-03
+it("refuses a password reset for an unknown address without saying so", () => {
+  // ...
+});
+```
+
+The title says what the test proves to someone reading a failure. The
+comment lets a reader, or a script, find the test from the criterion. Never
+put a criterion id in a comment that is not that binding, because a reader
+will take it as one.
+
+Write the test from the criterion's words, at the seam it names, before the
+implementation exists. Run it and read the failure. It must fail because the
+behavior is absent, not because of a typo or a missing import.
+
+A criterion with a proof form such as `(proof: screenshot)` is proven by the
+evidence a reviewer sees, not by a test. It may still have one.
+
+## Mutation: prove the test would notice
+
+A green suite proves the tests run, not that they would catch a bug. Check
+the code the change adds or alters.
+
+**By hand.** For every condition, guard, limit and assignment the change
+adds, break it: invert it, widen it, drop half of an `and`, ignore the field.
+Run the one test file that should catch it. If nothing fails, write the
+assertion that would. Then take each criterion and break the production code
+it describes. Its test must fail. A test bound to a criterion that survives
+the break is not coverage.
+
+**With a tool.** Mutation testing is optional. Where the repository has a
+mutation tool, run it over the changed lines only. Each mutant that survives
+is a test still to write, not a score to accept. Two mutants are equivalent
+only when no observable output can differ; say why when you claim it. Hand
+breaks still matter for files the tool does not mutate, such as SQL, shell
+scripts, markup and configuration.
+
+## The repository's own rules
+
+The instructions file may name test commands, required checks, mocking rules
+or coverage thresholds. Those come first where they are stricter than this
+skill. Add them here when they are the team's standard, because this file is
+the team's to edit.

package/skill-pack/validators/acceptance-criteria.yaml

@@ -0,0 +1,35 @@
+# Yours to edit. Written once by outerlayer init; never overwritten.
+#
+# How to satisfy this row: once the pull request is open, have an agent that
+# did not write the change judge each recorded acceptance criterion against
+# the test that cites it. Write its verdicts as an .html file and emit it as
+# a report artifact bound to this check:
+#   outerlayer emit artifact criteria.html --for acceptance-criteria --caption "Each criterion judged against the test that cites it"
+# Then run `outerlayer sync`, and copy the report's deep link from the pull
+# request's evidence comment. The link can take up to a minute to appear
+# after the sync. If it is not there yet, wait a minute and read the comment
+# again; do not give up after one look. Never build the link by hand, and
+# never link a pull request comment: a comment can be edited or deleted later.
+#
+# Then record the verdict once, with that link as its proof:
+#   outerlayer emit acceptance-criteria --item "$OUTERLAYER_WORK" --result pass --link <the report's deep link>
+# Use --result pass only when the judge found every criterion it judged met.
+# Use --result fail when it found one unmet. A criterion whose proof is a
+# screenshot, video or other artifact is not judged here: its own criterion
+# row asks for that artifact.
+# When there is no criterion to judge, nothing is judged and nothing is
+# recorded, so the row never reads as passed.
+# Until a result is recorded, the row reads "not proven". While a host still
+# holds the work item's claim, it reads as waiting.
+#
+# `where: ci` means the result comes from `outerlayer emit`: OuterLayer runs
+# nothing for this check, and a result from a session, CI or a person counts.
+# The row claims only what that proves: a criteria judge's result is
+# recorded, not that the criteria hold.
+id: acceptance-criteria
+kind: validation
+row: "A criteria judge result is recorded for this change"
+level: warn
+run:
+  where: ci
+  emit: acceptance-criteria

package/dist/mcp-install-cmd-VXVIH7PH.js

@@ -1,9 +0,0 @@
-#!/usr/bin/env node
-import { createRequire } from 'node:module';
-export { DEFAULT_MCP_COMMAND, DOCS_MCP_SERVER_NAME, McpInstallError, addDocsMcpEntryIfAbsent, addStdioMcpEntryIfAbsent, buildServerEntry, buildStdioServerEntry, defaultMcpUrl, handleMcpInstallError, runMcpInstall } from './chunk-R7OQTKWT.js';
-import './chunk-YRYMNBGQ.js';
-import './chunk-EABW6AJQ.js';
-import './chunk-VNVZDWO3.js';
-import './chunk-Z5GEFMRW.js';
-
-createRequire(import.meta.url);

package/dist/{chunk-NX57IBNK.js → chunk-4NPZVMJU.js}

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
 import { createRequire } from 'node:module';
-import { BUILDKIT_IMAGE } from './chunk-CX22S5BA.js';
-import { compareVersions } from './chunk-JXYVA45C.js';
 import { parseSize } from './chunk-7RQ73DLO.js';
 import { JOB_MOUNT, GATEWAY_PORT, GATEWAY_SOCKET, CLAUDE_PORT, CLAUDE_SOCKET, RELAY_PORT, DESTINATION_BASE_PORT } from './chunk-4Q7OMKAT.js';
+import { BUILDKIT_IMAGE } from './chunk-CX22S5BA.js';
+import { compareVersions } from './chunk-JXYVA45C.js';
 import { runnerDir } from './chunk-ZM2IMMYN.js';
 import { createHash } from 'crypto';
 import { realpathSync } from 'fs';

package/dist/{chunk-3FMPZPJQ.js → chunk-R7PF5OOU.js}

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { createRequire } from 'node:module';
-import { startTimeOf, claimPidFile, RunnerAlreadyRunningError, releasePidFile } from './chunk-N5FOE5PS.js';
 import { RecipeError, locateRecipe, readRecipe, assertBuildable, writeSanitizedRecipe, classifyProperties, SANITIZED_NAME } from './chunk-QOZKPLVJ.js';
+import { startTimeOf, claimPidFile, RunnerAlreadyRunningError, releasePidFile } from './chunk-N5FOE5PS.js';
 import { CLAUDE_CODE_VERSION, NODE_IMAGE, DEFAULT_BASE_IMAGE, TINI_VERSION, GH_VERSION, GH_SHA256, TINI_SHA256 } from './chunk-CX22S5BA.js';
 import { withGitConfig, tokenHeader } from './chunk-BYT5O5RV.js';
 import { RUNNER_DIR_MODE, repoCacheDir, imagesDir, attemptStamp, runnerDir, rootfsPathFor, RUNNER_FILE_MODE } from './chunk-ZM2IMMYN.js';