ArchScope

English | 简体中文

Evidence-driven architecture reconnaissance for complex, multi-repository software systems—built for DeepSeek Harness.

See the system before changing the code.

ArchScope helps AI agents genuinely take over an unfamiliar software system—not merely browse directories, count files, or produce an architecture summary that sounds complete.

It brings source discovery, evidence collection, system modeling, project profiling, layer gates, parallel orchestration, deterministic validation, and an architecture portal into one recoverable, verifiable, and extensible scanning protocol, delivered as a native DeepSeek Harness plugin.

Project status: v0.3.3 adds parent-owned deterministic Spring facts, paged project-evidence inputs, unified project-batch, specialization-routing, and short-task-envelope protocol loops; the npm package is not yet published. ArchScope can discover and index Git projects, run isolated system evidence workers, hand lossless evidence to the current DSH main agent, and enforce deterministic gates. Once the system gate is ready, single- and multi-project requests use the same bounded batch engine: each project gets isolated evidence and writer agents, lossless paging, structured conflict accounting, deterministic validation, and versioned publication. Runtime evidence and resume orchestration remain under development.

Core model: system level defines the worldview, project level defines the engineering profile, module level defines internal boundaries, and code level defines concrete paths.

Module analysis maps capabilities and responsibilities horizontally; code analysis follows real execution paths vertically.

Why ArchScope

When an agent enters a large codebase for the first time, the easiest result to produce is one that is locally correct but globally wrong:

• seeing a dependency and assuming it is enabled in production;
• seeing a few directories and treating them as the real business boundaries;
• scanning one repository while ignoring its role in the wider system;
• generating pages of conclusions with no traceable evidence;
• dispatching parallel agents without a shared fact base or conflict resolution;
• losing a session and no longer knowing what was completed or which results remain trustworthy.

ArchScope starts from a different premise:

Architecture understanding is not a one-shot code summary. It is an engineering process—from evidence to conclusions and from local detail to system context—that must be verifiable and recoverable.

What makes ArchScope different

Evidence before conclusions

Every important conclusion should point to reviewable evidence. Anything that cannot be proven must be marked for confirmation. A capability visible in source code is not necessarily enabled in production.

Establish the system worldview before profiling projects

ArchScope does not let multiple agents independently interpret a system without shared context. A system-level fact base first aligns production boundaries, project identities, infrastructure, entry points, and terminology. Project-level analysis then inherits those facts.

Let models reason; let programs enforce discipline

Models handle judgment and synthesis. Deterministic programs handle state machines, task plans, contract validation, identity resolution, batch recovery, exact relation statistics, portable-path checks, and credential-secret checks.

Multi-repository from day one

Project identity is based on the workspace-relative path, not the directory basename. Repositories with the same name, nested repositories, aggregation directories, and composite projects are never silently merged.

Native to the plugin runtime

ArchScope is not a long prompt wrapped in an npm package. It is designed around Cordis services, model-facing tools, capability providers, and a Harness bundle so that scanning capabilities can be composed, replaced, hot-reloaded, and reused.

Analysis model

ArchScope uses layers to control analysis order and the boundaries of each conclusion:

The internal map is optional navigation and does not claim to be the one correct module decomposition. Module studies and code traces both require a project profile, but neither depends on the other.

Project specialization and task envelopes

The parent coordinator deterministically freezes one specialization and template before dispatch. Spring-family Java backends, Vue/Web frontends, WeChat Mini Programs, native Android, native iOS, and generic projects use distinct evidence and writer identities. A Java build enters the Spring backend path only when an executable Spring Framework, Spring Boot, or Spring Cloud service boundary is proven.

For Spring backends, the parent also produces a DETERMINISTIC_FACTS dataset and deterministic-facts.json. Maven modules, local configuration files, Controller/Mapper files, and supported Spring annotation counts are measured directly from bounded project files. Agents may interpret these metrics but cannot replace them. The statistics section is rendered from the machine dataset, while unsupported zero/absence claims and conflicting counts in prose or diagrams block publication.

Evidence and writer agents initially receive only a short envelope containing the run ID, project identity, frozen specialization, tool names, and versioned protocol resource IDs. System facts, safe metadata, common rules, specialization checklists, and Markdown templates are fetched through read-only tools instead of being embedded in the first prompt. Evidence workers losslessly page through parent-redacted SAFE_METADATA and DETERMINISTIC_FACTS first, then the matching system evidence and system fact base; byte cursors preserve oversized records without relying on prompt-tail attention. The server derives an allowlist from the active run phase and frozen specialization, records reads in a ledger, and rejects progress or commit until every required dataset and resource has been loaded.

How it works

flowchart LR
    A["Workspace and repositories"] --> B["Project discovery and code intelligence"]
    B --> C["System fact base"]
    C --> D["Project profiles"]
    D --> E["Internal maps"]
    D --> F["Module studies"]
    D --> G["Code traces"]
    C -. "fact inheritance" .-> D
    H["Evidence fidelity and credential rules"] -.-> C
    H -.-> D
    I["Contracts, gates, and validation"] -.-> C
    I -.-> D
    I -.-> E
    I -.-> F
    I -.-> G
    C --> J["Documents, machine state, and architecture portal"]
    D --> J
    E --> J
    F --> J
    G --> J

A complete scan is not one giant prompt. It is a sequence of inspectable stages:

1. Recursively discover real Git repositories and assign stable identities.
2. Select and record the available code-intelligence capability, such as a code graph, LSP, or file search.
3. Collect system-level evidence; a single writer normalizes terminology and resolves conflicts.
4. Pass the system gate before analyzing projects in isolated contexts.
5. Use immutable task snapshots and machine-readable run state for parallel work.
6. Deterministically validate document structure, evidence references, state fields, and sensitive values.
7. Enter internal maps, module studies, or code traces only when needed.
8. Aggregate the result into human-readable reports and a navigable architecture portal.

Current MVP experience

ArchScope is designed to accept natural-language intent through Harness tools. The user-facing tools are archscope_scan_system, archscope_scan_projects, the compatibility entry point archscope_scan_project, and archscope_status; internal context, lossless paging, staged-artifact, and finalization tools support isolated project writers, and deeper analysis tools will be added behind the same service boundary.

Build a system-level fact base for this workspace.

Analyze the role of order-service in the wider system.

Scan every project that passes the gate in parallel. Preserve failed tasks so the run can resume.

Trace the order endpoint from its controller to database writes and message publication.

For deterministic, scriptable control, the same intents use one strict command namespace:

/archscope system [--refresh]
/archscope project <project-key> [--refresh]
/archscope projects --all [--refresh]
/archscope projects <project-key...> [--refresh]
/archscope help

The Chinese aliases 系统级扫描, 项目级扫描, and 帮助 are also accepted. Slash-command input is parsed strictly and never guessed; invalid input returns usage guidance. system performs discovery, independent indexing, and per-project evidence collection, then hands the run to the current DSH main agent. The main agent loads the complete system protocol and structured evidence, synthesizes the fact base and three diagrams, and submits them for deterministic validation. Progress and quarter milestones remain visible in the main conversation. A first scan—or a run with --refresh—can take substantial time; a normal run reuses indexes matched by the project's exact absolute root. Completed runs, and compatible runs awaiting main-agent synthesis, can be reused; BLOCKED runs are retried instead of permanently caching failure.

DeepSeek Harness currently does not dispatch Slash Commands from a completely blank new session. Select an existing session, or send a normal message to create the session before running /archscope. The command candidate itself displays this limitation so a silent first interaction is less surprising.

/archscope and /archscope help publish the guide back into the conversation as a normal assistant response. The command result itself stays empty, avoiding a long help document that looks like a tool or thinking card.

The project gate can become READY once source-level indexes and evidence are complete. This does not claim that the production topology has been confirmed. Missing MCP tools, failed indexes, failed workers, or scope violations keep the gate BLOCKED. system, project, projects, and help are public Slash Commands. A project batch accepts exact projectKeys from one pinned system registry and requires the system state to be COMPLETED / PASSED / READY; a single-project request is the same batch engine with one selected key. Each project gets isolated evidence and writer agents, while the caller receives aggregated result envelopes. Output is staged as one profile plus three diagrams and finalized only when all four artifacts are present. A bad evidence path gets one targeted repair attempt, and one failed project does not erase sibling results.

Lower-level findings never silently overwrite the pinned system fact base. Refinements need no reconciliation; source and cross-project contradictions are recorded as OPEN while non-blocking project artifacts may still publish; stale upstream bindings and identity mismatches block only the affected project. A later single-writer system reconciliation may create a new system revision after the batch finishes.

The planned model-facing surface will grow around capabilities like these:

scan system
scan project
scan all projects
build project map
scan module
trace code
show status
resume run
validate artifacts

Users should interact with a small set of clear analysis intents, not a long list of platform-specific commands.

Current system-scan artifacts

By default, ArchScope writes analysis artifacts to an isolated output directory and does not modify business code:

archscope_docs/
├── system/
│   ├── 00-system-fact-base.md
│   ├── project-registry.json
│   ├── index-manifest.json
│   ├── evidence/
│   │   ├── index.json
│   │   └── <project-key>.json
│   ├── relations.json
│   ├── protocol-lock.json
│   ├── synthesis.json
│   ├── validation.json
│   ├── history.json
│   └── diagrams/
│       ├── 01-system-context.mmd
│       ├── 02-internal-relations.mmd
│       └── 03-entry-overview.mmd
├── runs/
│   ├── latest.json
│   └── <run-id>/
│       ├── state.json
│       ├── system/                    # immutable terminal snapshot
│       │   ├── 00-system-fact-base.md
│       │   ├── evidence/
│       │   └── diagrams/
│       └── synthesis/
│           └── attempt-<n>/
│               ├── attempt.json
│               ├── 00-system-fact-base.md
│               └── diagrams/

system/ always represents the latest validated, published fact base. A fresh scan stages all registry, index, and evidence files below its own runs/<run-id>/system/, so an in-progress or failed run cannot erase the previous usable documents. Each terminal synthesis receives a monotonic document revision such as S0001; terminal snapshots and every synthesis attempt are retained by default. system/history.json links revisions to run ids, validation and gate states, immutable artifact roots, and the revision currently published under system/.

Each project's raw structured evidence is written separately before the current DSH main agent synthesizes the fact base. The main agent first receives a protocol-and-manifest bootstrap below the DSH inline threshold, then calls archscope_get_system_synthesis_page to sequentially read the project registry, index manifest, complete relation catalog, and every project evidence record under a fixed UTF-8 byte budget. Paging changes only transport batches: it never compacts, summarizes, truncates, or discards source records. Oversized records are split only at UTF-8 character boundaries and reconstructed losslessly by byte offset. SHA-256 digests protect every page, record, and dataset, while the server persists cursors, covered record keys, and page digests in the run's synthesis/read-ledger.json; commit is rejected until all four datasets are covered. The main agent still owns cross-project understanding, terminology, relationship judgment, conflict arbitration, and final prose; deterministic regex and name matching remain candidates rather than conclusions.

ArchScope records the writer session, model, and input/output digests in system/synthesis.json, and preserves every submitted draft plus its validation report under the run's synthesis/attempt-<n>/ directory. It validates Markdown and Mermaid artifacts for structure, evidence boundaries, exact agreement with machine-owned relation statistics, portable paths, atomic project-relative evidence files, credential leakage, explicit diagram edge semantics, and agreement between active project blockers and the downstream gate. Project-list and historical-project sections are also prevented from leaking controller, method, source-file, configuration-audit, or defect details. Route, symbol, configuration, and implementation details remain in per-project evidence JSON. With complete source evidence and no active project-level blocker, the document may be marked complete for the source view and the project gate may open; runtime facts remain explicitly unconfirmed.

Code definitions, routes, and call relationships remain codebase-memory-first. For manifests, READMEs, CI, containers, and deployment configuration that graphs often miss, ArchScope collects a bounded metadata baseline in the parent process with project-root containment, symlink rejection, file and aggregate size limits, and credential-value removal before model injection. Local fact artifacts preserve real service names, domains, IPs, routes, tables, topics, queues, and other architecture identifiers. Evidence workers do not receive arbitrary filesystem reads, shell access, or write capabilities.

System Protocol Pack

ArchScope ships system-level analysis knowledge as a versioned protocol/ directory. The pack contains machine contracts for evidence, project identity, index state, the 22-section system document, and layer gates; Markdown policies for analysis boundaries, local fact fidelity and credential handling, output paths, and validation; a complete system-writer instruction that is actually injected into the current DSH main agent; and a focused prompt for read-only evidence workers.

The plugin loads and validates this catalog at runtime. Every scan writes system/protocol-lock.json with the pack version plus SHA-256 digests for the manifest and every resource. A changed pack therefore creates a new run instead of silently reusing results produced under different rules. Script-worthy invariants are implemented in TypeScript and tested; the Markdown remains inspectable protocol content, not an unenforced appendix.

Configuration

The ArchScope bundle also mounts the official DeepSeek Harness @deepseek-ai/dsh-mcp-client and starts codebase-memory-mcp over stdio. Before starting DSH, make sure that executable is available on PATH:

command -v codebase-memory-mcp

After installing the plugin, verify that both configuration layers are present:

dsh --profile web --dump-config | rg -n -C 6 "archscope-codebase-memory|codebase_memory_mcp|dsh-archscope"

For local development, run pnpm install followed by pnpm check. ArchScope is not yet published to npm, so the public install command will be documented with the first release.

Plugin architecture direction

ArchScope is designed around the following internal boundaries:

ArchScope Bundle
├── ArchScope Service
│   ├── Scan state machine
│   ├── Tasks and recovery
│   ├── Artifact management
│   └── Contract validation
├── Model-facing Tools
├── Capability Providers
│   ├── Code Intelligence
│   ├── Workspace Discovery
│   ├── Subagent Orchestration
│   └── Runtime Evidence
├── Analysis Protocol
│   ├── Prompts
│   ├── Evidence Rules
│   └── Layer Gates
└── Report and Portal Generator

A code graph will be the preferred discovery mechanism, but never the only one. ArchScope will use capability interfaces to support codebase-memory, LSP, file search, and future providers.

Discovery and distribution

ArchScope will follow the official DeepSeek Harness plugin discovery convention. At public release, this repository will carry the exact dsh-plugin GitHub topic so it can appear in the Harness plugin discovery ecosystem.

Discoverability alone is not enough. Every release must also:

• ship as an installable bundle with a dsh.bundle manifest;
• provide a prebuilt npm package so ordinary users do not need to build source during installation;
• support installation and removal with dsh plugin --profile <name> add <package>;
• expose its configuration layer through dsh --profile <name> --dump-config;
• document a copyable install command, compatible Harness versions, and a minimal verification path;
• manage compatibility changes with semantic versions, GitHub Releases, and explicit migration notes.

Being indexed by the topic does not imply endorsement by DeepSeek. ArchScope treats “discoverable, installable, and verifiable” as one release gate—not as a label alone.

Design principles

• Traceable evidence: Important conclusions must lead back to source, configuration, runtime material, operations documentation, or human confirmation.
• Bounded facts: “Visible in source,” “declared in configuration,” “runtime-confirmed,” and “enabled in production” are different states.
• Explicit uncertainty: Missing, conflicting, and low-confidence information is part of the formal result.
• Inherited upstream facts: Lower layers report conflicts for review instead of silently rewriting the system worldview.
• Deterministic gates: Rules that programs can decide should not depend on a model remembering to comply.
• Context isolation: Project and module tasks receive only the context required to complete their responsibility.
• Recoverable execution: Long-running, multi-project scans expose status, preserve failures, and resume after interruption.
• Local fact fidelity: Default artifacts preserve architecture identifiers exactly; later share-safe export must create a derived copy rather than rewrite the fact base.
• Safe defaults: ArchScope does not modify business code or expose secrets, tokens, passwords, private keys, API keys, or embedded credentials.
• Replaceable models and tools: The core protocol does not depend on one model, index engine, or code-search tool.

What ArchScope is not

• It is not a counter for lines, directories, and dependencies.
• It is not a giant prompt that pours every repository into one context.
• It is not an architecture-fiction generator that infers production topology from source alone.
• It is not an automatic source of truth that replaces architects, developers, or operations confirmation.
• It is not a coding agent that modifies or “helpfully refactors” the scanned business code by default.

ArchScope aims to provide a more trustworthy starting point and a path for analysis that can be deepened and reviewed over time.

Roadmap

Phase 1: Minimum trustworthy loop

• Establish the TypeScript plugin project and Harness bundle
• Define the ArchScope Service, configuration schema, and foundational tools
• Implement multi-repository discovery and stable project identities
• Package the system-level contracts, policies, prompts, and protocol lock
• Complete independent indexing, read-only evidence collection, system fact-base generation, and deterministic validation
• Test plugin loading and the tool pipeline without a live model API

Phase 2: Project analysis and recoverable orchestration

• Isolated single-project scans
• Unified selected/all-project batch execution with pinned system revisions
• Project-type detection and template selection
• Resume and lease-based failure recovery
• Subagent Provider integration for system-level read-only evidence workers
• Project-document contracts, structured conflicts, and quality gates

Phase 3: Deep analysis and system maps

• Project internal maps
• Module studies
• Code execution traces
• Architecture portal
• Runtime-evidence Providers

Phase 4: Open ecosystem

• Stable Provider interfaces
• Third-party project types and report Profiles
• Custom evidence sources and organization policy packs
• Headless, Web, and automation workflow integration
• Share-safe/public export command that derives a redacted copy without changing local fact artifacts
• Publish a prebuilt npm bundle and verify standard installation and removal
• Add the dsh-plugin GitHub topic and verify that ArchScope appears in the ecosystem discovery entry point

The roadmap will evolve alongside the Developer Preview APIs of DeepSeek Harness.

Contributing

At this stage, ArchScope needs careful discussion of problem boundaries and protocol design more than a large volume of feature code. Useful questions include:

• Which facts are hardest to establish when taking over a large multi-repository system?
• Which architecture conclusions must require runtime evidence?
• What context contamination and conflicts most often appear in parallel agent analysis?
• What report contracts work well for both human review and machine validation?
• Which code-intelligence Providers should be supported first?
• How should we measure whether an architecture scan is trustworthy, rather than merely long?

Interfaces, names, and directory layouts remain open for discussion before the first stable release. Once a public contract exists, migration paths and compatibility notes will take priority.

License

ArchScope is released under the MIT License.

Acknowledgements

• DeepSeek Harness, for the “Everything is a Plugin” agent harness and Cordis plugin runtime.

ArchScope does not try to draw a beautiful architecture diagram whose claims have never been proven. It cares whether every important claim on that diagram knows where it came from.