@punal_manalan/blender-project-harness 0.0.0-stage → 1.0.2

package/.kilo/blender-project-harness/tools/harness/templates/project/Documents/WORKFLOW.md

@@ -0,0 +1,36 @@
+# Workflow — {{PROJECT_NAME}}
+
+Mode: Unset
+Selected: —
+Last changed: {{DATE}}
+
+## Current mode
+
+- [ ] Fully Autonomous
+- [ ] Partially Autonomous
+
+## Rules
+
+- Fully Autonomous: proceed within confirmed requirements. Stop for blockers, destructive choices, or scope changes.
+- Partially Autonomous: after every reviewable change (a bounded change with at least one apply),
+  seal, inspect with `look`, complete required grading and dispositions, then ask for approval or
+  revision direction before commit. Grader findings do not authorize corrections without that
+  direction.
+- Kilo removes `question` during an active goal in either mode. The orchestrator follows
+  `blender-project-goal` for required-input handoffs, questions, objective updates, and resume; never
+  delegate goal commands to the user or repeat the stop procedure for already stopped work. Wait for
+  every required answer. Pause, cancellation, no answer, and manual editing keep work stopped.
+- Commit through the harness `commit` action after each reviewed change: one scoped change per
+  commit, never one end-of-task dump. Manual project Git commits are blocked.
+- Collect workflow and review answers after requirements confirmation and before scaffolding, then
+  persist their exact records before filling and starting the goal. Ask both modes before resuming a
+  genuine later return. Routine approval, clarification, and manual-edit pauses within the same task,
+  automatic goal turns, and compaction retain modes without reasking. The user may switch at any time.
+- Require the final applicable `PASS` when grading is enabled and no genuine unresolved blocker or
+  major finding before completion. User approval does not waive those findings.
+
+## Change log
+
+| Date | Mode | Reason | Confirmed by |
+|---|---|---|---|
+| {{DATE}} | Unset | Project scaffolded. | Pending |

package/.kilo/blender-project-harness/tools/harness/templates/project/README.md

@@ -0,0 +1,130 @@
+# {{PROJECT_NAME}}
+
+Status: Draft
+Last updated: {{DATE}}
+
+## Purpose
+
+{{DESCRIPTION}}
+
+## What this project is
+
+Describe the subject, the intended audience, and the visual result this project must deliver. Keep
+this section short and concrete.
+
+## Requirements
+
+Confirmed scope and acceptance criteria: [`Documents/REQUIREMENTS.md`](Documents/REQUIREMENTS.md).
+
+- [ ] Summarize the highest-priority confirmed requirements.
+
+## Visual direction
+
+- Style:
+- Mood / references:
+- Colour and lighting:
+- Camera / framing:
+- Scale and units:
+
+## Deliverables
+
+- Main Blender file: `{{PROJECT_SLUG}}.blend` (planned at project root until first save)
+- Final renders: `renders/final/`
+- Exports: `exports/`
+- Documentation: `Documents/`
+- External assets: `assets/external/`
+
+## Project structure
+
+```text
+{{PROJECT_NAME}}/
+  README.md
+  {{PROJECT_SLUG}}.blend
+  .gitignore
+  Documents/
+    README.md
+    REQUIREMENTS.md
+    WORKFLOW.md
+    REVIEW.md
+    ASSETS.md
+    DECISIONS.md
+    TASKSTRACKER.md
+    Tasks/
+    Goals/
+    Reviews/
+    References/
+  assets/
+    external/
+    textures/
+    hdri/
+    models/
+    audio/
+  renders/
+    final/
+    wip/
+  exports/
+  scenes/
+  scripts/
+  logs/
+  backups/
+```
+
+## Blender
+
+- MCP port: owned by the workspace root `.kilo/kilo.jsonc`.
+- Launch and stop with `blender_workflow` `launch`/`stop`; never invoke Blender from the shell.
+- Before launch, require confirmed requirements, selected workflow and review records, and an active
+  filled goal. The harness validates project records, keeps the `.blend` inside this project, reads
+  the workspace MCP port, records the instance outside the repository, and rejects conflicting
+  workspace instances.
+- Each launch writes `logs/blender-<timestamp>.log`; `logs/` is ignored.
+- Main file: save the first scene as `{{PROJECT_SLUG}}.blend` in the project root. Before production
+  edits, verify MCP scene settings report that exact path; then replace the planned status above.
+- Keep external paths relative (`//assets/...`); do not use absolute paths.
+- Only one Blender project spawned by this workspace may be open at a time. Close the current one
+  before opening another.
+
+## Workflow
+
+- Record the selected autonomy mode in [`Documents/WORKFLOW.md`](Documents/WORKFLOW.md).
+- Record review mode `Off`, `All`, or `Single` in [`Documents/REVIEW.md`](Documents/REVIEW.md);
+  rounds live in [`Documents/Reviews/`](Documents/Reviews/README.md).
+- Collect both answers after requirements confirmation and before scaffolding; persist their exact
+  records after scaffolding and before filling and starting the goal. Launch only after that.
+- After registration, workflow and review modes are frozen. A requested mode change stops production
+  for explicit re-registration; routine approval, clarification, or manual-edit pauses retain them.
+- In Partially Autonomous mode, the agent seals, inspects, completes required grading, and obtains
+  approval or revision direction before the next reviewable change commits. In either mode, the agent
+  manages goal handoffs and continuation; users provide inputs and decisions.
+- Require the saved inspected review render, current documents, and final applicable `PASS` when
+  grading is enabled before completion; no genuine unresolved blocker or major finding permits it.
+
+## External assets
+
+See [`Documents/ASSETS.md`](Documents/ASSETS.md) and [`assets/external/README.md`](assets/external/README.md).
+
+- User files are brought in through `blender_workflow {action:"intake"}`; originals are never moved.
+- No external assets yet. Replace this line with a summary when assets are added.
+
+## Goals
+
+Goal prompts live in [`Documents/Goals/`](Documents/Goals/). Multiple goals are allowed.
+Identify the active goal's actual path; use it for grading rather than assuming the first brief.
+
+- [`01-project-brief.md`](Documents/Goals/01-project-brief.md)
+
+## References
+
+- [`Documents/References/README.md`](Documents/References/README.md)
+- Add links, moodboards, and source references here.
+
+## Open questions
+
+- [ ] Replace with unknown requirements or decisions.
+
+## Next steps
+
+- [ ] Persist the exact confirmed requirements and workflow/review answers collected before scaffold.
+- [ ] Fill this README and the active goal, then start the goal before launch.
+- [ ] Collect references and external assets.
+- [ ] Build the scene, save and inspect a review render, and complete applicable grading and approvals.

package/.kilo/blender-project-harness/tools/harness/templates/project/assets/README.md

@@ -0,0 +1,31 @@
+# Assets — {{PROJECT_NAME}}
+
+| Folder | Use |
+|---|---|
+| `external/` | Third-party models, textures, HDRIs, audio, and libraries. Register in `Documents/ASSETS.md`. |
+| `textures/` | Project-owned textures only. |
+| `hdri/` | Project-owned environment maps only. |
+| `models/` | Project-owned meshes and linked libraries only. |
+| `audio/` | Project-owned sound effects, music, and voice assets only. |
+
+Use relative paths from the `.blend` file (`//assets/...`). Do not embed absolute paths.
+Store licensed third-party assets and their derivatives under `external/<source>/<asset>/`; modifying
+an asset does not remove its source, licence, attribution, registration, or redistribution duties.
+Keep `SOURCE.md` and verbatim `LICENSE.txt` beside each external asset and register every derivative.
+
+Bring user files in with `blender_workflow {action:"intake"}`. Scan first, then copy inside an open
+change; it hashes, classifies, deduplicates, writes source/licence sidecars, and updates the registers.
+Use `download` only to fetch a public HTTPS asset into ignored staging. Do not ask the user to
+create folders or copy files by hand. Browser/provider and user-assisted files return through
+`intake` with their actual local path; never bypass authentication, CAPTCHA, or provider
+restrictions.
+
+External binaries under `assets/external/` are not committed unless `SOURCE.md` says
+`Redistribution allowed: yes`. Sidecars, hashes, and metadata are committed. Media generation is
+agent-owned and requires explicit permission before spending credits; pass the actual generated
+file to `intake` with generated metadata.
+
+Supported reviewed operations: `import_asset` for local GLB/glTF/FBX/OBJ/USD/`.blend`, `link_library`
+for `.blend` link/append, `import_audio`, `image_texture`, `world_hdri`, `check_assets`,
+`pack_assets`, and `export_scene`. Remote asset-library import and 3D generation remain blocked;
+`download` and `intake` are the supported local staging path.

package/.kilo/blender-project-harness/tools/harness/templates/project/assets/external/README.md

@@ -0,0 +1,43 @@
+# External Assets — {{PROJECT_NAME}}
+
+This folder holds third-party assets. The default `.gitignore` excludes asset binaries so a project
+does not accidentally commit large or non-redistributable files. Metadata stays tracked.
+
+## Layout
+
+```text
+assets/external/
+  <source-or-vendor>/
+    <asset-name>/
+      SOURCE.md
+      LICENSE.txt     # mandatory verbatim licence terms; preserve originals too
+      <asset files>
+```
+
+## Rules
+
+- Use `intake` for user files. It copies accepted files here and writes `SOURCE.md`,
+  `LICENSE.txt`, and the `ASSETS.md` row. Use `download` only to stage an HTTPS file in `.temp`;
+  then pass it to `intake` with source and licence details.
+- Never ask the user to create this folder tree or copy by hand. Original files are never moved.
+- Copy applicable licence terms verbatim into `LICENSE.txt`; preserve original licence files too.
+  Record the licence source URL and required attribution exactly. Stop if terms are unavailable or
+  do not permit the intended use; do not invent or summarize them. Verify `SOURCE.md` and
+  `LICENSE.txt` are tracked before committing the project.
+- Keep third-party originals and derivatives in this folder, including licensed assets. Register
+  derivatives and identify source and modifications; project modification does not remove licence duties.
+- Record the asset in `../../Documents/ASSETS.md`.
+- Do not commit an asset unless its licence allows redistribution. If it does, remove the ignore
+  rule for that exact path so the harness commit can stage it, and keep the licence beside it.
+  Force-add is unsupported; request reviewed tooling instead of using manual Git.
+- For large redistributable assets, use Git LFS rather than committing raw binaries.
+- Link or import with relative paths. Use the harness `import_asset` operation for local model files,
+  `link_library` for `.blend` libraries, `import_audio` for audio, and `image_texture`/`world_hdri`
+  for image assets. Check missing files with `check_assets` before delivery.
+- Search tools can find assets, but remote asset-library import is not implemented. Use `download`
+  for an exact HTTPS URL, then `intake`; or supply the local file path directly to `intake`.
+- Packing or embedding external data into a tracked or delivered `.blend` redistributes those bytes.
+  Verify the licence, attribution, and redistribution terms first, and record the packaging mode in
+  `../../Documents/ASSETS.md` and `SOURCE.md`.
+- Pack external data only for delivery copies when permitted; keep an unpacked working copy when the
+  assets need editing.

package/.kilo/blender-project-harness/tools/harness/templates/project/assets/external/SOURCE_TEMPLATE.md

@@ -0,0 +1,18 @@
+# Asset Source
+
+- Asset:
+- Source URL:
+- Author / vendor:
+- Licence:
+- Licence source URL:
+- Verbatim licence copy: LICENSE.txt (required; preserve original licence files too)
+- Attribution required:
+- Redistribution allowed:
+- Packaging in .blend: linked / packed / embedded / none
+- Local path:
+- Imported into:
+- Modifications:
+- Original asset / derivative relationship:
+- Acquisition instructions and file hashes:
+- Date:
+- Notes:

package/.kilo/blender-project-harness/tools/harness/templates/project/backups/README.md

@@ -0,0 +1,5 @@
+# Local Backups — {{PROJECT_NAME}}
+
+Manual snapshots of the `.blend` and important assets can go here. This folder is ignored by git;
+it is not the project history. Use git commits for tracked history and off-machine backups for
+disaster recovery.

package/.kilo/blender-project-harness/tools/harness/templates/project/exports/README.md

@@ -0,0 +1,11 @@
+# Exports — {{PROJECT_NAME}}
+
+Final interchange files (GLB, glTF, FBX, USD, OBJ) and other delivery outputs live here. Create them
+with the reviewed `export_scene` operation inside a declared scene change, with the output path under
+`exports/`. Record the export preset, scale, axis convention, and any known limitations in the project
+README. Sidecar files such as OBJ `.mtl` or separate glTF buffers follow the same ownership and
+licence rules as the main export.
+
+Every export produces a harness receipt with format, project-relative path, bytes, SHA-256, source
+scene, and signature check. Completion is denied for a missing or changed export. This validation is
+separate from `check_assets`.

package/.kilo/blender-project-harness/tools/harness/templates/project/renders/README.md

@@ -0,0 +1,7 @@
+# Renders — {{PROJECT_NAME}}
+
+- `final/` — reviewed renders that belong with the deliverable. Tracked.
+- `wip/` — iteration renders and test frames. Ignored by git.
+
+Use `//renders/...` paths relative to the `.blend` file. Record the render settings and the final
+render names in the project README.

package/.kilo/blender-project-harness/tools/harness/templates/project/scenes/README.md

@@ -0,0 +1,10 @@
+# Scenes — {{PROJECT_NAME}}
+
+Save the main `.blend` at the project root as `{{PROJECT_SLUG}}.blend`. Multiple authored scenes
+are supported inside that file. Use `create_scene`, `switch_scene`, `duplicate_scene`, and
+`delete_scene`; `create_scene` supports `NEW`, `EMPTY` (Copy Settings), `LINK_COPY`, and
+`FULL_COPY`. Existing operations accept an optional `scene` field. Declare exact scene names in
+`begin`/`extend` or add them through scene operations, and give each shot scene its own camera.
+A master Video Sequencer scene can use `scene_strip`. The harness seals and grades every declared
+scene; a single-scene project may omit scene names and keeps the existing behavior. Linked `.blend`
+libraries still use `link_library`. Use relative paths and document the primary scene.

package/.kilo/blender-project-harness/tools/harness/templates/project/scripts/README.md

@@ -0,0 +1,16 @@
+# Scripts — {{PROJECT_NAME}}
+
+Project-specific Blender Python source may live here. It is source-only: the harness never executes
+it. Use relative paths from the project root or the `.blend` file and never hardcode machine-specific
+paths.
+
+Use `blender_workflow {action:"intake"}` with `kind:"script"` to copy `.py`/`.pyw` source here. The
+harness accepts these files only under `scripts/` and records them in `Documents/INTAKE.md`.
+
+Workspace automation scripts are a separate category. They may run only through the existing shell
+command approval path, with the exact command, working directory, script SHA-256, reason, approval,
+and outcome recorded. They are not a sandbox.
+
+Any Blender Python execution requires a separately reviewed OS/VM isolation design. Do not use raw
+Python, `--python`, `exec()`, or a hidden runner. Document each script's purpose and any approved
+future invocation in this README.

package/.kilo/blender-project-harness/tools/harness/test-fixture.mjs

@@ -0,0 +1,91 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { Harness, git } from './engine.mjs';
+
+export function fixture(t, { partial = false, review = 'Off' } = {}) {
+  const tempBase = process.platform === 'win32' ? path.join(os.tmpdir(), 'kilo') : os.tmpdir();
+  const temp = fs.mkdtempSync(path.join(tempBase, 'workflow-integration-'));
+  t.after(() => fs.rmSync(temp, { force: true, recursive: true }));
+  const root = path.join(temp, 'workspace');
+  fs.mkdirSync(root);
+  const project = 'Blender/Test Project', scene = `${project}/scene.blend`, goal = 'Documents/Goals/01-test.md';
+  const write = (name, text) => {
+    const full = path.join(root, name);
+    fs.mkdirSync(path.dirname(full), { recursive: true });
+    fs.writeFileSync(full, text);
+    return full;
+  };
+  const objectiveText = '# Test Goal\n' + 'Confirmed fixture requirements and observable acceptance checks. '.repeat(4);
+  write(`${project}/README.md`, [
+    '# Fixture project',
+    'Status: Confirmed',
+    'Last updated: 2026-10-31',
+    '',
+    ...['Purpose', 'What this project is', 'Requirements', 'Visual direction', 'Deliverables', 'Project structure', 'Blender', 'Workflow', 'External assets', 'Goals', 'References', 'Open questions', 'Next steps'].flatMap((name) => [`## ${name}`, `Fixture ${name.toLowerCase()}.`, '']),
+  ].join('\n'));
+  write(`${project}/Documents/REQUIREMENTS.md`, [
+    '# Requirements',
+    'Status: Confirmed',
+    'Defined: 2026-10-31',
+    'Last updated: 2026-10-31',
+    'Confirmed: 2026-10-31',
+    'Confirmation: Confirm fixture requirements.',
+    '',
+    ...['Core value', 'Confirmed requirements', 'Constraints', 'Deferred', 'Out of scope', 'Open questions', 'Research notes', 'Change log'].flatMap((name) => [`## ${name}`, `Fixture ${name.toLowerCase()}.`, '']),
+  ].join('\n'));
+  write(`${project}/Documents/WORKFLOW.md`, [
+    '# Workflow',
+    `Mode: ${partial ? 'Partially' : 'Fully'} Autonomous`,
+    'Selected: 2026-10-31',
+    'Last changed: 2026-10-31',
+    '',
+    ...['Current mode', 'Rules', 'Change log'].flatMap((name) => [`## ${name}`, `Fixture ${name.toLowerCase()}.`, '']),
+  ].join('\n'));
+  write(`${project}/Documents/REVIEW.md`, [
+    '# Review Mode',
+    `Mode: ${review}`,
+    'Selected: 2026-10-31',
+    'Last changed: 2026-10-31',
+    'Single grader: visual',
+    '',
+    ...['Modes', 'Change log'].flatMap((name) => [`## ${name}`, `Fixture ${name.toLowerCase()}.`, '']),
+  ].join('\n'));
+  write(`${project}/Documents/ASSETS.md`, '# No external assets\n\n## Rules\n\nFixture asset rules.\n');
+  write(`${project}/Documents/DECISIONS.md`, '# Fixture decisions\n');
+  write(`${project}/Documents/TASKSTRACKER.md`, '# Task Tracker — Test Project\n\nStatus: Active\nLast updated: 2026-10-31\n\n## Tasks\n\n| Task | Kind | Change | Operation | Objects | Assigned | Child | State | Created | Finished | Result |\n|---|---|---|---|---|---|---|---|---|---|---|\n| — | — | — | — | — | — | — | — | — | — | — |\n');
+  const goalBody = objectiveText.replace(/^#\s+.*\r?\n/, '');
+  const objective = [
+    '# Goal: Fixture',
+    ...['Mission', 'Project', 'Visual outcome', 'Scope', 'Deliverables', 'Acceptance', 'Workflow', 'Done'].flatMap((name) => [`## ${name}`, goalBody, '']),
+  ].join('\n');
+  write(`${project}/${goal}`, objective);
+  write(scene, 'fixture blend bytes\n');
+  write(`${project}/Documents/Reviews/README.md`, '# Review Index\n\n## Index\n\nFixture index.\n\n## Rules\n\nFixture rules.\n');
+  write('.gitignore', '**/_evidence/**\n**/renders/wip/**\n/.kilo/blender-project-harness/config.json\n');
+  write(`${project}/.gitignore`, 'renders/wip/**\n');
+  const config = { blender_subagents: { workers: {
+    agent: 'blender-worker', provider: 'fixture-provider', model: 'fixture-model', variant: 'fixture-variant',
+    backup: { provider: 'backup-provider', model: 'backup-model', variant: 'backup-variant' },
+    max_minutes: 10, max_steps: 18, max_failed_attempts: 2, max_parallel: 1,
+  } } };
+  if (review !== 'Off') config.blender_subagents.graders = {
+    enabled: true, agent: 'blender-grader', max_parallel: 1, max_rounds: 2,
+    graders: [{ name: 'visual', focus: 'composition', provider: 'test', model: 'test-model', variant: 'test-variant', backup: { provider: 'backup-test', model: 'backup-test-model', variant: 'backup-test-variant' }, max_steps: 12, max_minutes: 5 }],
+  };
+  write('.kilo/blender-project-harness/config.json', JSON.stringify(config));
+  git(root, ['init', '--quiet']);
+  git(root, ['add', '--', '.']);
+  const commit = (message = 'test: fixture checkpoint') => git(root, ['-c', 'user.name=Harness Test', '-c', 'user.email=harness-test@example.invalid', 'commit', '--quiet', '-m', message]);
+  commit('test: fixture scaffold');
+  const harness = new Harness(root, { stateRoot: path.join(temp, 'state') });
+  const session = 'ses_orchestrator';
+  const questionArgs = (question, labels) => ({ questions: [{ question, custom: false, multiple: false, options: labels.map((label) => ({ label, description: label })) }] });
+  const registration = harness.prepare(session, { project, scene: 'scene.blend', goal });
+  harness.question(session, questionArgs(registration.question, registration.labels), [['Confirm registration']]);
+  const begin = () => {
+    harness.command(session, 'goal-active', { objective });
+    return harness.command(session, 'begin', { outcome: 'Create fixture composition', objects: ['Cube'], paths: ['notes.txt', 'Documents/DECISIONS.md'], final: true });
+  };
+  return { root, project, scene, goal, objective, write, commit, harness, session, questionArgs, begin };
+}

package/.kilo/blender-project-harness/tools/harness/workspace.mjs

@@ -0,0 +1,30 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const INSTALL_RELATIVE = path.join('.kilo', 'blender-project-harness');
+export const CONFIG_RELATIVE = path.join(INSTALL_RELATIVE, 'config.json');
+
+export function workspaceRoot(start) {
+  const explicit = process.env.BLENDER_WORKSPACE_ROOT;
+  if (explicit) {
+    const resolved = path.resolve(explicit);
+    if (fs.existsSync(resolved)) return resolved;
+  }
+  let current = path.resolve(start);
+  while (true) {
+    if (fs.existsSync(path.join(current, '.kilo'))
+      && (fs.existsSync(path.join(current, 'Blender')) || fs.existsSync(path.join(current, 'AGENTS.md')))) {
+      return current;
+    }
+    const parent = path.dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+  const cwd = path.resolve(process.cwd());
+  if (fs.existsSync(path.join(cwd, '.kilo'))) return cwd;
+  return path.resolve(start, '..', '..');
+}
+
+export function configPath(root) {
+  return path.join(root, CONFIG_RELATIVE);
+}

package/.kilo/blender-project-harness/tools/harness/workspace.test.mjs

@@ -0,0 +1,31 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import test from 'node:test';
+import { configPath, workspaceRoot } from './workspace.mjs';
+
+test('workspace root resolves from the installed harness path', (t) => {
+  const previous = process.env.BLENDER_WORKSPACE_ROOT;
+  delete process.env.BLENDER_WORKSPACE_ROOT;
+  t.after(() => {
+    if (previous === undefined) delete process.env.BLENDER_WORKSPACE_ROOT;
+    else process.env.BLENDER_WORKSPACE_ROOT = previous;
+  });
+  const temp = fs.mkdtempSync(path.join(os.tmpdir(), 'blender-workspace-root-'));
+  t.after(() => fs.rmSync(temp, { recursive: true, force: true }));
+  const root = path.join(temp, 'workspace');
+  fs.mkdirSync(path.join(root, '.kilo'), { recursive: true });
+  fs.mkdirSync(path.join(root, 'Blender'), { recursive: true });
+  const harness = path.join(root, '.kilo', 'blender-project-harness', 'tools', 'harness');
+  fs.mkdirSync(harness, { recursive: true });
+  assert.equal(workspaceRoot(harness), root);
+});
+
+test('config path is always the installed harness config', (t) => {
+  const temp = fs.mkdtempSync(path.join(os.tmpdir(), 'blender-workspace-config-'));
+  t.after(() => fs.rmSync(temp, { recursive: true, force: true }));
+  const root = path.join(temp, 'workspace');
+  fs.mkdirSync(root, { recursive: true });
+  assert.equal(configPath(root), path.join(root, '.kilo', 'blender-project-harness', 'config.json'));
+});