diff --git a/apps/workspace/src/doctor.rs b/apps/workspace/src/doctor.rs index 952af1cc..9037419c 100644 --- a/apps/workspace/src/doctor.rs +++ b/apps/workspace/src/doctor.rs @@ -86,6 +86,16 @@ fn old_controllers(base: &Path, ws: Option<&Path>, out: &mut Vec) { } } +/// A brief.ts that still keeps tasks in `stages` (docs/plan.feature PL8a): they read, unread, and belong in plan.org. +fn briefs_with_tasks(base: &Path, out: &mut Vec) { + let f = base.join("brief.ts"); + let Ok(text) = std::fs::read_to_string(&f) else { return }; + if text.lines().any(|l| l.trim_start().starts_with("stages:") || l.trim_start().starts_with("\"stages\":")) { + let says = format!("{}: keeps tasks in `stages`, which raea no longer reads; move each to the project's plan.org (an Org heading under its stage, its mark as TODO, DONE or DROPPED), then delete `stages`", f.display()); + out.push(Finding { says, fix: Fix::No }); + } +} + /// The `version:` in a SKILL.md's front matter. fn skill_version(md: &Path) -> Option { let text = std::fs::read_to_string(md).ok()?; @@ -101,6 +111,7 @@ pub fn findings(from: &Path, skills: &[(&str, PathBuf)], version: &str) -> Vec null;\n").unwrap(); std::fs::create_dir_all(d.join("controllers")).unwrap(); std::fs::write(d.join("controllers/pace.ts"), "import { controller } from \"raea/brief\";\nexport default controller({ title: \"Pace\", fields: {} });\n").unwrap(); + std::fs::write(d.join("brief.ts"), "import { brief } from \"raea/brief\";\nexport default brief({\n title: \"Old\",\n stages: [{ name: \"\", tasks: [{ text: \"Write the plan\" }] }],\n});\n").unwrap(); let found = doctor::registry_findings(&d); let says: Vec<&String> = found.iter().map(|f| &f.says).collect(); assert_eq!(found.len(), 1, "{says:?}"); assert!(says[0].contains("loose.tsx:1: isn't a composition") && !found[0].fixable(), "{says:?}"); // a controller from before 11-20 is told where its parts go, and kept let out = doctor::doctor(&["--fix".into(), d.display().to_string()], &[], "0.0.1", &|_| Ok(String::new())).unwrap(); - assert!(out.starts_with("APPLIED 2 of 4 fixed") && out.contains("controllers/pace.ts: a controller, which raea no longer reads") && out.contains("taste.ts"), "{out}"); - assert!(d.join("controllers/pace.ts").is_file(), "nothing of the person's is deleted"); + assert!(out.starts_with("APPLIED 2 of 5 fixed") && out.contains("controllers/pace.ts: a controller, which raea no longer reads") && out.contains("taste.ts"), "{out}"); + // a brief's old tasks are said to belong in plan.org (docs/plan.feature PL8a), and kept + assert!(out.contains("brief.ts: keeps tasks in `stages`") && out.contains("plan.org"), "{out}"); + assert!(d.join("controllers/pace.ts").is_file() && std::fs::read_to_string(d.join("brief.ts")).unwrap().contains("stages"), "nothing of the person's is deleted"); let _ = std::fs::remove_dir_all(&d); } diff --git a/core/brief/src/brief.rs b/core/brief/src/brief.rs index 9e4c3a48..840eaf41 100644 --- a/core/brief/src/brief.rs +++ b/core/brief/src/brief.rs @@ -1,5 +1,6 @@ -//! A project's brief: who it's for, the one thing they should believe, what it delivers and the work to get there. -//! The facts an agent guessed are listed in `assumed`, for the person to confirm. +//! A project's brief: who it's for, the one thing they should believe and what it delivers. The facts an agent guessed +//! are listed in `assumed`, for the person to confirm. Its tasks are in the project's plan.org, not here +//! (docs/plan.feature PL8a). use serde::{Deserialize, Serialize}; use ts_rs::TS; @@ -47,10 +48,11 @@ pub struct Brief { #[serde(default)] #[ts(as = "Option>", optional)] pub references: Vec, - /// the tasks, in stages ("Act one", "The cut") - #[serde(default)] - #[ts(as = "Option>", optional)] - pub stages: Vec, + /// an older brief's tasks, read only so it still loads: they belong in plan.org (docs/plan.feature PL8a), and + /// `raea doctor` says so; never written, and not in the schema an agent writes to + #[serde(default, skip_serializing)] + #[ts(skip)] + pub stages: Option, #[serde(default)] #[ts(as = "Option>", optional)] pub agents: Vec, @@ -88,43 +90,6 @@ pub struct Reference { pub note: Option, } -#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, TS)] -#[serde(deny_unknown_fields)] -pub struct Stage { - pub name: String, - pub tasks: Vec, -} - -#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize, TS)] -#[serde(rename_all = "lowercase")] -pub enum Mark { - #[default] - Todo, - Done, - Dropped, -} - -#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, TS)] -#[serde(rename_all = "camelCase", deny_unknown_fields)] -#[ts(optional_fields)] -pub struct Task { - pub text: String, - /// a task linked to an item takes the item's state (the work is the truth); this is for unlinked ones - #[serde(default)] - #[ts(as = "Option", optional)] - pub mark: Mark, - #[serde(default)] - #[ts(as = "Option>", optional)] - pub agents: Vec, - pub item: Option, - #[serde(default)] - #[ts(as = "Option>", optional)] - pub tags: Vec, - pub due: Option, - /// the craft verb it was written as ("quieter"): agents read it, the page shows the text - pub verb: Option, -} - #[derive(Debug, Clone, PartialEq, Serialize, Deserialize, TS)] #[serde(deny_unknown_fields)] #[ts(optional_fields)] diff --git a/core/brief/src/lib.rs b/core/brief/src/lib.rs index 1af26aa8..af30957d 100644 --- a/core/brief/src/lib.rs +++ b/core/brief/src/lib.rs @@ -1,15 +1,15 @@ //! What an agent writes for raea, as Rust types: a project's brief, a script (storyboard or screenplay), a person's -//! taste and an object's plan. The agent writes them as TypeScript modules (docs/handoff/authoring.md); `raea run` +//! taste and an object's parts. The agent writes them as TypeScript modules (docs/handoff/authoring.md); `raea run` //! evaluates one, and its default export arrives here as JSON. The TypeScript declarations are generated from these //! types (`declarations`), so what tsc checks is exactly what this crate reads. pub mod brief; -pub mod plan; +pub mod parts; pub mod script; pub mod taste; pub use brief::Brief; -pub use plan::Plan; +pub use parts::Parts; pub use script::Script; pub use taste::Taste; @@ -32,10 +32,10 @@ pub fn declarations() -> String { let cfg = Config::new(); let mut out = vec!["// Generated from raea-core-brief (core/brief) by its `declarations`; edit the Rust, not this.".to_string()]; out.extend(decls!(cfg; - brief::Brief, brief::Section, brief::Deliverable, brief::Reference, brief::Stage, brief::Mark, brief::Task, brief::Agent, + brief::Brief, brief::Section, brief::Deliverable, brief::Reference, brief::Agent, script::Script, script::Scene, script::Beat, script::Line, taste::Taste, taste::TasteSection, taste::Rule, taste::RuleCheck, taste::RuleLevel, taste::Check, - plan::Plan, plan::Concept, plan::Level, plan::Count, plan::Part, + parts::Parts, parts::Concept, parts::Level, parts::Count, parts::Part, )); out.join("\n\n") + "\n" } diff --git a/core/brief/src/plan.rs b/core/brief/src/parts.rs similarity index 88% rename from core/brief/src/plan.rs rename to core/brief/src/parts.rs index ce0e288b..eaad09a7 100644 --- a/core/brief/src/plan.rs +++ b/core/brief/src/parts.rs @@ -1,5 +1,6 @@ -//! An object's plan, written before any geometry and frozen when building starts (docs/handoff/solids.md, "The plan -//! is the contract"). Generic over what's made: a crown, a feather and a rocking horse are all a concept and a tree of +//! An object's parts (NAME.parts.ts, `parts()` from "raea/brief"), written before any geometry and frozen when +//! building starts (docs/handoff/solids.md, "The plan is the contract"; named parts since 11-20, so "plan" is only a +//! project's plan.org, docs/plan.feature PL8a). Generic over what's made: a crown, a feather and a rocking horse are all a concept and a tree of //! named parts, each with a level, a count, and a material and style it has or inherits. use std::collections::BTreeMap; @@ -9,7 +10,7 @@ use ts_rs::TS; #[derive(Debug, Clone, PartialEq, Serialize, Deserialize, TS)] #[serde(deny_unknown_fields)] -pub struct Plan { +pub struct Parts { pub concept: Concept, /// by name; the build's parts are typed from these keys, so a planned part the build skips is a tsc error pub parts: BTreeMap, @@ -77,7 +78,7 @@ pub struct Resolved { /// Everything wrong with a plan that would let a build leave something behind: a parent that isn't planned, a loop, /// no root, a range upside down, or a part that resolves to no material. Empty when the plan can be built against. -pub fn check(plan: &Plan) -> Vec { +pub fn check(plan: &Parts) -> Vec { let mut out = Vec::new(); let roots: Vec<&String> = plan.parts.iter().filter(|(_, p)| p.parent.is_none()).map(|(n, _)| n).collect(); if roots.is_empty() { @@ -107,7 +108,7 @@ pub fn check(plan: &Plan) -> Vec { } /// The part and its ancestors, nearest first; none on a loop or a missing parent. -fn chain<'a>(plan: &'a Plan, name: &str) -> Option> { +fn chain<'a>(plan: &'a Parts, name: &str) -> Option> { let mut out = Vec::new(); let mut at = plan.parts.get(name)?; loop { @@ -124,7 +125,7 @@ fn chain<'a>(plan: &'a Plan, name: &str) -> Option> { /// A part's material and style, inherited up its parents to the concept. Style always resolves (the concept has /// one); material may not. -pub fn resolve(plan: &Plan, name: &str) -> Option { +pub fn resolve(plan: &Parts, name: &str) -> Option { let chain = chain(plan, name)?; let material = chain.iter().find_map(|p| p.material.clone()).or_else(|| plan.concept.material.clone())?; let style = chain.iter().find_map(|p| p.style.clone()).unwrap_or_else(|| plan.concept.style.clone()); diff --git a/core/brief/src/tests.rs b/core/brief/src/tests.rs index ce6e06e6..14d289a6 100644 --- a/core/brief/src/tests.rs +++ b/core/brief/src/tests.rs @@ -14,9 +14,7 @@ fn declarations_match_the_committed_file() { #[test] fn a_brief_reads_and_its_doctor_asks_for_what_is_missing() { let b: Brief = read("brief.ts", r#"{"title": "A walkthrough", "mode": ["explain"], "assumed": ["voice"], "voice": "one calm narrator", - "deliver": [{"name": "Walkthrough", "specs": ["60 s", "16:9"]}], - "stages": [{"name": "", "tasks": [{"text": "Storyboard it", "agents": ["director"], "mark": "done"}]}]}"#).unwrap(); - assert_eq!(b.stages[0].tasks[0].mark, brief::Mark::Done); + "deliver": [{"name": "Walkthrough", "specs": ["60 s", "16:9"]}]}"#).unwrap(); let d = brief::doctor(&b); assert!(d.iter().any(|m| m.contains("`believe`")), "{d:?}"); assert!(d.iter().any(|m| m.contains("no script")), "{d:?}"); @@ -68,26 +66,34 @@ fn a_taste_line_holds_any_check_by_name_or_path_with_values_and_a_level() { } #[test] -fn a_plan_leaves_nothing_without_a_material() { - let ok: Plan = read("plan.ts", r#"{"concept": {"what": "flight feather", "style": "realistic", "size": 0.25, "seenFrom": 0.3, "material": "keratin"}, +fn an_objects_parts_leave_nothing_without_a_material() { + let ok: Parts = read("feather.parts.ts", r#"{"concept": {"what": "flight feather", "style": "realistic", "size": 0.25, "seenFrom": 0.3, "material": "keratin"}, "parts": { "rachis": {"role": "shaft", "level": "primary"}, "vane": {"role": "vane", "level": "secondary", "parent": "rachis", "count": 2, "style": "barred brown"}, "barb": {"role": "barb", "level": "tertiary", "parent": "vane", "count": {"min": 300, "max": 500}, "near": "separate barbs, a few split gaps"}}}"#).unwrap(); - assert_eq!(plan::check(&ok), Vec::::new()); - assert_eq!(plan::resolve(&ok, "barb").unwrap(), plan::Resolved { material: "keratin".into(), style: "barred brown".into() }); + assert_eq!(parts::check(&ok), Vec::::new()); + assert_eq!(parts::resolve(&ok, "barb").unwrap(), parts::Resolved { material: "keratin".into(), style: "barred brown".into() }); let mut bad = ok.clone(); bad.concept.material = None; bad.parts.get_mut("rachis").unwrap().parent = Some("calamus".into()); - let e = plan::check(&bad); + let e = parts::check(&bad); assert!(e.iter().any(|m| m.contains("`calamus` isn't planned")), "{e:?}"); assert!(e.iter().any(|m| m.contains("no root")), "{e:?}"); } #[test] fn a_close_view_needs_tertiary_detail() { - let p: Plan = read("plan.ts", r#"{"concept": {"what": "toy rocking horse", "style": "painted wood", "size": 0.9, "seenFrom": 0.5, "material": "beech"}, + let p: Parts = read("horse.parts.ts", r#"{"concept": {"what": "toy rocking horse", "style": "painted wood", "size": 0.9, "seenFrom": 0.5, "material": "beech"}, "parts": {"body": {"role": "body", "level": "primary"}, "rocker": {"role": "rocker", "level": "secondary", "parent": "body", "count": 2}}}"#).unwrap(); - assert!(plan::check(&p).iter().any(|m| m.contains("tertiary"))); + assert!(parts::check(&p).iter().any(|m| m.contains("tertiary"))); +} + +#[test] +fn an_older_brief_with_stages_still_reads_and_never_writes_them() { + let b: Brief = read("brief.ts", r#"{"title": "Old", "stages": [{"name": "", "tasks": [{"text": "Write the plan", "mark": "todo"}]}]}"#).unwrap(); + assert!(b.stages.is_some()); + assert!(!serde_json::to_string(&b).unwrap().contains("stages")); + assert!(!declarations().contains("stages"), "the schema an agent writes has no stages (docs/plan.feature PL8a)"); } diff --git a/docs/manual/concepts/workspaces.md b/docs/manual/concepts/workspaces.md index 5b09a594..5f900b60 100644 --- a/docs/manual/concepts/workspaces.md +++ b/docs/manual/concepts/workspaces.md @@ -56,7 +56,7 @@ raea's specs are TypeScript files whose default export is checked against a sche | `NAME.script.ts` | A storyboard: scenes of beats, what's on screen, what each scene must land | | `~/.raea/taste/taste.ts` | The person's taste, which beats any guide's default | | `taste.ts` | A workspace's or a project's rules, which `raea check` holds every piece to | -| `plan.ts` | A frozen plan for a build, checked by raea | +| `NAME.parts.ts` | An object's parts, frozen before it's built, checked by raea | ```sh raea spec brief.ts # prints the brief as JSON, checked against its schema diff --git a/docs/manual/reference/cli/index.md b/docs/manual/reference/cli/index.md index 648ffdcf..8d361139 100644 --- a/docs/manual/reference/cli/index.md +++ b/docs/manual/reference/cli/index.md @@ -49,7 +49,7 @@ The workspace, its projects and what a project holds. | [`raea init`](init.md) | Add a project's starting files where they're missing: edit.tsx, cuts.ts, components/ and AGENTS.md. | | [`raea workspace`](workspace.md) | Make, adopt or show a workspace: the git repository that holds a studio's projects and house taste. | | [`raea project`](project.md) | Make a project in the workspace, list them, or move one between inline and a repository of its own. | -| [`raea spec`](spec.md) | Print a spec file's default export as JSON, checked against its schema: briefs, scripts, taste and plans. | +| [`raea spec`](spec.md) | Print a spec file's default export as JSON, checked against its schema: briefs, scripts, taste and an object's parts. | | [`raea component`](component.md) | Copy a ready-made component or set into the project's components/, or the workspace's shared/components/, to use and change as your own. | | [`raea part`](part.md) | The old name of raea component: copy a ready-made component into the project's components/, to use and change as your own. | | [`raea add`](add.md) | Add, remove and install npm packages for a project, with no Node or npm: raea.lock and node_modules. | diff --git a/docs/manual/reference/cli/spec.md b/docs/manual/reference/cli/spec.md index eeb1f251..664ecc4b 100644 --- a/docs/manual/reference/cli/spec.md +++ b/docs/manual/reference/cli/spec.md @@ -1,12 +1,12 @@ --- title: "raea spec" -summary: "Print a spec file's default export as JSON, checked against its schema: briefs, scripts, taste and plans." +summary: "Print a spec file's default export as JSON, checked against its schema: briefs, scripts, taste and an object's parts." order: 25 sources: ["engine/cli/src/spec.rs"] --- raea's specs are TypeScript files whose default export is data: `brief.ts`, `NAME.script.ts`, `taste.ts` and -`plan.ts`. `raea spec` evaluates one, checks it against its schema and prints it as JSON, +`NAME.parts.ts`. `raea spec` evaluates one, checks it against its schema and prints it as JSON, so an agent can read a brief without running anything else, and a wrong field is caught before it matters. ```sh @@ -20,7 +20,7 @@ raea spec notes.ts --as taste ## Usage ```sh -raea spec FILE.ts [--as brief|script|taste|plan] (a spec's default export as JSON, checked against its schema: brief.ts, script.ts, taste.ts, plan.ts) +raea spec FILE.ts [--as brief|script|taste|parts] (a spec's default export as JSON, checked against its schema: brief.ts, script.ts, taste.ts, NAME.parts.ts) ``` Headless: it needs nothing running and opens no window. Takes up to 1 argument besides its flags. @@ -29,6 +29,6 @@ Headless: it needs nothing running and opens no window. Takes up to 1 argument b | Flag | Takes | What it does | | --- | --- | --- | -| `--as` | `brief\|script\|taste\|plan` | Which schema to check it against. By default from the file's name (`brief`, `script`, `plan`), and `taste` otherwise. | +| `--as` | `brief\|script\|taste\|parts` | Which schema to check it against. By default from the file's name (`brief`, `script`, `parts`), and `taste` otherwise. | diff --git a/docs/manual/reference/sdk/brief.md b/docs/manual/reference/sdk/brief.md index 954d75f9..9314ab1a 100644 --- a/docs/manual/reference/sdk/brief.md +++ b/docs/manual/reference/sdk/brief.md @@ -1,6 +1,6 @@ --- title: "raea/brief" -summary: "The specs an agent writes as data: brief, script, taste and plan, checked against raea's schemas." +summary: "The specs an agent writes as data: brief, script, taste and an object's parts, checked against raea's schemas." order: 4 sources: ["sdk/raea/src/brief.ts", "core/brief/src"] --- @@ -30,16 +30,17 @@ See [Workspaces and projects](../../concepts/workspaces.md) for where each spec ```ts -import { brief, fingerprint, plan, script } from "raea/brief" +import { brief, fingerprint, parts, script } from "raea/brief" ``` -`raea/brief` exports 5 functions, 27 types. Source: [sdk/raea/src/brief.ts](https://github.com/shinyobjectz/raea/blob/main/sdk/raea/src/brief.ts). +`raea/brief` exports 5 functions, 24 types. Source: [sdk/raea/src/brief.ts](https://github.com/shinyobjectz/raea/blob/main/sdk/raea/src/brief.ts). ## Functions ### `brief` -A project's brief (brief.ts): what to make, for whom, the one thing to believe, its deliverables and staged tasks. +A project's brief (brief.ts): what to make, for whom, the one thing to believe and its deliverables. Its tasks are +the project's plan.org. ```ts function brief(b: Brief): Brief @@ -53,12 +54,12 @@ A fingerprint (fingerprint.ts): its axes and the encoders its heads were trained function fingerprint(f: Fingerprint): Fingerprint ``` -### `plan` +### `parts` -An object's plan (plan.ts): its parts by name, levels, counts, materials. +An object's parts (NAME.parts.ts), written before any geometry: each by name, its level, count and material. ```ts -function plan(p: Plan): Plan +function parts(p: Parts): Parts ``` ### `script` @@ -170,12 +171,6 @@ type Level = "primary" | "secondary" | "tertiary" type Line = { /** * a character, or "narrator" */ who: string, says: string, /** * a screenplay's parenthetical ("quietly") */ how?: string, } ``` -### `Mark` - -```ts -type Mark = "todo" | "done" | "dropped" -``` - ### `Modality` What an axis's head reads: the frames (SigLIP 2), how they change, their look, the sound (CLAP) or its events (YAMNet). @@ -190,10 +185,10 @@ type Modality = "picture" | "change" | "look" | "sound" | "events" | "text" type Part = { /** * the label it carries into the world ("seat", "leaf", "gem") */ role: string, level: Level, /** * the part it sits on or in; none for the root */ parent?: string, count?: Count, /** * its own, else its parent's, else the concept's */ material?: string, style?: string, /** * what a near cro… ``` -### `Plan` +### `Parts` ```ts -type Plan = { concept: Concept, /** * by name; the build's parts are typed from these keys, so a planned part the build skips is a tsc error */ parts: { [key in string]: Part }, } +type Parts = { concept: Concept, /** * by name; the build's parts are typed from these keys, so a planned part the build skips is a tsc error */ parts: { [key in string]: Part }, } ``` ### `Reference` @@ -238,18 +233,6 @@ type Script = { title: string, logline?: string, scenes: Array, } type Section = { heading: string, text: string, } ``` -### `Stage` - -```ts -type Stage = { name: string, tasks: Array, } -``` - -### `Task` - -```ts -type Task = { text: string, /** * a task linked to an item takes the item's state (the work is the truth); this is for unlinked ones */ mark?: Mark, agents?: Array, item?: string, tags?: Array, due?: string, /** * the craft verb it was written as ("quieter"): agents read it, the page shows th… -``` - ### `Taste` ```ts diff --git a/docs/manual/reference/sdk/index.md b/docs/manual/reference/sdk/index.md index 71488223..1ad8240d 100644 --- a/docs/manual/reference/sdk/index.md +++ b/docs/manual/reference/sdk/index.md @@ -33,7 +33,7 @@ The composition, the app, and the specs and notes an agent writes. | --- | --- | --- | | [`raea`](raea.md) | The main entry: compositions, sequences, time, interpolation, springs, footage, sound and words. | 20 components, 9 hooks, 62 functions, 11 values, 107 types | | [`raea/app`](app.md) | The App, its plugins and schedules, and the registry a video's compositions are kept in. | 1 component, 1 hook, 4 functions, 3 classes, 17 values, 17 types | -| [`raea/brief`](brief.md) | The specs an agent writes as data: brief, script, taste and plan, checked against raea's schemas. | 5 functions, 27 types | +| [`raea/brief`](brief.md) | The specs an agent writes as data: brief, script, taste and an object's parts, checked against raea's schemas. | 5 functions, 24 types | | [`raea/note`](note.md) | A person's note as a file in the project: their words kept as written, and the asks the agent restates it as. | 1 function, 4 types | ## Time and motion diff --git a/docs/plan.feature b/docs/plan.feature index d8099ae8..f4774c78 100644 --- a/docs/plan.feature +++ b/docs/plan.feature @@ -21,7 +21,7 @@ Feature: Plans: a project's plan.org, kept by its agents # src/plan/agent.test.ts driving a turn's plan tools end to end on a faked host; tsc -b clean; e2e todo.spec.ts and # outside.spec.ts (7) and messages, primary, heads, consolidate (26) in Chrome; todo.spec.ts (4) and outside.spec.ts # (3) in raea's window (BLITZ_E2E bundle, node blitz/pw-run.mjs). The board (feed/Board.tsx, board/Lanes.tsx, - # board/CardSheet.tsx) reads the plan now, but no route mounts it. Not done: `raea project new` writes no plan.org yet + # board/CardSheet.tsx), which no route mounted, was removed with PL8: the to-do list is the plan's one view. Not done: `raea project new` writes no plan.org yet # (Rust, engine/cli), so reference/files.md, generated from it, doesn't list one; the page makes it on the first # write. The brief page (BriefView, unmounted) still draws a brief's own ## Tasks. Compositions can't import # @raea/task until sdk/tsconfig.base.json and raea's bundler map it. @@ -140,8 +140,8 @@ Feature: Plans: a project's plan.org, kept by its agents waits on; a critique's gate is " passes check and critique" with :ITEM: the newest critique And an item carries the tags of the tasks linked to it, a workflow field places a channel by its plan's tasks, and a session outside raea holds the tasks whose :AGENT: is @its-name or its inbox - And the board (feed/Board.tsx, board/Lanes.tsx, board/CardSheet.tsx) reads and edits the plan the same way, by - task id; no route mounts it yet + And the to-do list (feed/TodoPanel.tsx) reads and edits the plan the same way, by task id (the board that did + too, never mounted, went with PL8) @done Scenario: PL4c. A brief's tasks move into the plan once @@ -203,6 +203,8 @@ Feature: Plans: a project's plan.org, kept by its agents And none of it uses a dynamic import or dangerouslySetInnerHTML, so raea's window bundle (one IIFE) holds it Rule: PL7. An agent finishes what it planned + # 11-20 (PL8): the keeper's asks (PL7a, PL7b, PL7c, PL7f) are gone. Closing follows the work instead (PL8c), and the + # task per message and the starter task that filled plans with tasks nobody closed are gone too. PL7d and PL7e stay. # Shane, 2026-11-16: "i notice often that it makes tasks but never completes them itself". His plans that morning: # TarotChess's agent posted a first pass and left its own follow-ups TODO (frame rate, a clipping score, a dark # encode); Cadence's said "all six masters are finished and posted" over a plan still saying Track MAKING and Build, @@ -258,3 +260,67 @@ Feature: Plans: a project's plan.org, kept by its agents And over the composer, while it asks or after it pauses with tasks open, one line: "Plan 3 of its tasks open", "Finishing · ask 2" with × to stop asking until the next message, or "Paused · Continue" with why on hover + Rule: PL8. One way to keep work, and any tracker beside it + # Shane, 2026-11-20: "we continually in the desktop app get issues with tasks and starting or adding tasks and it + # never actually closes any out. so maybe we should align plan to be simpler", then "make sure the project management + # structure is clear dry and we dont have competing methods", and "the planning api will need to be able to easily + # sync and extend to whatever system enterprise clients use so we dont want to be too opinionated about planning as + # long as its consistent and fixable by the agent itself too". Read 11-20 in his workspaces: plans kept by an agent in + # a terminal close their tasks (gambit 82 of 133, driveeasier 13 of 13, castle-busters 11 of 13); plans made in the + # app don't (ten new projects hold only the app's own "Write the plan", open; p-pong 0 of 5), with PL7's keeper + # installed. Tasks were written in four places (brief.ts stages, the composer's task per message, the starter task, + # the agents' plan tools) and closed in one: an agent remembering to. Agreed with raea cloud (11-20), whose + # agents keep their projects in plan.org on @raea/task and start them from Asana, Linear, Jira and other boards. + + @done + Scenario: PL8a. plan.org is the one list + # core/brief (brief.rs, parts.rs, tests.rs), apps/workspace doctor.rs, the app's src/brief/spec.ts and format.ts + Then a project's tasks are in its plan.org and nowhere else: brief.ts says what to make (core/brief's Brief has no + stages or tasks), and a brief that still has them reads, its tasks unread, with `raea doctor` saying they + belong in plan.org + And the app's brief writer (src/brief/spec.ts) writes no stages, its starter brief has no ## Tasks, and a brief + that has them moves them into the plan once (PL4c, as before) + And core/brief's object plan, which was also called a plan, is `parts()` in NAME.parts.ts (`raea spec --as parts`) + + @done + Scenario: PL8b. A message is a message, not a task + # the app's src/plan/turn.ts and plan.test.ts; e2e/chat-plan.spec.ts in raea's window + Then the composer writes no task for a message sent: an agent plans tasks when the work is more than its turn + (the skill's plan.md), and the person adds their own in the to-do list + And a new project's plan starts empty, with no "Write the plan" task + + @done + Scenario: PL8c. Closing follows the work + Given a task linked to an item (:ITEM:) + When the person approves that item, or any version of it + Then the task closes DONE, stamped CLOSED, by the person, with no agent asked + And where an open task stands (making, waiting on the person) is read from its item and from a session at work + on it, as the to-do list already shows it (plan/words.ts standing), never from a keyword an agent must remember + to set + And it's checked in the app: src/plan/approve.test.ts, and e2e/todo.spec.ts in raea's window (checking off a + task on an item writes that task DONE) + + @done + Scenario: PL8d. The keywords are the file's + # sdk/task newPlan (test/trackers.test.ts); the app's src/plan/keywords.ts and host/plan.test.ts + Then a plan's #+TODO: lines are its keywords and Org's | says which close a task; raea reads any sequence that way + And a plan the app makes keeps TODO | DONE DROPPED; raea cloud's TODO MAKING REVIEW | DONE DROPPED and a client's + own words read the same, and newPlan(title, keywords) takes the sequence its caller keeps + + @done + Scenario: PL8e. A task kept in step with another tracker + # sdk/task src/trackers.ts; test/trackers.test.ts (with a raea cloud plan.org that passes checkPlan unflagged). + Then a task names its items in other trackers with one property, :LINK: linear:ENG-12 asana:1209876543 (each the + tracker's own key, never a URL; one per system), and the head maps each system's statuses to keywords, one line + a system: #+LINK_STATES: linear In Progress=MAKING; In Review=REVIEW; Done=DONE + And keywordFor(plan, system, status) is a status coming in and statusFor(plan, system, keyword) the status written + back (the first one listed for the keyword), so a sync needs a mapping, not code per client + And trackersOf(task) and trackerStates(plan) read them for a sync or a trigger's match + + @done + Scenario: PL8f. An agent can fix its own plan + Then checkPlan says each problem with its fix: an id on two tasks, a :LINK: entry that isn't SYSTEM:ID or is a + URL, a system named twice on one task, one tracker item on two tasks, a #+LINK_STATES: keyword the plan doesn't + know, and a plugin's kinds and properties (PL6) + And nothing else is required: no :ID:, no keyword on a heading, no property, so headings that group, hold notes or + hold a cloud agent's settings are never flagged diff --git a/engine/cli/src/cli.rs b/engine/cli/src/cli.rs index 52c1bb18..69c72658 100644 --- a/engine/cli/src/cli.rs +++ b/engine/cli/src/cli.rs @@ -143,7 +143,7 @@ pub fn run(args: &[String]) -> R<String> { // an agent's report of a bug in raea itself, to raea's server (engine/cli/src/bug.ts; Shane 11-16) let usage = format!("{usage}\n raea bug TITLE... --text TEXT [--command CMD] [--error TEXT] [--agent NAME] [--dry-run] (a bug in raea itself, not in your own composition, sent to raea's server with raea's version and the OS, no account needed: words only, paths, emails and keys taken out before it goes; five a day from a machine, the same bug again counted on the first report; --dry-run prints what would go and sends nothing)"); // a workspace's files and specs (docs/projects.feature), listed under render's usage like library - let usage = format!("{usage}\n raea spec FILE.ts [--as brief|script|taste|plan] (a spec's default export as JSON, checked against its schema: brief.ts, script.ts, taste.ts, plan.ts)\n raea workspace init [NAME] [--layout LAYOUT] | raea workspace adopt DIR [--name NAME] | raea workspace [--json] (a workspace: a git repo of projects under raea.root, ~/Documents/raea unless git config says)\n raea project new NAME [--storage inline|submodule] | raea project split NAME [--remote URL] | raea project join NAME | raea project [--json] (a project in the workspace: its folder, brief.ts, media/, out/; split and join keep its history)\n raea check EDIT.tsx --quick [--shape S] [--platform P] [--taste T] [-o check.json] (three stills of a composition checked for text: clipped, cramped, safe areas, sizes; about a second)\n raea hook [claude|codex|gemini|kimi] (every agent's tool hooks, which raea skills install adds: before a shell command, media opened in the Mac's viewer while the raea app is installed is stopped once for raea show (the same command again goes through); after a save, the quick check on a composition)\n raea next [DIR] (the two or three useful next steps for the project, from its brief, compositions, renders and checks)\n raea doctor [--fix] [DIR] (what doesn't match this raea: old brief files, an older workspace format, an agent's skill from another version)\n raea app run|check|bundle APP.tsx [--target web|native] [--size WxH] [--script steps.json] [--png DIR] [-o App.app] (a TSX app on @raea/ui: its window, the headless check, a Mac app; web is Blitz on Bevy, native is Rune; the app's `export const app` sets the target, web when it doesn't; raea rune ... is --target native)\n {}\n {}\n {} ({})\n {}\n {}\n {}", skill::USAGE, tools::blender::USAGE, tools::motion::SETUP_USAGE, tools::motion::SETUP_ABOUT, raea_app_engines::godot::USAGE, raea_app_engines::shot::USAGE, raea_app_engines::round::USAGE); + let usage = format!("{usage}\n raea spec FILE.ts [--as brief|script|taste|parts] (a spec's default export as JSON, checked against its schema: brief.ts, script.ts, taste.ts, NAME.parts.ts)\n raea workspace init [NAME] [--layout LAYOUT] | raea workspace adopt DIR [--name NAME] | raea workspace [--json] (a workspace: a git repo of projects under raea.root, ~/Documents/raea unless git config says)\n raea project new NAME [--storage inline|submodule] | raea project split NAME [--remote URL] | raea project join NAME | raea project [--json] (a project in the workspace: its folder, brief.ts, media/, out/; split and join keep its history)\n raea check EDIT.tsx --quick [--shape S] [--platform P] [--taste T] [-o check.json] (three stills of a composition checked for text: clipped, cramped, safe areas, sizes; about a second)\n raea hook [claude|codex|gemini|kimi] (every agent's tool hooks, which raea skills install adds: before a shell command, media opened in the Mac's viewer while the raea app is installed is stopped once for raea show (the same command again goes through); after a save, the quick check on a composition)\n raea next [DIR] (the two or three useful next steps for the project, from its brief, compositions, renders and checks)\n raea doctor [--fix] [DIR] (what doesn't match this raea: old brief files, an older workspace format, an agent's skill from another version)\n raea app run|check|bundle APP.tsx [--target web|native] [--size WxH] [--script steps.json] [--png DIR] [-o App.app] (a TSX app on @raea/ui: its window, the headless check, a Mac app; web is Blitz on Bevy, native is Rune; the app's `export const app` sets the target, web when it doesn't; raea rune ... is --target native)\n {}\n {}\n {} ({})\n {}\n {}\n {}", skill::USAGE, tools::blender::USAGE, tools::motion::SETUP_USAGE, tools::motion::SETUP_ABOUT, raea_app_engines::godot::USAGE, raea_app_engines::shot::USAGE, raea_app_engines::round::USAGE); let (export_game, capcut, layers, xml, scene, physics, splat, wear) = (raea_app_game::USAGE, raea_app_capcut::USAGE, raea_app_layers::USAGE, raea_app_layers::USAGE_XML, export::SCENE_USAGE, motion::physics::USAGE, tools::splat::USAGE, raea_runtime_wear::USAGE); let apps = format!(" {}\n {}\n {}\n {}\n {}\n {}\n {}\n {}\n {}\n", raea_app_direction::check::USAGE, raea_app_check::USAGE, raea_app_solid::USAGE, raea_app_judge::USAGE, raea_app_direction::USAGE, raea_app_direction::findings::USAGE, raea_app_notes::USAGE, raea_app_fingerprint::USAGE, raea_sys_index::cli::USAGE); return Ok(format!("raea: renders, plays and checks raea compositions (React and TypeScript) on the GPU.\n\nusage: {usage}\n raea init (a project's files where they're missing: edit.tsx, cuts.ts, components/, AGENTS.md)\n raea cut TAKE \"line\" ... | --at A-B ... [--append] (cuts.ts and words.json: a take under media/ cut in the pauses around each line it says, transcribed first if it has no TAKE.words.json; or at those seconds)\n raea frame TAKE [--at S] (how a take fits the edit: a talking take for <FaceFrame>, a screen for <ScreenFit>, from where its face is)\n raea component list | raea component add NAME ... [--shared] [--force] | raea part list | raea part add NAME ... [--shared] [--force] (a ready component or set copied into components/, or the workspace's shared/components/ with --shared, yours to change; raea part is its old name)\n raea brand DOMAIN|URL (the brand kit read from its website on this machine: brand/brand.css, brand/brand.json, BRAND.md, logos in media/brand; says when a plain fetch saw too little)\n raea guide [NAME] (craft, the floor read before any edit; the modes: pitch, explain, story, play, tool; motion, music, layout and the rest; bevy and bevy/NAME for 3D)\n raea context PROJECT (what to read before working on a project: taste, brief, look, the floor and its modes' guides)\n{apps} raea play EDIT.tsx [--input | --input-script KEYS.json] [--size WxH] [--seconds N|end] (a game, live; also: --input-log FILE --offscreen --snapshot T FILE --json FILE --seek F FILE --pick X,Y --view YAW,PITCH,DISTANCE --scrub N --baked --autoplay --no-vsync --master --3d)\n {export_game} (a game as a program of its own: a Mac app or a command)\n {capcut}\n {layers}\n {xml}\n {scene} (what each 3D part rests on: floating, sunk and clipping parts; light: the scene's lighting)\n {physics} (the bakes <Physics> and <Goo> make)\n {wear} (a .glb's weathering causes for raea/wear: the model with a second UV set and its cause maps, made once in the asset store)\n {splat} (footage trained into a Gaussian splat for <Splat>; setup installs its tools)\n raea run SCRIPT.ts (a TypeScript program on the engine, headless: its default export is called, what it prints is the answer; a check like a room's checkLayout; also: --timeout S)\n raea gen image|video|music|sfx|speech|mesh|text \"PROMPT\" | gen plan|run FLOW.ts|FLOW.json | gen comfy import|export|run|schema FILE | gen models | gen balance (generated media through made.app, fal, Replicate, OpenRouter, Modal or ComfyUI; ComfyUI workflows both ways: raea gen alone lists its flags)\n {neural_usage} (DLSS 5 neural rendering on a `render --aov` folder, with its motion and depth: your own MLX-DLSS build and weights, RAEA_MLXDLSS and RAEA_DLSS_MODEL)\n {light_usage} (each scene on each light path against its path-traced reference: distance in stops, the worst tile, a moving shot's flicker, a frame's cost; DIR/report.json)\n raea mezz [--check] PATH... (an intra-only ProRes copy of each long-GOP source over 1080p, for smooth scrubbing; --check says which would get one)\n raea traces [show [N|last|DIR]] (the sessions raea left, newest first: how each ended, its glitches; show tells one in full)")); diff --git a/engine/cli/src/spec.rs b/engine/cli/src/spec.rs index 40255d73..a5149046 100644 --- a/engine/cli/src/spec.rs +++ b/engine/cli/src/spec.rs @@ -1,5 +1,5 @@ //! Specs written in TypeScript (docs/handoff/authoring.md, docs/projects.feature PJ0): brief.ts, script.ts, taste.ts -//! and plan.ts. A spec is a module whose default export is data; the engine evaluates it headless +//! and NAME.parts.ts (an object's parts). A spec is a module whose default export is data; the engine evaluates it headless //! (bundle_module with PRINT_DEFAULT, run_bundle) and Rust reads the JSON against the schema in core/brief, so tsc's errors come first and //! these come second, naming the field. use super::*; @@ -89,14 +89,14 @@ pub fn tastes_ts(args: &[String]) -> R<Vec<schema::Taste>> { } /// `raea spec FILE.ts [--as KIND]`: the default export as JSON, checked as KIND (by default from the file's name: -/// brief, script, taste or plan in it; anything else is checked as Taste, the files in +/// brief, script, taste or parts in it; anything else is checked as Taste, the files in /// ~/.raea/taste being named for their kind). pub fn spec_cli(args: &[String]) -> R<String> { - const USAGE: &str = "usage: raea spec FILE.ts [--as brief|script|taste|plan]"; + const USAGE: &str = "usage: raea spec FILE.ts [--as brief|script|taste|parts]"; let file = args.iter().enumerate().find(|(i, a)| !a.starts_with("--") && (*i == 0 || args[i - 1] != "--as")).map(|(_, a)| PathBuf::from(a)).ok_or(USAGE)?; let kind = args.iter().position(|a| a == "--as").and_then(|i| args.get(i + 1)).cloned().unwrap_or_else(|| { let base = file.file_name().map(|n| n.to_string_lossy().to_lowercase()).unwrap_or_default(); - ["brief", "script", "plan"].iter().find(|k| base.contains(*k)).map(|k| k.to_string()).unwrap_or_else(|| "taste".into()) + ["brief", "script", "parts"].iter().find(|k| base.contains(*k)).map(|k| k.to_string()).unwrap_or_else(|| "taste".into()) }); let json = spec_json(&file)?; let name = file.file_name().map(|n| n.to_string_lossy().into_owned()).unwrap_or_default(); @@ -104,8 +104,8 @@ pub fn spec_cli(args: &[String]) -> R<String> { "brief" => serde_json::to_value(schema::read::<schema::Brief>(&name, &json)?), "script" => serde_json::to_value(schema::read::<schema::Script>(&name, &json)?), "taste" => serde_json::to_value(schema::read::<schema::Taste>(&name, &json)?), - "plan" => serde_json::to_value(schema::read::<schema::Plan>(&name, &json)?), - k => return Err(format!("raea spec can't check a {k:?}: brief, script, taste or plan\n{USAGE}")), + "parts" => serde_json::to_value(schema::read::<schema::Parts>(&name, &json)?), + k => return Err(format!("raea spec can't check a {k:?}: brief, script, taste or parts\n{USAGE}")), } .map_err(|e| e.to_string())?; Ok(value.to_string()) diff --git a/sdk/guides/craft/bevy/prompts.md b/sdk/guides/craft/bevy/prompts.md index 4cb0c230..ad6f8231 100644 --- a/sdk/guides/craft/bevy/prompts.md +++ b/sdk/guides/craft/bevy/prompts.md @@ -20,7 +20,7 @@ Where these texts come from: the published Blender + Claude workflows. ## What to do -1. Write the brief from the template (section 1). Write a `plan.ts` for every hero object. +1. Write the brief from the template (section 1). Write a `NAME.parts.ts` for every hero object. 2. Start the builder with the builder prompt (section 2), filled from the brief. 3. After every stage and every fix, run step R: the review sheets, then the judge prompt (section 3) in a new context and `raea judge` on the same sheets. @@ -29,7 +29,7 @@ Where these texts come from: the published Blender + Claude workflows. The brief is data, in three files: - `brief.ts` for the scene, made with `brief()` from `raea/brief`. -- A `plan.ts` for each hero object, made with `plan()`. +- A `NAME.parts.ts` for each hero object, made with `parts()`. - For an interior, the room plan that `checkLayout` reads (`raea/room`). Fields that have no schema yet go in `sections` as text. @@ -72,12 +72,12 @@ Each generated object needs a reference picture made from this template: > light, plain pale grey seamless background, the whole object in frame with margin, three-quarter view from slightly > above, sharp focus, no people, no text, no brand names, no logos. -Each hero object gets a plan. Its fields are the frozen contract that `raea solid info --expect` and the judge check +Each hero object gets its parts (NAME.parts.ts). Its fields are the frozen contract that `raea solid info --expect` and the judge check against: ```ts -import { plan } from "raea/brief"; -export default plan({ +import { parts } from "raea/brief"; +export default parts({ concept: { what: "coin-op tumble dryer, stacked pair", style: "worn 1990s commercial", size: 1.9, seenFrom: 1.2, material: "enamelled steel" }, parts: { @@ -104,7 +104,7 @@ finished scene must read as the same place, the same objects and the same light. invent in the same world. brief.ts notDoing is a hard list: add nothing on it, and nothing the brief doesn't name. ORDER OF WORK (one stage at a time; a stage that fails its check is fixed before the next one starts) -0. Plan. Every object row in brief.ts has a route, a real size and, for each hero, a plan.ts with its part tree and +0. Plan. Every object row in brief.ts has a route, a real size and, for each hero, a NAME.parts.ts with its part tree and connection map. If any is missing, write it first, from how the real thing is built: look up the real product. 1. Space. Block the room as boxes at real size. Place furniture with place() from raea/3d (on, against, beside, near, apart, facing, align, clear), never typed coordinates; its `found` must be empty. Check: `raea run checks.ts` diff --git a/sdk/guides/craft/bevy/scenes.md b/sdk/guides/craft/bevy/scenes.md index 0713d00a..b066141d 100644 --- a/sdk/guides/craft/bevy/scenes.md +++ b/sdk/guides/craft/bevy/scenes.md @@ -28,7 +28,7 @@ The brief template, the builder prompt and the judge prompt to paste are in `bev - Printed matter. - Motion. - Budget: generation cents and judge rounds. -- Each hero object gets a `plan.ts` (`plan()`) with its concept (what, style, size, seenFrom, material) and parts, each +- Each hero object gets a `NAME.parts.ts` (`parts()`) with its concept (what, style, size, seenFrom, material) and parts, each with a role, a level (primary, secondary, tertiary), a parent, a count and `near` detail. Below it, add a connection map with one line per joint: `door <-> cabinet hinge side touches`. - Write the plan from how the real thing is built: look up the product, the catalogue or a drawing. @@ -65,7 +65,7 @@ check names a script (`bevy/blender`). It never places, lights, frames, material ### 3. Build, one stage at a time; a stage that fails its check is fixed first -0. **Plan.** Every object row has a route and a real size, and every hero has a `plan.ts`. +0. **Plan.** Every object row has a route and a real size, and every hero has a `NAME.parts.ts`. 1. **Space.** Block the room as boxes at real size. Place furniture by relations, not typed coordinates: `place({ room, objects, rules })` from raea/3d. Rules are `on`, `against` a wall, `beside`, `near`, `apart`, `facing`, `align` and `clear` (floor kept free in front). It returns each object's `center`, `base` and `yaw`, diff --git a/sdk/raea/src/brief.gen.ts b/sdk/raea/src/brief.gen.ts index 08e977a9..8025909e 100644 --- a/sdk/raea/src/brief.gen.ts +++ b/sdk/raea/src/brief.gen.ts @@ -40,11 +40,7 @@ assumed?: Array<string>, /** * prose sections beyond the fields above (Goal, Background), in order */ -sections?: Array<Section>, deliver?: Array<Deliverable>, references?: Array<Reference>, -/** - * the tasks, in stages ("Act one", "The cut") - */ -stages?: Array<Stage>, agents?: Array<Agent>, }; +sections?: Array<Section>, deliver?: Array<Deliverable>, references?: Array<Reference>, agents?: Array<Agent>, }; export type Section = { heading: string, text: string, }; @@ -68,20 +64,6 @@ script?: string, }; export type Reference = { target: string, note?: string, }; -export type Stage = { name: string, tasks: Array<Task>, }; - -export type Mark = "todo" | "done" | "dropped"; - -export type Task = { text: string, -/** - * a task linked to an item takes the item's state (the work is the truth); this is for unlinked ones - */ -mark?: Mark, agents?: Array<string>, item?: string, tags?: Array<string>, due?: string, -/** - * the craft verb it was written as ("quieter"): agents read it, the page shows the text - */ -verb?: string, }; - export type Agent = { name: string, role?: string, }; export type Script = { title: string, logline?: string, scenes: Array<Scene>, }; @@ -161,7 +143,7 @@ export type RuleLevel = "error" | "warn" | "note"; export type Check = { "form": "text-hold", "value": number } | { "form": "text-above", "value": number } | { "form": "text-below", "value": number } | { "form": "text-margin", "value": number } | { "form": "loudness", "value": number } | { "form": "still-max", "value": number }; -export type Plan = { concept: Concept, +export type Parts = { concept: Concept, /** * by name; the build's parts are typed from these keys, so a planned part the build skips is a tsc error */ diff --git a/sdk/raea/src/brief.ts b/sdk/raea/src/brief.ts index 3819766c..3b08a790 100644 --- a/sdk/raea/src/brief.ts +++ b/sdk/raea/src/brief.ts @@ -7,13 +7,14 @@ // // The types are generated from the Rust schemas (core/brief, raea-core-brief) into brief.gen.ts, so what tsc checks is // what raea reads: `raea context` evaluates the module and Rust validates its default export again. -import type { Brief, Plan, Script, Taste } from "./brief.gen"; +import type { Brief, Parts, Script, Taste } from "./brief.gen"; export type * from "./brief.gen"; export { fingerprint } from "./fingerprint"; export type { Applies, Axis, Fingerprint, Modality } from "./fingerprint"; -/** A project's brief (brief.ts): what to make, for whom, the one thing to believe, its deliverables and staged tasks. */ +/** A project's brief (brief.ts): what to make, for whom, the one thing to believe and its deliverables. Its tasks are + * the project's plan.org (docs/plan.feature PL8a). */ export const brief = (b: Brief): Brief => b; /** A storyboard or a screenplay (script.ts): scenes, beats, lines, camera and cut. */ export const script = (s: Script): Script => s; @@ -22,5 +23,5 @@ export const script = (s: Script): Script => s; * (`"loudness"`), or the project's own by its path from this file (`"../checks/clear.ts"`), with its `values`. * `raea check` runs every one that applies. */ export const taste = (t: Taste): Taste => t; -/** An object's plan (plan.ts): its parts by name, levels, counts, materials. */ -export const plan = (p: Plan): Plan => p; +/** An object's parts (NAME.parts.ts), written before any geometry: each by name, its level, count and material. */ +export const parts = (p: Parts): Parts => p; diff --git a/sdk/task/src/edit.ts b/sdk/task/src/edit.ts index db0c2b9c..b3ce1688 100644 --- a/sdk/task/src/edit.ts +++ b/sdk/task/src/edit.ts @@ -65,7 +65,9 @@ export const tagOf = (s: string) => s.trim().replace(/^[#:]+/, "").replace(/[^\p export const toggled = (t: { ref: string; state?: State }): PlanEdit => ({ op: "state", ref: t.ref, state: isClosed(t.state) ? "todo" : "done" }) /** A new project's plan: its title, and raea's keywords spelled out for Emacs and any other Org reader. */ -export const newPlan = (title: string) => `#+TITLE: ${title.replace(/\s+/g, " ").trim()}\n#+TODO: TODO MAKING REVIEW | DONE DROPPED\n\n` +/** A new plan.org's text. `keywords` is its #+TODO: sequence: raea's whole one unless the caller keeps fewer (the app + * keeps TODO | DONE DROPPED: where a linked task stands is its item's, PL8). */ +export const newPlan = (title: string, keywords = "TODO MAKING REVIEW | DONE DROPPED") => `#+TITLE: ${title.replace(/\s+/g, " ").trim()}\n#+TODO: ${keywords}\n\n` const oneLine = (s: string) => s.replace(/\s+/g, " ").trim() const propOf = (s: Section, key: string) => s.props?.find(([k]) => k.toUpperCase() === key)?.[1] diff --git a/sdk/task/src/extend.ts b/sdk/task/src/extend.ts index 7368b338..0cd1ad8b 100644 --- a/sdk/task/src/extend.ts +++ b/sdk/task/src/extend.ts @@ -4,6 +4,7 @@ // (TODO MAKING REVIEW | DONE DROPPED), its properties and its views are in every registry from the start. import type { TaskFields } from "./edit.ts" import type { Plan, State, Task } from "./model.ts" +import { trackerProblems } from "./trackers.ts" import { agenda, board, outline } from "./views.ts" export const STATES: readonly State[] = ["todo", "making", "review", "done", "dropped"] @@ -127,7 +128,9 @@ export interface Diagnostic { } /** What is wrong in a plan by the registry's rules: ids used twice, properties that fail their check, kinds nobody - * defined, a kind's missing properties, keywords outside a kind's sequence, and the kinds' own checks. */ + * defined, a kind's missing properties, keywords outside a kind's sequence, the kinds' own checks, and its links to + * other trackers (trackers.ts: an entry that isn't SYSTEM:ID, one tracker item on two tasks, a #+LINK_STATES: + * keyword the plan doesn't know). Nothing else is required: no :ID:, no keyword on a heading, no property. */ export function checkPlan(plan: Plan, reg: PlanRegistry = plans): Diagnostic[] { const out: Diagnostic[] = [] const seen = new Map<string, Task>() @@ -153,5 +156,6 @@ export function checkPlan(plan: Plan, reg: PlanRegistry = plans): Diagnostic[] { const why = kind.check?.(t, plan) if (why) say(why) } + for (const p of trackerProblems(plan)) out.push({ ref: p.task?.ref ?? "head", line: p.task?.line ?? p.line ?? 0, severity: "error", message: p.message }) return out } diff --git a/sdk/task/src/index.ts b/sdk/task/src/index.ts index 2a40d5a3..65f0028c 100644 --- a/sdk/task/src/index.ts +++ b/sdk/task/src/index.ts @@ -9,3 +9,4 @@ export { checkPlan, createRegistry, defineKeywords, definePlanKind, defineProper export { agenda, board, outline, type Agenda, type AgendaDay, type Lane, type OutlineNode } from "./views.ts" export { planDigest, taskLine } from "./digest.ts" export { answerPlanTool, PLAN_TOOLS, planToolEdits, type NewTaskInput, type PlanTool, type PlanToolHost, type TaskChange } from "./tools.ts" +export { keywordFor, statusFor, trackerStates, trackersOf, type Tracker, type TrackerStates } from "./trackers.ts" diff --git a/sdk/task/src/trackers.ts b/sdk/task/src/trackers.ts new file mode 100644 index 00000000..e7c41976 --- /dev/null +++ b/sdk/task/src/trackers.ts @@ -0,0 +1,99 @@ +// A task kept in step with another tracker (Asana, Linear, Jira, ...: raea cloud's board triggers, a client's own +// system), with no code per client: the file says it all (docs/plan.feature PL8). +// :LINK: linear:ENG-12 asana:1209876543 on a task: one SYSTEM:ID per system, the tracker's own key, never a URL +// #+LINK_STATES: linear In Progress=MAKING; In Review=REVIEW; Done=DONE in the head: one line per system +// A status comes in as its keyword (trimmed, any case); a keyword goes out as the FIRST status the line lists for it. +import type { Plan, Task } from "./model.ts" + +export interface Tracker { + system: string + id: string +} + +export interface TrackerStates { + /** a status (lower case, trimmed) to its keyword */ + toKeyword: Map<string, string> + /** a keyword to the first status listed for it, as written */ + toStatus: Map<string, string> +} + +const SYSTEM = /^[a-z0-9][a-z0-9-]*$/ +const STATES_LINE = /^[ \t]*#\+LINK_STATES:[ \t]*(\S+)[ \t]*(.*)$/i + +/** One :LINK: entry, or why it isn't one. */ +function entry(s: string): Tracker | string { + const at = s.indexOf(":") + const system = at > 0 ? s.slice(0, at) : "" + const id = at > 0 ? s.slice(at + 1) : "" + if (!SYSTEM.test(system) || !id) return `"${s}" isn't SYSTEM:ID (linear:ENG-12)` + if (/^\/\/|^https?:/i.test(id) || /^https?$/.test(system)) return `"${s}" is a URL; :LINK: takes the tracker's own key, the URL goes in the task's text` + return { system, id } +} + +/** The trackers a task is kept in step with, in the order its :LINK: names them (what isn't SYSTEM:ID is left out). */ +export function trackersOf(task: Task): Tracker[] { + return (task.props.LINK ?? "").split(/\s+/).filter(Boolean).map(entry).filter((e): e is Tracker => typeof e !== "string") +} + +/** Each system's status map, from the head's #+LINK_STATES: lines. */ +export function trackerStates(plan: Plan): Map<string, TrackerStates> { + const out = new Map<string, TrackerStates>() + for (const line of plan.doc.head) { + const m = STATES_LINE.exec(line) + if (!m) continue + const system = m[1].toLowerCase() + const s = out.get(system) ?? { toKeyword: new Map(), toStatus: new Map() } + for (const pair of m[2].split(";")) { + const eq = pair.lastIndexOf("=") + const status = pair.slice(0, eq).trim() + const keyword = pair.slice(eq + 1).trim() + if (eq < 0 || !status || !keyword) continue + s.toKeyword.set(status.toLowerCase(), keyword) + if (!s.toStatus.has(keyword)) s.toStatus.set(keyword, status) + } + out.set(system, s) + } + return out +} + +/** The keyword a system's status means here, or undefined when the head doesn't map it. */ +export const keywordFor = (plan: Plan, system: string, status: string): string | undefined => + trackerStates(plan).get(system.toLowerCase())?.toKeyword.get(status.trim().toLowerCase()) + +/** The status to write back to a system for a keyword: the first one its line lists, or undefined. */ +export const statusFor = (plan: Plan, system: string, keyword: string): string | undefined => trackerStates(plan).get(system.toLowerCase())?.toStatus.get(keyword) + +/** What's wrong with the plan's links, for checkPlan: an entry that isn't SYSTEM:ID, a system named twice on one task, + * one SYSTEM:ID on two tasks, and a #+LINK_STATES: keyword the plan doesn't know. Each says its fix. */ +export function trackerProblems(plan: Plan): { task?: Task; line?: number; message: string }[] { + const out: { task?: Task; line?: number; message: string }[] = [] + const owner = new Map<string, Task>() + for (const t of plan.entries) { + const systems = new Set<string>() + for (const raw of (t.props.LINK ?? "").split(/\s+/).filter(Boolean)) { + const e = entry(raw) + if (typeof e === "string") { + out.push({ task: t, message: `:LINK: ${e}` }) + continue + } + if (systems.has(e.system)) out.push({ task: t, message: `:LINK: names ${e.system} twice; a task is one item in each system` }) + systems.add(e.system) + const key = `${e.system}:${e.id}` + const was = owner.get(key) + if (was) out.push({ task: t, message: `:LINK: ${key} is also ${was.text}'s; one tracker item is one task, so keep it on one of them`, }) + else owner.set(key, t) + } + } + plan.doc.head.forEach((line, i) => { + const m = STATES_LINE.exec(line) + if (!m) return + if (!SYSTEM.test(m[1].toLowerCase())) out.push({ line: i, message: `#+LINK_STATES: starts with its system's name (linear), not "${m[1]}"` }) + for (const pair of m[2].split(";").map((p) => p.trim()).filter(Boolean)) { + const eq = pair.lastIndexOf("=") + const keyword = eq < 0 ? "" : pair.slice(eq + 1).trim() + if (eq <= 0 || !keyword) out.push({ line: i, message: `#+LINK_STATES: "${pair}" isn't Status=KEYWORD` }) + else if (!plan.words.has(keyword)) out.push({ line: i, message: `#+LINK_STATES: ${keyword} isn't one of this plan's keywords (${[...plan.words.keys()].join(" ")}); add it to #+TODO: or map the status to one that is` }) + } + }) + return out +} diff --git a/sdk/task/test/trackers.test.ts b/sdk/task/test/trackers.test.ts new file mode 100644 index 00000000..c7f23537 --- /dev/null +++ b/sdk/task/test/trackers.test.ts @@ -0,0 +1,149 @@ +// PL8: a task kept in step with another tracker by :LINK: and #+LINK_STATES:, with checkPlan saying what's wrong, and +// a raea cloud plan.org (the cloud's writer, 11-20) passing it with nothing flagged. +import { describe, expect, test } from "vitest" +import { checkPlan, keywordFor, newPlan, readPlan, statusFor, trackersOf, trackerStates } from "../src/index.ts" + +const LINKED = `#+TITLE: Launch +#+TODO: TODO MAKING REVIEW | DONE DROPPED +#+LINK_STATES: linear In Progress=MAKING; In Review=REVIEW; Done=DONE; Canceled=DROPPED; Duplicate=DROPPED + +* Cut +** TODO Hero cut +:PROPERTIES: +:ID: t-hero +:LINK: linear:ENG-12 asana:1209876543 +:END: +` + +describe("PL8: links to other trackers", () => { + test("a task's trackers are its :LINK: entries, in order", () => { + const p = readPlan(LINKED) + expect(trackersOf(p.tasks[0])).toEqual([{ system: "linear", id: "ENG-12" }, { system: "asana", id: "1209876543" }]) + // each tracker's own key, as raea cloud writes them (11-20): GitHub's org/repo#12, Slack's channel/ts, Trello's shortLink + const keys = readPlan(LINKED.replace("linear:ENG-12 asana:1209876543", "github:acme/site#12 slack:C0123/1700000000.123 trello:aB3dE9 jira:PROJ-7")) + expect(trackersOf(keys.tasks[0]).map((t) => t.id)).toEqual(["acme/site#12", "C0123/1700000000.123", "aB3dE9", "PROJ-7"]) + expect(checkPlan(keys)).toEqual([]) + }) + + test("a status comes in as its keyword, and a keyword goes out as the first status listed for it", () => { + const p = readPlan(LINKED) + expect(keywordFor(p, "linear", " in review ")).toBe("REVIEW") + expect(keywordFor(p, "Linear", "Duplicate")).toBe("DROPPED") + expect(statusFor(p, "linear", "DROPPED")).toBe("Canceled") + expect(keywordFor(p, "linear", "Backlog")).toBeUndefined() + expect(keywordFor(p, "jira", "Done")).toBeUndefined() + expect([...trackerStates(p).keys()]).toEqual(["linear"]) + expect(checkPlan(p)).toEqual([]) + }) + + test("checkPlan says what's wrong with a link, and how to fix it", () => { + const bad = `${LINKED.replace("asana:1209876543", "linear:ENG-13 https://linear.app/x ENG-14")}** TODO Same item +:PROPERTIES: +:LINK: linear:ENG-12 +:END: +`.replace("Duplicate=DROPPED", "Blocked=WAITING") + const says = checkPlan(readPlan(bad)).map((d) => d.message) + expect(says.some((m) => /names linear twice/.test(m))).toBe(true) + expect(says.some((m) => /is a URL/.test(m))).toBe(true) + expect(says.some((m) => /"ENG-14" isn't SYSTEM:ID/.test(m))).toBe(true) + expect(says.some((m) => /linear:ENG-12 is also Hero cut's/.test(m))).toBe(true) + expect(says.some((m) => /WAITING isn't one of this plan's keywords/.test(m))).toBe(true) + }) + + test("a new plan keeps the keywords it's given", () => { + expect(newPlan("Pong")).toContain("#+TODO: TODO MAKING REVIEW | DONE DROPPED") + expect(newPlan("Pong", "TODO | DONE DROPPED")).toContain("#+TODO: TODO | DONE DROPPED\n") + }) +}) + +// what raea cloud writes (11-20): an * Agent heading, triggers under * Triggers (and the old * Inputs), +// projects with their properties, a project's own sections, checkpoints, team stage checklists and logbook notes +const CLOUD = `#+TITLE: Cutter +#+TODO: TODO MAKING REVIEW | DONE DROPPED +#+LINK_STATES: linear In Progress=MAKING; In Review=REVIEW; Done=DONE + +* Agent +:PROPERTIES: +:FOR: Acme's paid social +:AT_A_TIME: no limit +:TOOLS: computer judge web +:END: +- [X] Client review (amber): where its review goes +- [ ] Legal (red): legal@acme.com + +* Triggers +** Linear: In Review on ENG +:PROPERTIES: +:TRIGGER: tr-lin1 +:APP: linear +:WHERE: ENG +:SIGNAL: status +:VALUE: In Review +:FIELD: state +:FILTERS: label=video; priority=high +:REPLY: webhook https://hooks.acme.com/raea +:END: +** Every Monday +:PROPERTIES: +:TRIGGER: tr-sched +:AT: 09:00 +:REPEAT: weekly +:END: + +* Inputs +** Old form +:PROPERTIES: +:INPUT: in-1 +:END: + +* Projects +** REVIEW Spring sale cut [1/2] +:PROPERTIES: +:ID: pj-1 +:AGENT: ag-cutter +:BOT: bot-1 +:SKILL: sk-cut +:REPO: project-pj-1 +:ASSIGNEE: email:ana@acme.com Ana Ruiz +:FROM: tr-lin1 +:REPLY: email ana@acme.com +:CLIENT: Acme +:BRAND: Acme +:CREATED: [2026-11-20 Fri 10:02] +:SPENT: 0.039 +:RESPONSES: 3 +:WAITING: Client review +:LINK: linear:ENG-12 +:END: +:LOGBOOK: +- Note taken on [2026-11-20 Fri 10:10] \\\\ + first cut posted +:END: +- [X] Approve the plan +- [ ] Client review: Review the first cut +*** Input +[[https://linear.app/acme/issue/ENG-12][ENG-12]] +*** Attachments +*** Expected output +*** Checkpoint: Approve the plan +:PROPERTIES: +:AT: [2026-11-20 Fri 10:05] +:ANSWER: approve +:NOTE: go +:END: +** DROPPED Old idea +:PROPERTIES: +:ID: pj-0 +:OUTCOME: failed +:END: +*** What went wrong +*** Last answer +*** Delivered +` + +test("PL8: a raea cloud plan.org passes checkPlan with nothing flagged", () => { + const p = readPlan(CLOUD) + expect(checkPlan(p)).toEqual([]) + expect(p.tasks.map((t) => t.keyword)).toEqual(["REVIEW", "DROPPED"]) + expect(trackersOf(p.tasks[0])).toEqual([{ system: "linear", id: "ENG-12" }]) +}) diff --git a/skills b/skills index 76691d08..bd29ad82 160000 --- a/skills +++ b/skills @@ -1 +1 @@ -Subproject commit 76691d080ab3e26a100e8d3a755ac23dc84d6696 +Subproject commit bd29ad82ac61817d25ed39d39c4d975e6d29bb71 diff --git a/tools/skills.sh b/tools/skills.sh index ec50d5d5..576199c3 100755 --- a/tools/skills.sh +++ b/tools/skills.sh @@ -205,7 +205,7 @@ gen_files() { echo "## The spec files" echo echo "Each spec's fields, as raea/brief's types (sdk/raea/src/brief.gen.ts, generated from the schemas in core/brief that" - echo "\`raea spec\` checks against): brief.ts is a Brief, NAME.script.ts a Script, taste.ts a Taste and plan.ts a Plan." + echo "\`raea spec\` checks against): brief.ts is a Brief, NAME.script.ts a Script, taste.ts a Taste and NAME.parts.ts an object's Parts." echo "A field marked ? may be left out." echo echo '```ts'