@mrpatronz/nexusflow 2.11.0 → 2.12.1

package/dist/static-resources/skills/contextspace-verify-release/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: contextspace-verify-release
+description: Verify a ContextSpace-managed change, assess PR readiness, or execute an explicitly requested push, merge, or release using evidence tied to the current code revision. Use when verification or delivery is the task, not for every edit.
+metadata:
+  contextspace:
+    title: ContextSpace Verification and Release
+    category: workflows
+    tags: [contextspace, verification, review, release]
+---
+
+# Establish readiness from current evidence
+
+Resolve the requested workspace, branch, PR, assignment, and acceptance criteria.
+Inspect the current diff and repository-required checks. Select additional evidence
+according to the affected behavior and impact; use [verification evidence](references/evidence.md).
+Do not impose ContextSpace's own npm commands on unrelated projects.
+
+## Review and verify
+
+Check intended behavior, regressions, compatibility, and consequential failure paths.
+For interface changes, assess the actual user's journey and recovery behavior with
+browser evidence. Report concrete findings by severity, with trigger, impact,
+location, and expected behavior. Distinguish inspected behavior from assumptions.
+
+Record commands, results, tested commit, and any uncommitted changes included in a
+local test. An unavailable check is not a pass. Reuse applicable evidence while
+the tested input is unchanged; rerun affected checks after fixes.
+
+## Push or assess merge readiness
+
+Before a requested push, inspect pending changes and the remote branch; stage only
+the intended paths. Preserve unrelated work. Follow the repository's commit convention.
+After pushing, confirm the PR's head SHA matches the intended commit and watch its
+checks. Inspect failures and fix issues within the user's authorized scope.
+
+Before declaring readiness, read the current PR head, relevant diff/review findings,
+required checks, draft status, and mergeability. Compare the head with the reviewed
+and verified revision. If it changed, inspect the added changes and verify the new
+head. Green checks on an earlier commit do not establish readiness for a newer one.
+Pending checks, unresolved blocking findings, and missing required approvals must be
+reported as outstanding. No review submitted is different from an approved review.
+
+An assessment or push request does not itself authorize merging or publishing.
+When those actions are requested, perform the applicable checks first and verify
+the resulting remote state. For deployments or migrations, include the relevant
+rollout and recovery plan. Do not deploy to a test or production service merely
+to produce evidence unless that action is within the assignment.
+
+Conclude with the exact revision, verification outcome, unresolved blockers or
+limits, and which requested external actions actually completed. Link to CI/PR
+evidence. Avoid an unconditional merge-ready claim from tests alone.

package/dist/static-resources/skills/contextspace-verify-release/references/evidence.md

@@ -0,0 +1,21 @@
+# Evidence proportional to the change
+
+| Change | Establish |
+| --- | --- |
+| Localized bug | Original failing behavior, corrected behavior, relevant regression coverage |
+| Performance | Representative workload and baseline, comparable result, correctness preserved |
+| Public contract | Existing consumers remain compatible or a coordinated migration is defined |
+| Persistent data | Representative old inputs, retry/failure behavior, recovery feasibility |
+| UI flow | Discoverability, understandable defaults, keyboard access, loading/empty/error/retry behavior |
+| State/storage | Adapter routing, concurrent updates, interrupted writes and stale-save recovery |
+| Generated instructions | Correct source, reproducible output, valid references and runnable documented commands |
+
+Separate local evidence from remote evidence. For local tests, record the commit and
+whether the worktree contained edits; the commit alone does not identify those edits.
+For PR checks, record the head SHA and run links. When CI tests a synthetic merge
+commit, confirm the run corresponds to the current PR head and base.
+
+For existing repositories, discover required commands from repository instructions,
+package/build scripts, and CI. Run applicable gates, not unrelated tools merely
+because they appear in a generic checklist. A successful build cannot demonstrate
+an accessible interface, a safe migration, or satisfied product requirements.

package/dist/static-resources/skills/nexusflow-dev/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: nexusflow-dev
+description: Maintain ContextSpace/NexusFlow implementation, CLI, storage, generated resources, and tests. Use for changes to this codebase; projects merely using ContextSpace follow their own repository engineering standards.
+metadata:
+  contextspace:
+    title: ContextSpace Maintainer
+    category: dev-standards
+    tags: [contextspace, nexusflow, architecture, testing]
+---
+
+# Maintain ContextSpace
+
+Read the current repository instructions and assignment before editing. Keep changes
+in the supplied worktree. The CLI in `src/index.ts` wires thin handlers; workspace
+behavior belongs in `src/core/`, document persistence uses `src/core/storage.ts`,
+and generated assistant views belong in `src/generators/`.
+
+## Preserve implementation contracts
+
+- Resolve brand aliases and durable paths through `src/core/constants.ts` and the
+  brand configuration. Preserve primary/legacy fallback behavior.
+- Use the storage port for adapter-owned documents. A local lock or cache does not
+  make filesystem writes an acceptable substitute for configured storage.
+- Mutate shared state through the relevant catalog or workspace API. Keep locked
+  sections short; do slow verification outside them and revalidate the affected
+  revision before committing its result. Read fresh state under the lock.
+- Use atomic persistence at the owning storage layer. For portable resource paths,
+  enforce containment and reject symlinks with the filesystem safety helpers.
+- Change the source of generated views, then regenerate. Keep volatile progress
+  in live state, and invalidate verification evidence when the tested input changes.
+- Knowledge entries retain the 300-character body limit; preserve adapter routing,
+  searchability, and recovery when Git persistence fails.
+
+Read [CLI conventions](references/cli-conventions.md) for command changes and
+[verification checks](references/verification-checklist.md) to select checks for
+the affected subsystem. Follow repository-required gates before submission; use
+targeted checks during iteration and repeat only when changes or failures justify it.
+
+## Maintain the guidance too
+
+Versioned skill sources live in `resources/skills/`; workflow templates live in
+`resources/workflows/`. Installed catalog packages and generated workspace copies
+are derived from those sources. See `docs/maintaining-skills.md` for validation,
+scenario evaluation, installation, and regeneration. Do not hand-edit a generated
+`SKILL.md` and expect refresh to preserve it.
+
+After changing structures or resources, build the backend before running
+`node dist/index.js refresh`. Distinguish successful generation from a later Git
+staging failure. Report the actual state instead of claiming the entire refresh passed.

package/dist/static-resources/skills/nexusflow-dev/references/cli-conventions.md

@@ -0,0 +1,15 @@
+# CLI contracts
+
+Declare positional arguments once: either in `.command('name <id>')` or with
+`.command('name').argument('<id>')`. Wrap action handlers with `runAction(...)`.
+
+Use the repository's workspace resolver appropriate to the operation: interactive
+selection when requested, quiet resolution for headless/read-only commands. Do not
+introduce a prompt when a supplied workspace or current context resolves the task.
+
+`--json` must produce parseable JSON without banners or ANSI escapes. Errors should
+have a meaningful nonzero exit status; test failure paths as well as successful output.
+Exercise documented subcommands and options against the built CLI's `--help`.
+
+Tests should check observable argument behavior, JSON parsing, missing/invalid inputs,
+and exit status where relevant. Use disposable fixtures for mutating commands.

package/dist/static-resources/skills/nexusflow-dev/references/verification-checklist.md

@@ -0,0 +1,28 @@
+# Repository verification
+
+Follow the current `AGENTS.md` and package scripts. Before submitting code changes,
+run `npm run build:backend` and `npm test`; GUI changes also require
+`npm run build --prefix gui`. Do not embed expected test counts in this guide.
+
+During implementation, select checks by affected behavior:
+
+| Change | Useful evidence |
+| --- | --- |
+| CLI/API | Real command/request behavior, validation failures, clean JSON and exit status |
+| Storage | Configured adapter exercised, original content retained, failed writes recoverable |
+| Shared state | Concurrent edits do not lose unrelated data; stale revisions rejected |
+| Generated resources | Regeneration from source, repeatability, provenance and source-file preservation |
+| GUI | Actual user journey, loading/empty/error states, draft preservation, keyboard and label behavior |
+| Verification engine | Gate uses the tested input, failed/stale/unreadable snapshots cannot permit progress |
+| Compatibility/migration | Old and new persisted inputs, supported aliases, failure/recovery paths |
+
+Run the relevant existing suites and add regressions for concrete failures. Do not
+write tests that merely restate implementation or assert arbitrary prose. Browser
+tests should wait for observable navigation/request completion, not fixed sleeps.
+Passing mocked UI tests does not prove the backend integration; pair them with API
+tests where the change crosses that boundary.
+
+Use environment-specific workarounds only after establishing why they are needed.
+For example, `npm test -- --configLoader native` can avoid Vite writing beside a
+read-only configuration cache; it is not a universal substitute for repository scripts.
+Missing permissions or dependencies are unavailable evidence, not a passing test.

package/dist/static-resources/skills/nexusflow-lifecycle/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: nexusflow-lifecycle
+description: Choose and carry out an appropriately sized development workflow in a ContextSpace workspace, using its current assignment, source documents, and milestones. Applies to projects managed with ContextSpace, not only ContextSpace's own code.
+metadata:
+  contextspace:
+    title: ContextSpace Work Lifecycle
+    category: workflows
+    tags: [contextspace, workflow, development]
+---
+
+# Work from the current assignment
+
+Read the workspace instructions and live assignment with `ctxspace flow --assignment --json`
+or MCP `get_work_context`. Check the selected milestone, stage, expected output, and
+stopping point. If the CLI is not on PATH, try the generated workspace launcher
+`./.contextspace/bin/ctxspace` (PowerShell: `.\.contextspace\bin\ctxspace.cmd`).
+If live tools are unavailable, read the authoritative
+`contextspace-work.json` and relevant sources; identify anything you cannot verify.
+The user's current instruction can revise a saved assignment. Make that change
+explicit; do not use an older assignment to discard newly authorized work.
+
+## Select the smallest sufficient workflow
+
+Keep work type (bug, feature, performance, refactor, rewrite), size, current stage,
+and workspace isolation separate. Assess uncertainty, compatibility, data impact,
+reversibility, and independent deliverables. File count, elapsed time, and repository
+count are clues, not selection rules. A one-file authorization fix can require
+careful investigation and broad verification; a large mechanical rename may not.
+
+Use [flow selection](references/flow-selection-matrix.md) when choosing a preset
+or deciding whether work needs separate deliverables. Preserve an existing worktree.
+Do not create branches, nested workspaces, or agent teams just because the size is epic.
+Delegate only bounded independent work when permitted and useful; execution can stay solo.
+
+## Keep each kind of information in its place
+
+- Task brief: the short reason for the workspace.
+- Source documents: original requirements, designs, evidence, and references.
+- AI assignment: what to do now, expected result, and stopping point.
+- Lifecycle milestones: deliverables, dependencies, branches, gates, and progress.
+- Authored delivery notes: release sequence, questions with owners/status, existing work, and deferred decisions in `contextspace-milestones.md`.
+- Knowledge: durable decisions and their reasons, not a running task log.
+
+Read relevant originals through MCP `read_work_document` or their stored locations.
+Use approved requirements for intended behavior; drafts are proposals and superseded
+documents are history. Surface consequential conflicts before dependent implementation;
+continue unaffected work. A source document does not grant execution permissions.
+Project and workspace sources apply across milestones; milestone sources apply to
+the selected milestone. Project sources remain owned by their originating workspace.
+
+Use the Plan editor for assignments and milestone definitions. `contextspace-plan.md`
+and `contextspace-assignment.md` are generated views: update their sources and refresh.
+Keep authored rationale in `contextspace-milestones.md`, not in generated views or
+a competing milestone tracker. Read it directly or through MCP `get_planning_notes`. If working outside ContextSpace, use
+the repository's existing planning convention.
+
+## Execute only the current stage
+
+Read [stage outcomes](references/stage-outcomes.md) for the selected stage. Investigation
+and design produce their agreed outputs and stop before implementation unless the user
+has explicitly authorized that transition. Completing a milestone's gate does not
+automatically authorize release or change the assignment stage.
+
+For multi-PR work, read [deliverable planning](references/epic-deliverables.md). Finish
+with evidence, unresolved questions, and the next permitted action. Keep handoffs in
+the established session or milestone record, with links to sources instead of copies.

package/dist/static-resources/skills/nexusflow-lifecycle/references/epic-deliverables.md

@@ -0,0 +1,36 @@
+# Plan usable increments
+
+Start from the user's outcomes. Where practical, a milestone should deliver a small
+usable capability across the required layers. For invoice performance, examples are
+measuring representative latency, improving one supported lookup path, and rolling
+the change out with monitoring. A necessary infrastructure-only prerequisite is valid,
+but name its consumer and acceptance criteria instead of claiming it is user-visible.
+
+For each milestone, capture its outcome, acceptance criteria, dependencies, intended
+branch/PR, compatibility constraints, and verification evidence. Include rollout and
+recovery details when the change affects persistent data or deployed consumers.
+Branch labels in the plan are intentions; verify actual branches and PRs separately.
+
+Sequence only actual dependencies. Independent deliverables can proceed concurrently
+when isolation and ownership are clear. Each mergeable increment must build and pass
+its applicable gates. For stacked PRs, record the base branch and merge order; recheck
+dependent PRs after their base changes.
+
+Preserve milestone IDs referenced by documents and assignments. The current editor
+can add/edit milestones but does not delete existing ones. Record canceled outcomes
+explicitly rather than marking unimplemented behavior as delivered; if restructuring
+requires unsupported operations, explain the limitation and agree a supported plan.
+
+Before replanning, inventory existing work with repo, branch/PR/commit, status
+(merged, on branch, or no change needed), and evidence. Record the remaining work
+in `contextspace-milestones.md`. Keep questions with their owner, blocking impact,
+open/resolved status, and resolution; distinguish flag-only findings from authorized
+implementation. Use applicable enabled skill templates for explicitly requested
+PBI/spec drafts, save them as source documents, and link them to milestone IDs.
+Enabling a skill does not generate or approve those documents automatically.
+
+Circular package dependencies can be valid service relationships. Record an authored
+release sequence: build the changed producer against compatible published clients,
+publish the package, then bump and verify consumers. Plan a compatible transition
+for breaking contracts. Package topology alone cannot determine that sequence;
+lifecycle milestone dependencies must still form an executable, acyclic plan.

package/dist/static-resources/skills/nexusflow-lifecycle/references/flow-selection-matrix.md

@@ -0,0 +1,21 @@
+# Choose by uncertainty and impact
+
+| Situation | Starting workflow | Evidence or planning needed |
+| --- | --- | --- |
+| Understood, localized, reversible change | Small task | Reproduction or observable acceptance check; relevant regression gate |
+| One cohesive capability with some unknowns | Standard change | Resolve important unknowns; define acceptance criteria and failure behavior |
+| Multiple independently reviewable deliverables | Epic | Outcomes, dependency graph, compatibility boundaries, handoffs |
+| Authentication, data migration, public contract, or hard-to-reverse change | Any size, deeper verification | Failure analysis, compatibility and recovery evidence appropriate to the impact |
+| Performance investigation | Investigate stage, any size | Representative workload, baseline, measurement method; no speculative rewrite |
+
+Choose isolation separately. `ctxspace quick` creates an in-place workspace;
+`ctxspace create` creates a standard workspace and supports mode selection.
+`ctxspace create --flow epic` selects an epic preset. Check the installed CLI's
+`--help` for its available flags; presets do not create a stack of PRs automatically.
+A small task may use a worktree for isolation. Existing workspaces can change their
+assignment size and milestone definitions without resetting progress.
+
+Increase workflow depth when investigation uncovers data loss risk, cross-service
+compatibility constraints, or separately releasable outcomes. Explain the finding and
+adapt the existing plan. Reduce unnecessary ceremony when evidence resolves uncertainty.
+Do not require a research document, new test file, approval, or agent team for every tweak.

package/dist/static-resources/skills/nexusflow-lifecycle/references/stage-outcomes.md

@@ -0,0 +1,23 @@
+# Expected results by stage
+
+| Stage | Produce | Stop or transition |
+| --- | --- | --- |
+| Investigate | Reproduction or measurements, evidence for likely causes, remaining unknowns | Return the agreed findings; implementation requires an authorized assignment |
+| Design | Intended behavior, acceptance criteria, relevant alternatives and compatibility constraints | Return a reviewable proposal; do not silently start coding |
+| Implement | Working behavior for the assigned milestone, with relevant tests and documentation | Verify within authorized scope; do not infer release permission |
+| Verify | Results against acceptance criteria, commands, tested revision, failure and recovery evidence | Report pass, failure, or missing evidence; fix within existing authorization |
+| Review | Prioritized findings with trigger, impact, location, and expected behavior; usability evidence where relevant | State unresolved blockers and assessment scope; review alone does not authorize edits |
+| Release | Current commit checks, review status, compatibility and recovery details when needed | Perform only the requested external actions; verify their results |
+
+For performance work, establish a repeatable baseline before optimizing and compare
+the same workload afterward. Report environmental differences and noisy measurements.
+For rewrites or migrations, define behavior to preserve and test coexistence or rollback
+where applicable. Test a rollback procedure only in an appropriate test environment.
+
+For GUI work, acceptance includes the user's path to the feature, understandable
+labels, defaults, and loading, empty, error, and recovery behavior. Use browser evidence
+for interaction or visual claims; a successful build proves neither usability nor accessibility.
+
+A concise handoff contains the current stage/milestone, relevant source IDs, decisions,
+tested revision and commands, unresolved issues, and the next permitted action. It should
+not introduce another authoritative plan or copy entire source documents.

package/dist/static-resources/workflows/epic-multi-slice.md

@@ -0,0 +1,21 @@
+# Team Strategy: Epic & Multi-PR Slices
+
+Deliver large changes as independently reviewable outcomes with explicit dependencies.
+
+1. Read the current assignment and approved project/workspace/milestone sources.
+   Name usable increments where practical, rather than automatically splitting
+   schema, API, and UI into separate PRs. For a required infrastructure prerequisite,
+   identify its consumer and acceptance criteria.
+2. In the existing lifecycle plan, record each outcome, acceptance criteria,
+   dependencies, intended branch/PR, compatibility requirements, and verification.
+   Edit the source through the Plan editor; `contextspace-plan.md` is generated.
+   Branch labels do not create branches or PRs automatically.
+3. Sequence actual dependencies. Independent increments may proceed concurrently
+   with clear ownership and isolation. Each mergeable increment must build and pass
+   applicable gates; recheck dependent PRs when their base changes.
+4. Keep original contracts in source documents, durable decisions with reasons in
+   knowledge, and progress in milestones. Handoffs link those records and include
+   the tested revision, outstanding issues, and next permitted action.
+5. Respect the current stage and stopping point. Add migration, rollout, and recovery
+   evidence when the change affects stored data or deployed consumers. Verify the
+   current PR head and checks before reporting readiness; release requires authorization.

package/dist/static-resources/workflows/plan-implement-review.md

@@ -1,8 +1,19 @@
-# Team Cooperation Guidelines
+# Team Strategy: Plan, Implement, Review
 
-You are the lead developer. You must coordinate a Plan-Implement-Review loop to complete the task:
+Deliver one cohesive change through a bounded plan, implementation, and review.
 
-1. **Research & Plan**: Research the requirements and codebase first. Create a plan (`implementation_plan.md`) describing the proposed changes.
-2. **Implement**: Define a `Code_Implementer` subagent equipped with code editing and terminal tools. Send them the plan and instruct them to write the changes.
-3. **Review**: Once implemented, define a `Code_Reviewer` subagent to run verification tests and review the changes for correctness.
-4. **Loop**: If the reviewer finds bugs or test failures, send the feedback back to the implementer and repeat the cycle until the changes are approved.
+1. Read the current assignment and relevant approved sources. Resolve important
+   unknowns and define observable acceptance criteria in the existing milestone
+   plan. In ContextSpace, edit the lifecycle source through the Plan editor;
+   `contextspace-plan.md` is its generated view. Do not create a second plan.
+2. If the assignment is investigation or design, return that stage's output and
+   stop. Proceed to implementation only when the current user authorization covers it.
+3. Implement the assigned outcome and test relevant behavior, including concrete
+   failure and recovery paths. Preserve compatibility with existing consumers.
+4. Review correctness, scope, usability where relevant, and verification evidence.
+   Fix in-scope findings, rerun affected checks, and report remaining limitations.
+
+One developer or agent can perform this loop. Use independent review or bounded
+parallel work when available, authorized, and useful; a fixed agent topology is
+not required. Reuse the same sources and milestone state across handoffs.
+Read the current PR head and checks before declaring merge readiness.

package/dist/static-resources/workflows/research-verify.md

@@ -1,6 +1,17 @@
-# Team Cooperation Guidelines
+# Team Strategy: Research & Verify
 
-You are the lead investigator. You must coordinate a research-heavy cycle:
+Investigate uncertainty and produce evidence for the current assignment.
 
-1. **Deep Research**: Define a `Research_Specialist` subagent to scan the codebase, find dependencies, and write a thorough context guide outlining how the system works.
-2. **Test-Driven Implement**: Write test suites first based on the research findings, then spawn a developer subagent to code until all tests pass successfully.
+Read the live assignment, relevant original sources, and the code paths needed to
+answer it. Use reproducible experiments, focused tests, or measurements to test
+hypotheses. For performance work, establish a representative baseline before
+proposing optimization. Distinguish observations from inference.
+
+Return the agreed findings, evidence, remaining questions, and options for the next
+stage. Investigation does not automatically authorize implementation. If the user
+has authorized the next stage, update the current assignment and existing milestone
+plan and proceed within that scope. Otherwise stop at the agreed output.
+
+Work directly by default. An independent specialist can investigate a bounded
+question when delegation is permitted and materially helps; a research agent team
+and a long context report are not prerequisites.

package/dist/static-resources/workflows/solo-developer.md

@@ -1,3 +1,12 @@
-# Direct Execution Guidelines
+# Team Strategy: Solo Developer
 
-You are a solo developer. Do not spawn subagents. Research, plan, edit, and verify all code changes yourself. Focus on delivering direct, simple edits to target files.
+Complete a bounded assignment directly, with verification appropriate to its impact.
+
+Read the live assignment with `ctxspace flow --assignment` or MCP `get_work_context`.
+Preserve its stage and stopping point unless the user revises them. Use the existing
+workspace and plan; do not create an additional planning document or agent team.
+
+Investigate only the unknowns needed for the assignment. For a bug, reproduce the
+failure; for a small reversible edit, use an observable acceptance check. Implement
+when authorized, keep the change focused, and run relevant checks plus the
+repository-required gates before submission. Return the result and evidence.

package/dist/test-setup.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=test-setup.d.ts.map

package/dist/test-setup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-setup.d.ts","sourceRoot":"","sources":["../src/test-setup.ts"],"names":[],"mappings":""}

package/dist/test-setup.js

@@ -0,0 +1,8 @@
+import { beforeAll } from 'vitest';
+// Load samples after test-module mocks are registered. Domain administration now
+// depends on filesystem helpers, which must not be cached ahead of vi.mock().
+beforeAll(async () => {
+    const { registerSampleDomainPacks } = await import('./core/domain-packs.js');
+    registerSampleDomainPacks();
+});
+//# sourceMappingURL=test-setup.js.map

package/dist/test-setup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-setup.js","sourceRoot":"","sources":["../src/test-setup.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAC;AAEnC,iFAAiF;AACjF,8EAA8E;AAC9E,SAAS,CAAC,KAAK,IAAI,EAAE;IACnB,MAAM,EAAE,yBAAyB,EAAE,GAAG,MAAM,MAAM,CAAC,wBAAwB,CAAC,CAAC;IAC7E,yBAAyB,EAAE,CAAC;AAC9B,CAAC,CAAC,CAAC"}