@stonepandastudio/cairn 0.4.1 → 0.5.0

package/presets/angular/code-guidelines.md

@@ -0,0 +1,197 @@
+# Code Guidelines
+
+<!-- cairn preset: angular -->
+
+* In angular templates use new template syntax instead of old `*ng` syntax.
+* Unsubscribe from observables in `ngOnDestroy`
+* Use standalone Angular components by default, refactor component to standalone if it's not standalone component
+* Every utility function, model, constant or mapping function should stay in separated file.
+* For file names use dash-case (Example: `my-long-module.module.ts`)
+* Use Reactive Forms for any new forms.
+* All data access is handled through dedicated services.
+* Complex data manipulation is placed in utils files
+
+## Theming and Colors
+
+The application uses a CSS variables-based theming system with the following architecture:
+
+**Chain**: Global CSS Variables → SCSS Palette Variables → Abstract SCSS Variables → Component `.scss` files
+
+### Architecture Layers
+
+1. **Global CSS Variables** (`src/scss/themes/default/colors.scss`)
+   - Defines actual color values as CSS custom properties
+   - Example: `--fotofixer-color-primary: #00aabc;`
+   - Changing these allows dynamic theme switching without page refresh
+
+2. **SCSS Palette Variables** (`src/scss/themes/colors.scss`)
+   - Maps CSS variables to SCSS variables using `var()` function
+   - Example: `$fotofixer-color-primary: var(--fotofixer-color-primary);`
+   - **DO NOT import this file directly in component SCSS**
+
+3. **Abstract SCSS Variables** (`src/scss/themes/theme.scss`)
+   - Provides semantic/abstract names for colors
+   - Example: `$font-color-secondary: colors.$main-color-main-10;`
+   - **This is the only file you should import in component SCSS files**
+
+### Rules for Using Colors in SCSS Files
+
+* **DO NOT** use hardcoded colors (e.g., `#ffffff`, `white`, `rgb(...)`)
+* **DO NOT** use CSS variables directly (e.g., `var(--main-color-main-11)`)
+* **DO NOT** import `colors.scss` directly
+* **DO** import `theme.scss` using `@use` directive
+* **DO** use abstract SCSS variables from `theme.scss`
+* **DO** add new abstract variables to `theme.scss` if needed
+
+### Example Usage
+
+```scss
+@use "themes/theme" as theme;
+
+.my-component {
+  background-color: theme.$background-color-white;
+  border: 1px solid theme.$border-color-secondary;
+  color: theme.$font-color;
+
+  .secondary-text {
+    color: theme.$font-color-secondary;
+  }
+
+  .muted-text {
+    color: theme.$font-color-muted;
+  }
+
+  .primary-action {
+    background-color: theme.$fotofixer-color-primary;
+
+    &:hover {
+      background-color: theme.$fotofixer-color-hover;
+    }
+  }
+}
+```
+
+### Available Abstract Variables (from `theme.scss`)
+
+**Primary Colors:**
+- `$fotofixer-color-primary` - Main brand color (cyan)
+- `$fotofixer-color-secondary` - Light brand color
+- `$fotofixer-color-tetriary` - Very light brand color
+- `$fotofixer-color-hover` - Brand hover state
+
+**Background Colors:**
+- `$background-color-main` - Main background (light gray)
+- `$background-color-secondary` - Secondary background
+- `$background-color-secondary-hover` - Secondary hover state
+- `$background-color-white` - White background
+
+**Font Colors:**
+- `$font-color` - Main text color (black)
+- `$font-color-navbar` - Navbar text
+- `$font-color-secondary` - Secondary text (dark gray)
+- `$font-color-muted` - Muted/disabled text (medium gray)
+- `$invert-font-color` - Inverted text (white)
+
+**Border Colors:**
+- `$border-color` - Main border color
+- `$border-color-secondary` - Secondary border (light gray)
+- `$divider-color` - Divider lines (very light gray)
+
+**Message Colors:**
+- `$error-message-color` - Error text
+- `$error-message-background-color` - Error background
+- `$success-message-color` - Success text
+
+**Other:**
+- `$disabled-color` - Disabled state
+- `$link-hover-color` - Link hover state
+
+## Component Selectors
+
+* Do NOT use `app-` prefix for component selectors in new components
+* Use descriptive, kebab-case selector names (Example: `popover`, `project-status-icon`, `connected-projects-popover`)
+* Selector should match the component's purpose without generic prefixes
+
+## Translations and Internationalization
+
+### General Rules
+
+* Always use translation keys for static text in templates.
+* For dynamic text in templates use translation keys when possible. If not possible, add a comment explaining why.
+* **Locale files are generated artifacts.** Never hand-edit them and never add a key to one to make a feature render — any manual change is destroyed by the next sync.
+
+Where translations come from, and how new keys are submitted, is project-specific:
+
+{{> slot: translation-source }}
+
+### Translation Key Naming Conventions
+
+* Use PascalCase for naming translation keys.
+* Key structure depends on context:
+  * **Common text (no specific context)**: Use 2 parts - `"Common.SaveButton"`, `"Common.CancelButton"`
+  * **Context-specific text**: Use nested structure - `"[PageName].[Subcontext].[TextDescription]"`
+
+### Examples
+
+**Common keys:**
+```json
+"Common": {
+  "SaveButton": "Save",
+  "CancelButton": "Cancel",
+  "Loading": "Loading..."
+}
+```
+
+**Page-specific keys:**
+```json
+"DevicesTable": {
+  "Title": "Devices Table",
+  "Header": {
+    "CityColumn": "City",
+    "DeviceColumn": "Device"
+  },
+  "Button": {
+    "DownloadReport": "Download Report"
+  }
+}
+```
+
+**Message keys:**
+```json
+"Messages": {
+  "Devices": {
+    "FailedLoadDevices": "Failed to load devices",
+    "FailedDownloadReport": "Failed to download report"
+  }
+}
+```
+
+### Checking Existing Keys
+
+Before creating new translation keys, check the existing English locale file for examples and to avoid duplication. Read it only — see the generated-artifact rule above.
+
+## Change detection
+
+* **Match the strategy used by nearby/similar components.** The codebase mixes `Default` and `OnPush`; don't default to `OnPush` unless the surrounding components use it. Most page-level components currently use `ChangeDetectionStrategy.Default`.
+* If you're adding a component to an area where everything is `Default`, use `Default`. If you're adding one next to `OnPush` components, use `OnPush`.
+* Don't "upgrade" an existing component from `Default` to `OnPush` as a drive-by change — that's a focused refactor, not part of a feature plan.
+
+## Comments
+
+* **Default to no comments.** Good names carry meaning; small functions are self-documenting.
+* Only write a comment when the *why* is non-obvious: a hidden constraint, a subtle invariant, a workaround for a specific bug, behavior that would surprise a reader.
+* Don't explain *what* the code does — identifiers and structure already do that.
+* Don't reference task IDs, PR flows, or "added for feature X" in code comments — that context belongs in commit messages and PR descriptions, and rots as the codebase evolves.
+* No multi-paragraph docstrings or multi-line comment blocks — one short line is the ceiling.
+
+## Constants
+
+File name template: `xx-yy.constant.ts` for `XxYy` constant
+
+Files with constants should be placed in the `constants/` folder within the corresponding module (see `ai/infrastructure/project-structure.md` for module details)
+
+## Enums
+
+File name template: `xx-yy.enum.ts` for `XxYy` enum
+
+Files with enums should be placed in the `enums/` folder within the corresponding module (see `ai/infrastructure/project-structure.md` for module details)

package/presets/angular/slots/architect-discussion-topics.md

@@ -0,0 +1,10 @@
+<!-- cairn preset: angular — fills {{> stack/architect-discussion-topics }} (A.3). -->
+- **Ambiguities** — anything in the description that admits multiple reasonable interpretations
+- **UX / design tradeoffs** — popup vs. page, tabs vs. stacked sections, inline vs. separate component
+- **Integration tensions** — e.g. global company state vs. route-scoped company id
+
+**Optional aid — `frontend-design` skill.** When the discussion hinges on a
+visual/UX tradeoff, `frontend-design` can explore mockups. **Treat its output as
+inspiration only** — it does not know this project's conventions (Material UI,
+`theme.scss` variables, base classes, new template syntax, no `app-` prefix,
+translation keys). Never feed its generated code into the plan.

package/presets/angular/slots/architect-mandatory-docs.md

@@ -0,0 +1,5 @@
+<!-- cairn preset: angular — fills {{> stack/architect-mandatory-docs }} (A.2). -->
+- `ai/infrastructure/code-guidelines.md`
+- `ai/infrastructure/project-structure.md`
+- `ai/infrastructure/patterns.md`
+- `ai/infrastructure/mappers.md`

package/presets/angular/slots/architect-references.md

@@ -0,0 +1,4 @@
+<!-- cairn preset: angular — fills {{> stack/architect-references }} (A.1). -->
+- Frontend source files (components, services, base classes)
+- The backend repo's context docs — entity definitions, business logic, controllers
+- Backend source files, for API-shape confirmation

package/presets/angular/slots/implementation-reference.md

@@ -0,0 +1,34 @@
+<!-- cairn preset: angular — fills {{> stack/implementation-reference }} in the core
+     developer. snap-proof/frontend/ai/agents/angular-developer.md has no block like
+     the nestjs one — it points at patterns.md + code-guidelines.md and stops.
+     This is a minimal synthesis from angular-developer + angular-reviewer; extend
+     it when a second Angular repo shows what is actually shared. -->
+
+The authoritative source is `ai/infrastructure/code-guidelines.md`; the base-class
+and header-flow catalogue is `ai/infrastructure/patterns.md`. Reminders:
+
+### Components
+- Standalone components — no `NgModule` declarations block
+- No `app-` prefix in the selector
+- Match the change-detection strategy of nearby components
+- Subscriptions collected in a `Subscription`, unsubscribed in `ngOnDestroy`
+- Complex data manipulation goes in a `utils/` file, not inlined
+
+### Templates
+- Control flow: `@if` / `@for` / `@switch` — never `*ngIf` / `*ngFor`
+- Every `@for` carries a `track` expression
+- Every static string is a translation key — no bare literals
+
+### Styles
+- Only `theme.$variable` from `@use "themes/theme" as theme` — no `#hex`, `rgb()`, or CSS custom properties
+
+### Forms
+- Reactive forms only — no `ngModel`
+
+### Files
+- Models, enums, constants, and mapper functions each in their own kebab-case file
+- `enums/`, `constants/`, `mappers/` folders per module
+- Mapper shapes: `EntityResponse → Entity`, `Entity ↔ EntityForm`, `Entity → EntityPayload`
+
+### Build
+- Run the project's production build before reporting completion; a failing build blocks the report

package/presets/angular/slots/key-patterns.md

@@ -0,0 +1,11 @@
+<!-- cairn preset: angular — fills {{> stack/key-patterns }} in the core architect
+     and developer. From architect-lead.md / angular-developer.md. -->
+
+Canonical catalogue: **`ai/infrastructure/patterns.md`** — base classes, the
+`x-admin-profile` header flow, routing. Plans should lean on these instead of
+reinventing them.
+
+Micro-level conventions (theming, translations, template syntax, change detection,
+file naming): **`ai/infrastructure/code-guidelines.md`**.
+
+Mapper conventions: **`ai/infrastructure/mappers.md`**.

package/presets/angular/slots/plan-step-ordering.md

@@ -0,0 +1,11 @@
+<!-- cairn preset: angular — fills {{> stack/plan-step-ordering }} in the core
+     architect's Plan format. architect-lead.md gives no explicit ordering beyond
+     "each step leaves the app working"; this is a synthesis, refine against a
+     second Angular repo. -->
+1. Models, enums, constants, mapper functions
+2. Service methods (API calls, state)
+3. Component logic (`.ts`)
+4. Template (`.html`) and styles (`.scss`)
+5. Routing and module wiring
+6. Translation keys
+7. Context doc updates

package/presets/angular/slots/review-checklist.md

@@ -0,0 +1,16 @@
+<!-- cairn preset: angular — fills {{> stack/review-checklist }} in the core reviewer.
+     Verbatim from snap-proof/frontend/ai/agents/angular-reviewer.md § Dimension 2. -->
+
+| New template syntax (`@if`, `@for`, `@switch`) — no `*ngIf`/`*ngFor` | `.html` files |
+| `@for` always includes a `track` expression — missing `track` is a compile error in Angular 17+ | `.html` files |
+| Standalone components — no `NgModule` declarations block | Component `.ts` files |
+| Observables subscribed inside components are collected in a `Subscription` and unsubscribed in `ngOnDestroy` | Component `.ts` files |
+| No hardcoded colors (`#hex`, `rgb()`, CSS custom properties) — only `theme.$variable` from `@use "themes/theme" as theme` | `.scss` files |
+| No `app-` prefix in component selectors | Component `.ts` files |
+| All static text in templates uses translation keys — no bare string literals | `.html` files |
+| `src/assets/i18n/*.json` never hand-edited — autogenerated, replaced during localization — **blocking** if the diff touches these files directly | `src/assets/i18n/*.json` |
+| Reactive forms only — no template-driven forms (`ngModel`) | Component `.ts` files |
+| Complex data manipulation goes in `utils/` files, not inlined in components | Component `.ts` files |
+| Mapper pattern respected: `EntityResponse → Entity`, `Entity ↔ EntityForm`, `Entity → EntityPayload` | `mappers/` files |
+| Models, enums, constants, and mapper functions each in their own kebab-case file | Module folder structure |
+| Enums in `enums/` folder, constants in `constants/` folder, mappers in `mappers/` folder | Module structure |

package/presets/angular/variants/i18n-external-service.md

@@ -0,0 +1,11 @@
+<!-- cairn variant: translation-source = external-service. Fills the
+     translation-source slot in presets/angular/code-guidelines.md.
+     In use by: snap-frontend. A third-party localization vendor owns the values. -->
+
+## slot: translation-source
+
+Never add or update translation values for translation keys in `src/assets/i18n/*.json` files directly. These are autogenerated files that will be replaced by a third-party service during the localization process.
+
+### Checking Existing Keys
+
+Before creating new translation keys, check existing keys in `src/assets/i18n/en-us.json` for examples and to avoid duplication.

package/presets/angular/variants/i18n-glossr.md

@@ -0,0 +1,63 @@
+<!-- cairn variant: translation-source = glossr. Fills the translation-source slot
+     in presets/angular/code-guidelines.md.
+     In use by: glossr-frontend. This project dogfoods the product. -->
+
+## slot: translation-source
+
+**Glossr itself is the source of truth for all translations.** This project dogfoods the product: keys and values live in the Glossr instance at `glossr.stonepandastudio.com`, not in any file in this repo. There is no `en.json` — do not create one.
+
+### Where Translations Come From
+
+Each app consumes Glossr differently:
+
+| App | Mechanism | Files |
+|---|---|---|
+| `glossr-frontend` | **Pipeline pull.** `npm run glossr:pull` fetches the CDN and overwrites the locale files, one per target in `glossr.config.json`. | everything under `apps/glossr-frontend/src/assets/i18n/` |
+| `glossr-admin` | **Runtime fetch.** `GlossrCdnTranslateLoader` requests `${translationUrl}/${lang}` on load. | none — no locale files on disk |
+
+### Translation Assets Are Generated — Never Touch Them
+
+**Every file under `apps/glossr-frontend/src/assets/i18n/` is a build artifact.** The set is whatever `glossr.config.json` lists as targets (`en-us.json`, `ru-ru.json`, `pl-pl.json`, …) — treat the folder as generated, not the individual filenames, so adding a locale needs no change here.
+
+The pipeline runs `npm run glossr:pull` and **replaces these files wholesale**. Consequences:
+
+* **Never hand-edit them.** Any manual change is silently destroyed by the next pull — including "just adding the one key I need to see the UI render".
+* **Never add a key to them** to make a new feature display real text. New keys go to `ai/tasks/GLO-[task]/keys.json` (see below) and reach the app only after a human imports the story and pulls.
+* **Read-only reference is fine** — consult `en-us.json` to check whether a key already exists or to copy a naming pattern.
+* **Ignore them when reviewing a diff.** A changed locale file is pull output, not authored work; it is neither a finding nor scope creep. The only locale-file change worth flagging is one made *by hand* in place of a `keys.json` entry.
+* Adding a locale is a `glossr.config.json` change plus the app's language registration — the resulting `.json` is generated, so do not write it by hand.
+
+### Adding New Keys
+
+The Glossr CLI is **pull-only** (`glossr --help` → `pull` is the only command), so new keys reach Glossr by manual import. A `push` command is planned; until it exists, keys accumulate in a per-story file and are uploaded once.
+
+**One `keys.json` per story — not per step.**
+
+```
+ai/tasks/GLO-[task]/keys.json
+```
+
+Every step of a story writes into that same file:
+
+* **File does not exist** (usually step 1) → create it, containing only that step's keys.
+* **File already exists** (step 2+) → **merge** the new keys into it. Deep-merge the nested structure; keep every key earlier steps added. Never overwrite the file wholesale, and never create `keys-step-2.json` or similar.
+* A step that introduces **no** new keys leaves the file untouched.
+
+Shape: nested JSON matching the CDN payload, English values, PascalCase keys per the naming conventions below.
+
+**Lifecycle:**
+
+| When | What | Who |
+|---|---|---|
+| During each step | Create or merge into `keys.json` | developer agent |
+| Story complete | Import `keys.json` into Glossr — **once, for the whole story** | human |
+| After import | `npm run glossr:pull` | human |
+| After pull | Commit the regenerated files in `assets/i18n/` | human |
+
+The upload is deliberately deferred to story completion: a story's keys tend to churn across steps, and importing per-step would push keys into Glossr that a later step renames or drops.
+
+**Consequence:** for the whole life of the story, the app renders raw key strings for its new keys. That is expected, not a bug — do not "fix" it by editing a locale file. `keys.json` is the durable, git-tracked record of what the story introduced, and it survives the pull that overwrites the locale files.
+
+### Checking Existing Keys
+
+Check `apps/glossr-frontend/src/assets/i18n/en-us.json`. Do not use the root-level `all-keys-en.json` / `all-keys-en-admin.json` dumps as a reference — they are untracked one-off exports and already stale (`all-keys-en.json` is 27 keys behind `en-us.json`).

package/presets/core/AGENTS.md

@@ -0,0 +1,49 @@
+# `AGENTS.md`
+
+<!-- cairn preset: core. Rendered from workflow.steps[] + the repo's tracker config.
+     The Workflow Example numbering, the Agent Profiles, and the tracker section
+     all come from config — which is what stops one repo's AGENTS.md drifting from
+     its own commands. -->
+
+The agents in the **{{ project.assistantName }}** — a small multi-agent system that
+runs {{ stack.0 }} feature work from brief to review.
+
+## High-Level Architecture
+
+`{{ architectAgent }}` interprets the request, discusses it, and produces the plan.
+`{{ developerAgent }}` implements the plan. `{{ reviewerAgent }}` checks the result
+against the plan and the guidelines. Each runs in its own session.
+
+**Workflow Example.** A task moves through these named invocations; you own the
+transitions. Dispatch table: `ai/INITIAL_PROMPT.md`.
+
+{{#each workflow.steps}}
+{{ @index_1 }}. **`/{{ this.command }} {{ tracker.exampleKey }}-NNN 1`** — `{{ this.agentName }}`{{#if this.model}} ({{ this.model }}){{/if}} — {{ this.oneLine }}
+{{/each}}
+
+Informal engagement on a task defaults to the first step.
+
+---
+
+## Agent Profiles
+
+{{#each agents}}
+### `{{ this.name }}`
+
+Read `{{ this.doc }}` for the full role, workflow, tools, and instructions.{{#if this.note}} {{ this.note }}{{/if}}
+
+{{/each}}
+
+---
+
+## Tracker
+
+{{#if tracker.remote}}
+`create_brief`, `enrich_description` and `plan_task` sync task state to the
+`{{ tracker.exampleKey }}` project on {{ tracker.providerLabel }} as a side effect.
+Mapping, sync points, stage names, and the `LOCAL-*` rule: `ai/WORKFLOW.md`. Manual:
+`/{{ tracker.slug }}-status`, `/{{ tracker.slug }}-assign`.
+{{else}}
+No remote tracker (`tracker.provider` is `none`). A task is its `ai/tasks/[KEY]/`
+folder; the sync steps are no-ops. See `ai/WORKFLOW.md`.
+{{/if}}

package/presets/core/README.md

@@ -0,0 +1,35 @@
+# `presets/core`
+
+Stack-agnostic content shared by every repo, whatever the framework: the agent
+**role contracts**, the command-stub template, and the `WORKFLOW.md` / `AGENTS.md`
+skeletons.
+
+Extracted 2026-09-09 from `snap-proof/{backend,frontend}` (see `../EXTRACTION.md`).
+These are **seeds** — no renderer consumes them yet. They are the canonical version
+of scaffolding that currently exists as two hand-synced copies, already useful as a
+reference to pull the copies back together by hand.
+
+## What lives here vs. in a stack preset
+
+`core` holds the parts the backend and frontend agent docs share **verbatim modulo
+two variables** — the workflow scaffold (`R.1`–`R.4`, `E.1`–`E.5`, Mode A / Mode B),
+the report and plan-format templates, the "when to stop" lists. Measured 85–92%
+identical across the two repos.
+
+A stack preset (`../nestjs`, `../angular`) fills the slots these contracts declare:
+
+| slot in a core agent | nestjs | angular |
+|---|---|---|
+| `{{> stack/review-checklist }}` | TypeORM / class-validator / `@ResponseMapper` rules | `@if`/`@for` / standalone / theme vars / i18n rules |
+| `{{> stack/implementation-reference }}` | module / controller / service / entity / DTO / migration | component / template / SCSS / reactive-form |
+| `{{> stack/key-patterns }}` | `project-structure.md` + `DATABASE_SCHEMA.md` pointers | `patterns.md` (base classes, `x-admin-profile`) pointers |
+
+## Variables
+
+Placeholders the renderer substitutes per repo, from `workspace.json` + the repo's
+`cairn.config.json`:
+
+- `{{ architectAgent }}` / `{{ developerAgent }}` / `{{ reviewerAgent }}` — the persona names
+- `{{ model }}` — the model the reviewer/QA agents require (`claude-sonnet-5`)
+- `{{ step.fn }}` / `{{ step.command }}` — the workflow verb for a step (`code_review` vs `review_plan` is drift to be removed, not a variant)
+- `{{ tracker.* }}` — provider, stage names, example issue key — for the sync sub-steps and `WORKFLOW.md`

package/presets/core/WORKFLOW.md

@@ -0,0 +1,56 @@
+# Task Workflow
+
+<!-- cairn preset: core. Rendered from workflow.steps[] + the repo's tracker config.
+     With a remote tracker (jira-server / youtrack) the sync half renders; with
+     `tracker: none` only the local half does. Project-specific bits (a retrofit
+     procedure for pre-sync tasks, say) stay in the repo, outside this file. -->
+
+A task lives in `ai/tasks/[KEY]/` as a set of step files:
+
+| File | Written by |
+|---|---|
+| `brief-step-[N].md` | you — the raw ask, never modified after creation |
+| `description-step-[N].md` | {{ architectAgent }} (Mode A) — the enriched brief |
+| `plan-step-[N].md` | {{ architectAgent }} (Mode B) — the implementation plan |
+
+`[KEY]` is the task folder name. Speculative or un-tracked work uses a `LOCAL-`
+prefix so a folder name can never collide with a real issue key.
+
+{{#if tracker.remote}}
+## Sync to {{ tracker.providerLabel }}
+
+`ai/tasks/[KEY]/` mirrors to the `{{ tracker.exampleKey }}` project. The folder name
+is the parent issue key; each step's child-issue key is stamped into the first line
+of its `brief-step-[N].md`:
+
+```
+<!-- {{ tracker.subtaskMarker }}: {{ tracker.exampleKey }}-4 -->
+```
+
+Issue keys are project-sequential, not per-parent — a parent and child with
+unrelated numbers is normal. The parent link is the tracker's own link, not the key.
+
+**In scope:** a folder starting `{{ tracker.exampleKey }}-` whose step file carries
+`{{ tracker.subtaskMarker }}` frontmatter. **Not in scope:** a `LOCAL-` folder — work
+it locally, mention that once, never sync it.
+
+### Sync points (one-way: local → tracker)
+
+| Command | Tracker actions |
+|---|---|
+{{#each workflow.steps}}
+| `{{ this.fn }}(task, step)` | {{ this.trackerAction }} |
+{{/each}}
+
+Later stage moves (`{{ tracker.reviewStage }}` onward) are manual — the tracker UI,
+`/{{ tracker.slug }}-status`, or `cairn tracker close-task`.
+
+Everything goes through `cairn tracker <command> …` (or the vendored
+`ai/scripts/*.js` shim). Credentials live in `.env` (gitignored).
+{{else}}
+## No remote tracker
+
+`tracker.provider` is `none` — the workflow steps that would sync are no-ops. A task
+is exactly its `ai/tasks/[KEY]/` folder; there is nothing else to update. Pick any
+stable `[KEY]` scheme (a sequential id, a sprint slug) and keep it consistent.
+{{/if}}