archik 0.8.0 → 0.9.1

package/.claude/commands/archik/evolve.md

@@ -102,8 +102,16 @@ any file under `.archik/`.
    - Preserve every existing node id you keep — only add or remove
      ids, never rename. Renames break diff and require the user to
      manually re-link references in code.
-   - Don't drop `description`, `responsibilities`, or `notes`
-     fields the user authored. Carry them over verbatim.
+   - Don't drop `description`, `responsibilities`, `notes`, or
+     `sourcePath` fields the user authored. Carry them over verbatim.
+   - Every new code-bearing node (`service`, `function`, `worker`,
+     `module`, `page`, `component`, `store`, `hook`) needs a
+     `sourcePath:` that exists on disk — the validator rejects
+     fabricated paths. If the refactor proposes a not-yet-built
+     module (e.g. extracting a `payments` context that doesn't have
+     a directory yet), describe it in prose for the user to
+     consider, then either skip that node or move the work to a
+     `*.archik.discussion.yaml` file via `--main`.
    - Every change should be motivated by step 3, not by aesthetics.
 
    If `suggest set` reports validation errors, re-run with the

package/.claude/commands/archik/spawn.md

@@ -89,7 +89,28 @@ archik suggest set` stages it.
    When unsure, pick the closest fit and add a `notes:` entry
    explaining the inference rather than picking `custom`.
 
-6. **Nest by structure**, mirroring the directories.
+6. **Attach `sourcePath` to every code-bearing node.** This is
+   non-negotiable in a normal/suggested file — the validator rejects
+   any `service`, `function`, `worker`, `module`, `page`, `component`,
+   `store`, or `hook` without a `sourcePath` that points at an
+   existing file or directory. The whole point of `spawn` is "mirror
+   the source tree", so the path you used to discover the node is
+   exactly what goes into `sourcePath:`. Verify each path with `ls`
+   before authoring; do not paste a path you haven't seen on disk.
+
+   ```yaml
+   - id: orders-api
+     kind: service
+     name: Orders API
+     stack: Fastify
+     sourcePath: services/orders/api   # must exist on disk
+   ```
+
+   For non-code-bearing kinds (`external`, `database`, `queue`,
+   `cloud`, etc.) `sourcePath` is optional — they typically map to
+   third-party systems or infra rather than checked-in files.
+
+7. **Nest by structure**, mirroring the directories.
    - Top-level grouping dir (e.g. `services/`) → a `module` container.
    - Each child dir → a node with `parentId` pointing at the container.
    - If a node has substantial internal structure (e.g.
@@ -98,7 +119,7 @@ archik suggest set` stages it.
      sub-file. Don't nest beyond two levels in the main file —
      drill-down is what `archikFile` is for.
 
-7. **Wire the edges.** Be conservative — only add an edge when you
+8. **Wire the edges.** Be conservative — only add an edge when you
    have actual evidence:
    - Cross-package imports → `depends_on` or a more specific
      relationship (`uses`, `invokes`).
@@ -112,7 +133,7 @@ archik suggest set` stages it.
    When in doubt, leave the edge out. The user will add it via
    `/archik:suggest` later.
 
-8. **Stage the draft.** Pipe the YAML straight into `npx archik
+9. **Stage the draft.** Pipe the YAML straight into `npx archik
    suggest set -` via a heredoc — no temp files, no `/tmp/` paths.
    Sub-files come first because the main draft references them via
    `archikFile`, and `suggest set` validates that those targets
@@ -172,7 +193,7 @@ archik suggest set` stages it.
    c. If `suggest set` reports validation errors, re-run with the
       corrected YAML. Never edit the sidecar by hand.
 
-9. **Tell the user how to review and what's next.** Surface the
+10. **Tell the user how to review and what's next.** Surface the
    canvas URL plus the natural follow-up:
    - "📝 Initial diagram staged from source tree — open the
      canvas at <URL> and use Review to see the proposed nodes."

package/.claude/commands/archik/suggest.md

@@ -58,7 +58,16 @@ the contract with the user.
    `npx archik suggest set -` via a heredoc — no temp file, no
    `/tmp/` paths. The CLI validates the schema, checks cross-file
    references, stamps `metadata.suggestion`, and atomically writes
-   `.archik/main.archik.suggested.yaml`:
+   `.archik/main.archik.suggested.yaml`.
+
+   **Every new code-bearing node** (`service`, `function`, `worker`,
+   `module`, `page`, `component`, `store`, `hook`) must declare a
+   `sourcePath:` that you have verified exists on disk. The
+   validator rejects fabricated paths. If the source doesn't exist
+   yet (you're proposing a not-yet-built component), suggest the
+   user run with `--main .archik/<name>.archik.discussion.yaml`
+   instead — discussion files relax the sourcePath rule for
+   greenfield drafts.
 
    ```bash
    npx archik suggest set --note "$ARGUMENTS" - <<'YAML'

package/.claude/skills/archik/SKILL.md

@@ -27,6 +27,42 @@ You MUST NOT use `Read`, `Write`, or `Edit` against any file under `.archik/`, a
 
 If `npx archik` is unreachable (offline, sandboxed, missing), STOP and tell the user. Do NOT fall back to reading or editing YAML by hand.
 
+## File modes — pick the right one before authoring
+
+Archik files have **three modes**, selected by filename suffix. Validation strictness differs per mode — picking the wrong one will either reject your draft or pollute the canonical architecture with greenfield speculation.
+
+| Suffix                             | Mode         | When to use                                                                                          | sourcePath rule                                                                 |
+| ---------------------------------- | ------------ | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
+| `*.archik.yaml`                    | **normal**   | The canonical architecture of code that exists.                                                      | Required for code-bearing kinds; **must exist on disk** (validated).            |
+| `*.archik.suggested.yaml`          | **suggested**| A pending change to a normal file. Owned by `suggest set`. Becomes normal on `suggest accept`.       | Same rules as normal — it'll become normal when accepted.                       |
+| `*.archik.discussion.yaml`         | **discussion**| Greenfield / exploratory drafts: a brand-new project, an "what if we built X?" sketch, an option.   | `sourcePath` is **optional**, and may point at paths that don't exist yet.      |
+
+**Code-bearing kinds** (those that must declare `sourcePath` in normal/suggested files): `service`, `function`, `worker`, `module`, `page`, `component`, `store`, `hook`. Other kinds (`external`, `cloud`, `prompt`, `llm`, `route`, `interface`, `adapter`, `port`, `database`, `cache`, `queue`, `topic`, `stream`, `gateway`, `cdn`, `agent`, `frontend`, `vectordb`, `storage`, `auth`, `observability`, `tool`, `custom`) are exempt.
+
+**Picking the mode:**
+- Are you describing real code that exists in this repo? → **normal** (or **suggested** if proposing a change).
+- Are you sketching a not-yet-built system, or proposing an architecture for a new project? → **discussion**. Don't pollute the main file with speculation.
+- Are you adding a `sourcePath` for a node whose code is going to be created soon? → **discussion**, then move to **normal** once the code exists.
+
+If `suggest set` rejects your draft with a `sourcePath` error, the right answer is usually one of: (a) fix the path to point at real code, (b) move the work into `*.archik.discussion.yaml`, (c) use a non-code-bearing kind (e.g., `external` for a third-party service), or (d) mark the node `status: proposed` if it's a planned-but-not-built component (see "Lifecycle status" below).
+
+## Lifecycle status — `proposed`, `active`, `deprecated`
+
+Nodes carry an optional `status` field. Use it to keep the canonical diagram honest about what's built vs. what's planned vs. what's going away — without dropping nodes from the file or shoving them into a discussion sketch.
+
+| status                    | When                                                                                          | sourcePath rule                                            | Visual                                |
+| ------------------------- | --------------------------------------------------------------------------------------------- | ---------------------------------------------------------- | ------------------------------------- |
+| absent / `active`         | Built and live (default).                                                                     | Required for code-bearing kinds, must exist on disk.       | Standard solid stroke.                |
+| `proposed`                | Planned for the next iteration — node belongs in the canonical map but the code isn't there yet. | Optional. If you supply one, it must still exist on disk. | Dashed stroke + reduced opacity.      |
+| `deprecated`              | Being phased out; reads/writes shouldn't depend on it going forward.                          | Optional. Same on-disk rule as `proposed` if you set one.  | Dashed stroke + amber + strikethrough name. |
+
+**`proposed` vs. a discussion file.** They're complementary, not interchangeable:
+
+- A `*.archik.discussion.yaml` file is for **whole hypothetical architectures** — a sketch the team is exploring, a diagram for a not-yet-started project, a "what if we built X?" option. The whole file is a draft.
+- `status: proposed` on a node lives inside the **canonical normal file**. The architecture as a whole is real; this one node is the next thing to build. `archik drift` skips proposed nodes so they don't trigger orphan warnings before their code lands.
+
+When in doubt: if the user is adding a single planned component to a real project, use `status: proposed` in the normal file. If they're sketching something with no anchor in the existing codebase, use a discussion file.
+
 ## Slash commands (user-facing entry points)
 
 | Command                     | Purpose                                       |
@@ -68,6 +104,8 @@ Then `ls -F . src/ services/ packages/ apps/ 2>/dev/null` for the source tree. B
 
 When the user asks "where would I add X?", you should already have the answer because you ran the queries above.
 
+**Every code-bearing node you propose for a normal/suggested file must declare a `sourcePath` that you have verified exists on disk** (e.g. `ls src/payments/worker.ts` before authoring `sourcePath: src/payments/worker.ts`). The validator rejects fabricated paths — and the rejection is non-negotiable, exactly so hallucinated nodes can't slip into the canonical architecture. If the source doesn't exist yet, draft in `*.archik.discussion.yaml` first.
+
 ## Authoring drafts (sidecar workflow)
 
 When work introduces, removes, or rewires components, you stage a proposal as a sidecar via the CLI. The user reviews on the canvas and accepts / rejects.