diff --git a/_bmad-output/planning-artifacts/briefs/brief-opencli-Razormind-2026-08-24/.memlog.md b/_bmad-output/planning-artifacts/briefs/brief-opencli-Razormind-2026-08-24/.memlog.md new file mode 100644 index 00000000..9c2d57e6 --- /dev/null +++ b/_bmad-output/planning-artifacts/briefs/brief-opencli-Razormind-2026-08-24/.memlog.md @@ -0,0 +1,13 @@ +--- +topic: OpenCLI Agent-First Operations System +updated: 2026-08-24T12:44 +--- + +- (event) 当前 Agent Home 被判定为错误方向：三栏空壳、虚假的 Requirements/Plan/Evidence、全 mock 验收以及登录状态 401；决定重新定义整套 Agent 系统，再进入 UX 和 Designer Pipeline。 +- (decision) 产品定位：OpenCLI 是本地部署的 Agent-first 爬虫与数据上游平台；通过 Agent 将采集目标持久化为项目，借助工作流发布插件，把浏览器执行节点与数据结果自动关联；负责信息获取与拆解，供下游 Agent 或其他系统消费；不做 SaaS 工作部署平台，也不接受低自动化、难部署、难扩展的工具形态，并需对齐现有 OpenCLI 与 CloseI。 +- (decision) 首要演进方向是 Deep Research：一级目标依次为实时获取信息、强化 Deep Research 能力、维护可信源数据链（最关键）。当前核心痛点是不智能、难部署、难复用；多源数据杂乱且缺少统一可消费契约，使下游 Agent 难以使用，Deep Research 能力因此薄弱。智能化应建立在可追踪、可复核、可更新的源数据链上，而不只是聊天交互。 +- (event) 上游 Issues/PRs 复核确认：产品不是从零开始。已合入的基础包括 thin-channel/thick-runner 采集框架、真实浏览器/Crawl4AI/RSS/OpenCLI 来源、MCP、SourceBinding 与受治理 Agent Control、DataFlow 清洗与 provenance、存储级去重、API-first runtime evidence、自托管安装、后端权威能力节点和 SearXNG/RSSHub；仍在开放或部分实现的包括 L1 通用采集节点与逐源 lineage、多 Agent CAS 编辑、schema drift 传感器与适配器自愈、统一插件中心、持久 Agent Run 和外部 Agent runtime。 +- (decision) Product Brief 必须采用存量能力收束而非重造：将 OpenCLI 定义为分层的本地 Deep Research 数据上游——Acquisition Plane 负责实时多源采集，Evidence Plane 负责原始内容、逐源结果、lineage、版本与运行证据，Research Plane 负责问题拆解、检索编排、冲突/缺口识别与带引用综合，Consumption Plane 通过 MCP/SDK/API 向下游 Agent/系统交付。 +- (event) 发现两项方向冲突需在 Brief 中显式裁决：Issue #15 将产品扩展为数据采集、处理与外部交付平台，且要求全局 Agent Dock；当前用户将边界收窄为本地爬虫/数据上游并正在质疑独立 Agent Home。Issue #15 应作为历史产品证据，而非无条件继承的最新权威。 +- (assumption) 当前最大缺口不是来源数量或节点数量，而是尚未形成一条面向 Deep Research 的统一、可查询、可引用、可复现、可更新的 Source→Snapshot/Record→Transform→Claim/Citation→Research Output 源数据链；这一判断需要结合现有数据模型和用户确认继续验证。 + diff --git a/_bmad-output/planning-artifacts/briefs/brief-opencli-Razormind-2026-08-24/brief.md b/_bmad-output/planning-artifacts/briefs/brief-opencli-Razormind-2026-08-24/brief.md new file mode 100644 index 00000000..19260d77 --- /dev/null +++ b/_bmad-output/planning-artifacts/briefs/brief-opencli-Razormind-2026-08-24/brief.md @@ -0,0 +1,37 @@ +--- +title: OpenCLI Agent-First Operations System +status: draft +created: 2026-08-24 +updated: 2026-08-24 +--- + +# Product Brief: OpenCLI Agent-First Operations System + +## Executive Summary + +待通过产品发现补充。 + +## The Problem + +待通过产品发现补充。 + +## The Solution + +待通过产品发现补充。 + +## Who This Serves + +待通过产品发现补充。 + +## Success Criteria + +待通过产品发现补充。 + +## Scope + +待通过产品发现补充。 + +## Vision + +待通过产品发现补充。 + diff --git a/_bmad-output/specs/spec-opencli-Razormind/.memlog.md b/_bmad-output/specs/spec-opencli-Razormind/.memlog.md new file mode 100644 index 00000000..fa1dc626 --- /dev/null +++ b/_bmad-output/specs/spec-opencli-Razormind/.memlog.md @@ -0,0 +1,41 @@ +--- +topic: OpenCLI Local Deep Research Data Upstream +updated: 2026-08-24T14:15 +--- + +- (direction) Express distillation from the active Product Brief discovery, its canonical memlog, and first-party upstream Issues/PRs; unresolved product boundaries remain explicit. +- (decision) OpenCLI is a locally deployed, Agent-first crawler and Deep Research data upstream, not a SaaS work-deployment platform. +- (capability) CAP-1 Persistent Research Projects: an Agent or human can turn a research objective into one durable project whose workflow, sources, runs, evidence, and revisions survive sessions. +- (capability) CAP-2 Real-time Multi-source Acquisition: a project can continuously acquire current information through governed browser, web, API, RSS, and OpenCLI/plugin sources with per-source outcomes. +- (capability) CAP-3 Verifiable Source Chain: every research output can be traced through citations and claims to transformations, records or snapshots, source identity, acquisition run, workflow version, and timestamps. +- (capability) CAP-4 Deep Research Orchestration: the system can decompose a research objective, plan and execute multi-source retrieval, detect conflicts and evidence gaps, and produce a structured evidence-backed research output. +- (capability) CAP-5 Agent/System Consumption: downstream Agents and systems can discover capabilities and consume normalized records, evidence, provenance, run status, and research outputs through stable MCP, SDK, or HTTP contracts. +- (capability) CAP-6 Governed Reusable Extensions: source adapters, browser execution nodes, transforms, research operators, and sinks can be installed and published as versioned workflow/plugin capabilities with declared readiness and permissions. +- (capability) CAP-7 Local Deployment and Recovery: an operator can install, configure, run, observe, upgrade, and recover the complete platform locally without depending on an OpenCLI-hosted SaaS control plane. +- (capability) CAP-8 Unified Agent and Visual Editing: Agent interaction and manual UI operate the same authoritative project and workflow objects using proposals, revisions, validation, and durable execution evidence rather than chat-only shadow state. +- (constraint) Source-chain integrity is the highest-priority invariant; synthesis without resolvable citations and preserved raw evidence cannot be authoritative. +- (constraint) The system is local-first and self-hosted; hosted coordination may be optional but cannot be required for core acquisition, research, storage, or consumption. +- (constraint) Existing verified OpenCLI capabilities and merged contracts must be reused; catalog presence, previews, fixtures, and open PRs must not be represented as runnable production capability. +- (constraint) Agent and UI edits must converge on the same durable domain state; high-risk changes, credentials, publication, and external effects remain governed and auditable. +- (constraint) Plugins and workflows declare version, typed contracts, permissions, readiness, and failure semantics; unknown, stale, or unsafe capabilities fail closed. +- (decision) External business delivery and SaaS work orchestration are non-goals for the core product; downstream delivery is an optional plugin/consumer boundary. +- (decision) A generic chatbot, a generic low-code platform, an infrastructure topology product, and a UI that exposes the raw capability catalog as the primary experience are non-goals. +- (assumption) The spec assumes OpenCLI owns evidence-backed research outputs in addition to normalized evidence, pending explicit user confirmation of the synthesis boundary. +- (question) Must the first-party product produce final narrative research conclusions, or only structured evidence packages and citation graphs for downstream Agents to synthesize? +- (question) Should the primary Agent surface be a contextual global dock, a project-scoped workspace, or both, given the rejected standalone Agent Home and the older Issue #15 dock direction? +- (event) project-context.md was configured as a persistent fact but is absent; no facts were inferred from it. +- (event) Self-validation pass 1 (coherence): PASS — five kernel fields present; CAP-1 through CAP-8 are unique and each has one WHAT-level intent plus a demonstrable success criterion; constraints bend design; non-goals and a concrete end-to-end success signal are present; inferred boundaries are isolated as assumptions or questions. +- (event) Self-validation pass 2 (preservation): PASS — local-first crawler identity, persistent Agent projects, real-time acquisition, Deep Research, source-chain priority, downstream consumption, extensibility, deployment, existing merged foundations, open work, and Issue #15 boundary conflicts land in SPEC.md, brownfield.md, or source-chain.md. +- (event) Wrapper-only content dropped: empty Product Brief placeholder headings and workflow ceremony carry no load-bearing product contract. +- (direction) User separated two requirements: cross-device portability of previously authored projects/workflows is a product capability; administration of migration and related content belongs under Settings as a distinct information-architecture rule. +- (capability) CAP-9 Portable Project and Workflow Transfer: an operator can export a durable project or workflow from one OpenCLI instance and import it into another device or LAN deployment with preserved graph/version identity, explicit dependency preflight, connection remapping, and no secret leakage. +- (constraint) Settings is the authoritative administration surface for import/export, migration history, compatibility reports, dependency repair, connection remapping, backup, and restore; contextual project pages may link there but must not create a parallel migration authority. +- (question) Must a portable package support workflow-only transfer, full project transfer including records/evidence/run history, or both as explicit profiles? +- (event) Observed brownfield evidence on 2026-08-24: the Gaojixing project shell, one primary workflow, published v1, six runs, and 76 events exist in the current backend, but all runs are failed/blocked and the project has zero records, fields, and sources; the prior LAN migration is partial rather than complete. +- (event) Spec update self-validation pass 1 (coherence): PASS - CAP-9 is stable and unique, has one WHAT-level intent and a cross-instance demonstrable success criterion; Settings ownership is a separate design-bending constraint; all nine capabilities retain intent/success pairs. +- (event) Spec update self-validation pass 2 (preservation): PASS - the two user claims remain separate in SPEC.md and portability.md; current partial-migration evidence lands in brownfield.md; workflow portability, dependency preflight, secret exclusion, transactional import, Settings authority, and the unresolved historical-data profile are preserved. +- (decision) CAP-9 supports both explicit profiles: Workflow Package for reusable workflow definitions and dependency manifests, and Full Project Package for project metadata plus workflows, source descriptors, records, evidence, artifacts, run history, and audit provenance; neither profile contains reusable secrets or host-bound execution grants. +- (decision) The earlier portability-profile question is resolved: both profiles are mandatory first-class contracts, selected explicitly during export and verified independently during import. +- (event) Spec update self-validation pass 1 (coherence): PASS - CAP-9 remains one stable capability with both mandatory profiles named in its success criterion; the resolved profile question was removed; all nine capabilities retain complete intent/success pairs. +- (event) Spec update self-validation pass 2 (preservation): PASS - Workflow Package preserves reusable design and dependency contracts; Full Project Package preserves project state, records, evidence, artifacts, lineage, runs, events, checkpoints, and audit history; both exclude secrets and have independent conformance journeys. + diff --git a/_bmad-output/specs/spec-opencli-Razormind/SPEC.md b/_bmad-output/specs/spec-opencli-Razormind/SPEC.md new file mode 100644 index 00000000..a7285f7a --- /dev/null +++ b/_bmad-output/specs/spec-opencli-Razormind/SPEC.md @@ -0,0 +1,90 @@ +--- +id: SPEC-opencli-Razormind +companions: + - brownfield.md + - portability.md + - source-chain.md +sources: + - ../../planning-artifacts/briefs/brief-opencli-Razormind-2026-08-24/brief.md +--- + +> **Canonical contract.** This SPEC and the files in `companions:` are the complete, preservation-validated contract for what to build, test, and validate. Source documents listed in frontmatter are for traceability only. + +# OpenCLI Local Deep Research Data Upstream + +## Why + +Researchers and downstream Agents need current information, but heterogeneous sources, fragile acquisition, fragmented provenance, and chat-only automation make research difficult to reproduce or reuse. OpenCLI already contains substantial acquisition, workflow, evidence, Agent-control, and self-hosting foundations. The work is to converge them into a local-first Deep Research upstream whose intelligence is grounded in a durable source chain rather than rebuild another crawler UI or SaaS operations platform. + +## Capabilities + +- **CAP-1 — Persistent Research Projects** + - **intent:** An Agent or human can turn a research objective into one durable project containing its workflow, sources, runs, evidence, and revisions. + - **success:** After restart or session change, the project can resume from its persisted state and every run resolves to the project and exact workflow revision that produced it. + +- **CAP-2 — Real-time Multi-source Acquisition** + - **intent:** A project can continuously acquire current information through governed browser, web, API, RSS, and OpenCLI/plugin sources. + - **success:** A live mixed-source run records an outcome for every configured source, preserves successful results during partial failure, and reports blocked or failed sources without claiming completeness. + +- **CAP-3 — Verifiable Source Chain** + - **intent:** A consumer can trace every research claim and citation back through transformations to preserved source material and acquisition context. + - **success:** Given any published research claim, an API query resolves its citation, transformed record, raw snapshot or artifact, source identity, acquisition timestamp, run, and workflow version; any missing link makes the claim non-authoritative. + +- **CAP-4 — Deep Research Orchestration** + - **intent:** The system can decompose a research objective, coordinate multi-source retrieval, identify conflicts and evidence gaps, and produce a structured evidence-backed research output. + - **success:** A reference research task produces a persisted plan, source-backed findings, explicit conflicts and unresolved gaps, and citations that pass CAP-3 trace verification. + +- **CAP-5 — Agent and System Consumption** + - **intent:** Downstream Agents and systems can discover capabilities and consume normalized records, evidence, provenance, run state, and research outputs through stable machine contracts. + - **success:** An external Agent completes the reference research journey through MCP or HTTP without scraping the UI, and receives versioned schemas plus stable identifiers shared with the first-party interface. + +- **CAP-6 — Governed Reusable Extensions** + - **intent:** Operators can install and reuse versioned source adapters, browser nodes, transforms, research operators, and optional sinks as workflow/plugin capabilities. + - **success:** A certified extension declares typed inputs and outputs, version, readiness, permissions, and failure semantics; it compiles and runs when ready, while forged, stale, unverified, or unsafe capabilities fail closed. + +- **CAP-7 — Local Deployment and Recovery** + - **intent:** An operator can install, configure, run, observe, upgrade, and recover the complete platform on local infrastructure. + - **success:** A clean supported host passes an authenticated install-and-run smoke journey, executes the reference research task, retains data across restart, and restores operation without an OpenCLI-hosted SaaS dependency. + +- **CAP-8 — Unified Agent and Visual Editing** + - **intent:** Agent interaction and manual UI operate the same authoritative project and workflow state without chat-only shadow objects. + - **success:** Agent and human edits carry base revisions and concrete diffs; non-conflicting changes preserve both edits, conflicting or stale changes cannot overwrite newer state, and accepted changes appear identically through UI and API. + +- **CAP-9 — Portable Project and Workflow Transfer** + - **intent:** An operator can move a previously authored project or workflow between OpenCLI instances, devices, and LAN deployments without rebuilding it manually. + - **success:** Both a Workflow Package and a Full Project Package export from instance A import into a clean instance B with their profile-specific content preserved, produce explicit compatibility and missing-dependency reports, expose connection remapping without exporting secrets, and pass their independent conformance journeys after reported gaps are repaired. + +## Constraints + +- Source-chain integrity is the highest-priority invariant: synthesis without resolvable citations and preserved source evidence cannot be authoritative. +- Core acquisition, research, storage, and consumption must run locally; hosted coordination may be optional but cannot be required. +- Reuse merged and verified OpenCLI contracts. Catalog entries, previews, fixtures, open Issues, and open PRs must not be presented as production capability. +- Agent and UI operations share durable domain state. Credentials, publication, destructive changes, permission changes, and external side effects remain governed and auditable. +- Plugins and workflows declare versions, typed contracts, permissions, readiness, and failure semantics. Unknown, stale, unavailable, or unsafe capability bindings fail closed. +- Raw evidence and lineage survive cleaning, merging, retries, partial failure, workflow publication, and downstream export. +- Settings is the authoritative administration surface for import/export, migration history, compatibility reports, dependency repair, connection remapping, backup, and restore. Project pages may link into that surface but cannot create a parallel migration authority. + +## Non-goals + +- Operating a SaaS work-deployment or hosted data-processing platform. +- Becoming a generic chatbot, generic low-code builder, or infrastructure-topology product. +- Making external business delivery the core workflow; delivery remains an optional plugin or downstream consumer boundary. +- Treating the number of adapters, nodes, or catalog entries as proof of research quality. +- Recreating existing verified acquisition, workflow, MCP, evidence, or installation foundations under a parallel abstraction. +- Requiring operators to copy databases, edit package internals, recreate graphs, or transfer reusable credentials manually to move work between supported instances. + +## Success signal + +From a fresh local installation, an operator imports a project or workflow from another supported OpenCLI instance, resolves the reported local dependencies in Settings, and runs a persistent research project that acquires live multi-source information, produces a structured output with claim-level citations, and lets an external Agent traverse every citation to preserved source evidence through MCP or HTTP. Restarting or rerunning does not lose state or silently change the executed workflow version. + +## Assumptions + +- OpenCLI owns evidence-backed research outputs in addition to normalized evidence; the exact narrative-synthesis boundary still needs confirmation. +- OpenCLI and CloseI alignment means compatible capability and consumption contracts, not merging their product identities. + +## Open Questions + +- Must the first-party product produce final narrative conclusions, or only structured evidence packages and citation graphs for downstream Agents to synthesize? +- Should the primary Agent surface be a contextual global dock, a project-scoped workspace, or both? +- Which benchmark research journey and source set will be the release-level conformance test for CAP-1 through CAP-9? + diff --git a/_bmad-output/specs/spec-opencli-Razormind/brownfield.md b/_bmad-output/specs/spec-opencli-Razormind/brownfield.md new file mode 100644 index 00000000..d3564bd4 --- /dev/null +++ b/_bmad-output/specs/spec-opencli-Razormind/brownfield.md @@ -0,0 +1,41 @@ +# Brownfield Capability Baseline + +This companion prevents downstream work from confusing existing foundations with planned work. GitHub state is recorded as observed on 2026-08-24; implementation must recheck current upstream state before relying on an open item. + +## Verified merged foundations + +| Contract area | Evidence | What may be reused | +|---|---|---| +| Acquisition architecture | [PR #3](https://github.com/2233admin/opencli-Razormind/pull/3), [PR #4](https://github.com/2233admin/opencli-Razormind/pull/4) | Thin-channel/thick-runner model, retries, limits, cursoring, credentials, Crawl4AI, RSS, MCP | +| Cleaning and provenance | [PR #41](https://github.com/2233admin/opencli-Razormind/pull/41) | Versioned native data operators, graph execution, provenance, fail-closed behavior | +| OpenCLI acquisition and deduplication | [PR #42](https://github.com/2233admin/opencli-Razormind/pull/42) | Thick fetch contract, catalog-driven matching, storage-level deduplication proof | +| Governed sources and Agent control | [PR #45](https://github.com/2233admin/opencli-Razormind/pull/45) | Source bindings, proposal/revision control path, capability reconciliation | +| Governed workflow authoring | [PR #46](https://github.com/2233admin/opencli-Razormind/pull/46), [PR #48](https://github.com/2233admin/opencli-Razormind/pull/48) | Backend-authoritative sources, workflow authoring, real-source templates, partial-success semantics | +| Certified capability nodes | [PR #49](https://github.com/2233admin/opencli-Razormind/pull/49) | Version pins, typed ports, readiness, permissions, stale/forged ID rejection | +| Search and feed nodes | [PR #50](https://github.com/2233admin/opencli-Razormind/pull/50) | Governed SearXNG and RSSHub projections over existing executors | +| Local distribution | [PR #53](https://github.com/2233admin/opencli-Razormind/pull/53) | Public images, installers, authenticated login smoke, loopback browser surface | +| Agent-facing runtime evidence | [PR #58](https://github.com/2233admin/opencli-Razormind/pull/58) | HTTP/MCP demand, compile, lifecycle and trace surfaces; preview-versus-runtime boundary | +| Trigger-scoped execution | [PR #60](https://github.com/2233admin/opencli-Razormind/pull/60) | Authoritative compilation of the active trigger graph while retaining parked design nodes | + +## Open or partial work + +| Gap | Evidence | Contract relevance | +|---|---|---| +| Durable Project-centered product model | [Issue #15](https://github.com/2233admin/opencli-Razormind/issues/15) | Supports CAP-1 and CAP-8, but its external-delivery platform scope and Agent Dock direction are not automatically authoritative | +| L1 acquisition nodes and per-source lineage | [Issue #38](https://github.com/2233admin/opencli-Razormind/issues/38) | Supports CAP-2, CAP-3, and multi-Agent revision safety | +| Schema-drift sensing and adapter self-healing | [Issue #31](https://github.com/2233admin/opencli-Razormind/issues/31) | Supports sustained CAP-2 reliability; existing control machinery lacks complete channel signals | +| Unified plugin center | [Issue #25](https://github.com/2233admin/opencli-Razormind/issues/25) | Supports CAP-6 productization without multiplying top-level product areas | +| Durable observable Agent runs | [PR #70](https://github.com/2233admin/opencli-Razormind/pull/70) | Supports CAP-1 and CAP-8 but remains open and notes a dedicated test gap | +| External Agent runtime adapters | [PR #74](https://github.com/2233admin/opencli-Razormind/pull/74) | Supports runtime interoperability but remains open and one real provider path was blocked by billing | + +## Directional precedence + +1. The current user direction and this SPEC define the product boundary. +2. Merged, verified runtime contracts define the reusable technical baseline. +3. Open Issues and PRs are design evidence or candidate work, not shipped capability. +4. Issue #15 remains useful for persistent projects, revisions, workflow versions, and Agent governance, but its broad external-delivery platform identity is superseded by the local Deep Research upstream boundary. + +## Observed portability failure + +On 2026-08-24, the currently connected backend contained the migrated `gaojixing-doubao-evidence` project shell, one primary workflow, published version `v1`, six persisted runs, and 76 events. All six runs were failed or blocked, while the project Data Workbench reported zero records, zero fields, and zero sources. The frontend was also connected to a Docker backend launched from a different checkout with a different Fleet token. This proves partial object transfer, not a complete, compatible project migration, and is the brownfield motivation for CAP-9. + diff --git a/_bmad-output/specs/spec-opencli-Razormind/portability.md b/_bmad-output/specs/spec-opencli-Razormind/portability.md new file mode 100644 index 00000000..cc848da1 --- /dev/null +++ b/_bmad-output/specs/spec-opencli-Razormind/portability.md @@ -0,0 +1,89 @@ +# Project and Workflow Portability Contract + +CAP-9 defines portable work as a governed product contract, not database copying. + +## Package boundary + +A portable package must carry enough stable information to reconstruct the selected project or workflow without environment-owned secrets: + +- package schema version, producer version, export time, and integrity manifest; +- project and workflow identity required by the selected transfer profile; +- mutable draft revisions and immutable published workflow versions; +- node, edge, trigger, typed-port, capability, plugin, and version-pin references; +- source definitions, connection requirements, policies, and automation references as non-secret descriptors; +- declared optional payload classes such as records, evidence, artifacts, and run history when the selected profile includes them. + +Passwords, API keys, cookies, bearer tokens, reusable session credentials, host-specific paths, and active execution grants are never portable payloads. + +## Required package profiles + +### Workflow Package + +The reusable-design profile contains: + +- selected workflow identity, mutable draft revisions, and immutable published versions; +- graph structure, node parameters, triggers, typed ports, and validation metadata; +- plugin, capability, adapter, schema, and version-pin dependency manifest; +- source and connection requirements as non-secret descriptors; +- automation definitions in an inactive state when they are selected for export. + +It does not contain collected records, evidence, artifacts, or execution history. Import may create a new project, attach to a selected project, or create a reviewed new workflow revision according to the explicit collision plan. + +### Full Project Package + +The complete-state profile contains: + +- project identity, metadata, policies, memberships or role requirements, and all selected workflows; +- workflow drafts, immutable published versions, inactive automation definitions, and dependency manifests; +- source definitions and destination-side connection requirements without credentials; +- collected records, raw snapshots or artifact references and payloads, evidence units, claim/citation relationships, and lineage; +- workflow runs, events, checkpoints, errors, recovery state, costs, timestamps, and audit provenance; +- package-local integrity references that prove every included record, artifact, evidence edge, and run-history object was transferred or explicitly excluded. + +The full profile must preserve historical truth without activating old schedules, replaying external effects, or treating destination credentials and execution resources as transferable state. + +## Import lifecycle + +1. **Inspect:** Read the package without mutating authoritative state; verify integrity, schema, and producer compatibility. +2. **Preflight:** Report supported objects, blocked objects, missing capabilities/plugins, stale pins, unresolved connections, policy conflicts, and expected data volume. +3. **Plan:** Let the operator choose the required package profile, destination workspace/project, collision behavior, included payload classes allowed by that profile, and local connection mappings. +4. **Apply:** Import transactionally; failure must not leave a runnable half-project or overwrite an existing project silently. +5. **Validate:** Compile imported workflows and verify references without activating automations or creating external side effects. +6. **Activate:** Publishing or enabling imported automations remains a separate governed action. +7. **Audit:** Persist package identity, operator, decisions, mappings, warnings, result, and rollback or recovery status. + +## Settings ownership + +Settings owns the authoritative surfaces for: + +- package export and import; +- migration history and audit results; +- compatibility and dependency reports; +- plugin/capability installation and version repair; +- connection and credential remapping; +- backup, restore, and retention policy. + +Project and workflow pages may offer contextual actions such as “Export this workflow” or “Resolve imported dependency,” but those actions deep-link to the same Settings-owned operation and state. + +## Safety and compatibility invariants + +- Import is dry-run/preflight first and fail-closed on unknown schema or unsafe capability. +- Stable IDs are preserved where they identify portable history; local collisions are resolved explicitly and recorded. +- Reimport is idempotent or produces a reviewed new revision; it never creates silent duplicates. +- Missing plugins, sources, or connections leave the import visible but non-runnable rather than fabricating readiness. +- Connection mappings reference destination-owned credentials; packages never contain reusable secrets. +- Cross-version transforms are deterministic, versioned, and covered by fixture-based compatibility tests. +- Historical evidence retains its original source, time, workflow version, and package provenance when included. +- Full Project Package import is complete only when its manifest accounts for every selected record, evidence edge, artifact, and run-history object; silent omission is failure. +- Workflow Package and Full Project Package use distinct schema/profile identifiers and conformance tests; one cannot be mislabeled as the other. + +## Minimum conformance demonstrations + +### Workflow Package + +On instance A, export a published workflow that uses at least one plugin capability and one credentialed source reference. On a clean instance B with neither dependency configured, import preflight must identify both gaps without creating a runnable workflow. After installing the capability and mapping a destination-owned connection through Settings, the imported workflow must compile, preserve its graph and published-version identity, and complete a real run. Reimporting the same package must not duplicate the workflow or silently overwrite a newer local revision. + +### Full Project Package + +On instance A, export a project containing multiple workflow versions, at least one completed and one failed run, records, raw evidence, claim relationships, and run events. Import it into a clean instance B. The manifest reconciliation must account for every selected object; historical runs must remain non-executable history, citations must traverse to the transferred source evidence, automations must remain inactive, and no credential may be present. After destination dependencies are repaired in Settings, a new run must append new history without changing imported records, evidence, versions, or run events. + diff --git a/_bmad-output/specs/spec-opencli-Razormind/source-chain.md b/_bmad-output/specs/spec-opencli-Razormind/source-chain.md new file mode 100644 index 00000000..fef04354 --- /dev/null +++ b/_bmad-output/specs/spec-opencli-Razormind/source-chain.md @@ -0,0 +1,45 @@ +# Source Chain Contract + +CAP-3 is the governing contract. Exact storage schemas are architecture decisions, but every implementation must preserve the following semantic chain. + +```mermaid +flowchart LR + S[Source identity] --> A[Acquisition event] + A --> X[Raw snapshot or artifact] + X --> R[Normalized record] + R --> T[Versioned transformation] + T --> E[Evidence unit] + E --> C[Claim and citation] + C --> O[Research output] + W[Workflow version] --> A + U[Run and source result] --> A + U --> T +``` + +## Required identities + +| Object | Required stable context | +|---|---| +| Source | Source ID, source type, locator or account scope, adapter capability and version | +| Acquisition | Project ID, workflow version, run ID, source result, acquisition time, status, error classification | +| Raw material | Content hash, immutable artifact or snapshot reference, media type, capture metadata | +| Transformation | Operator identity and version, inputs, outputs, parameters or configuration reference | +| Evidence unit | Stable ID, normalized content, links to raw material and transformation history | +| Claim or citation | Stable ID, supported text or structured assertion, supporting evidence IDs, confidence or conflict state | +| Research output | Stable ID and revision, originating objective and plan, included claims, gaps, conflicts, creation time | + +## Invariants + +- No transformation, cleaning, merge, or export may erase upstream identity. +- Merge combines source results and lineage explicitly; it does not silently clean or deduplicate. +- Deduplication records equivalence without deleting the ability to inspect each acquisition occurrence. +- Partial success remains partial: successful evidence is usable, while absent or failed sources remain visible in completeness metadata. +- A claim with no traversable supporting evidence is draft or unsupported, never authoritative. +- Reacquisition creates a new temporal observation; it does not rewrite the evidence used by an older published research output. +- Workflow and capability versions used by a run are immutable references. +- Secrets, session cookies, and sensitive authentication data never enter lineage, trace, citation, or exported research payloads. + +## Minimum conformance demonstration + +Run one persistent project against at least three heterogeneous live sources with one intentional source failure. Produce a research output containing a supported claim, a conflicting claim, and an unresolved gap. Through the public MCP or HTTP surface, traverse the supported claim to its evidence, normalized record, raw artifact, acquisition event, failed sibling source result, run, and workflow version. Repeat acquisition after a source changes and prove that both observations and the older output remain reconstructable. +