@mrpatronz/nexusflow 2.11.0 → 2.12.0

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,62 @@
+---
+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 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.
+- 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.
+Do not create a second implementation plan. 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,22 @@
+# 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.

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"}

package/dist/types.d.ts

@@ -112,6 +112,8 @@ export interface ChatMessage {
 export interface ResumptionConfig {
     /** The command to run verification tests. */
     testCommand?: string;
+    /** Explicit verification command override (alias for testCommand). */
+    verifyCommand?: string;
     /** The command to spin up dev databases/mocks/caches. */
     mockCommand?: string;
     /** The command to start workspace services manually if needed. */
@@ -166,6 +168,9 @@ export interface IsolatedRepoInfo {
 }
 /** A feature workspace that spans one or more repos. */
 export interface Feature {
+    workType?: 'bug' | 'feature' | 'performance' | 'refactor' | 'rewrite';
+    /** Explicit lifecycle preset, preserved independently of branch naming. */
+    flowType?: 'quick' | 'feature' | 'epic';
     /** Unique identifier — the git branch name (worktree mode) or slugified workspace name (in-place mode). */
     id: string;
     /** Repo attachment mode. Absent in manifests written before modes existed — treat as 'worktree'. */
@@ -200,6 +205,10 @@ export interface Feature {
     resumption?: ResumptionConfig;
     /** Custom teamwork coordination instructions for the agent team. */
     teamworkInstructions?: string;
+    /** Optional organization/company identifier (e.g. 'acme'). */
+    organizationId?: string;
+    /** Active domain packs for this workspace (e.g. ['economy']). */
+    domainPacks?: string[];
     /** Explicit runtime/intra-repo seams that package dependency analysis cannot infer. */
     contracts?: Array<{
         from: string;
@@ -428,6 +437,33 @@ export interface WorkspaceStatus {
     activeAssistants?: AIAssistant[];
 }
 /** Persisted sync/validation state for a single repo in a workspace. */
+export type VerificationStatus = 'pass' | 'pass_dirty' | 'fail' | 'timeout' | 'no-tests' | 'skipped';
+/** Detailed mechanical verification proof for a single repo. */
+export interface RepoVerificationReport {
+    repoName: string;
+    repoPath: string;
+    status: VerificationStatus;
+    command: string;
+    exitCode: number | null;
+    headSha: string;
+    clean: boolean;
+    dirtyFiles?: string[];
+    durationMs: number;
+    stdout?: string;
+    stderr?: string;
+    error?: string;
+    verifiedAt: string;
+}
+/** Aggregate mechanical verification report across all repos in a workspace. */
+export interface WorkspaceVerificationReport {
+    workspacePath: string;
+    overallStatus: VerificationStatus;
+    canProgress: boolean;
+    verifiedAt: string;
+    durationMs: number;
+    repos: RepoVerificationReport[];
+}
+/** Persisted sync/validation state for a single repo in a workspace. */
 export interface RepoSyncState {
     /** Directory name of the repo. */
     repoName: string;
@@ -443,6 +479,48 @@ export interface RepoSyncState {
     lastValidationResult?: 'pass' | 'fail' | null;
     /** ISO timestamp of the last validation run. */
     lastValidatedAt?: string;
+    /** Last structured mechanical verification proof, if any. */
+    lastVerification?: RepoVerificationReport;
+}
+export type LifecycleStepStatus = 'pending' | 'in_progress' | 'verified' | 'completed' | 'blocked';
+/** A vertical slice or discrete development milestone in the workspace lifecycle. */
+export interface LifecycleStep {
+    id: string;
+    title: string;
+    description?: string;
+    branch?: string;
+    owner?: string;
+    status: LifecycleStepStatus;
+    dependsOn?: string[];
+    verificationCommand?: string;
+    requiresVerification?: boolean;
+    lastVerificationSha?: string;
+    lastVerificationStatus?: VerificationStatus;
+    completedAt?: string;
+}
+/** Information about sister branches and collaborator commits tracked in the workspace. */
+export interface BranchFleetMember {
+    branch: string;
+    repoName: string;
+    owner?: string;
+    isCurrent: boolean;
+    headSha?: string;
+    ahead: number;
+    behind: number;
+    lastCommitMessage?: string;
+    lastCommitAuthor?: string;
+    lastCommitDate?: string;
+    remoteTracked: boolean;
+}
+/** Machine-readable workspace lifecycle state. */
+export interface WorkspaceLifecycle {
+    revision?: number;
+    workspaceId: string;
+    flowType: 'quick' | 'feature' | 'epic';
+    currentStepId?: string;
+    steps: LifecycleStep[];
+    fleet?: BranchFleetMember[];
+    updatedAt: string;
 }
 /** State file saved to track per-repo sync/validation status (`.nexusflow-state.json`). */
 export interface WorkspaceState {
@@ -450,6 +528,10 @@ export interface WorkspaceState {
     workspacePath: string;
     /** Per-repo state, keyed by repo name. */
     repos: Record<string, RepoSyncState>;
+    /** Most recent workspace-wide mechanical verification result. */
+    lastVerification?: WorkspaceVerificationReport;
+    /** Active structured lifecycle state machine. */
+    lifecycle?: WorkspaceLifecycle;
     /** Timestamp when the state was last updated. */
     updatedAt: string;
 }
@@ -513,6 +595,10 @@ export interface SkillItem {
     description: string;
     /** Tags / Keywords for discovery. */
     tags?: string[];
+    /** Optional company / organization identifier (e.g. 'acme'). */
+    organization?: string;
+    /** Optional domain subsystem this skill belongs to (e.g. 'economy', 'hr'). */
+    domain?: string;
     /** Allowed / required tool primitives. */
     allowedTools?: string[];
     /** Typed arguments / parameters. */
@@ -527,6 +613,25 @@ export interface SkillItem {
     references?: SkillSupportingFile[];
     /** Helper scripts inside `scripts/`. */
     scripts?: SkillSupportingFile[];
+    /** Static assets, schemas, templates, diagrams inside `assets/`. */
+    assets?: SkillSupportingFile[];
+    /** Scope of the skill: 'workspace' for project-specific or 'global' for machine-wide catalog. */
+    scope?: 'workspace' | 'global';
+    /** Additional frontmatter metadata (custom properties, deeply nested configurations, etc.). */
+    metadata?: Record<string, unknown>;
+    /** Optional license expression or identifier. */
+    license?: string;
+    /** Optional environment/assistant compatibility statement. */
+    compatibility?: string;
+}
+/** Options for saving a skill to the global or workspace catalog. */
+export interface SaveSkillOptions {
+    scope?: 'workspace' | 'global';
+    workspacePath?: string;
+    category?: string;
+    overwrite?: boolean;
+    readonly beforeCommit?: () => Promise<void>;
+    readonly supportFileModes?: Readonly<Record<string, number>>;
 }
 /** A reusable Codex custom-agent definition. */
 export interface CodexAgentItem {
@@ -566,4 +671,74 @@ export interface WorkspaceSkillsConfig {
     /** Active enabled category IDs. */
     enabledCategories?: string[];
 }
+/** Universal conventions for a company / organization (e.g. Acme). */
+export interface OrganizationConventions {
+    /** Unique slug (e.g. 'acme'). */
+    id: string;
+    /** Human-readable company name. */
+    name: string;
+    /** Regex pattern enforced on commit messages (e.g. Jira issue key format). */
+    commitMessagePattern?: string;
+    /** Example commit message compliant with company standard. */
+    commitExample?: string;
+    /** Relative path to PR template file. */
+    prTemplate?: string;
+    /** Universal company rules injected into all assistant contexts. */
+    rules: string[];
+    /** True if this is a sample starter template rather than a user-created organization. */
+    isTemplate?: boolean;
+}
+export type CategoryType = 'vertical' | 'trait';
+/** Microservice / repository binding with target mode ('edit' vs 'reference'). */
+export interface CategoryRepoBinding {
+    name: string;
+    target?: 'edit' | 'reference';
+    description?: string;
+    suggestedTestCommand?: string;
+}
+/** A modular category & tag pack scoped to a subsystem or cross-cutting trait. */
+export interface DomainPack {
+    /** Unique category / tag slug (e.g. 'economy', 'workforce/payroll', 'compliance/gdpr'). */
+    id: string;
+    /** Human-readable category name (e.g. 'Economy & Invoicing', 'Payroll'). */
+    name: string;
+    /** Description of this subsystem's scope and rules. */
+    description: string;
+    /** Parent category slug for tree hierarchy (e.g. 'workforce' for 'workforce/payroll'). */
+    parent?: string;
+    /** Category classification: 'vertical' (business subsystem) or 'trait' (cross-cutting horizontal). */
+    categoryType?: CategoryType;
+    /** Associated organization ID if company-specific. */
+    organization?: string;
+    /** Keywords / tags for discovery and auto-matching from specs. */
+    tags: string[];
+    /** IDs of skills bundled in this category pack. */
+    skills?: string[];
+    /** Relative or absolute paths to reference context documents. */
+    contextFiles?: string[];
+    /** Category-specific mechanical verification command override. */
+    verifyCommand?: string;
+    /** Architectural, domain, or compliance rules. */
+    rules?: string[];
+    /** Repositories typically associated with this category. */
+    defaultRepos?: string[];
+    /** Microservice bindings with edit vs reference modes. */
+    microservices?: CategoryRepoBinding[];
+    /** True if this is a sample starter template rather than a user-created pack. */
+    isTemplate?: boolean;
+    /** True if this pack originated from built-in starter templates. */
+    builtin?: boolean;
+}
+/** Alias for DomainPack reflecting hierarchical Category & Tag Tree architecture. */
+export type CategoryTagPack = DomainPack;
+export interface ResolvedCategoryRules {
+    organization: OrganizationConventions | null;
+    domainPacks: DomainPack[];
+    verticals: DomainPack[];
+    traits: DomainPack[];
+    allRules: string[];
+    compositeVerifyCommand?: string;
+    editRepos: string[];
+    referenceRepos: string[];
+}
 //# sourceMappingURL=types.d.ts.map