@difflab/difflab-cli 0.12.0 → 0.13.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +6 -6
  2. package/dist/index.js +217 -127
  3. package/package.json +2 -2
package/README.md CHANGED
@@ -66,7 +66,7 @@ difflab-cli templates list
66
66
  difflab-cli templates scaffold spec-driven-plan docs/plans first-plan.md --cwd /absolute/project/path
67
67
  ```
68
68
 
69
- The CLI defaults `--cwd` to its current directory. The MCP server exposes `template_list({})` and `scaffold({"name":"spec-driven-plan","cwd":"/absolute/project/path","path":"docs/plans","filename":"first-plan.md"})`. Both interfaces take a hyphenated template name, a relative destination **directory** (`path`, or `.` for `cwd`), and a separate **filename**. MCP always requires an absolute existing `cwd`. Missing destination directories are created. Available names: `spec-driven-plan`, `software-architecture-design`, `architecture-decision-record`, `product-requirements-document`, `agents`, `code-review`, `code-review-rubric`, `planning-intent`, `ui-component-architecture`, `pull-request-description` (adapted from Diffpi's PR template), `flow-definition`, `flow-instance`, `exploration-summary`, `exploration-research`, `exploration-proposal`, and `poc-readme`.
69
+ The CLI defaults `--cwd` to its current directory. The MCP server exposes `template_list({})` and `scaffold({"name":"spec-driven-plan","cwd":"/absolute/project/path","path":"docs/plans","filename":"first-plan.md"})`. Both interfaces take a hyphenated template name, a relative destination **directory** (`path`, or `.` for `cwd`), and a separate **filename**. MCP always requires an absolute existing `cwd`. Missing destination directories are created. Available names: `spec-driven-plan`, `software-architecture-design`, `architecture-decision-record`, `product-requirements-document`, `agents`, `code-review`, `code-review-rubric`, `planning-intent`, `ui-component-architecture`, `pull-request-description` (adapted from Diffpi's PR template), `flow-definition`, `flow-instance`, `exploration-summary`, `exploration-research`, `exploration-proposal`, `poc-readme`, `hook-definition`, and `task`.
70
70
 
71
71
  Reviews scaffold `code-review` as `REVIEW.md` and `code-review-rubric` as `rubric.yaml` in `.difflab/reviews/YYMMDD-name`. The installed rubric is `~/.difflab/templates/code-review-rubric.yaml`. Fill its criterion results during the review. File-scoped criteria require a path-tagged result for every changed source file. Function findings can include `file:line` locations. Evidence guidance and review instructions stay in the review skill, outside the lean YAML template.
72
72
 
@@ -74,15 +74,15 @@ Use `difflab-cli templates scaffold agents . AGENTS.md --cwd /absolute/project/p
74
74
 
75
75
  On first use, missing bundled templates and filled examples are copied to `~/.difflab/templates` and `~/.difflab/templates/examples`. Edit the installed templates to customize future documents. Later runs add missing files but never replace existing ones, even after an upgrade. Examples are for reference, not selectable templates. Copying is literal: prompts and placeholders are not substituted. An unknown name, missing or invalid source, unsafe path, symlink, or existing destination causes an error; destination files are never overwritten. The target directory must remain inside `cwd` and the filename must be a single file name without separators. The one symlink exception is an initialized repository's `.difflab` link to its own user project store: `templates scaffold spec-driven-plan .difflab/plans/YYMMDD-name PLAN.md --cwd /absolute/repo` works in Git worktrees as well. To restore a bundled default, move your installed copy aside before listing again.
76
76
 
77
- 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.
77
+ The portable `skills/difflab-plan`, `skills/difflab-review`, `skills/difflab-flow`, `skills/difflab-hooks`, `skills/difflab-bdd`, `skills/difflab-writing-style`, `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.
78
78
 
79
- 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 with `[M/A/D/R]` notation and BDD-style `given`/`when`/`then` clauses mapped to existing suites or clearly labeled manual acceptance checks. 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.
79
+ The [plan authoring guide](../../skills/difflab-plan/references/authoring.md) applies `difflab-writing-style` and `difflab-bdd`. It requires component/process/artifact visuals, compact interfaces, and a directory-grouped `[M/A/D/R]` repo tree at the start of `Consequences`. Add a `Testing` subsection with a behavior flowchart and a matching `[M/A/D/R]` BDD test tree (`given`/`when`/`then`) mapped to existing suites or clearly labeled manual acceptance checks. 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.
80
80
 
81
- The [review rubric](../../skills/difflab-review/references/rubric.md) follows written `AGENTS.md` rules and named style guides. Existing patterns are context, not requirements. Flag material antipatterns even when nearby code shares them. Refactor unclear code at the scope needed. Prefer outside-in tests (`e2e` > `integration` > `unit`) with human-verifiable outputs, and scrutinize unit test organization for BDD/Gherkin structure and clear Arrange/Act/Assert blocks. Untested private functions alone are not findings. Keep whole reports and comments short (one sentence per comment ideally) and use simple English; prefer code snippets or diagrams over walls of text. State findings once and keep detailed coverage in YAML. Omit nitpicks and minor optimizations. Explicit security/performance focuses deepen those audits.
81
+ The [review rubric](../../skills/difflab-review/references/rubric.md) follows written `AGENTS.md` rules, `difflab-writing-style`, and `difflab-bdd`. Existing patterns are context, not requirements. Flag material antipatterns even when nearby code shares them. Refactor unclear code at the scope needed. Prefer outside-in tests (`e2e` > `integration` > `unit`) with human-verifiable outputs, and scrutinize test suites against the component's behavior flowchart to propose BDD tree reorganizations (`given`/`when`/`then` with hoisted fixtures) when needed. Untested private functions alone are not findings. Keep whole reports and comments short (one sentence per comment ideally) and use simple English; prefer code snippets or diagrams over walls of text. State findings once and keep detailed coverage in YAML. Omit nitpicks and minor optimizations. Explicit security/performance focuses deepen those audits.
82
82
 
83
- Reviews keep the selected frontier model regardless of vendor. One reviewer covers the full rubric. `--bg` runs a complete review in the background. `--council [model-a,model-b]` uses full reviewers per model and saves reports under `council/`. Names accept aliases and clear typos. The lead aggregates supported findings and publishes once. `--adversarial` challenges all dimensions, including Security. Missing model capabilities or incomplete passes are reported honestly.
83
+ Reviews run in the current single agent without subagents or councils, keeping the selected frontier model regardless of vendor. `--adversarial` challenges all dimensions, including Security.
84
84
 
85
- PR creation through `pr new`, create, open, or draft uses the installed `pull-request-description` template. Fill its sections before creating the request, then read the saved body back. `pr merge --squash` selects a native forge squash merge before the operation. These are Agent Skill requests, not CLI subcommands.
85
+ PR creation through `pr new`, create, open, or draft always scaffolds and fills the installed `pull-request-description` template before creating the request, then reads the saved body back. `pr merge` watches post-merge CI and then invokes `~/.difflab/hooks/on-merge/HOOK.md` via `difflab-hooks` when registered. `pr merge --squash` selects a native forge squash merge before the operation. These are Agent Skill requests, not CLI subcommands.
86
86
 
87
87
  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.
88
88
 
package/dist/index.js CHANGED
@@ -12497,7 +12497,7 @@ var init_migration = __esm(() => {
12497
12497
  init_migrator();
12498
12498
  });
12499
12499
 
12500
- // ../../libs/difflab-db/src/migrations.ts
12500
+ // ../../libs/difflab-db-legacy/src/migrations.ts
12501
12501
  async function migrate(db) {
12502
12502
  const { error } = await new Migrator({ db, provider }).migrateToLatest();
12503
12503
  if (error)
@@ -12696,7 +12696,7 @@ var init_normal = __esm(() => {
12696
12696
  };
12697
12697
  });
12698
12698
 
12699
- // ../../libs/difflab-db/src/retry.ts
12699
+ // ../../libs/difflab-db-legacy/src/retry.ts
12700
12700
  async function retryDatabaseOperation(work, retryable = isSqliteContention) {
12701
12701
  for (let attempt = 1;; attempt++) {
12702
12702
  try {
@@ -12726,7 +12726,7 @@ function errorChain(error) {
12726
12726
  }
12727
12727
  var maxAttempts = 10;
12728
12728
 
12729
- // ../../libs/difflab-db/src/registry.ts
12729
+ // ../../libs/difflab-db-legacy/src/registry.ts
12730
12730
  import { lstat } from "fs/promises";
12731
12731
  import { resolve } from "path";
12732
12732
  async function withDatabaseAccess(path, work) {
@@ -19227,7 +19227,7 @@ var init_zod = __esm(() => {
19227
19227
  init_external();
19228
19228
  });
19229
19229
 
19230
- // ../../libs/difflab-db/src/entities/repository.ts
19230
+ // ../../libs/difflab-db-legacy/src/entities/repository.ts
19231
19231
  var repositorySchema, validateRepository = (value) => repositorySchema.parse(value);
19232
19232
  var init_repository = __esm(() => {
19233
19233
  init_zod();
@@ -19239,7 +19239,7 @@ var init_repository = __esm(() => {
19239
19239
  });
19240
19240
  });
19241
19241
 
19242
- // ../../libs/difflab-db/src/entities/project.ts
19242
+ // ../../libs/difflab-db-legacy/src/entities/project.ts
19243
19243
  var projectSchema, validateProject = (value) => projectSchema.parse(value);
19244
19244
  var init_project = __esm(() => {
19245
19245
  init_zod();
@@ -19251,7 +19251,7 @@ var init_project = __esm(() => {
19251
19251
  });
19252
19252
  });
19253
19253
 
19254
- // ../../libs/difflab-db/src/queries/projects.ts
19254
+ // ../../libs/difflab-db-legacy/src/queries/projects.ts
19255
19255
  import { randomUUID } from "crypto";
19256
19256
  function validateProjectKey(key) {
19257
19257
  const normalized = key.trim().toUpperCase();
@@ -19355,7 +19355,7 @@ var init_projects = __esm(() => {
19355
19355
  };
19356
19356
  });
19357
19357
 
19358
- // ../../libs/difflab-db/src/queries/repositories.ts
19358
+ // ../../libs/difflab-db-legacy/src/queries/repositories.ts
19359
19359
  import { randomUUID as randomUUID2 } from "crypto";
19360
19360
  function createRepositoryQueries(db, readonly, dbPath) {
19361
19361
  return {
@@ -19412,7 +19412,7 @@ var init_repositories = __esm(() => {
19412
19412
  init_projects();
19413
19413
  });
19414
19414
 
19415
- // ../../libs/difflab-db/src/index.ts
19415
+ // ../../libs/difflab-db-legacy/src/index.ts
19416
19416
  async function createDifflabDb(dbPath, options = {}) {
19417
19417
  const readonly = options.readonly ?? false;
19418
19418
  const db = await openDatabase(dbPath, readonly);
@@ -48351,44 +48351,47 @@ var spec_driven_plan_default = `# [Outcome to deliver]
48351
48351
 
48352
48352
  ## Intent
48353
48353
 
48354
- [Who needs this change, what should be possible afterward, and why now?]
48354
+ [State who needs this change, what becomes possible afterward, and why it matters now.]
48355
48355
 
48356
48356
  ## Requirements
48357
48357
 
48358
- - [Observable outcome and how to tell whether it works.]
48359
- - [Limits and explicit non-goals.]
48358
+ [List observable behavioral capabilities and performance, security, cost, isolation, and reliability characteristics from a client, caller, or end-user perspective. Use plain bullets without \`FR\` or \`NFR\` prefixes. Put internal types, function names, CLI flags, configuration internals, file layouts, and code-style rules in Design and Phases.]
48359
+
48360
+ - [Observable client or end-user behavior and how to make sure that it works.]
48361
+ - [Observable performance, security, cost, isolation, or reliability characteristic.]
48362
+ - [Explicit boundaries and non-goals.]
48360
48363
 
48361
48364
  ## Design
48362
48365
 
48363
48366
  ### Big Ideas
48364
48367
 
48365
- [Lead with compact diagrams. Minimize prose and do not repeat the visual. Use short sentences and familiar words. 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.]
48368
+ [Lead with compact Mermaid diagrams or fenced trees. Drop prose when a diagram shows the structure or flow. Show component relationships with a component diagram, processes with a flowchart, and file artifacts with a tree. Keep decisions, responsibilities, invariants, and failure behavior beside the visual. Draw only affected parts, and include enough detail to execute without the original chat.]
48366
48369
 
48367
48370
  ### Infrastructure Changes
48368
48371
 
48369
- [Actual hosting, services, deployment, networking, or managed-resource changes. New source modules belong in Repo Changes. Write N/A. if no infrastructure changes.]
48372
+ [List hosting, service, deployment, network, or managed-resource changes. Put new source modules in Repo Changes. If no infrastructure changes, write N/A.]
48370
48373
 
48371
48374
  ### Interfaces
48372
48375
 
48373
- [Use compact commands, signatures, code, or pseudocode to show changed public interactions and contracts, including important failure results. Keep implementation actions in the phases.]
48376
+ [Show changed public interactions, contracts, and failure results with compact commands, signatures, code, or pseudocode. Keep implementation steps in Phases.]
48374
48377
 
48375
48378
  ### Consequences
48376
48379
 
48377
48380
  #### Repo Changes
48378
48381
 
48379
- [Start with a selected file tree: [M] modified, [A] added, [D] deleted, [R] renamed before changed filenames, including tests. Identify the largest edits in a short note. Include new modules and meaningful structural changes. Use real inspected paths; label proposed files. State when nothing is removed.]
48382
+ [Draw a directory-grouped file tree with \`[M]\` modified, \`[A]\` added, \`[D]\` deleted, and \`[R]\` renamed markers. Apply \`/difflab-writing-style\`. Use real paths for existing files, label new files, and note the largest edits. If no files are removed, state that explicitly.]
48380
48383
 
48381
48384
  #### Testing
48382
48385
 
48383
- [Inspect the actual test setup first. Show a nested outline of behavior checks mapped to existing suites and configured tasks, using [M], [A], [D], or [R] notation on suites and scenarios just like Repo Changes. Prefer BDD-style test organization with nested given/when/then or it clauses. Label skill checks without a harness as manual acceptance. Do not invent an end-to-end suite or runner. 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.]
48386
+ [Apply \`/difflab-bdd\`. Draw a Mermaid behavior flowchart from the user or caller perspective with context branches, state transitions, and converging states. Map the flowchart to a nested \`[M/A/D/R]\` BDD test tree starting at \`given <context>\` with \`when\` and \`then\` clauses. Collapse single-outcome branches to \`when <action>, then <outcome>\`, and hoist shared fixtures. Prioritize \`e2e\` over \`integration\` over \`unit\`, and name human-verifiable outputs such as screenshots, snapshots, JSON payloads, or logs. If a skill change has no test harness, label its validation steps \`manual acceptance\`.]
48384
48387
 
48385
48388
  #### Trade-offs
48386
48389
 
48387
- [Risks, compatibility, and what is deferred.]
48390
+ [State risks, compatibility limits, and deferred work.]
48388
48391
 
48389
48392
  ## Phases
48390
48393
 
48391
- [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.]
48394
+ [List ordered tasks with file or module targets. Keep design decisions in Design. Name application behavior for end-to-end tests and public module behavior for integration tests. Use separate Arrange, Act, and Assert steps. Follow the execution workflow permissions for commits and pushes.]
48392
48395
 
48393
48396
  ### Phase 1: [Outcome]
48394
48397
 
@@ -48397,9 +48400,9 @@ var spec_driven_plan_default = `# [Outcome to deliver]
48397
48400
  - [ ] [Task C]
48398
48401
  - [ ] [Task D]
48399
48402
  - [ ] Validation
48400
- - [ ] [Observable application/module contract and the existing or proposed check.]
48401
- - [ ] [Relevant format, lint, or build checks.]
48402
- - [ ] [Commit and confirm CI is green, if expected and authorized.]
48403
+ - [ ] [Make sure that the observable application or module contract passes its test.]
48404
+ - [ ] [Run format, lint, and build tasks.]
48405
+ - [ ] [If execution authorizes commits and expects CI, commit changes and make sure that CI passes.]
48403
48406
 
48404
48407
  ### Phase 2: [Outcome]
48405
48408
 
@@ -48408,9 +48411,9 @@ var spec_driven_plan_default = `# [Outcome to deliver]
48408
48411
  - [ ] [Task C]
48409
48412
  - [ ] [Task D]
48410
48413
  - [ ] Validation
48411
- - [ ] [Observable application/module contract and the existing or proposed check.]
48412
- - [ ] [Relevant format, lint, or build checks.]
48413
- - [ ] [Commit and confirm CI is green, if expected and authorized.]
48414
+ - [ ] [Make sure that the observable application or module contract passes its test.]
48415
+ - [ ] [Run format, lint, and build tasks.]
48416
+ - [ ] [If execution authorizes commits and expects CI, commit changes and make sure that CI passes.]
48414
48417
 
48415
48418
  ### Phase 3: [Outcome]
48416
48419
 
@@ -48419,46 +48422,48 @@ var spec_driven_plan_default = `# [Outcome to deliver]
48419
48422
  - [ ] [Task C]
48420
48423
  - [ ] [Task D]
48421
48424
  - [ ] Validation
48422
- - [ ] [Observable application/module contract and the existing or proposed check.]
48423
- - [ ] [Relevant format, lint, or build checks.]
48424
- - [ ] [Commit and confirm CI is green, if expected and authorized.]
48425
+ - [ ] [Make sure that the observable application or module contract passes its test.]
48426
+ - [ ] [Run format, lint, and build tasks.]
48427
+ - [ ] [If execution authorizes commits and expects CI, commit changes and make sure that CI passes.]
48425
48428
 
48426
48429
  ## References
48427
48430
 
48428
- - [Source or related decision.]
48429
- - [External references, docs supporting the implementation plan.]
48431
+ - [Source issue or architecture decision.]
48432
+ - [Supporting external specification or documentation.]
48433
+ - [Related repository path or prior plan.]
48430
48434
  `;
48431
48435
  var init_spec_driven_plan = () => {};
48432
48436
 
48433
48437
  // templates/software-architecture-design.md
48434
- var software_architecture_design_default = `# [System or feature] \u2014 software architecture
48438
+ var software_architecture_design_default = `# [System or feature]: software architecture
48435
48439
 
48436
48440
  ## Overview
48437
48441
 
48438
- [Purpose, system boundary, users, and explicit non-goals.]
48442
+ [State the purpose, system boundary, users, and explicit non-goals.]
48439
48443
 
48440
48444
  ## Requirement
48441
48445
 
48442
48446
  ### Functional
48443
48447
 
48444
- [Functionality app, lib or product must perform.]
48448
+ [List observable behavioral capabilities from a client, caller, or end-user perspective. Use plain bullets without \`FR\` prefixes. Put internal types, function names, configuration internals, file layouts, and code-style rules in Design and Implementation.]
48445
48449
 
48446
- - FR1
48447
- - FR2
48448
- - ...
48450
+ - [Client or end-user capability and observable outcome.]
48451
+ - [Additional client or end-user capability and observable outcome.]
48452
+ - [Explicit behavioral boundary or rejection rule.]
48449
48453
 
48450
48454
  ### Non-Functional
48451
48455
 
48452
- [Performance, security, cost and other non-functional characteristics which the system must fulfil.]
48456
+ [List performance, security, cost, isolation, and reliability characteristics from a client, caller, or end-user perspective. Use plain bullets without \`NFR\` prefixes. Put internal mechanisms in Design and Implementation.]
48453
48457
 
48454
- - NFR1
48455
- - NFR2
48458
+ - [Observable performance, reliability, or cost bound.]
48459
+ - [Observable security or isolation guarantee.]
48460
+ - [Additional external operational characteristic.]
48456
48461
 
48457
48462
  ## Design
48458
48463
 
48459
48464
  ### Components and Responsibilities
48460
48465
 
48461
- [System diagram(s) with bullet list enumerating and explaining components and their relationships. Prefer mermaid diagrams unless user/AGENTS.md provde other stated preferences.]
48466
+ [Draw a system diagram and list each component with its responsibility and relationships. Use Mermaid diagrams unless \`AGENTS.md\` states another format.]
48462
48467
 
48463
48468
  > @agent: add example mermaid diagram
48464
48469
 
@@ -48466,31 +48471,33 @@ var software_architecture_design_default = `# [System or feature] \u2014 softwar
48466
48471
 
48467
48472
  \`\`\`
48468
48473
 
48469
- - Component A does this.
48470
- - It then calls component B to do this.
48471
- - And so on.
48474
+ - [Component A handles this responsibility.]
48475
+ - [Component A calls Component B for that responsibility.]
48476
+ - [Component C stores this state.]
48472
48477
 
48473
48478
  ### Data and Control Flow
48474
48479
 
48475
- [Describe the main request/event path and where state lives. Include flow charts or sequence diagrams if applicable.]
48480
+ [Trace the main request or event path and name where state lives. If a flowchart or sequence diagram clarifies the path, include it.]
48476
48481
 
48477
48482
  ### Interfaces and Contracts
48478
48483
 
48479
- [Database entities, input/output schemas, endpoints, core types, and public methods. Include ERD where applicable.]
48484
+ [List database entities, input and output schemas, endpoints, core types, and public methods. If data models change, include an entity-relationship diagram.]
48480
48485
 
48481
48486
  ## Implementation
48482
48487
 
48483
48488
  ### Important topic 1
48484
48489
 
48485
- [Owned modules, dependency direction, and extension points.]
48490
+ [List owned modules, dependency direction, and extension points.]
48486
48491
 
48487
48492
  ### Important topic 2
48488
48493
 
48489
- [More important topics.]
48494
+ [List operational rules, configuration internals, or code-level invariants.]
48490
48495
 
48491
48496
  ## References
48492
48497
 
48493
48498
  - [Relevant code, ADR, or external specification.]
48499
+ - [Related design document or issue.]
48500
+ - [Applicable external standard or API contract.]
48494
48501
  `;
48495
48502
  var init_software_architecture_design = () => {};
48496
48503
 
@@ -48562,59 +48569,69 @@ var init_architecture_decision_record = () => {};
48562
48569
  // templates/product-requirements-document.md
48563
48570
  var product_requirements_document_default = `# [User outcome or product change]
48564
48571
 
48565
- > @agent: make this closer to the PRD under prd dir!
48566
-
48567
48572
  - **Status:** draft
48568
48573
  - **Owner:** [person or team]
48569
48574
  - **Date:** [YYYY-MM-DD]
48570
48575
 
48571
48576
  ## Summary
48572
48577
 
48573
- [What changes for users, and why?]
48578
+ [State what changes for users and why it matters.]
48574
48579
 
48575
48580
  ## Problem and Evidence
48576
48581
 
48577
- [Who has the problem? Give observed evidence or mark assumptions.]
48582
+ [Name who has the problem and state observed evidence or explicit assumptions.]
48578
48583
 
48579
48584
  ## Users and Use Cases
48580
48585
 
48581
- - [User]: [job to be done and context.]
48586
+ - [Primary user]: [Job to be done and context.]
48587
+ - [Secondary user]: [Job to be done and context.]
48588
+ - [Operator or caller]: [Job to be done and context.]
48582
48589
 
48583
48590
  ## Goals
48584
48591
 
48585
- - [User outcome to achieve.]
48592
+ - [Primary user outcome to achieve.]
48593
+ - [Secondary user outcome to achieve.]
48594
+ - [Operational or quality outcome to achieve.]
48586
48595
 
48587
48596
  ## Non-Goals
48588
48597
 
48589
- - [Related need that this work does not address.]
48598
+ - [Related need that this work excludes.]
48599
+ - [Out-of-scope workflow or integration.]
48600
+ - [Deferred capability for a later release.]
48590
48601
 
48591
48602
  ## Proposed Experience
48592
48603
 
48593
- [Describe the user journey, inputs, outputs, errors, and recovery.]
48604
+ [Describe the user journey, inputs, outputs, error messages, and recovery path.]
48594
48605
 
48595
48606
  ## Requirements
48596
48607
 
48597
- ### [Capability]
48608
+ [Describe observable behavioral capabilities and performance, security, cost, isolation, and reliability characteristics from an end-user or client perspective. Do not use \`FR\` or \`NFR\` prefixes. Leave internal types, function names, configuration internals, file layouts, and code-style rules out of this section.]
48609
+
48610
+ ### [Capability or quality characteristic]
48598
48611
 
48599
- [Required user-facing behavior, edge cases, and constraints.]
48612
+ [State required user-facing behavior, edge cases, and operational bounds.]
48600
48613
 
48601
- **Acceptance:** [Observable way to check the requirement.]
48614
+ Acceptance: [State an observable way to make sure that the requirement works.]
48602
48615
 
48603
48616
  ## Success Measures
48604
48617
 
48605
- [Signal, baseline or assumption, target, and when/how it will be measured.]
48618
+ [State the signal, baseline or assumption, target, and measurement method.]
48606
48619
 
48607
48620
  ## Risks and Dependencies
48608
48621
 
48609
- - [Risk or dependency]: [mitigation or owner.]
48622
+ - [Technical or product risk]: [Mitigation or owner.]
48623
+ - [External dependency]: [Mitigation or owner.]
48624
+ - [Operational or rollout risk]: [Mitigation or owner.]
48610
48625
 
48611
48626
  ## Open Questions
48612
48627
 
48613
- - [Question and decision owner.]
48628
+ - [Product decision and owner.]
48629
+ - [Scope question and owner.]
48630
+ - [Rollout question and owner.]
48614
48631
 
48615
48632
  ## Rollout
48616
48633
 
48617
- [Release, feedback, migration, and rollback plan, if needed.]
48634
+ [Describe the release plan, feedback loop, migration path, and rollback steps.]
48618
48635
  `;
48619
48636
  var init_product_requirements_document = () => {};
48620
48637
 
@@ -48663,9 +48680,9 @@ var code_review_default = `# Review: [change or pull request]
48663
48680
  - **Revision:** [commit or diff]
48664
48681
  - **Intent:** [stated objective and source]
48665
48682
  - **Reviewer:** [actual model identity]
48666
- - **Mode:** [normal/adversarial; single model or council with linked model reports]
48683
+ - **Mode:** [normal/adversarial]
48667
48684
 
48668
- [Use short sentences, active voice, and familiar words throughout. Keep section assessments brief and link to findings instead of repeating them. Keep detailed criterion coverage in rubric.yaml. Apply AGENTS.md and named style guides. Informal conventions are context, not requirements. Flag material antipatterns even when existing code shares them.]
48685
+ [Apply \`/difflab-writing-style\` and \`/difflab-bdd\`. Use short sentences, active voice, and familiar words throughout. Keep section assessments brief and link to findings instead of repeating them. Keep detailed criterion coverage in rubric.yaml. Apply AGENTS.md and named style guides. Informal conventions are context, not requirements. Flag material antipatterns even when existing code shares them.]
48669
48686
 
48670
48687
  ## Intent Delivery
48671
48688
 
@@ -48685,11 +48702,11 @@ var code_review_default = `# Review: [change or pull request]
48685
48702
 
48686
48703
  ## Reliability/Testing
48687
48704
 
48688
- [Prioritize end-to-end application behavior, then module behavior through public APIs, then focused unit behavior with public APIs first. Flag tests that only verify external dependencies rather than the repository's source behavior or integration contract. Require test names to identify the function or functionality tested and its expected behavior, regardless of grouping style. 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.]
48705
+ [Apply \`/difflab-bdd\`. Analyze tests against the component's behavior flowchart (converging state branches, \`e2e\` > \`integration\` > \`unit\`, and human-verifiable outputs such as screenshots, replays, file dumps, snapshots, JSON outputs, or debug logs). Propose a concrete \`[M/A/D/R]\` BDD test tree reorganization (\`given\` -> \`when\` -> \`then\` with hoisted fixtures) when tests are flat, repeat downstream assertions across converged states, or obscure setup. Flag tests that only verify external dependencies rather than the repository's source behavior. Report executed checks and limits honestly.]
48689
48706
 
48690
48707
  ## Documentation
48691
48708
 
48692
- [Flag walls of text, complex language, and text that only restates the implementation. Require concise, simple-English explanations. Prefer diagrams when they clarify structures, flows, or relationships better than long prose.]
48709
+ [Apply \`/difflab-writing-style\`. Flag walls of text, complex language, and text that only restates the implementation. Require concise \`/simple-english\` explanations, domain terminology, and Mermaid/Draw.io diagrams or \`[M/A/D/R]\` trees when visuals communicate structure or flow better than prose.]
48693
48710
 
48694
48711
  ## Performance
48695
48712
 
@@ -48728,7 +48745,6 @@ State each finding once here, with its issue, effect, and useful fix. Use short,
48728
48745
 
48729
48746
  - **Checks run:** [command and result.]
48730
48747
  - **Not verified:** [environment, path, behavior, or applicable repository guidance that could not be checked.]
48731
- - **Council:** [source reports, actual model identities, unresolved disagreements, or not selected.]
48732
48748
  - **Rubric:** [path to the copied YAML rubric with completed criterion results. Disclose missing, pending, skipped, or stale results.]
48733
48749
  `;
48734
48750
  var init_code_review = () => {};
@@ -48744,8 +48760,6 @@ review:
48744
48760
  changed_files: []
48745
48761
  exclusions: []
48746
48762
  reviewers: []
48747
- model_inputs: []
48748
- model_results: []
48749
48763
  sections:
48750
48764
  - title: Intent Delivery
48751
48765
  criteria:
@@ -48765,12 +48779,12 @@ sections:
48765
48779
  scope: file
48766
48780
  default_severity: consider
48767
48781
  issue: >-
48768
- Function or other names misrepresent behavior, hide side effects, or violate written naming rules.
48782
+ Function or symbol names misrepresent behavior, hide side effects, or break written naming rules.
48769
48783
  results: []
48770
48784
  - id: readability.structure
48771
48785
  scope: file
48772
48786
  default_severity: consider
48773
- issue: The changed flow is materially hard to follow.
48787
+ issue: The changed control flow is hard to follow.
48774
48788
  results: []
48775
48789
  - title: Semantic Organization
48776
48790
  criteria:
@@ -48782,25 +48796,25 @@ sections:
48782
48796
  - id: organization.architecture
48783
48797
  scope: review
48784
48798
  default_severity: consider
48785
- issue: Files or classes mix responsibilities, obscure ownership, or violate written architecture rules.
48799
+ issue: Files or classes mix responsibilities, obscure ownership, or break written architecture rules.
48786
48800
  results: []
48787
48801
  - id: organization.api-ergonomics
48788
48802
  scope: applicable-file
48789
48803
  applies_when: Added or modified public APIs, exported types, methods, or classes.
48790
48804
  default_severity: consider
48791
- issue: Public APIs expose types unrelated to the module role or are hard to discover and use.
48805
+ issue: Public APIs expose types unrelated to the module role or remain hard to discover and use.
48792
48806
  results: []
48793
48807
  - id: organization.new-files
48794
48808
  scope: applicable-file
48795
48809
  applies_when: Added source files that introduce a module or submodule. A rename alone does not qualify.
48796
48810
  default_severity: consider
48797
48811
  issue: >-
48798
- A new file lacks a justified module boundary or contains functions that belong in an existing module.
48812
+ A new file lacks a clear module boundary or contains functions that belong in an existing module.
48799
48813
  results: []
48800
48814
  - id: organization.file-structure
48801
48815
  scope: file
48802
48816
  default_severity: consider
48803
- issue: A file breaks the project-prescribed structure or declaration order.
48817
+ issue: A file breaks the prescribed section order or declaration layout.
48804
48818
  results: []
48805
48819
  - title: Maintainability
48806
48820
  criteria:
@@ -48808,93 +48822,101 @@ sections:
48808
48822
  scope: review
48809
48823
  default_severity: consider
48810
48824
  issue: >-
48811
- New fields, types, wrappers, helpers, dependencies, or layers lack a justified use and add needless complexity.
48825
+ New fields, types, wrappers, helpers, dependencies, or layers lack a clear caller need and add complexity.
48812
48826
  results: []
48813
48827
  - id: maintainability.complexity
48814
48828
  scope: applicable-file
48815
48829
  applies_when: >-
48816
- Files with added or changed executable functions. For new functions, assess whether the introduced decision paths are justified.
48830
+ Files with added or changed executable functions. For new functions, evaluate whether required behavior needs the introduced branches.
48817
48831
  default_severity: consider
48818
- issue: Cyclomatic complexity grows without justification from the required behavior.
48832
+ issue: Cyclomatic complexity grows beyond what the required behavior needs.
48819
48833
  results: []
48820
48834
  - id: maintainability.utilities
48821
48835
  scope: review
48822
48836
  default_severity: consider
48823
- issue: Duplicated state or behavior, or inline work, makes a function harder to read or maintain.
48837
+ issue: Duplicated state, repeated logic, or inline work makes a function hard to read or maintain.
48824
48838
  results: []
48825
48839
  - id: maintainability.packages
48826
48840
  scope: review
48827
48841
  default_severity: consider
48828
48842
  issue: >-
48829
- Custom code recreates functionality that an established, widely used package suitably provides.
48843
+ Custom code recreates functionality that an established package already provides.
48830
48844
  results: []
48831
48845
  - title: Reliability/Testing
48832
48846
  criteria:
48833
48847
  - id: testing.correctness
48834
48848
  scope: file
48835
48849
  default_severity: blocking
48836
- issue: The changed code produces incorrect behavior.
48850
+ issue: The changed code produces wrong behavior.
48837
48851
  results: []
48838
48852
  - id: testing.application
48839
48853
  scope: review
48840
48854
  default_severity: consider
48841
48855
  issue: >-
48842
- Required behavior lacks outside-in test evidence (e2e > integration > unit), or e2e/integration tests lack human-verifiable outputs such as snapshots, test logs, or JSON outputs.
48856
+ Required behavior lacks outside-in test evidence (e2e over integration over unit), or tests lack human-verifiable outputs such as snapshots, logs, or JSON payloads.
48843
48857
  results: []
48844
48858
  - id: testing.relevance
48845
48859
  scope: applicable-file
48846
48860
  applies_when: Added or modified test files.
48847
48861
  default_severity: consider
48848
48862
  issue: >-
48849
- Verbose unit tests pad coverage without proving real contracts, or a test verifies external dependency behavior without establishing behavior of the repository's own source code.
48863
+ Verbose unit tests pad coverage without proving real contracts or exercise only external dependencies. Tests inspect static asset or template structure, test the test apparatus, or add same-changeset or alpha regression tests.
48850
48864
  results: []
48851
48865
  - id: testing.names
48852
48866
  scope: applicable-file
48853
48867
  applies_when: Added or modified test files.
48854
48868
  default_severity: consider
48855
48869
  issue: >-
48856
- A test name does not identify the function or functionality tested and its expected behavior.
48870
+ A test name omits the tested functionality or its expected outcome.
48857
48871
  results: []
48858
48872
  - id: testing.arrange-act-assert
48859
48873
  scope: applicable-file
48860
48874
  applies_when: Added or modified test files.
48861
48875
  default_severity: consider
48862
48876
  issue: >-
48863
- Test organization lacks clear BDD/Gherkin structure (given/when/then) or interleaves setup, actions, and assertions so coverage or expected results are hard to see.
48877
+ Test organization lacks clear BDD structure (given, when, then) or mixes setup, actions, and assertions.
48864
48878
  results: []
48865
48879
  - id: testing.fixtures
48866
48880
  scope: applicable-file
48867
48881
  applies_when: Added or modified tests, fixtures, test setup, or test utility files.
48868
48882
  default_severity: consider
48869
48883
  issue: >-
48870
- Repeated setup, unsuitable fixtures, or recreated shared utilities obscure tests or duplicate existing helpers.
48884
+ Repeated setup, unsuitable fixtures, or duplicated helpers obscure tests.
48871
48885
  results: []
48872
48886
  - title: Documentation
48873
48887
  criteria:
48874
48888
  - id: documentation.conciseness
48875
48889
  scope: applicable-file
48876
- applies_when: Added or modified documentation, including documentation comments.
48890
+ applies_when: Added or modified documentation and documentation comments.
48877
48891
  default_severity: consider
48878
- issue: Long, dense, or complex text makes documentation hard to understand.
48892
+ issue: Long, dense, or complex prose makes documentation hard to read.
48879
48893
  results: []
48880
48894
  - id: documentation.redundancy
48881
48895
  scope: applicable-file
48882
- applies_when: Added or modified documentation, including documentation comments.
48896
+ applies_when: Added or modified documentation and documentation comments.
48883
48897
  default_severity: consider
48884
- issue: Documentation repeats the implementation or other text without adding useful context.
48898
+ issue: Documentation repeats code or existing prose without adding context.
48885
48899
  results: []
48886
48900
  - id: documentation.visuals
48887
48901
  scope: applicable-file
48888
48902
  applies_when: Added or modified documentation that explains structures, flows, or relationships.
48889
48903
  default_severity: consider
48890
- issue: A long textual explanation obscures information that a diagram would make clearer.
48904
+ issue: Long prose hides structure or flow that a diagram or tree shows clearly.
48905
+ results: []
48906
+ - id: documentation.requirements
48907
+ scope: applicable-file
48908
+ applies_when: >-
48909
+ Added or modified plans, architecture designs, PRDs, or planning intents with Requirement or Requirements sections.
48910
+ default_severity: consider
48911
+ issue: >-
48912
+ Requirement or Requirements sections use FR or NFR prefixes or state internal implementation specifications. Requirements omit observable behavior or performance, security, cost, isolation, and reliability characteristics from a client or end-user perspective.
48891
48913
  results: []
48892
48914
  - title: Performance
48893
48915
  criteria:
48894
48916
  - id: performance.regressions
48895
48917
  scope: review
48896
48918
  default_severity: consider
48897
- issue: The change causes a material performance regression.
48919
+ issue: The change introduces a material performance regression.
48898
48920
  results: []
48899
48921
  - title: Security
48900
48922
  optional: true
@@ -48912,19 +48934,19 @@ var planning_intent_default = `# Intent: [short name]
48912
48934
 
48913
48935
  ## Objective
48914
48936
 
48915
- [What do you want to add/change?]
48937
+ [State what you want to add or change for clients, callers, or end users.]
48916
48938
 
48917
48939
  ## Requirements/Instructions
48918
48940
 
48919
- [Requirements deliverable must meet. Alternately, imperative instructions which must be followed.]
48941
+ [List observable behavioral capabilities from a client, caller, or end-user perspective, or write direct instructions to follow. Use plain statements without \`FR\` or \`NFR\` prefixes. Leave internal types, function names, configuration internals, file layouts, and code-style rules out of requirements.]
48920
48942
 
48921
48943
  ## Constraints
48922
48944
 
48923
- [Implementation requirements (particularly non-functional ones), important invariants, behavioral must-haves or limits. Optional.]
48945
+ [State observable performance, security, cost, isolation, and reliability characteristics, key invariants, or explicit boundaries. Optional.]
48924
48946
 
48925
48947
  ## Open Questions
48926
48948
 
48927
- [Decisions you want help making. Optional.]
48949
+ [List product or design decisions that need input before planning. Optional.]
48928
48950
  `;
48929
48951
  var init_planning_intent = () => {};
48930
48952
 
@@ -49247,6 +49269,46 @@ The \`base_commit\` is the full SHA of \`origin/main\` when this branch was crea
49247
49269
  `;
49248
49270
  var init_poc_readme = () => {};
49249
49271
 
49272
+ // templates/hook-definition.md
49273
+ var hook_definition_default = `# {{name}}
49274
+
49275
+ ## Trigger
49276
+
49277
+ {{trigger}}
49278
+
49279
+ ## Action
49280
+
49281
+ - Handler: \`{{handler}}\`
49282
+ - Requires: \`{{requires}}\`
49283
+ - Receives: \`{{receives}}\`
49284
+
49285
+ ## Instructions
49286
+
49287
+ {{instructions}}
49288
+ `;
49289
+ var init_hook_definition = () => {};
49290
+
49291
+ // templates/task.md
49292
+ var task_default = `# [Task title]
49293
+
49294
+ ## Objective
49295
+
49296
+ [One-line description of what needs to be done.]
49297
+
49298
+ ## Context
49299
+
49300
+ [Relevant background written using \`/difflab-writing-style\`, kept as terse as possible. Link to relevant architecture docs instead of repeating them. For a bug ticket, describe only the observable issue and impact; do not propose a solution.]
49301
+
49302
+ ## Technical Approach
49303
+
49304
+ _To be completed by the person doing the work._
49305
+
49306
+ ## References
49307
+
49308
+ - [Relevant links to wikis, architecture docs, tickets, external resources, CI logs, or incident portals.]
49309
+ `;
49310
+ var init_task = () => {};
49311
+
49250
49312
  // templates/examples/plan-feature.md
49251
49313
  var plan_feature_default = `# Invite teammates to a project
49252
49314
 
@@ -49321,18 +49383,31 @@ src/
49321
49383
 
49322
49384
  #### Testing
49323
49385
 
49386
+ \`\`\`mermaid
49387
+ flowchart TD
49388
+ Invite["Owner creates invitation"] --> Saved["State: Pending invitation saved<br/>(even if email queue fails)"]
49389
+ Saved --> Accept["Recipient submits token"]
49390
+ Accept --> Eligible{"Intended recipient,<br/>unused & unexpired?"}
49391
+ Eligible -->|"no"| Reject["Reject; membership & token unchanged"]
49392
+ Eligible -->|"yes"| Tx["Consume token + add member"]
49393
+ Tx -->|"tx fails"| Rollback["Roll back membership & token"]
49394
+ Tx -->|"tx succeeds"| Member["Return active membership"]
49395
+ \`\`\`
49396
+
49324
49397
  \`\`\`text
49325
49398
  src/
49326
49399
  \u251C\u2500\u2500 http/
49327
49400
  \u2502 \u2514\u2500\u2500 [A] invitations.spec.ts (application behavior)
49328
- \u2502 \u2514\u2500\u2500 [A] describe invitation endpoints
49329
- \u2502 \u251C\u2500\u2500 [A] given an owner invite, when recipient accepts, then membership appears
49330
- \u2502 \u2514\u2500\u2500 [A] given a wrong recipient or expired/used token, when accepted, then it rejects without changing state
49401
+ \u2502 \u2514\u2500\u2500 [A] given a pending owner invitation
49402
+ \u2502 \u251C\u2500\u2500 [A] when the intended recipient accepts, then membership appears in JSON response
49403
+ \u2502 \u2514\u2500\u2500 [A] when a wrong recipient or expired/used token is submitted, then it rejects without changing state
49331
49404
  \u2514\u2500\u2500 invitations/
49332
49405
  \u2514\u2500\u2500 [A] service.spec.ts (public module behavior)
49333
- \u2514\u2500\u2500 [A] describe invitation service
49334
- \u251C\u2500\u2500 [A] given a failed transaction, when accepting, then membership and token changes roll back
49335
- \u2514\u2500\u2500 [A] given an email failure, when creating, then the saved invitation stays pending for retry
49406
+ \u251C\u2500\u2500 [A] given an email queue failure, when creating an invitation, then the saved invitation stays pending for retry
49407
+ \u2514\u2500\u2500 [A] given a pending invitation (converged state)
49408
+ \u2514\u2500\u2500 [A] when the database transaction fails during acceptance
49409
+ \u251C\u2500\u2500 [A] then membership changes roll back
49410
+ \u2514\u2500\u2500 [A] then the invitation token remains unconsumed
49336
49411
  \`\`\`
49337
49412
 
49338
49413
  Use BDD-style nested \`given\`/\`when\`/\`then\` scenarios in \`src/http/invitations.spec.ts\` and \`src/invitations/service.spec.ts\`. Reuse fixtures with a real test store.
@@ -49444,17 +49519,26 @@ src/
49444
49519
 
49445
49520
  #### Testing
49446
49521
 
49522
+ \`\`\`mermaid
49523
+ flowchart TD
49524
+ Write["writeActivity(event)"] --> Dual["Dual write with stable ID"]
49525
+ Dual -->|"destination fails"| Retry["Retry failed store"] --> Parity["State: Both stores hold identical events"]
49526
+ Backfill["Interrupted backfill"] --> Resume["Resume batch"] --> Parity
49527
+ Parity --> Cutover["Switch read flag to new store"]
49528
+ Cutover --> ReadCutover["Page history across cutover"]
49529
+ Cutover --> Rollback["Write post-cutover events, then roll back flag"]
49530
+ \`\`\`
49531
+
49447
49532
  \`\`\`text
49448
49533
  src/
49449
49534
  \u2514\u2500\u2500 activity/
49450
49535
  \u251C\u2500\u2500 [M] history.spec.ts (application behavior)
49451
- \u2502 \u2514\u2500\u2500 [A] describe activity history cutover
49452
- \u2502 \u251C\u2500\u2500 [A] given dual writes, when paging history across cutover, then records and cursors match
49453
- \u2502 \u2514\u2500\u2500 [A] given writes after cutover, when rolling back, then no events are lost
49536
+ \u2502 \u2514\u2500\u2500 [A] given dual-written stores at parity (converged state)
49537
+ \u2502 \u251C\u2500\u2500 [A] when paging history across reader cutover, then records and cursors match
49538
+ \u2502 \u2514\u2500\u2500 [A] when rolling back the reader after new writes, then no events are lost
49454
49539
  \u2514\u2500\u2500 [A] migration.spec.ts (public module behavior)
49455
- \u2514\u2500\u2500 [A] describe activity storage migration
49456
- \u251C\u2500\u2500 [A] given a failed destination write, when retried, then one logical event exists in each store
49457
- \u2514\u2500\u2500 [A] given an interrupted backfill, when resumed, then IDs and order match without duplicates
49540
+ \u251C\u2500\u2500 [A] given a failed destination write, when retried, then one logical event exists in each store
49541
+ \u2514\u2500\u2500 [A] given an interrupted backfill batch, when resumed, then IDs and order match without duplicates
49458
49542
  \`\`\`
49459
49543
 
49460
49544
  Use BDD-style nested \`given\`/\`when\`/\`then\` scenarios in \`src/activity/history.spec.ts\` for application behavior and \`src/activity/migration.spec.ts\` for public storage APIs with real test stores.
@@ -49500,25 +49584,26 @@ Dual writes increase latency and allow partial failure. Record discrepancies and
49500
49584
  var init_plan_migration = () => {};
49501
49585
 
49502
49586
  // templates/examples/design-service.md
49503
- var design_service_default = `# Notification service \u2014 software architecture
49587
+ var design_service_default = `# Notification service: software architecture
49504
49588
 
49505
49589
  ## Overview
49506
49590
 
49507
- The service delivers email notifications for account events. It consumes messages from the application queue; it does not decide who should receive a message or block account requests on email delivery.
49591
+ The notification service sends email notifications for account events. Callers submit events without waiting for email delivery. The service does not choose notification recipients.
49508
49592
 
49509
49593
  ## Requirement
49510
49594
 
49511
49595
  ### Functional
49512
49596
 
49513
- - FR1: Consume and validate account events with an ID, type, recipient, and timestamp.
49514
- - FR2: Deduplicate deliveries, send email, and record each attempt and its outcome.
49515
- - FR3: Retry transient provider failures and report permanent rejections.
49597
+ - Callers submit account events with an event ID, event type, recipient address, and timestamp, and the service rejects malformed events.
49598
+ - Recipients receive an email for each valid account event, and callers can inspect the delivery outcome for each event.
49599
+ - The service retries temporary email failures automatically and reports permanent rejections.
49516
49600
 
49517
49601
  ### Non-Functional
49518
49602
 
49519
- - NFR1: Queue redelivery must not send the same event twice; retain a durable event ID for deduplication.
49520
- - NFR2: Provider credentials must stay outside event payloads and the account service.
49521
- - NFR3: A burst of events must not delay account requests; alert when the queue grows.
49603
+ - Submitting the same event ID more than once sends at most one email to the recipient.
49604
+ - Callers submit events without holding email provider credentials, and event payloads never expose secrets.
49605
+ - Event bursts do not add latency to caller account requests, and operators receive an alert when pending deliveries grow.
49606
+ - Duplicate and permanently rejected events do not trigger paid provider retries.
49522
49607
 
49523
49608
  ## Design
49524
49609
 
@@ -49533,32 +49618,32 @@ flowchart LR
49533
49618
  Consumer --> Store[(Attempt store)]
49534
49619
  \`\`\`
49535
49620
 
49536
- - The account service publishes events and knows only the event contract.
49537
- - The durable queue isolates delivery from account requests and retries transient failures.
49538
- - The consumer validates and deduplicates events; the sender formats and submits mail to the provider.
49539
- - The attempt store records event IDs, delivery outcomes, and retry attempts.
49621
+ - The account service publishes events and depends only on the event contract.
49622
+ - The durable queue decouples email delivery from account requests and retries temporary failures.
49623
+ - The consumer parses and deduplicates events before the sender submits mail to the provider.
49624
+ - The attempt store records event IDs, delivery outcomes, and retry counts.
49540
49625
 
49541
49626
  ### Data and Control Flow
49542
49627
 
49543
- An account event enters the queue. The consumer validates it and checks the attempt store for its ID before the sender calls the provider. The consumer records the result; a transient failure is retried, while a permanent rejection is reported. Sending synchronously would avoid the queue but could delay account requests whenever the provider is slow.
49628
+ An account event enters the queue. The consumer parses the payload and queries the attempt store for the event ID before the sender calls the provider. The consumer records each attempt. The queue retries temporary failures, and the consumer reports permanent rejections. Synchronous delivery avoids the queue, but slow provider responses then delay account requests.
49544
49629
 
49545
49630
  ### Interfaces and Contracts
49546
49631
 
49547
- \`AccountEvent\` contains \`id\`, \`type\`, \`recipient\`, and \`timestamp\`. \`handle(event)\` consumes the event, \`send(message)\` calls the provider, and \`record(attempt)\` persists its result. The event ID is the deduplication key; provider credentials never enter the payload.
49632
+ \`AccountEvent\` contains \`id\`, \`type\`, \`recipient\`, and \`timestamp\`. \`handle(event)\` processes the event, \`send(message)\` calls the provider, and \`record(attempt)\` saves the result. The event ID acts as the deduplication key. Provider credentials never enter the event payload.
49548
49633
 
49549
49634
  ## Implementation
49550
49635
 
49551
49636
  ### Consumer and storage
49552
49637
 
49553
- The notification service owns its consumer and attempt store; the account service imports only the event contract. Persist the deduplication key with the delivery outcome so queue redelivery is safe. Integration tests simulate duplicate events and provider timeouts.
49638
+ The notification service owns the consumer and attempt store. The account service imports only the event contract. Save the deduplication key with the delivery outcome so queue redelivery stays safe. Integration tests cover duplicate events and provider timeouts.
49554
49639
 
49555
49640
  ### Delivery operations
49556
49641
 
49557
- Keep provider credentials in the notification service. Alert on a growing queue and repeated provider failures; disable sending and drain pending work if credentials are compromised. Load tests cover bursts without slowing the account service.
49642
+ Keep provider credentials inside the notification service configuration. Alert operators when the queue grows or when provider calls fail repeatedly. If credentials leak, disable sending and drain pending work. Load tests cover event bursts so account request latency stays flat.
49558
49643
 
49559
49644
  ## References
49560
49645
 
49561
- - EX-34 \u2014 example notification requirement.
49646
+ - EX-34: example notification requirement.
49562
49647
  `;
49563
49648
  var init_design_service = () => {};
49564
49649
 
@@ -49747,7 +49832,6 @@ Address the two requests. No unrelated cleanup is needed.
49747
49832
  - **Checks run:** None. This is a fictional example.
49748
49833
  - **Not verified:** Execution and real repository guidance.
49749
49834
  - **Rubric:** A real review links its filled rubric here.
49750
- - **Council:** Not selected.
49751
49835
  `;
49752
49836
  var init_review_change = () => {};
49753
49837
 
@@ -49919,6 +50003,8 @@ var init_source = __esm(() => {
49919
50003
  init_exploration_research();
49920
50004
  init_exploration_proposal();
49921
50005
  init_poc_readme();
50006
+ init_hook_definition();
50007
+ init_task();
49922
50008
  init_plan_feature();
49923
50009
  init_plan_migration();
49924
50010
  init_design_service();
@@ -49946,6 +50032,8 @@ var init_source = __esm(() => {
49946
50032
  "exploration-research.md": exploration_research_default,
49947
50033
  "exploration-proposal.md": exploration_proposal_default,
49948
50034
  "poc-readme.md": poc_readme_default,
50035
+ "hook-definition.md": hook_definition_default,
50036
+ "task.md": task_default,
49949
50037
  "examples/plan-feature.md": plan_feature_default,
49950
50038
  "examples/plan-migration.md": plan_migration_default,
49951
50039
  "examples/design-service.md": design_service_default,
@@ -49977,7 +50065,9 @@ var init_source = __esm(() => {
49977
50065
  { name: "exploration-summary", description: "Source-grounded technical exploration summary" },
49978
50066
  { name: "exploration-research", description: "Technical exploration research notes" },
49979
50067
  { name: "exploration-proposal", description: "Optional technical exploration approach" },
49980
- { name: "poc-readme", description: "Disposable proof-of-concept branch README" }
50068
+ { name: "poc-readme", description: "Disposable proof-of-concept branch README" },
50069
+ { name: "hook-definition", description: "Reusable global Agent Skill hook definition" },
50070
+ { name: "task", description: "Terse task or bug ticket with objective, context, and references" }
49981
50071
  ];
49982
50072
  embeddedSource = {
49983
50073
  catalog,
@@ -52536,7 +52626,7 @@ function createProgram(write = console.log, version = "0.1.0", options = {}) {
52536
52626
 
52537
52627
  // src/index.ts
52538
52628
  init_errors3();
52539
- var version2 = "0.12.0";
52629
+ var version2 = "0.13.1";
52540
52630
  try {
52541
52631
  await createProgram(console.log, version2).parseAsync(process.argv);
52542
52632
  } catch (error) {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@difflab/difflab-cli",
3
- "version": "0.12.0",
3
+ "version": "0.13.1",
4
4
  "private": false,
5
5
  "description": "A minimal Bun CLI starter built with Commander",
6
6
  "license": "Apache-2.0",
@@ -47,7 +47,7 @@
47
47
  },
48
48
  "devDependencies": {
49
49
  "@types/bun": "1.4.2",
50
- "difflab-db": "workspace:*",
50
+ "difflab-db-legacy": "workspace:*",
51
51
  "prettier": "3.9.8",
52
52
  "typescript": "7.0.2",
53
53
  "utils": "workspace:*"