@difflab/difflab-cli 0.8.0 → 0.9.0

package/README.md

@@ -31,7 +31,7 @@ Initialization requires a GitHub HTTPS or SSH origin and never creates a Git rep
 
 If initialization is interrupted, retry `difflab init <PROJECT_KEY>`; matching partial links and database rows can be reused, but conflicting paths require manual inspection. Do not delete the shared database to repair a repository link.
 
-The `project_context({ cwd })` MCP tool inspects initialized repositories without creating files or applying migrations. If it reports missing or inconsistent setup, load the portable `skills/difflab-init/SKILL.md` in your client's Agent Skills directory and follow its CLI steps. Existing `todo_*` MCP tools remain available.
+The `project_context({ cwd })` MCP tool inspects initialized repositories without creating files or applying migrations. Existing `todo_*` MCP tools remain available.
 
 ## MCP setup
 
@@ -72,6 +72,12 @@ On first use, missing bundled templates and filled examples are copied to `~/.di
 
 The portable `skills/difflab-plan`, `skills/difflab-review`, `skills/difflab-flow`, `skills/difflab-explore`, `skills/difflab-adr`, and `skills/difflab-poc` directories contain natural-language agent workflows for these templates. Install each skill in your client's Agent Skills directory. The MCP-only `log_append({"path":"/absolute/physical/project-store/plans/YYMMDD-name/logs.txt","message":"Phase started"})` tool creates an append-only progress log on first use; pass the physical path, not the `.difflab` symlink. There is no log CLI command.
 
+The [plan authoring guide](../../skills/difflab-plan/references/authoring.md) requires component/process/artifact visuals, compact interfaces, and a nested repo tree at the start of `Consequences`. Add a `Testing` outline of exact end-to-end and integration scenarios. Keep expected commit and green-CI gates, including for `plan go --commit`. That flag permits scoped commits. Push requires separate authorization. Write `N/A.` when infrastructure stays unchanged. Source examples live in the skill's `references/examples/` and are not CLI templates.
+
+The [review rubric](../../skills/difflab-review/references/rubric.md) follows language conventions, codebase patterns, and applicable `AGENTS.md` rules. Refactor unclear code at the scope needed. Review application behavior first, then module public APIs, then focused unit behavior. Require clear Arrange/Act/Assert blocks and useful fixtures. Untested private functions alone are not findings. Keep comments short and use simple English. Omit nitpicks and minor optimizations. Explicit security/performance focuses deepen those audits.
+
+For an upgrade, reinstall changed skills and reload the client. Back up and move aside only the installed templates/examples you want refreshed, then list templates again. For these changes, inspect `~/.difflab/templates/{spec-driven-plan,code-review}.md` and `examples/{plan-feature,plan-migration,review-change}.md`. Preserve customizations in backups and merge deliberately; never reset the whole directory. Older templates still work: skills add missing subsections to generated documents while preserving human content and existing phase completion state.
+
 ## Flow definitions and runs
 
 `flow new <name>` and `flow go <name>` are Agent Skill requests, not CLI subcommands. The agent creates a definition once at `~/.difflab/flows/<name>.md`. It calls MCP `scaffold` with `cwd=<absolute home>/.difflab`, `path="flows"`, and `filename="<name>.md"`. Do not use `cwd=<home>,path=".difflab/flows"`: that route is for a repository project store. You can edit a definition before another run. A new run uses a fresh snapshot and does not alter old runs.

package/dist/index.js

@@ -37320,6 +37320,37 @@ var require_utils = __commonJS(function(exports, module) {
     }
     return output.join("");
   }
+  function removeDotSegmentsRelative(path) {
+    if (path === "" || path[0] === "/") {
+      return removeDotSegments(path);
+    }
+    const segments = path.split("/");
+    const last = segments.length - 1;
+    const output = [];
+    let trailingDirectory = false;
+    for (let i = 0;i <= last; i++) {
+      const segment = segments[i];
+      if (segment === "." || segment === "..") {
+        if (segment === "..") {
+          if (output.length !== 0 && output[output.length - 1] !== "..") {
+            output.pop();
+          } else {
+            output.push("..");
+          }
+        }
+        trailingDirectory = i === last;
+      } else {
+        output.push(segment);
+      }
+    }
+    if (trailingDirectory && output[output.length - 1] !== "..") {
+      output.push("");
+    }
+    if (output.length === 0 || output[0] === "" || output[0].includes(":")) {
+      output.unshift(".");
+    }
+    return output.join("/");
+  }
   var HOST_DELIMS = { "@": "%40", "/": "%2F", "?": "%3F", "#": "%23", ":": "%3A" };
   var HOST_DELIM_RE = /[@/?#:]/g;
   var HOST_DELIM_NO_COLON_RE = /[@/?#]/g;
@@ -37580,6 +37611,7 @@ var require_utils = __commonJS(function(exports, module) {
     encodeFragment,
     escapePreservingEscapes,
     removeDotSegments,
+    removeDotSegmentsRelative,
     isIPv4,
     isUUID,
     normalizeIPv6,
@@ -37764,16 +37796,18 @@ var require_schemes = __commonJS(function(exports, module) {
 
 // ../../node_modules/fast-uri/index.js
 var require_fast_uri = __commonJS(function(exports, module) {
-  var { normalizeIPv6, removeDotSegments, recomposeAuthority, normalizePercentEncoding, normalizePathEncoding, serializePathEncoding, normalizeQueryFragmentEncoding, encodeQuery, encodeFragment, reescapeHostDelimiters, isIPv4, nonSimpleDomain } = require_utils();
+  var { normalizeIPv6, removeDotSegments, removeDotSegmentsRelative, recomposeAuthority, normalizePercentEncoding, normalizePathEncoding, serializePathEncoding, normalizeQueryFragmentEncoding, encodeQuery, encodeFragment, reescapeHostDelimiters, isIPv4, nonSimpleDomain } = require_utils();
   var { SCHEMES, getSchemeHandler } = require_schemes();
   var VALID_SCHEME = /^[A-Za-z][A-Za-z0-9+.-]*$/u;
   var MALFORMED_SCHEME_ERROR = "URI scheme is malformed.";
-  function decodeValidScheme(scheme) {
-    const decodedScheme = unescape(String(scheme));
-    if (!VALID_SCHEME.test(decodedScheme)) {
+  var MALFORMED_HOST_ERROR = "URI host is malformed.";
+  var FORBIDDEN_DOMAIN_HOST_CHARACTER = /[\0-\x20"#/:<>?@[\\\]^`{|}\x7F]/u;
+  function validateScheme(scheme) {
+    const stringScheme = String(scheme);
+    if (!VALID_SCHEME.test(stringScheme)) {
       throw new TypeError(MALFORMED_SCHEME_ERROR);
     }
-    return decodedScheme;
+    return stringScheme;
   }
   function normalize(uri, options) {
     if (typeof uri === "string") {
@@ -37808,6 +37842,9 @@ var require_fast_uri = __commonJS(function(exports, module) {
     const resolvedSchemeHandler = getSchemeHandler(options && options.scheme || resolved.scheme);
     const resolvedHost = resolved.host;
     const resolvedHostIsIP = resolvedHost !== undefined && resolvedHost !== "" && (isIPv4(resolvedHost) || normalizeIPv6(resolvedHost).isIPV6);
+    if (hasForbiddenDomainHost(resolved, options || {}, resolvedSchemeHandler, resolvedHostIsIP)) {
+      throw new Error(MALFORMED_HOST_ERROR);
+    }
     canonicalizeHost(resolved, options || {}, resolvedSchemeHandler, resolvedHostIsIP);
     const encodedASCIIHost = resolvedHost && resolvedHost.indexOf("%") !== -1 && !/\P{ASCII}/u.test(resolvedHost);
     if (resolved.error && !encodedASCIIHost) {
@@ -37849,14 +37886,15 @@ var require_fast_uri = __commonJS(function(exports, module) {
           if (relative.path[0] === "/") {
             target.path = removeDotSegments(relative.path);
           } else {
-            if ((base.userinfo !== undefined || base.host !== undefined || base.port !== undefined) && !base.path) {
+            const baseHasAuthority = base.userinfo !== undefined || base.host !== undefined || base.port !== undefined;
+            if (baseHasAuthority && !base.path) {
               target.path = "/" + relative.path;
             } else if (!base.path) {
               target.path = relative.path;
             } else {
               target.path = base.path.slice(0, base.path.lastIndexOf("/") + 1) + relative.path;
             }
-            target.path = removeDotSegments(target.path);
+            target.path = base.scheme === undefined && !baseHasAuthority && target.path[0] !== "/" ? removeDotSegmentsRelative(target.path) : removeDotSegments(target.path);
           }
           target.query = relative.query;
         }
@@ -37894,13 +37932,14 @@ var require_fast_uri = __commonJS(function(exports, module) {
     const options = Object.assign({}, opts);
     const uriTokens = [];
     if (component.scheme) {
-      component.scheme = decodeValidScheme(component.scheme);
+      component.scheme = validateScheme(component.scheme);
     }
     const schemeHandler = getSchemeHandler(options.scheme || component.scheme);
     if (schemeHandler && schemeHandler.serialize)
       schemeHandler.serialize(component, options);
     const hasAuthority = component.userinfo !== undefined || component.host !== undefined || component.port !== undefined;
-    const pathNoScheme = !options.skipEscape && component.scheme === undefined && !hasAuthority;
+    const schemelessReference = (component.scheme === undefined || options.reference === "suffix") && !hasAuthority;
+    const pathNoScheme = !options.skipEscape && schemelessReference;
     if (component.path !== undefined) {
       if (!options.skipEscape) {
         component.path = serializePathEncoding(component.path, pathNoScheme);
@@ -37909,7 +37948,7 @@ var require_fast_uri = __commonJS(function(exports, module) {
       }
     }
     if (options.reference !== "suffix" && component.scheme) {
-      component.scheme = decodeValidScheme(component.scheme);
+      component.scheme = validateScheme(component.scheme);
       uriTokens.push(component.scheme, ":");
     }
     const authority = recomposeAuthority(component);
@@ -37925,9 +37964,9 @@ var require_fast_uri = __commonJS(function(exports, module) {
     if (component.path !== undefined) {
       let s = component.path;
       if (!options.absolutePath && (!schemeHandler || !schemeHandler.absolutePath)) {
-        s = removeDotSegments(s);
+        s = schemelessReference && s[0] !== "/" ? removeDotSegmentsRelative(s) : removeDotSegments(s);
       }
-      if (pathNoScheme) {
+      if (schemelessReference) {
         s = serializePathEncoding(s, true);
       }
       if (authority === undefined && s[0] === "/" && s[1] === "/") {
@@ -37975,16 +38014,32 @@ var require_fast_uri = __commonJS(function(exports, module) {
     return hasMalformedPercentEncoding(matches[3]) || host !== undefined && !isIPLiteral(host) && hasMalformedPercentEncoding(host) || hasMalformedPercentEncoding(matches[6]) || hasMalformedPercentEncoding(matches[7]) || hasMalformedPercentEncoding(matches[8]);
   }
   function canonicalizeHost(parsed, options, schemeHandler, isIP) {
+    if (hasForbiddenDomainHost(parsed, options, schemeHandler, isIP)) {
+      parsed.error = parsed.error || MALFORMED_HOST_ERROR;
+      return true;
+    }
     if (!options.unicodeSupport && (!schemeHandler || !schemeHandler.unicodeSupport) && parsed.host && !isIPLiteral(parsed.host) && (options.domainHost || schemeHandler && schemeHandler.domainHost) && isIP === false && nonSimpleDomain(parsed.host)) {
+      let url;
       try {
-        parsed.host = new URL("http://" + parsed.host).hostname;
+        url = new URL("http://" + parsed.host);
       } catch (e) {
         parsed.error = parsed.error || "Host's domain name can not be converted to ASCII: " + e;
         return true;
       }
+      if (!isHostOnlyURL(url)) {
+        parsed.error = parsed.error || MALFORMED_HOST_ERROR;
+        return true;
+      }
+      parsed.host = url.hostname;
     }
     return false;
   }
+  function hasForbiddenDomainHost(parsed, options, schemeHandler, isIP) {
+    return Boolean(parsed.host && isIP === false && !isIPLiteral(parsed.host) && (options.domainHost || schemeHandler && schemeHandler.domainHost) && FORBIDDEN_DOMAIN_HOST_CHARACTER.test(parsed.host));
+  }
+  function isHostOnlyURL(url) {
+    return url.username === "" && url.password === "" && url.port === "" && url.pathname === "/" && url.search === "" && url.hash === "" && url.hostname !== "";
+  }
   function parseWithStatus(uri, opts) {
     const options = Object.assign({}, opts);
     const parsed = {
@@ -38039,9 +38094,8 @@ var require_fast_uri = __commonJS(function(exports, module) {
       parsed.query = matches[7];
       parsed.fragment = matches[8];
       if (parsed.scheme !== undefined) {
-        const decodedScheme = unescape(parsed.scheme);
-        if (VALID_SCHEME.test(decodedScheme)) {
-          parsed.scheme = decodedScheme.toLowerCase();
+        if (VALID_SCHEME.test(parsed.scheme)) {
+          parsed.scheme = parsed.scheme.toLowerCase();
         } else {
           parsed.error = parsed.error || MALFORMED_SCHEME_ERROR;
           malformedScheme = true;
@@ -38069,7 +38123,7 @@ var require_fast_uri = __commonJS(function(exports, module) {
           malformedIPLiteral = hasIPLiteralBracket && (!bracketedIPLiteral || ipv6result.error === true);
           parsed.host = isIP ? ipv6result.host : ipv6result.host.toLowerCase();
           if (malformedIPLiteral) {
-            parsed.error = parsed.error || "URI host is malformed.";
+            parsed.error = parsed.error || MALFORMED_HOST_ERROR;
             malformedAuthorityOrPort = true;
           }
         } else {
@@ -38097,7 +38151,7 @@ var require_fast_uri = __commonJS(function(exports, module) {
         if (!isIP) {
           host = normalizePercentEncoding(host.toLowerCase());
         }
-        parsed.host = reescapeHostDelimiters(host, isIP);
+        parsed.host = isIP || options.scheme !== "null" ? reescapeHostDelimiters(host, isIP) : host;
       }
       if (!schemeHandler || schemeHandler && !schemeHandler.skipNormalize) {
         if (parsed.path) {
@@ -48308,23 +48362,33 @@ var spec_driven_plan_default = `# [Outcome to deliver]
 
 ### Big Ideas
 
-[Describe the intended behavior and the main architectural choices.]
+[Show changed component relationships with a component diagram, new processes with flowcharts, and new file-based artifacts with trees or suitable visuals. Use Mermaid and fenced text where useful. Keep decisions, responsibilities, invariants, and important failure behavior beside the relevant visual. Draw only the affected parts; keep enough detail to execute without the original chat.]
 
 ### Infrastructure Changes
 
-[Any infra changes. Optional. Only include if there's actual infra being handled in repo.]
+[Actual hosting, services, deployment, networking, or managed-resource changes. New source modules belong in Repo Changes. Write N/A. if no infrastructure changes.]
 
 ### Interfaces
 
-[CLI commands, API endpoint, data contracts, db entities, modules, apps, libs, project tasks added, changed or removed. Summary of how a user's interaction with the app/lib/cli/sdk/etc. will change as a result.]
+[Use compact commands, signatures, code, or pseudocode to show changed public interactions and contracts, including important failure results. Keep implementation actions in the phases.]
 
 ### Consequences
 
-[Trade-offs, risks, compatibility, and what is deferred.]
+#### Repo Changes
+
+[Start with a selected file tree: + new, ~ changed, - removed, * largest edits. Include new modules and meaningful structural changes. Use real inspected paths; label proposed files. State when nothing is removed.]
+
+#### Testing
+
+[Show a nested outline of end-to-end and integration test scenarios, grouped by feature and behavior. Name the entry point, input/action, and expected result for each scenario. Reuse existing fixtures and suites. Match the scenarios to requirements and phase checks.]
+
+#### Trade-offs
+
+[Risks, compatibility, and what is deferred.]
 
 ## Phases
 
-[Instructions broken down granularly, specifying modules/classes/methods/files to be added/updated/removed, and relevant technical work done with terse reasoning. Terse for human readers, sufficiently detailed for delegating implementation to less capable language models i.e. a fool proof guide for a junior developer.]
+[Ordered tasks with file/module targets and enough detail to act. Keep decisions and contracts in the design. Specify the exact application behavior for end-to-end tests and the public module behavior for integration tests. Require clear Arrange/Act/Assert blocks. Use relevant checks and existing helpers. Keep conditional commit and CI gates when expected, including for plan go --commit. Follow the execution workflow's commit/push permissions.]
 
 ### Phase 1: [Outcome]
 
@@ -48333,8 +48397,9 @@ var spec_driven_plan_default = `# [Outcome to deliver]
 - [ ] [Task C]
 - [ ] [Task D]
 - [ ] Validation
-  - [ ] Lint, format, etc.
-  - [ ] Commit, CI green (if expected)
+  - [ ] [Observable application/module contract and the existing or proposed check.]
+  - [ ] [Relevant format, lint, or build checks.]
+  - [ ] [Commit and confirm CI is green, if expected and authorized.]
 
 ### Phase 2: [Outcome]
 
@@ -48343,8 +48408,9 @@ var spec_driven_plan_default = `# [Outcome to deliver]
 - [ ] [Task C]
 - [ ] [Task D]
 - [ ] Validation
-  - [ ] Lint, format, etc.
-  - [ ] Commit, CI green (if expected)
+  - [ ] [Observable application/module contract and the existing or proposed check.]
+  - [ ] [Relevant format, lint, or build checks.]
+  - [ ] [Commit and confirm CI is green, if expected and authorized.]
 
 ### Phase 3: [Outcome]
 
@@ -48353,8 +48419,9 @@ var spec_driven_plan_default = `# [Outcome to deliver]
 - [ ] [Task C]
 - [ ] [Task D]
 - [ ] Validation
-  - [ ] Lint, format, etc.
-  - [ ] Commit, CI green (if expected)
+  - [ ] [Observable application/module contract and the existing or proposed check.]
+  - [ ] [Relevant format, lint, or build checks.]
+  - [ ] [Commit and confirm CI is green, if expected and authorized.]
 
 ## References
 
@@ -48564,31 +48631,35 @@ var code_review_default = `# Review: [change or pull request]
 
 ## Readability
 
-[Can a new reader follow the flow, names, and error paths? Is code readable for and understandable for an average mide-level developer at a glance?]
+[Do names and code structure show what happens? Compare names with behavior, side effects, and callers. Follow language conventions and established codebase patterns. Flag misleading names and flows that are hard to follow.]
 
 ## Semantic Organization
 
-[Are responsibilities, boundaries, and public APIs arranged by meaning? Are modules semantically meaningful? Is code in applications and libraries well sliced by concerns?]
+[Do modules have clear roles and useful public APIs? Identify mixed responsibilities and unclear ownership. Refactor or simplify at the scope needed to make the change understandable, including across files. Keep unrelated work out of scope.]
 
 ## Maintainability
 
-[Is the code DRY? Is the code over-engineered beyond required scope? Are well trusted / industry-standard libraries and frameworks used for standard tasks? Are domain specific conventions approprate for the codebase being followed? Is basic linting, formatting and static analysis hygiene present?]
+[Does the change follow established codebase patterns and applicable AGENTS.md rules? Check new fields, types, helpers, and dependencies against existing code and callers. Reuse suitable code and remove needless complexity.]
 
 ## Reliability/Testing
 
-[Behavior, edge cases, test coverage, and evidence from executed checks. Adhere to repo testing standards if specified in AGENTS.md or docs. Otherwise, generally prioritize e2e coverage and test readability and organization.]
+[Prioritize end-to-end application behavior, then module behavior through public APIs, then focused unit behavior with public APIs first. Name missing observable contracts or regressions; do not demand coverage of every function or a percentage. Check semantic grouping, clear Arrange/Act/Assert blocks, fixtures, and existing shared helpers. Flag walls of repeated setup or interleaved actions/assertions that hide the behavior. Report executed checks and limits honestly.]
+
+## Repository Guidance
+
+[List root/applicable nested AGENTS.md paths and material deviations in changed files. Cite actual rules, including code/test organization and helper placement where prescribed. If none applies or guidance could not be read, say so. Keep this assessment brief.]
 
 ## Performance
 
-[Cost, allocations, I/O, scaling, and measured or expected impact. State SKIPPED with reasons for non-perf bugfixes, minor refactors, and non-performance critical applications.]
+[Report material regressions with evidence. Avoid nitpicks and minor optimizations. Deepen the audit for an explicit performance focus. Otherwise mark a deeper audit SKIPPED with a short reason.]
 
 ## Security
 
-[Evaluate authentication and autorization, permissions, secrets, dependencies, input validation, proper error handling, and trust boundaries. State SKIPPED if skipped with reason, for example for chores, simple scripting, pure cosmetic UI work, documentation, etc.]
+[Report clear security defects, including exposed secrets or broken authorization/trust boundaries. Deepen the audit for an explicit security focus; avoid unrelated hardening requests. State SKIPPED with a short reason when a deeper audit is not warranted.]
 
 ## Change Requests
 
-Track actionable inline requests with one entry per request. End each generated request and response with its own model attribution quote; preserve human text unchanged.
+Use short comments in simple English. State the problem and its effect directly. Phrase recommendations as suggestions with \u201CLet's\u201D, \u201CI suggest\u201D, or \u201CI recommend\u201D, usually in one to three sentences total. Use the scope that fixes the problem, including a refactor when needed. Group repeated instances of one cause. Omit nitpicks, minor optimizations, and speculative findings. End each generated request and response with its model attribution quote. Preserve human text unchanged.
 
 ### [file:line \u2014 request]
 
@@ -48603,13 +48674,13 @@ Track actionable inline requests with one entry per request. End each generated
 
 ## Findings
 
-| Severity                 | Location    | Evidence and impact        | Required change or question |
-| ------------------------ | ----------- | -------------------------- | --------------------------- |
-| [blocking/consider/note] | [file:line] | [reproducible observation] | [concrete action]           |
+| Severity | Location | Evidence and impact | Required change or question |
+| --- | --- | --- | --- |
+| [blocking/consider/note] | [file:line] | [reproducible observation] | [concrete action] |
 
 ## Overall Assessment
 
-[Recommendation and reasons; distinguish findings from preferences.]
+[Recommendation and reasons; distinguish material findings from preferences. A clean review may have no change requests. Keep section assessments concise.]
 
 ## Verification and Limits
 
@@ -48726,11 +48797,11 @@ var flow_definition_default = `# {{name}}
 
 ## Flags
 
-| Flag            | Default | Capability    | Effect                                                                             |
-| --------------- | ------- | ------------- | ---------------------------------------------------------------------------------- |
-| --local         | false   | local         | Omit steps with \`unless: --local\`; never forward to every skill.                   |
-| --commit        | false   | local-commit  | Permit only explicitly commit-capable selected steps to make scoped local commits. |
-| --remote-review | false   | remote-review | Opt in to remote review with independent forge authorization.                      |
+| Flag | Default | Capability | Effect |
+| --- | --- | --- | --- |
+| --local | false | local | Omit steps with \`unless: --local\`; never forward to every skill. |
+| --commit | false | local-commit | Permit only explicitly commit-capable selected steps to make scoped local commits. |
+| --remote-review | false | remote-review | Opt in to remote review with independent forge authorization. |
 
 ## Steps
 
@@ -48918,6 +48989,22 @@ base_commit: '{{full SHA of origin/main at branch creation}}'
 
 {{Question to answer and the smallest useful success criterion.}}
 
+## Setup and tasks
+
+{{Tool versions, dependency installation, environment inputs, and required services.}}
+
+| Task | Command | Purpose | Observed result |
+| --- | --- | --- | --- |
+| Build | \`mise run {{build-task}}\` | {{Build the experiment}} | {{Actual result or pending}} |
+| Test | \`mise run {{test-task}}\` | {{Validate the experimental behavior}} | {{Actual result or pending}} |
+| Run {{approach}} | \`mise run {{run-task}}\` | {{Run this prototype; repeat for every approach}} | {{Actual result or pending}} |
+
+{{Explain any genuinely inapplicable build/test task and its alternative validation. Identify unrun checks explicitly.}}
+
+## Code map
+
+{{Focused submodules, their responsibilities and small public APIs, entrypoints, and minimal examples. Keep the experiment direct and avoid speculative abstractions or giant implementation files.}}
+
 ## Alternatives
 
 - {{Alternative or variation to compare, if any.}}
@@ -48963,15 +49050,77 @@ Project owners need to invite teammates without sharing credentials. Recipients
 
 ### Big Ideas
 
-Store a single-use invitation tied to project, email, and expiry. Acceptance adds membership in the same transaction that consumes the invitation. Queue delivery after saving the invite so a temporary email failure cannot lose it.
+Keep invitation policy in the service and transport concerns in the handler. Store a single-use token hash, project, recipient, and expiry. Use the existing mail queue; no new service is needed.
+
+\`\`\`mermaid
+flowchart LR
+  HTTP["HTTP handler"] --> Service["Invitation service<br/>eligibility and acceptance"]
+  Service --> Store["Invitation store<br/>atomic membership + consumption"]
+  Service --> Queue["Existing mail queue"]
+\`\`\`
+
+Acceptance adds membership and consumes the invitation in one transaction. Invalid acceptance leaves both unchanged. Queue delivery after saving, so an email outage cannot lose an invitation.
+
+\`\`\`mermaid
+flowchart TD
+  Accept["Recipient accepts"] --> Check{"Correct recipient,<br/>unused and unexpired?"}
+  Check -->|"no"| Reject["Reject; leave state unchanged"]
+  Check -->|"yes"| Save["Create membership + consume token<br/>in one transaction"]
+  Save --> Result["Return membership"]
+\`\`\`
+
+### Infrastructure Changes
+
+N/A.
 
 ### Interfaces
 
-\`POST /projects/:id/invitations\` creates a pending invite; \`POST /invitations/:token/accept\` returns membership or a safe expired/used error. \`src/invitations/store.ts\` owns persistence; \`src/invitations/service.ts\` owns eligibility, expiry, and token consumption; \`src/http/invitations.ts\` maps results to responses.
+\`\`\`text
+POST /projects/:id/invitations      -> pending invitation (owner only)
+POST /invitations/:token/accept     -> membership or safe rejection
+
+createInvitation(project, email)   -> save token hash, then queue delivery
+acceptInvitation(token, recipient) -> validate, then atomically consume + join
+\`\`\`
+
+Never log raw tokens. Apply the existing request rate limit to creation; do not disclose another recipient's account details.
 
 ### Consequences
 
-Email delivery can fail after persistence, so queue retries and show a pending invitation. Rate-limit creation to avoid abuse. Resend and cancellation are deferred.
+#### Repo Changes
+
+Illustrative paths: \`+\` new, \`~\` changed, \`*\` largest edits. No files are removed.
+
+\`\`\`text
+src/
+\u251C\u2500\u2500 invitations/
+\u2502   \u251C\u2500\u2500 store.ts               +   persistence and transaction
+\u2502   \u251C\u2500\u2500 service.ts             + * invitation policy
+\u2502   \u2514\u2500\u2500 service.spec.ts        +   public API with real test store
+\u2514\u2500\u2500 http/
+    \u251C\u2500\u2500 routes.ts              ~   register invitation handlers
+    \u251C\u2500\u2500 invitations.ts         +   transport and authorization
+    \u2514\u2500\u2500 invitations.spec.ts    +   application request scenarios
+\`\`\`
+
+#### Testing
+
+\`\`\`text
+end-to-end/
+\u2514\u2500\u2500 invitation acceptance
+    \u251C\u2500\u2500 owner sends invite -> recipient accepts -> membership appears
+    \u2514\u2500\u2500 wrong recipient, expired, or used token -> rejection; state unchanged
+integration/
+\u2514\u2500\u2500 invitation service
+    \u251C\u2500\u2500 failed transaction -> membership and token changes roll back
+    \u2514\u2500\u2500 email failure -> saved invitation stays pending for retry
+\`\`\`
+
+Use request scenarios in \`src/http/invitations.spec.ts\` and service scenarios in \`src/invitations/service.spec.ts\`. Reuse fixtures with a real test store.
+
+#### Trade-offs
+
+Email delivery can fail after persistence. Use existing queue retries and keep the invitation pending. Resend, cancellation, and bulk invitations are deferred.
 
 ## Phases
 
@@ -48979,19 +49128,20 @@ Email delivery can fail after persistence, so queue retries and show a pending i
 
 - [ ] Add a unique token hash, recipient email, project ID, expiry, and consumed timestamp to invitation storage in \`src/invitations/store.ts\`; never log raw tokens.
 - [ ] Implement transactional membership creation and token consumption in \`src/invitations/service.ts\`; reject expired, used, or wrong-recipient tokens without a membership change.
-- [ ] Add boundary, repeat-use, and rollback tests in \`src/invitations/service.test.ts\`.
+- [ ] Exercise \`createInvitation\` and \`acceptInvitation\` through the service public API with the real test store in \`src/invitations/service.spec.ts\`. Verify rejection leaves membership and token state unchanged, including a failed transaction.
 - [ ] Validation
-  - [ ] Run invitation unit tests, lint, and format checks.
-  - [ ] Commit this phase and confirm CI is green.
+  - [ ] Run the service contract scenarios; use grouped fixtures and clear Arrange/Act/Assert blocks.
+  - [ ] Run relevant lint and format checks.
 
 ### Phase 2: Expose and deliver invitations
 
 - [ ] Add owner creation and recipient acceptance handlers in \`src/http/invitations.ts\` with safe error responses and creation rate limits.
 - [ ] Queue delivery after persistence, retry transient mail failures, and expose the pending state to owners.
-- [ ] Add endpoint integration tests for authorization, expiry, used tokens, and delivery failures in \`src/http/invitations.spec.ts\`.
+- [ ] In \`src/http/invitations.spec.ts\`, send an owner invitation, accept as its recipient, and read back membership. Verify wrong-recipient, expired, and used-token requests leave state unchanged. Verify an email failure keeps the saved invitation pending.
 - [ ] Validation
-  - [ ] Run unit and integration tests, lint, and format checks.
-  - [ ] Commit this phase and confirm CI is green.
+  - [ ] Run the end-to-end acceptance/rejection scenarios, then the service integration scenarios listed above.
+  - [ ] Run relevant lint and format checks. This example grants no commit or push permission.
+  - [ ] If execution authorizes commits and expects CI, commit the changes and confirm CI is green for that commit.
 
 ## References
 
@@ -49022,17 +49172,77 @@ Readers should retain access to historical activity while the team changes stora
 
 Write to both stores temporarily, backfill older records with stable IDs, compare counts and ordering, then switch readers behind a reversible flag. Keep the legacy reader authoritative until the new store is verified.
 
+\`\`\`mermaid
+flowchart LR
+  Writer["Activity writer"] --> Old["Legacy store"]
+  Writer -->|"new dual write"| New["New store"]
+  Old --> Backfill["Resumable backfill"] --> New
+  Reader["Public history reader"] --> Flag{"Read flag"}
+  Flag -->|"default / rollback"| Old
+  Flag -->|"after parity check"| New
+\`\`\`
+
+Stable IDs make retries safe. Track failed writes so comparison cannot silently treat missing data as a successful migration.
+
+\`\`\`mermaid
+flowchart TD
+  Provision["Provision store and credentials"] --> Dual["Enable dual writes"]
+  Dual --> Backfill["Backfill in restartable batches"]
+  Backfill --> Compare{"IDs, order,<br/>and cursors match?"}
+  Compare -->|"no"| Repair["Report and repair; keep old reader"] --> Backfill
+  Compare -->|"yes"| Switch["Switch read flag; keep dual writes"]
+  Switch --> Rollback["Rollback: select old reader<br/>without losing new writes"]
+\`\`\`
+
 ### Infrastructure Changes
 
 Provision the new activity store and credentials before dual writes. Retain the legacy store and its capacity until the rollback window closes; monitor write failures for each store separately.
 
 ### Interfaces
 
-\`listActivity(projectId, cursor)\` preserves ordering and cursor behavior during cutover. \`src/activity/writer.ts\` owns dual writes, \`src/activity/backfill.ts\` copies historical records, and \`src/activity/reader.ts\` selects the store behind the feature flag.
+\`\`\`text
+writeActivity(event)                 -> stable ID; retry failed destination writes
+backfillActivity(projectId, cursor)  -> checkpoint + discrepancy report
+listActivity(projectId, cursor)      -> same records, order, and cursor contract
+readSource = legacy | new            # reversible; legacy remains default
+\`\`\`
 
 ### Consequences
 
-Dual writes increase latency and create a risk of partial failure. Record discrepancies and retry failed writes instead of hiding them. Removing the legacy store is outside this plan.
+#### Repo Changes
+
+Illustrative paths: \`+\` new, \`~\` changed, \`*\` largest edits. No files are removed.
+
+\`\`\`text
+infra/
+\u2514\u2500\u2500 activity-store.tf            +   store, credentials, write-failure metrics
+src/
+\u2514\u2500\u2500 activity/
+    \u251C\u2500\u2500 writer.ts                ~ * dual writes and retries
+    \u251C\u2500\u2500 backfill.ts              + * resumable batches and comparison
+    \u251C\u2500\u2500 reader.ts                ~   reversible read source
+    \u251C\u2500\u2500 migration.spec.ts        +   public API parity and restart scenarios
+    \u2514\u2500\u2500 history.spec.ts          ~   application history across cutover/rollback
+\`\`\`
+
+#### Testing
+
+\`\`\`text
+end-to-end/
+\u2514\u2500\u2500 activity history
+    \u251C\u2500\u2500 write and page history across cutover -> same records and cursors
+    \u2514\u2500\u2500 write after cutover, then roll back -> no lost events
+integration/
+\u2514\u2500\u2500 activity storage
+    \u251C\u2500\u2500 retry a failed destination -> one logical event in each store
+    \u2514\u2500\u2500 interrupt and resume backfill -> same IDs and order; no duplicates
+\`\`\`
+
+Use \`src/activity/history.spec.ts\` for application scenarios and \`src/activity/migration.spec.ts\` for public storage APIs with real test stores.
+
+#### Trade-offs
+
+Dual writes increase latency and allow partial failure. Record discrepancies and retry failed writes instead of hiding them. Removing the legacy store is outside this plan.
 
 ## Phases
 
@@ -49040,28 +49250,29 @@ Dual writes increase latency and create a risk of partial failure. Record discre
 
 - [ ] Provision the new store and credentials; add write-failure metrics for both stores.
 - [ ] Make \`src/activity/writer.ts\` write idempotently to both stores with stable activity IDs while retaining the legacy reader.
-- [ ] Test partial-write retries and duplicate events in \`src/activity/writer.test.ts\`.
+- [ ] Exercise \`writeActivity\` against both test stores in \`src/activity/migration.spec.ts\`: retry a failed destination and verify one logical event in each store.
 - [ ] Validation
-  - [ ] Run writer tests, lint, and format checks; confirm write-failure metrics are visible.
-  - [ ] Commit this phase and confirm CI is green.
+  - [ ] Run public writer contract scenarios; confirm write-failure metrics are visible.
+  - [ ] Run relevant lint and format checks.
 
 ### Phase 2: Backfill and compare
 
 - [ ] Add resumable, idempotent batches in \`src/activity/backfill.ts\` without replacing newer dual-written records.
 - [ ] Compare record IDs, counts, and ordering per project; report mismatches before any reader switch.
-- [ ] Add backfill restart and parity tests in \`src/activity/backfill.test.ts\`.
+- [ ] Extend \`migration.spec.ts\` through \`backfillActivity\` and \`listActivity\`: interrupt and resume a batch, then verify IDs, ordering, and cursors match without duplicate or lost events.
 - [ ] Validation
-  - [ ] Run backfill and writer tests, lint, and format checks; review mismatch reports.
-  - [ ] Commit this phase and confirm CI is green.
+  - [ ] Run module public-API scenarios and review mismatch reports. Keep fixtures shared and Arrange/Act/Assert visible.
+  - [ ] Run relevant lint and format checks.
 
 ### Phase 3: Switch reads with rollback
 
 - [ ] Route \`listActivity(projectId, cursor)\` through a reversible flag in \`src/activity/reader.ts\` and preserve cursor compatibility.
-- [ ] Test new-store reads, cursor boundaries, and rollback to the legacy reader in \`src/activity/reader.spec.ts\`.
+- [ ] Extend application scenarios in \`src/activity/history.spec.ts\`: write and read paged history, switch stores, write again, and roll back. Assert the same visible history without lost events; do not assert private helper calls.
 - [ ] Keep dual writes and monitor parity through the rollback window.
 - [ ] Validation
-  - [ ] Run unit and integration tests, lint, and format checks; verify flag rollback.
-  - [ ] Commit this phase and confirm CI is green.
+  - [ ] Run the end-to-end cutover/rollback scenarios, then the storage integration scenarios listed above.
+  - [ ] Run relevant lint and format checks. This example grants no commit or push permission.
+  - [ ] If execution authorizes commits and expects CI, commit the changes and confirm CI is green for that commit.
 
 ## References
 
@@ -49246,54 +49457,97 @@ Enable for a small cohort, compare completion and feedback, then expand or disab
 var init_prd_onboarding = () => {};
 
 // templates/examples/review-change.md
-var review_change_default = `# Review: invitation expiry change
+var review_change_default = `# Review: invitation acceptance
+
+- **Revision:** illustrative-change-17
+- **Intent:** Accept a valid invitation and reject an expired one without changing membership.
+- **Reviewer:** Authored example, not an executed review.
 
-- **Revision:** example-change-17
-- **Intent:** Reject expired invitations without creating membership.
-- **Reviewer:** Example reviewer
+This is a fictional example. A real review must use its runtime model name in attribution.
 
 ## Intent Delivery
 
-The acceptance path checks expiry before membership creation. The resend path was not part of this change.
+The change adds an acceptance path. Helper tests do not establish that the request saves membership or leaves it unchanged on rejection.
 
 ## Readability
 
-Function names describe outcomes, and the request path is understandable without tracing helpers. Move the expiry guard before token decoding so a mid-level maintainer can see the rejection path at a glance.
+\`loadInvitation\` consumes the token and creates membership. I suggest \`acceptInvitation\` so callers can see the write.
 
 ## Semantic Organization
 
-Invitation policy belongs in the invitation service, not the HTTP handler. The handler should own transport errors; the service should own token and membership rules.
+The handler maps HTTP to the service. The store owns persistence. No refactor is needed here.
 
 ## Maintainability
 
-The shared expiry helper avoids duplicate rules in request and background paths. No new library or abstraction is needed for this change; formatting and static analysis should remain clean.
+The change follows the existing store pattern and reuses invitation status.
 
 ## Reliability/Testing
 
-Tests cover expiry at the boundary and a used token. A clock-skew case is missing; add a readable test that checks the server clock source and confirms no membership is created on rejection.
+Helper tests do not prove that acceptance saves membership. Let's add application scenarios for acceptance and rejection, then read membership back.
+
+Repeated setup and nested assertions hide the scenario in \`service.spec.ts:18\`. I suggest a fixture and separate blocks:
+
+\`\`\`ts
+describe('acceptInvitation', () => {
+  test('rejects an expired invitation without adding membership', async () => {
+    // Arrange
+    const { service, members, recipient, expiredToken } = await invitationFixture()
+
+    // Act
+    const acceptance = service.acceptInvitation(expiredToken, recipient.id)
+
+    // Assert
+    await expect(acceptance).rejects.toThrow(InvitationExpiredError)
+    expect(await members.list(recipient.id)).toEqual([])
+  })
+})
+\`\`\`
+
+The fixture creates a real test store. I recommend keeping the action and assertions visible and reusing shared setup.
+
+## Repository Guidance
+
+The fictional \`AGENTS.md\` requires Arrange/Act/Assert blocks and local helpers at the bottom. I suggest separating the mixed steps in \`service.spec.ts:18\`.
 
 ## Performance
 
-One lookup occurs per acceptance; no new unbounded loop is present.
+SKIPPED: no concrete performance regression is shown and no deep performance audit was requested.
 
 ## Security
 
-The response does not reveal whether an address has an account. The recipient is authorized before the token is consumed, tokens are treated as opaque values, and failed acceptance does not create membership.
+SKIPPED: no concrete security defect is shown; an exhaustive security audit is outside this example's scope.
+
+## Change Requests
+
+### src/invitations/service.ts:42 \u2014 Name the state-changing operation
+
+- **Status:** open
+- **Request:** \`loadInvitation\` also writes membership. I suggest renaming it to \`acceptInvitation\` and updating callers.
+
+> Generated via [actual model name from runtime]
+
+### src/invitations/service.spec.ts:18 \u2014 Expose the scenario and test its public result
+
+- **Status:** open
+- **Request:** I suggest the fixture and Arrange/Act/Assert blocks above. Let's add acceptance/rejection scenarios that check saved membership, not just helpers.
+
+> Generated via [actual model name from runtime]
 
 ## Findings
 
-| Severity | Location                | Evidence and impact                               | Required change or question                           |
-| -------- | ----------------------- | ------------------------------------------------- | ----------------------------------------------------- |
-| consider | \`src/invitations.ts:52\` | Clock skew near expiry may reject valid requests. | Add a boundary test and document server clock source. |
+| Severity | Location | Evidence and impact | Required change or question |
+| --- | --- | --- | --- |
+| consider | \`src/invitations/service.ts:42\` | A query-like name hides token consumption and membership creation. | I suggest renaming the operation and callers. |
+| consider | \`src/invitations/service.spec.ts:18\` | Repeated setup hides the action; helper coverage does not establish saved membership or rejection behavior. | I suggest clear blocks, a fixture, and a public/application scenario. |
 
 ## Overall Assessment
 
-No blocking issue found in the reviewed path; address the boundary test before release.
+I recommend clearer API naming and acceptance/rejection scenarios. No private-helper coverage or speculative clock-skew request is needed.
 
 ## Verification and Limits
 
-- **Checks run:** \`bun test src/invitations.test.ts\` \u2014 passed in this example.
-- **Not verified:** Real email delivery and production clock behavior.
+- **Checks run:** none; this is an authored example, not a report of passing tests.
+- **Not verified:** execution, actual repository guidance, real email delivery, and production behavior.
 `;
 var init_review_change = () => {};
 
@@ -52070,7 +52324,7 @@ function createProgram(write = console.log, version = "0.1.0", options = {}) {
 
 // src/index.ts
 init_errors3();
-var version2 = "0.8.0";
+var version2 = "0.9.0";
 try {
   await createProgram(console.log, version2).parseAsync(process.argv);
 } catch (error) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@difflab/difflab-cli",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "private": false,
   "description": "A minimal Bun CLI starter built with Commander",
   "license": "Apache-2.0",