@tailor-platform/erp-kit 0.5.1 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tailor-platform/erp-kit",
-  "version": "0.5.1",
+  "version": "0.7.0",
   "description": "Opinionated ERP toolkit for building business applications on Tailor Platform",
   "license": "MIT",
   "bin": {

package/skills/erp-kit-app-1-requirements/SKILL.md

@@ -7,6 +7,18 @@ description: Create Tier 1-2 documentation (requirements, actors, business-flow)
 
 Create Tier 1-2 documentation: Requirements, Actors, and Business Flows.
 
+## Progress Logging
+
+Log to the audit trail at every checkpoint. See [erp-kit-app-shared/references/progress-protocol.md](../erp-kit-app-shared/references/progress-protocol.md) for the full protocol.
+
+```bash
+npx erp-kit app progress log --json '<ProgressInput JSON>'
+```
+
+Required checkpoints: `step.start` (on invocation), `decision` (on user choices), `agent.dispatch`/`agent.result` (on subagent lifecycle), `artifact.create` (on file writes), `validation` (on `erp-kit app check` or build commands), `step.complete` (on finish), `error` (on failures).
+
+Bundle all conversation since the last checkpoint into the `conversation` array. Use your session ID as `sessionId`. Use the user's original prompt as `prompt`.
+
 ## Workflow Phases
 
 ```
@@ -28,12 +40,12 @@ Focus on "what" the application should do, not "how" it will be implemented.
 
 Use AskUserQuestion to clarify undefined requirements. Focus on business-level scope and workflows — not platform capabilities like authentication.
 
-| Category         | Example Questions                                                            |
-| ---------------- | ---------------------------------------------------------------------------- |
-| Scope            | Which steps are MVP-essential? Any steps that can be deferred?               |
-| Edge Cases       | How far to handle cancellation, rejection, or mid-flow abandonment?          |
-| Actor Boundaries | Are approver and executor separate? What is each actor's operational scope?  |
-| Business Rules   | Which steps are automated vs manual? What conditional branches exist?        |
+| Category         | Example Questions                                                           |
+| ---------------- | --------------------------------------------------------------------------- |
+| Scope            | Which steps are MVP-essential? Any steps that can be deferred?              |
+| Edge Cases       | How far to handle cancellation, rejection, or mid-flow abandonment?         |
+| Actor Boundaries | Are approver and executor separate? What is each actor's operational scope? |
+| Business Rules   | Which steps are automated vs manual? What conditional branches exist?       |
 
 Ask 3-4 questions at a time using multiSelect where appropriate.
 
@@ -44,13 +56,13 @@ Generate documentation using `erp-kit` CLI. `{APP_ROOT}` is the parent directory
 ```bash
 # Tier 1: Requirements + project structure
 # Creates {APP_ROOT}/{APP_NAME}/README.md
-erp-kit app init {APP_NAME} {APP_ROOT}
+npx erp-kit app init {APP_NAME} {APP_ROOT}
 
 # Tier 2: Actors
-erp-kit app generate doc actors {ACTOR_NAME} -p {APP_ROOT}/{APP_NAME}
+npx erp-kit app generate doc actors {ACTOR_NAME} -p {APP_ROOT}/{APP_NAME}
 
 # Tier 2: Business Flows
-erp-kit app generate doc business-flow {FLOW_NAME} -p {APP_ROOT}/{APP_NAME}
+npx erp-kit app generate doc business-flow {FLOW_NAME} -p {APP_ROOT}/{APP_NAME}
 ```
 
 **Directory structure after init + generate:**
@@ -80,6 +92,7 @@ After creating business flows, extract and create story documentation.
 
 1. **Collect** all business flow docs: glob `<APP_ROOT>/docs/business-flow/*/README.md`
 2. **Dispatch story extraction agents** — one Agent per business flow (parallelize if possible). Each agent:
+
    - Reads the prompt template from [references/story-extraction.md](references/story-extraction.md)
    - Replace `{{APP_NAME}}` with the resolved app name
    - Replace `{{ACTOR_DOCS}}` with the actor doc file paths
@@ -90,7 +103,7 @@ After creating business flows, extract and create story documentation.
 
 ```bash
 # For each story identified
-erp-kit app generate doc story <flow>/<actor>--<story> -p {APP_ROOT}/{APP_NAME}
+npx erp-kit app generate doc story <flow>/<actor>--<story> -p {APP_ROOT}/{APP_NAME}
 ```
 
 4. **Link stories** in business flow READMEs: replace `- TBD` placeholders in each flow's `## Stories` section with actual links:
@@ -102,18 +115,21 @@ erp-kit app generate doc story <flow>/<actor>--<story> -p {APP_ROOT}/{APP_NAME}
 ### Phase 4: Validate
 
 ```bash
-erp-kit app check -p {APP_ROOT}
+# NOTE: -p takes {APP_ROOT} (parent directory), NOT {APP_ROOT}/{APP_NAME}.
+# generate doc uses -p {APP_ROOT}/{APP_NAME}, but check uses -p {APP_ROOT}.
+# Example: if app is at apps/user-management, use -p apps
+npx erp-kit app check -p {APP_ROOT}
 ```
 
-See [schema-constraints.md](../erp-kit-app-shared/references/schema-constraints.md) for notes on expected "No matching files found" output.
+**Expected passing output:** `✓ No violations found` for each doc type that has files. "No matching files found" appears for doc types not yet created (e.g., screens and resolvers at Tier 1-2) — this is normal and not an error.
 
 ## Schema Reference
 
-| Schema              | Tier | Output Path                           |
-| ------------------- | ---- | ------------------------------------- |
-| `requirements.yml`  | 1    | `README.md`                           |
-| `actors.yml`        | 2    | `docs/actors/<name>.md`               |
-| `business-flow.yml` | 2    | `docs/business-flow/<flow>/README.md` |
+| Schema              | Tier | Output Path                                          |
+| ------------------- | ---- | ---------------------------------------------------- |
+| `requirements.yml`  | 1    | `README.md`                                          |
+| `actors.yml`        | 2    | `docs/actors/<name>.md`                              |
+| `business-flow.yml` | 2    | `docs/business-flow/<flow>/README.md`                |
 | `story.yml`         | 2    | `docs/business-flow/<flow>/story/<actor>--<name>.md` |
 
 ## Next Step

package/skills/erp-kit-app-2-requirements-review/SKILL.md

@@ -7,6 +7,18 @@ description: Review requirements quality and documentation consistency for appli
 
 Review **requirements quality** and **documentation consistency** for an application's Tier 1-2 documentation.
 
+## Progress Logging
+
+Log to the audit trail at every checkpoint. See [erp-kit-app-shared/references/progress-protocol.md](../erp-kit-app-shared/references/progress-protocol.md) for the full protocol.
+
+```bash
+npx erp-kit app progress log --json '<ProgressInput JSON>'
+```
+
+Required checkpoints: `step.start` (on invocation), `decision` (on user choices), `agent.dispatch`/`agent.result` (on subagent lifecycle), `artifact.create` (on file writes), `validation` (on `erp-kit app check` or build commands), `step.complete` (on finish), `error` (on failures).
+
+Bundle all conversation since the last checkpoint into the `conversation` array. Use your session ID as `sessionId`. Use the user's original prompt as `prompt`.
+
 ## When to Use
 
 - After writing application requirements and business flows (step 1)

package/skills/erp-kit-app-3-plan/SKILL.md

@@ -7,6 +7,18 @@ description: Create Tier 3-4 documentation (screens, resolvers) by breaking down
 
 Convert Tier 2 business flows and stories into Tier 3 (screens) and Tier 4 (resolvers) documentation using parallel extraction agents.
 
+## Progress Logging
+
+Log to the audit trail at every checkpoint. See [erp-kit-app-shared/references/progress-protocol.md](../erp-kit-app-shared/references/progress-protocol.md) for the full protocol.
+
+```bash
+npx erp-kit app progress log --json '<ProgressInput JSON>'
+```
+
+Required checkpoints: `step.start` (on invocation), `decision` (on user choices), `agent.dispatch`/`agent.result` (on subagent lifecycle), `artifact.create` (on file writes), `validation` (on `erp-kit app check` or build commands), `step.complete` (on finish), `error` (on failures).
+
+Bundle all conversation since the last checkpoint into the `conversation` array. Use your session ID as `sessionId`. Use the user's original prompt as `prompt`.
+
 ## When to Use
 
 - User has Tier 1-2 documentation and wants to plan Tier 3-4
@@ -40,7 +52,7 @@ Verify at least `STORY_DOCS` is non-empty. If no story docs exist, stop with: "N
 Collect module overview:
 
 ```bash
-erp-kit doc modules
+npx erp-kit doc modules
 ```
 
 This returns each module's name, overview, command/query/model counts, and dependencies. Save the full output as `MODULE_OVERVIEW` — both agents receive it.
@@ -100,10 +112,10 @@ Scaffold using `erp-kit` CLI:
 
 ```bash
 # Tier 3: Screens
-erp-kit app generate doc screen <screen-name> -p {APP_ROOT}/{APP_NAME}
+npx erp-kit app generate doc screen <screen-name> -p {APP_ROOT}/{APP_NAME}
 
 # Tier 4: Resolvers
-erp-kit app generate doc resolver <resolver-name> -p {APP_ROOT}/{APP_NAME}
+npx erp-kit app generate doc resolver <resolver-name> -p {APP_ROOT}/{APP_NAME}
 ```
 
 Fill scaffolded docs with details from agent extraction results.
@@ -119,7 +131,9 @@ Read-only stories should have `None` under `## Resolvers`.
 ## Step 6: Validate
 
 ```bash
-erp-kit app check -p {APP_ROOT}
+# NOTE: -p takes {APP_ROOT} (parent directory), NOT {APP_ROOT}/{APP_NAME}.
+# generate doc uses -p {APP_ROOT}/{APP_NAME}, but check uses -p {APP_ROOT}.
+npx erp-kit app check -p {APP_ROOT}
 ```
 
 ## Naming Conventions

package/skills/erp-kit-app-3-plan/references/resolver-extraction.md

@@ -16,7 +16,7 @@ The following modules are available in erp-kit. Use this to map resolvers to rea
 To inspect a specific module's commands in detail, run:
 
 ```bash
-erp-kit doc module <module-name> command <command-name>
+npx erp-kit doc module <module-name> command <command-name>
 ```
 
 ## Instructions

package/skills/erp-kit-app-3-plan/references/screen-extraction.md

@@ -16,7 +16,7 @@ The following modules are available in erp-kit. Use this to understand which ent
 To inspect a specific module's model (domain description, state transitions, invariants, commands), run:
 
 ```bash
-erp-kit doc module <module-name> model <model-name>
+npx erp-kit doc module <module-name> model <model-name>
 ```
 
 ## Instructions

package/skills/erp-kit-app-4-plan-review/SKILL.md

@@ -7,6 +7,18 @@ description: Review parity between Tier 2 (business flows, actors, stories) and
 
 Review **documentation consistency** across Tier 2 (business flows, actors, stories), Tier 3 (screens), and Tier 4 (resolvers) documentation.
 
+## Progress Logging
+
+Log to the audit trail at every checkpoint. See [erp-kit-app-shared/references/progress-protocol.md](../erp-kit-app-shared/references/progress-protocol.md) for the full protocol.
+
+```bash
+npx erp-kit app progress log --json '<ProgressInput JSON>'
+```
+
+Required checkpoints: `step.start` (on invocation), `decision` (on user choices), `agent.dispatch`/`agent.result` (on subagent lifecycle), `artifact.create` (on file writes), `validation` (on `erp-kit app check` or build commands), `step.complete` (on finish), `error` (on failures).
+
+Bundle all conversation since the last checkpoint into the `conversation` array. Use your session ID as `sessionId`. Use the user's original prompt as `prompt`.
+
 ## When to Use
 
 - After writing Tier 3-4 documentation, check for gaps

package/skills/erp-kit-app-5-impl-backend/SKILL.md

@@ -7,6 +7,18 @@ description: Implement backend code for applications using erp-kit modules. Use
 
 Implement backend resolvers and application configuration for an application, driven by Tier 1-4 documentation (actors, business flows, stories, screens, resolvers).
 
+## Progress Logging
+
+Log to the audit trail at every checkpoint. See [erp-kit-app-shared/references/progress-protocol.md](../erp-kit-app-shared/references/progress-protocol.md) for the full protocol.
+
+```bash
+npx erp-kit app progress log --json '<ProgressInput JSON>'
+```
+
+Required checkpoints: `step.start` (on invocation), `decision` (on user choices), `agent.dispatch`/`agent.result` (on subagent lifecycle), `artifact.create` (on file writes), `validation` (on `erp-kit app check` or build commands), `step.complete` (on finish), `error` (on failures).
+
+Bundle all conversation since the last checkpoint into the `conversation` array. Use your session ID as `sessionId`. Use the user's original prompt as `prompt`.
+
 ## When to Use
 
 - Implementing backend resolvers from resolver spec docs
@@ -90,7 +102,10 @@ For each resolver, check whether its spec (`docs/resolver/*.md`) documents error
 
 Do not directly mutate module-owned tables via Kysely — always use module commands.
 
+After resolvers are done, implement the story integration test stubs generated in Phase 1b (`backend/src/tests/stories/`). Each stub has `it()` descriptions from the story doc's `## Test Cases`. Use the scaffolded GraphQL client and `inject("url")` / `inject("token")` to call resolvers. Run `pnpm test:integration` and `pnpm erp-kit app sync-check` to verify.
+
 > **Parallelize if possible:** Dispatch one agent per resolver. Each agent writes only to its own files:
+>
 > - `src/resolvers/<resolverName>.ts`
 > - `src/executors/<resolverName>.ts`
 >
@@ -107,10 +122,10 @@ Do not directly mutate module-owned tables via Kysely — always use module comm
 
 Frontend implementation requires a deployed backend (for GraphQL schema generation). Prompt the user to:
 
-1. Create a workspace and configure `.env` (including `TAILOR_PLATFORM_WORKSPACE_ID`)
-2. Run `pnpm deploy` and `pnpm generate`
-3. Run `pnpm seed` if seed data was created
-4. Retrieve OAuth2 client ID via `tailor-sdk oauth2client get default --json` for frontend `.env`
+1. Create a workspace via `tailor-sdk workspace create --name <NAME> --region <us-west|asia-northeast>` and configure `.env` (including `TAILOR_PLATFORM_WORKSPACE_ID`)
+2. Run `pnpm run deploy` and `pnpm run generate`
+3. Run `pnpm run seed` if seed data was created
+4. Retrieve OAuth2 client ID via `tailor-sdk oauth2client get default --json --env-file-if-exists .env` for frontend `.env`
 
 Wait for the user to confirm deployment is complete before proceeding.
 

package/skills/erp-kit-app-6-impl-frontend/SKILL.md

@@ -7,6 +7,18 @@ description: Implement frontend code for applications. Use after deploying the b
 
 Implement frontend pages for an application, driven by screen spec documentation and a deployed backend.
 
+## Progress Logging
+
+Log to the audit trail at every checkpoint. See [erp-kit-app-shared/references/progress-protocol.md](../erp-kit-app-shared/references/progress-protocol.md) for the full protocol.
+
+```bash
+npx erp-kit app progress log --json '<ProgressInput JSON>'
+```
+
+Required checkpoints: `step.start` (on invocation), `decision` (on user choices), `agent.dispatch`/`agent.result` (on subagent lifecycle), `artifact.create` (on file writes), `validation` (on `erp-kit app check` or build commands), `step.complete` (on finish), `error` (on failures).
+
+Bundle all conversation since the last checkpoint into the `conversation` array. Use your session ID as `sessionId`. Use the user's original prompt as `prompt`.
+
 ## When to Use
 
 - Implementing frontend pages from screen spec docs

package/skills/erp-kit-app-7-impl-review/SKILL.md

@@ -7,6 +7,18 @@ description: Review implementation parity between documentation and code for app
 
 Review **implementation consistency** between Tier 3-4 documentation and actual backend/frontend code.
 
+## Progress Logging
+
+Log to the audit trail at every checkpoint. See [erp-kit-app-shared/references/progress-protocol.md](../erp-kit-app-shared/references/progress-protocol.md) for the full protocol.
+
+```bash
+npx erp-kit app progress log --json '<ProgressInput JSON>'
+```
+
+Required checkpoints: `step.start` (on invocation), `decision` (on user choices), `agent.dispatch`/`agent.result` (on subagent lifecycle), `artifact.create` (on file writes), `validation` (on `erp-kit app check` or build commands), `step.complete` (on finish), `error` (on failures).
+
+Bundle all conversation since the last checkpoint into the `conversation` array. Use your session ID as `sessionId`. Use the user's original prompt as `prompt`.
+
 ## When to Use
 
 - After backend and frontend implementation, verify code matches documentation
@@ -60,10 +72,10 @@ Run build checks and source-doc sync check inline:
 ```bash
 cd <APP_ROOT>/backend && pnpm lint && pnpm typecheck
 cd <APP_ROOT>/frontend && pnpm lint && pnpm typecheck && pnpm build
-erp-kit app sync-check -p <APP_ROOT>/..
+npx erp-kit app sync-check -p <APP_ROOT>
 ```
 
-Report pass/fail for each check. `sync-check` detects missing resolver implementations and orphaned docs, so groups A-C agents can skip file-existence checks and focus on content parity.
+Report pass/fail for each check. `sync-check` detects missing resolver implementations, orphaned docs, and story doc ↔ integration test case mismatches, so groups A-C agents can skip file-existence checks and focus on content parity.
 
 ## Step 3: Aggregate Results
 

package/skills/erp-kit-app-shared/references/progress-protocol.md

@@ -0,0 +1,77 @@
+# Progress Logging Protocol
+
+## Overview
+
+All `erp-kit-app-*` skills log to an append-only audit trail at `.erp-kit/progress.jsonl`. This records conversations, decisions, and agent activity across sessions.
+
+The log is NOT the source of truth for progress — the produced docs and code are. The log answers "what happened and why."
+
+## CLI Commands
+
+### Log an event
+
+```bash
+npx erp-kit app progress log --json '<ProgressInput JSON>'
+```
+
+### Validate without writing
+
+```bash
+npx erp-kit app progress log --dry-run --json '<ProgressInput JSON>'
+```
+
+### Get the JSON Schema
+
+```bash
+npx erp-kit app progress schema
+```
+
+## When to Log
+
+Log at natural checkpoints — moments where the skill is already pausing to take action. Bundle all conversation since the last checkpoint into the `conversation` array.
+
+| Checkpoint | Event type | When |
+|---|---|---|
+| Skill invocation | `step.start` | First thing after skill is invoked |
+| User decision | `decision` | User approves, corrects, or chooses |
+| Subagent launch | `agent.dispatch` | Before dispatching a subagent |
+| Subagent return | `agent.result` | After subagent completes |
+| File write | `artifact.create` | After creating/modifying/deleting a file |
+| Validation | `validation` | After running `erp-kit app check`, build, lint, etc. |
+| Skill completion | `step.complete` | Last thing before skill finishes |
+| Failure | `error` | When something fails |
+| Free-form | `note` | Anything else (e.g., session pause) |
+
+## Entry Format
+
+Every entry requires:
+
+- `v` — Schema version, always `1`
+- `sessionId` — Your AI session ID
+- `prompt` — The user's original prompt (the request that triggered this skill)
+- `event` — Event type from the table above
+- `data` — Event-specific payload (see schema)
+- `conversation` — Array of `{role, message}` since last checkpoint (optional, defaults to `[]`)
+
+The CLI auto-adds `timestamp` and `git` context.
+
+## Example
+
+```bash
+npx erp-kit app progress log --json '{
+  "v": 1,
+  "sessionId": "claude-abc123",
+  "prompt": "Create screens for manufacturing flows",
+  "event": "decision",
+  "conversation": [
+    {"role": "agent", "message": "Flat list or collapsible tree for BOM?"},
+    {"role": "user", "message": "Collapsible tree"}
+  ],
+  "data": {
+    "question": "BOM list view style",
+    "choice": "Collapsible tree",
+    "alternatives": ["Flat list with indent"],
+    "rationale": "Better UX for multi-level BOMs"
+  }
+}'
+```

package/skills/erp-kit-mock-scenario/SKILL.md

@@ -112,7 +112,7 @@ Create `mocks/{provider}/{scenario}/README.md` with:
 ### Step 5: Validate
 
 ```bash
-erp-kit mock validate
+npx erp-kit mock validate
 ```
 
 Fix any failures before finishing.

package/skills/erp-kit-module-1-requirements/SKILL.md

@@ -70,7 +70,7 @@ The final feature set becomes the union of all `Include` features. Proceed with
 First, scaffold the module if it doesn't exist:
 
 ```bash
-erp-kit module init <module-name> <MODULES_ROOT>/<module-name>
+npx erp-kit module init <module-name> <MODULES_ROOT>/<module-name>
 ```
 
 Then, for each `Include` feature, launch an Agent:

package/skills/erp-kit-module-3-plan/SKILL.md

@@ -44,9 +44,9 @@ Produce consolidated plan:
 Scaffold using `erp-kit` CLI. **Names must be PascalCase** (see [naming convention](references/naming.md)):
 
 ```bash
-erp-kit module generate doc model ModelName -p <MODULES_ROOT>/<module-name>
-erp-kit module generate doc command CommandName -p <MODULES_ROOT>/<module-name>
-erp-kit module generate doc query QueryName -p <MODULES_ROOT>/<module-name>
+npx erp-kit module generate doc model ModelName -p <MODULES_ROOT>/<module-name>
+npx erp-kit module generate doc command CommandName -p <MODULES_ROOT>/<module-name>
+npx erp-kit module generate doc query QueryName -p <MODULES_ROOT>/<module-name>
 ```
 
 Fill in the scaffolded docs with details from the extraction in Step 2.

package/skills/erp-kit-module-3-update-plan/SKILL.md

@@ -78,9 +78,9 @@ For each item in the fix plan:
 Scaffold using `erp-kit` CLI. **Names must be PascalCase** (see [naming convention](references/naming.md)):
 
 ```bash
-erp-kit module generate doc model ModelName -p <MODULES_ROOT>/<module-name>
-erp-kit module generate doc command CommandName -p <MODULES_ROOT>/<module-name>
-erp-kit module generate doc query QueryName -p <MODULES_ROOT>/<module-name>
+npx erp-kit module generate doc model ModelName -p <MODULES_ROOT>/<module-name>
+npx erp-kit module generate doc command CommandName -p <MODULES_ROOT>/<module-name>
+npx erp-kit module generate doc query QueryName -p <MODULES_ROOT>/<module-name>
 ```
 
 Populate the new docs using the extraction rules from:

package/skills/erp-kit-module-5-impl/SKILL.md

@@ -37,7 +37,7 @@ Verify at least one doc type exists. If none, stop with: "No docs found for modu
 Run generation first to create `.generated.ts` files (error classes, permission definitions, command/query shells) before implementing any code:
 
 ```bash
-erp-kit module generate code -p <MODULES_ROOT>/<module>
+npx erp-kit module generate code -p <MODULES_ROOT>/<module>
 ```
 
 Never edit these generated files.

package/skills/erp-kit-module-6-impl-review/SKILL.md

@@ -31,35 +31,57 @@ Define shared context for all agents:
 
 Verify at least `MODEL_DOCS`, `COMMAND_DOCS`, or `QUERY_DOCS` is non-empty. If no docs exist, stop with: "No docs found for module <MODULE_NAME>."
 
-## Step 2: Dispatch Agents (parallelize if possible)
+## Step 2: Dispatch Agents (parallelize ALL agents in a single message)
 
-Launch 3 Agent tool calls in parallel — one per domain (model, command, query).
-Each agent receives: MODULE_NAME, all relevant doc/code/test file paths for its domain.
-Each agent runs all parity perspectives (doc→code, error, doc→test) internally and returns: structured JSON per [references/impl-parity-report-format.md](references/impl-parity-report-format.md).
-If a doc or code directory is empty, the agent reports "no files found" and skips.
+Split each parity check into its own agent, then further split by file batches when there are many files. Target **~5 agents per domain** (model, command, query) for maximum parallelism. Launch **ALL agents in a single message** — do NOT wait for one domain to finish before starting another.
 
-| Agent | Domain  | Prompt Templates                                                                                                                                                                                                                                                                   | Inputs                                                              |
-| ----- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
-| 1     | Model   | [references/model-doc-code-parity.md](references/model-doc-code-parity.md)                                                                                                                                                                                                         | MODEL_DOCS, MODEL_CODE                                              |
-| 2     | Command | [references/command-doc-code-parity.md](references/command-doc-code-parity.md), [references/command-error-implementation-parity.md](references/command-error-implementation-parity.md), [references/command-doc-test-parity.md](references/command-doc-test-parity.md)               | COMMAND_DOCS, COMMAND_CODE, COMMAND_TEST_CODE, ERROR_DEFS           |
-| 3     | Query   | [references/query-doc-code-parity.md](references/query-doc-code-parity.md), [references/query-error-implementation-parity.md](references/query-error-implementation-parity.md), [references/query-doc-test-parity.md](references/query-doc-test-parity.md)                         | QUERY_DOCS, QUERY_CODE, QUERY_TEST_CODE, ERROR_DEFS                |
+If a doc or code directory is empty, skip that agent entirely.
+
+### Splitting Strategy
+
+1. **Each parity check type = separate agent** (never combine different check types in one agent)
+2. **File batching**: If a check has more than 5 doc files, split docs into batches of 3-5 files each. Each batch becomes its own agent running the same check type on a subset of files.
+3. **Corresponding code/test files**: When batching by doc files, include only the matching code and test files for those specific docs (match by filename stem, e.g., `docs/commands/createFoo.md` → `command/createFoo.ts` + `command/createFoo.test.ts`).
+
+### Agent Table
+
+| Check Type | Domain  | Prompt Template                                                                                            | Inputs per agent                                                     |
+| ---------- | ------- | ---------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
+| M-1        | Model   | [references/model-doc-code-parity.md](references/model-doc-code-parity.md)                                 | MODEL_DOCS (batch), MODEL_CODE (matching)                            |
+| C-1        | Command | [references/command-doc-code-parity.md](references/command-doc-code-parity.md)                              | COMMAND_DOCS (batch), COMMAND_CODE (matching)                        |
+| C-2        | Command | [references/command-error-implementation-parity.md](references/command-error-implementation-parity.md)      | COMMAND_DOCS (batch), COMMAND_CODE (matching), ERROR_DEFS            |
+| C-3        | Command | [references/command-doc-test-parity.md](references/command-doc-test-parity.md)                              | COMMAND_DOCS (batch), COMMAND_TEST_CODE (matching)                   |
+| Q-1        | Query   | [references/query-doc-code-parity.md](references/query-doc-code-parity.md)                                 | QUERY_DOCS (batch), QUERY_CODE (matching)                            |
+| Q-2        | Query   | [references/query-error-implementation-parity.md](references/query-error-implementation-parity.md)          | QUERY_DOCS (batch), QUERY_CODE (matching), ERROR_DEFS               |
+| Q-3        | Query   | [references/query-doc-test-parity.md](references/query-doc-test-parity.md)                                 | QUERY_DOCS (batch), QUERY_TEST_CODE (matching)                      |
+
+### Batching Example
+
+If a module has 8 command docs: split into 3 batches (3+3+2). Each batch spawns 3 agents (C-1, C-2, C-3) → 9 command agents total. If it has 4 command docs: no batching needed, 3 agents (C-1, C-2, C-3).
+
+For model docs: if 6 models → 2 batches (3+3) → 2 agents (M-1 × 2). If 3 models → 1 agent.
+
+### Agent Dispatch
 
 For each agent:
 
-1. Read ALL prompt template files listed for that agent
+1. Read the prompt template file for that check type
 2. Replace `{{MODULE_NAME}}` with the resolved module name
-3. Replace `{{MODEL_DOCS}}`, `{{COMMAND_DOCS}}`, `{{QUERY_DOCS}}`, `{{MODEL_CODE}}`, `{{COMMAND_CODE}}`, `{{QUERY_CODE}}`, `{{COMMAND_TEST_CODE}}`, `{{QUERY_TEST_CODE}}`, `{{ERROR_DEFS}}` with the actual file paths
-4. Combine the templates into a single prompt and dispatch the agent
+3. Replace template placeholders (`{{MODEL_DOCS}}`, `{{COMMAND_DOCS}}`, `{{QUERY_DOCS}}`, `{{MODEL_CODE}}`, `{{COMMAND_CODE}}`, `{{QUERY_CODE}}`, `{{COMMAND_TEST_CODE}}`, `{{QUERY_TEST_CODE}}`, `{{ERROR_DEFS}}`) with the actual file paths **for this batch only**
+4. Dispatch the agent with the filled prompt
+
+**IMPORTANT**: Launch ALL agents across ALL domains in a single parallel message. Do not serialize by domain.
 
 ## Step 3: Aggregate Results
 
 After ALL agents return:
 
 1. Collect the JSON results from each agent
-2. Merge all `gaps[]` arrays into a single list
-3. Merge all `inconsistencies[]` arrays into a single list
-4. Deduplicate: if two gaps share the same `source + target + check`, keep only one
-5. Calculate totals across all summaries
+2. **Merge batches**: If a check type was split across multiple batches (e.g., C-1 batch 1 + C-1 batch 2), merge their `gaps[]` and `inconsistencies[]` into a single result per check type
+3. Merge all `gaps[]` arrays across all check types into a single list
+4. Merge all `inconsistencies[]` arrays into a single list
+5. Deduplicate: if two gaps share the same `source + target + check`, keep only one
+6. Calculate totals across all summaries
 
 ## Step 4: Severity Validation
 

package/src/commands/app/index.ts

@@ -8,6 +8,7 @@ import { runGenerateAppCode } from "../../generator/generate-app-code";
 import { runGenerateSeed } from "../../generator/generate-seed";
 import { runInitAppWithReadme } from "../init-module";
 import { executeCommand, success, silentFailure } from "../lib/command-result";
+import { progressCommand } from "./progress/index";
 
 const cwd = process.cwd();
 
@@ -129,5 +130,6 @@ export const appCommand = defineCommand({
     "sync-check": syncCheckCommand,
     init: initCommand,
     generate: generateCommand,
+    progress: progressCommand,
   },
 });

package/src/commands/app/progress/git-context.ts

@@ -0,0 +1,16 @@
+import { execFileSync } from "node:child_process";
+import type { GitContext } from "../../../progress/schema";
+
+export function getGitContext(cwd: string): GitContext {
+  const branch = execFileSync("git", ["rev-parse", "--abbrev-ref", "HEAD"], {
+    cwd,
+    encoding: "utf-8",
+  }).trim();
+
+  const commit = execFileSync("git", ["rev-parse", "--short", "HEAD"], {
+    cwd,
+    encoding: "utf-8",
+  }).trim();
+
+  return { branch, commit };
+}

package/src/commands/app/progress/index.ts

@@ -0,0 +1,45 @@
+import { z } from "zod";
+import { defineCommand, arg } from "politty";
+import { executeCommand } from "../../lib/command-result";
+import { runProgressLog } from "./log";
+import { runProgressSchema } from "./schema-cmd";
+
+const cwd = process.cwd();
+
+const logCommand = defineCommand({
+  name: "log",
+  description: "Append a validated entry to the progress log",
+  args: z.object({
+    json: arg(z.string(), {
+      description: "JSON payload (ProgressInput schema)",
+    }),
+    "dry-run": arg(z.boolean().default(false), {
+      description: "Validate without writing",
+    }),
+  }),
+  run: (args) => {
+    return executeCommand(() => {
+      return runProgressLog(args.json, args["dry-run"], cwd);
+    });
+  },
+});
+
+const schemaCommand = defineCommand({
+  name: "schema",
+  description: "Output JSON Schema for progress log input",
+  args: z.object({}),
+  run: () => {
+    return executeCommand(() => {
+      return runProgressSchema();
+    });
+  },
+});
+
+export const progressCommand = defineCommand({
+  name: "progress",
+  description: "Audit log for app skill sessions",
+  subCommands: {
+    log: logCommand,
+    schema: schemaCommand,
+  },
+});