Merge pull request #39 from escoffier-labs/feat/work-import-schema

feat: add work import schema

Author: solomonneas

CHANGELOG.md

@@ -46,9 +46,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `brigade work tasks` plus `brigade work task add/show/done` to manage a gitignored local task ledger under `.brigade/work/tasks.json`.
 - `brigade work run --queue-next` to queue the successful run's extracted next step, with duplicate pending task protection.
 - `brigade work import add/list/show/promote` to manage a gitignored local import inbox for scanner-discovered candidate work.
+- `brigade work import validate` and `brigade work import ingest` for scanner-authored JSONL import files.
+- `brigade work import memory-care` to convert `memory/cards/decay/refresh-queue.json` into local work imports.
 - `brigade work import triage` to group pending imports by source and kind.
 - `brigade work import dismiss` to close noisy imports without promoting them.
 - `brigade work import promote --all` with optional `--source` and `--kind` filters for batch promotion.
+- `docs/import-schema.md` documenting the local import JSONL contract for scanners and wrappers.
 - `ROADMAP.md` covering the daily-driver path, scanner-ready inbox, chat-surface scanners, memory-card decay refresh, and portable operator setup.
 - `brigade work note` to append timestamped checkpoints to the active work session without ending it.
 - `brigade work doctor` to check dogfood config, Codex availability, local artifact paths, handoff inbox, ignore coverage, and latest run context for the daily work loop.

README.md

@@ -152,6 +152,9 @@ brigade work task add --from-next
 brigade work task done <task-id>
 brigade work import add --kind task --source slack "refresh the stale memory card"
 brigade work import list
+brigade work import validate imports.jsonl
+brigade work import ingest imports.jsonl
+brigade work import memory-care
 brigade work import triage
 brigade work import promote <import-id>
 brigade work import promote --all --source memory-care --kind task
@@ -186,7 +189,7 @@ CLI runs write artifacts by default under `.brigade/runs/<id>` below `--cwd`; do
 
 Use `--output-dir <path>` to pick the artifact directory, or `--no-artifacts` for a throwaway run.
 
-Use `brigade work bootstrap` once in a repo to initialize the daily loop: it writes or verifies `.brigade/dogfood.toml`, creates local run and work artifact directories, creates the configured handoff inbox, updates the managed `.gitignore` block, and reports whether the repo is ready to run. Use `brigade work brief` as the normal start-of-day command. It shows branch and dirty-file state, active and latest work sessions, pending local tasks, pending local import counts by source and kind, latest dogfood run, extracted next task, recent sessions, and the command to continue; add `--json` for wrappers. Use `brigade work tasks` to list the local task ledger stored in `.brigade/work/tasks.json`, `brigade work task add "..."` to queue work manually, `brigade work task add --from-next` to promote the latest extracted dogfood next step, and `brigade work task done <task-id>` to close queued work. Use `brigade work import add "..."` as a scanner-ready local inbox for candidate tasks, findings, decisions, preferences, incidents, links, and commands from systems such as chat crawlers or memory-care decay scans; imports are stored under `.brigade/work/imports/inbox.jsonl`, stay gitignored, and do not write memory directly. Use `brigade work import triage` to group pending imports by source and kind, `brigade work import show <import-id>` to inspect one item, `brigade work import dismiss <import-id>` to remove noise from the pending queue, `brigade work import promote <import-id>` to promote one reviewed import into the task ledger, or `brigade work import promote --all --source memory-care --kind task` to batch-promote filtered pending imports with source metadata preserved. Use `brigade work status` as the quick daily dashboard for a repo. It reports the current branch, dirty files, dogfood readiness, configured dogfood paths, latest dogfood run, and extracted next step without starting a new orchestration. Use `brigade work doctor` to check whether the repo is ready for the daily loop: dogfood config, Codex CLI, local artifact paths, handoff inbox, ignore coverage, and latest run context. Use `brigade work resume` when returning to a repo; it shows the active or latest work session, latest dogfood run, extracted next step, and the suggested command to continue. Use `brigade work next` when you only need the task Brigade would run next, or `brigade work next --json` for wrappers that want the active session, dogfood snapshot, resolved task, and suggested command as structured output. `brigade work run` is the one-command daily loop: it starts a work session, consumes the oldest pending ledger task when no task is passed, otherwise uses the latest extracted dogfood next step, runs `brigade dogfood`, marks consumed ledger tasks done after successful runs, ends the session, writes a work-session Memory Handoff by default, and prints a compact recap. Add `--queue-next` to queue the successful run's extracted next step for the next session; duplicate pending task text is reused instead of added again. Pass a task to override the resolved next step, `--title` to name the session, `--no-handoff` to skip the work handoff, or `--dogfood-handoff` to also let the underlying dogfood run write its own handoff. `brigade work start "title"` opens a local work session under `.brigade/work/<id>/`, records the starting git and dogfood context, and writes `start.md`. `brigade work note "checkpoint"` appends a timestamped note to the active session without ending it. `brigade work end --note "what happened"` closes the active session, records ending context, and writes `end.md`. Add `--handoff` to also write a Memory Handoff for the closed session; it defaults to the configured dogfood handoff inbox or `.codex/memory-handoffs`.
+Use `brigade work bootstrap` once in a repo to initialize the daily loop: it writes or verifies `.brigade/dogfood.toml`, creates local run and work artifact directories, creates the configured handoff inbox, updates the managed `.gitignore` block, and reports whether the repo is ready to run. Use `brigade work brief` as the normal start-of-day command. It shows branch and dirty-file state, active and latest work sessions, pending local tasks, pending local import counts by source and kind, latest dogfood run, extracted next task, recent sessions, and the command to continue; add `--json` for wrappers. Use `brigade work tasks` to list the local task ledger stored in `.brigade/work/tasks.json`, `brigade work task add "..."` to queue work manually, `brigade work task add --from-next` to promote the latest extracted dogfood next step, and `brigade work task done <task-id>` to close queued work. Use `brigade work import add "..."` as a scanner-ready local inbox for candidate tasks, findings, decisions, preferences, incidents, links, and commands from systems such as chat crawlers or memory-care decay scans; imports are stored under `.brigade/work/imports/inbox.jsonl`, stay gitignored, and do not write memory directly. Scanner authors can write JSONL records documented in [`docs/import-schema.md`](docs/import-schema.md), then run `brigade work import validate imports.jsonl` and `brigade work import ingest imports.jsonl`. Use `brigade work import memory-care` to convert `memory/cards/decay/refresh-queue.json` into local imports. Use `brigade work import triage` to group pending imports by source and kind, `brigade work import show <import-id>` to inspect one item, `brigade work import dismiss <import-id>` to remove noise from the pending queue, `brigade work import promote <import-id>` to promote one reviewed import into the task ledger, or `brigade work import promote --all --source memory-care --kind task` to batch-promote filtered pending imports with source metadata preserved. Use `brigade work status` as the quick daily dashboard for a repo. It reports the current branch, dirty files, dogfood readiness, configured dogfood paths, latest dogfood run, and extracted next step without starting a new orchestration. Use `brigade work doctor` to check whether the repo is ready for the daily loop: dogfood config, Codex CLI, local artifact paths, handoff inbox, ignore coverage, and latest run context. Use `brigade work resume` when returning to a repo; it shows the active or latest work session, latest dogfood run, extracted next step, and the suggested command to continue. Use `brigade work next` when you only need the task Brigade would run next, or `brigade work next --json` for wrappers that want the active session, dogfood snapshot, resolved task, and suggested command as structured output. `brigade work run` is the one-command daily loop: it starts a work session, consumes the oldest pending ledger task when no task is passed, otherwise uses the latest extracted dogfood next step, runs `brigade dogfood`, marks consumed ledger tasks done after successful runs, ends the session, writes a work-session Memory Handoff by default, and prints a compact recap. Add `--queue-next` to queue the successful run's extracted next step for the next session; duplicate pending task text is reused instead of added again. Pass a task to override the resolved next step, `--title` to name the session, `--no-handoff` to skip the work handoff, or `--dogfood-handoff` to also let the underlying dogfood run write its own handoff. `brigade work start "title"` opens a local work session under `.brigade/work/<id>/`, records the starting git and dogfood context, and writes `start.md`. `brigade work note "checkpoint"` appends a timestamped note to the active session without ending it. `brigade work end --note "what happened"` closes the active session, records ending context, and writes `end.md`. Add `--handoff` to also write a Memory Handoff for the closed session; it defaults to the configured dogfood handoff inbox or `.codex/memory-handoffs`.
 
 Memory and bootstrap readiness are part of the same operating-system health story. `brigade doctor` checks installed bootstrap files against built-in hard byte budgets so overgrown files fail before agents load truncated context. It also checks `memory/cards/*.md` budgets, verifies that `MEMORY.md` card links resolve under `memory/cards/`, and reports memory-care freshness from `memory/cards/decay/scan-latest.json`. Workspace installs include `.brigade/memory-care.example.json` as a scanner wiring contract for whatever scheduler or memory owner produces the decay files. Missing memory-care decay state is advisory for fresh installs, but corrupt scan or refresh-queue JSON fails once the loop is wired. Bootstrap truncation is treated as a hard failure to prevent, not a cosmetic warning; keep cards atomic and bootstrap files as slim indexes.
 

ROADMAP.md

@@ -16,13 +16,16 @@ Status: in progress.
 
 ## Next Phase: Scanner-Ready Inbox
 
-Status: in progress.
+Status: active.
 
 Goal: make Brigade a safe target for local automations that discover useful work.
 
 - Keep raw scanner output private and gitignored under `.brigade/work/imports/`.
 - Normalize imports into small records with `kind`, `source`, text, timestamps, and metadata.
+- Document the scanner JSONL contract so external producers can target Brigade without importing Brigade internals.
+- Validate and ingest scanner-authored JSONL files.
 - Let wrappers import candidate tasks, findings, decisions, preferences, incidents, links, and commands without knowing Brigade internals.
+- Convert memory-care refresh queues into local task imports.
 - Promote selected imports into the work task ledger, with source metadata preserved.
 - Dismiss noisy imports so scanners can be useful without leaving permanent queue clutter.
 - Batch-promote reviewed imports by source and kind.

docs/import-schema.md

@@ -0,0 +1,81 @@
+# Brigade Work Import JSONL Schema
+
+Brigade work imports are the local handoff contract for scanners, wrappers, and chat adapters that discover candidate work. Producers write JSON Lines files, then an operator or wrapper validates and ingests them with `brigade work import`.
+
+Imports are local review items. They do not write canonical memory directly.
+
+## Commands
+
+```bash
+brigade work import validate imports.jsonl
+brigade work import ingest imports.jsonl
+brigade work import memory-care
+brigade work import triage
+brigade work import promote --all --source memory-care --kind task
+```
+
+`validate` checks a JSONL file without writing. `ingest` appends valid records into `.brigade/work/imports/inbox.jsonl`, skipping duplicate pending records with the same source, kind, and normalized text. `memory-care` reads `memory/cards/decay/refresh-queue.json` and converts queued cards into task imports.
+
+## Record Shape
+
+Each non-empty line must be one JSON object:
+
+```json
+{"text":"Refresh memory card memory/cards/tools.md: source-of-truth changed","kind":"task","source":"memory-care","metadata":{"card_file":"memory/cards/tools.md","reason":"source-of-truth changed"}}
+```
+
+Required fields:
+
+- `text`: non-empty string. The operator-facing candidate work.
+
+Optional fields:
+
+- `kind`: one of `task`, `finding`, `decision`, `preference`, `incident`, `link`, or `command`. Defaults to `task`.
+- `source`: non-empty string identifying the producer, such as `memory-care`, `slack`, `discord`, `telegram`, or `repo-scan`. Defaults to `manual`.
+- `metadata`: JSON object with producer-specific context.
+
+Recommended metadata keys:
+
+- `card_file`: memory card path for memory-care records.
+- `reason`: short reason the item was produced.
+- `workspace`: chat workspace or source workspace.
+- `channel`: chat channel or surface name.
+- `thread`: thread id, message range, or export locator.
+- `confidence`: producer confidence such as `low`, `medium`, or `high`.
+- `evidence`: local evidence path or compact summary, not raw private chat text.
+
+## Privacy Rules
+
+- Keep raw chat exports, message bodies, and third-party personal details out of public docs and public repos.
+- Store source locators and summaries in metadata instead of raw message quotes.
+- Route durable memory changes through reviewed Memory Handoffs. Do not let scanners edit memory cards directly by default.
+
+## Memory-Care Producer
+
+The memory-care producer reads this refresh queue by default:
+
+```text
+memory/cards/decay/refresh-queue.json
+```
+
+Minimal queue shape:
+
+```json
+{
+  "cards": [
+    {
+      "file": "memory/cards/example.md",
+      "reason": "source-of-truth changed"
+    }
+  ]
+}
+```
+
+Run:
+
+```bash
+brigade work import memory-care
+brigade work import triage
+```
+
+The producer writes `task` imports with source `memory-care`, preserving `card_file`, `reason`, and `queue_path` metadata.

src/brigade/cli.py

@@ -180,6 +180,24 @@ def _build_parser() -> argparse.ArgumentParser:
     p_work_import_list.add_argument("--all", action="store_true", help="Include promoted imports.")
     p_work_import_list.add_argument("--json", action="store_true", help="Print machine-readable JSON.")
     p_work_import_list.add_argument("--limit", type=int, default=20, help="Maximum imports to show.")
+    p_work_import_validate = import_sub.add_parser("validate", help="Validate a work import JSONL file.")
+    p_work_import_validate.add_argument("input_path", type=Path, help="JSONL file to validate.")
+    p_work_import_validate.add_argument("--json", action="store_true", help="Print machine-readable JSON.")
+    p_work_import_ingest = import_sub.add_parser("ingest", help="Validate and append a work import JSONL file.")
+    p_work_import_ingest.add_argument("input_path", type=Path, help="JSONL file to ingest.")
+    p_work_import_ingest.add_argument("--target", "-t", type=Path, default=Path("."), help="Repo or workspace to update.")
+    p_work_import_ingest.add_argument("--dry-run", action="store_true", help="Validate and report without writing imports.")
+    p_work_import_ingest.add_argument("--json", action="store_true", help="Print machine-readable JSON.")
+    p_work_import_memory_care = import_sub.add_parser("memory-care", help="Import memory-care refresh queue entries.")
+    p_work_import_memory_care.add_argument("--target", "-t", type=Path, default=Path("."), help="Repo or workspace to update.")
+    p_work_import_memory_care.add_argument(
+        "--queue",
+        type=Path,
+        default=None,
+        help="Refresh queue JSON. Defaults to memory/cards/decay/refresh-queue.json under target.",
+    )
+    p_work_import_memory_care.add_argument("--dry-run", action="store_true", help="Report without writing imports.")
+    p_work_import_memory_care.add_argument("--json", action="store_true", help="Print machine-readable JSON.")
     p_work_import_triage = import_sub.add_parser("triage", help="Group pending imports by source and kind.")
     p_work_import_triage.add_argument("--target", "-t", type=Path, default=Path("."), help="Repo or workspace to inspect.")
     p_work_import_triage.add_argument("--json", action="store_true", help="Print machine-readable JSON.")
@@ -572,6 +590,22 @@ def main(argv=None) -> int:
                     json_output=args.json,
                     limit=args.limit,
                 )
+            if args.import_command == "validate":
+                return work_cmd.import_validate(input_path=args.input_path, json_output=args.json)
+            if args.import_command == "ingest":
+                return work_cmd.import_ingest(
+                    target=args.target,
+                    input_path=args.input_path,
+                    dry_run=args.dry_run,
+                    json_output=args.json,
+                )
+            if args.import_command == "memory-care":
+                return work_cmd.import_memory_care(
+                    target=args.target,
+                    queue=args.queue,
+                    dry_run=args.dry_run,
+                    json_output=args.json,
+                )
             if args.import_command == "triage":
                 return work_cmd.import_triage(target=args.target, json_output=args.json, limit=args.limit)
             if args.import_command == "show":