Assessment Workflow
Run continuous SOP assessment against your codebase with weft assess — scoped scans, multiple output formats, and CI integration.
The WeftOS assessment workflow (weft assess) maintains a continuously updated picture of your codebase by scanning files, counting complexity, tracking dependencies, and surfacing findings. It's the entry point for SOP 4 (Continuous Assessment) from the deployment SOPs.
Quick Start
# Initialize assessment config
weft assess init
# Run a full assessment
weft assess
# Assess only last commit
weft assess run --scope commit
# CI mode with GitHub annotations
weft assess run --scope ci --format github-annotationsCommands
weft assess
Run an assessment with default scope (full) and format (table):
weft assessWeftOS Assessment Report
========================
Timestamp: 2026-04-03T12:00:00Z
Scope: full
Project: /path/to/my-project
Summary
-------
Files scanned: 142
Lines of code: 28,341
Rust files: 89
TypeScript files: 31
Config files: 12
Doc files: 10
Dependency files: 4
Coherence score: 11.2%
Complexity warns: 3
Findings (7 total)
---------
[ medium] src/engine.rs — 623 lines — consider splitting (target: `<500`)
[ medium] src/pipeline.rs — 518 lines — consider splitting (target: `<500`)
[ info] src/config.rs:42 — // TODO: validate provider configweft assess run
Full form with all options:
weft assess run --scope <SCOPE> --format <FORMAT> [--dir <PATH>]| Flag | Values | Default | Description |
|---|---|---|---|
--scope | full, commit, ci, dependency | full | What to scan |
--format | table, json, github-annotations | table | Output format |
--dir | path | . | Project directory |
--pr-number | number | — | PR number, reserved for a github-pr format that does not exist yet |
weft assess status
Show the results of the last assessment:
weft assess statusweft assess init
Create .weftos/weave.toml (assessment config), .weftos/artifacts/, .weftos/memory/ and an empty .weftos/peers.json (run_init in crates/clawft-cli/src/commands/assess_cmd.rs). If .weftos/weave.toml exists it stops unless --force is given:
weft assess init
weft assess init --force # overwrite existingScopes
full
Scans every file under the project with the extensions rs, ts, tsx, js, json, toml, md and mdx, skipping the directories node_modules, target, .git, .next, .weftos, .claude and .planning (collect_all_files and collect_files_recursive in assess_cmd.rs).
commit
Only files changed in the last git commit. Uses git diff --name-only HEAD~1 HEAD.
ci
All files changed relative to the main branch. Uses git diff --name-only origin/main...HEAD, or origin/master...HEAD when origin/main does not resolve. Ideal for PR pipelines.
dependency
Only dependency manifests: Cargo.toml, Cargo.lock, package.json, package-lock.json, yarn.lock, pnpm-lock.yaml.
Output Formats
table
Human-readable summary with file counts, LOC, coherence score, and a list of findings. Default for terminal use.
json
Machine-readable report saved to stdout. Also always saved to .weftos/artifacts/assessment-latest.json.
github-annotations
GitHub Actions annotation format. Each finding becomes a ::warning or ::error annotation that appears inline in PR diffs:
# .github/workflows/assess.yml
- name: WeftOS Assessment
run: weft assess run --scope ci --format github-annotationsConfiguration
Assessment configuration lives in .weftos/weave.toml (this is the file weft assess init writes, not the project-root weave.toml that weaver init writes). The kernel's assessment service loads it (AssessmentService::load_config); the one-shot weft assess scan collectors use their built-in extension and skip lists, shown under Scopes. weft assess init writes this:
[assessment]
version = 1
[assessment.sources.files]
patterns = ["**/*.rs", "**/*.ts", "**/*.tsx", "**/*.json"]
exclude = ["node_modules/**", "target/**", ".weftos/**", ".git/**"]
[assessment.triggers.filesystem]
enabled = false
debounce_ms = 2000
[assessment.triggers.scheduled]
enabled = false
cron = "0 2 * * *"
scope = "full"
[assessment.reporting]
default_format = "table"
save_artifacts = trueCross-Project Assessment
Link projects for comparative analysis:
# Link a local project: <NAME> <PATH to its .weftos/ directory>
weft assess link frontend /path/to/frontend/.weftos
# Link a remote project by URL
weft assess link api https://api.example.com/weftos/artifacts
# List linked peers
weft assess peers
# Compare your last assessment with a peer's
weft assess compare frontend
# Show assessment mesh peer state (needs a running daemon with mesh enabled)
weft assess mesh-statusThe cross-project mesh uses MeshCoordinator with AssessmentMessage protocol for gossip-based peer discovery and bidirectional assessment exchange. Linked projects share assessment summaries (not raw source code) for trend analysis and organizational benchmarking.
Multi-Project Namespace
Configure project identity in .weftos/weave.toml:
[project]
name = "my-service"
org = "acme-corp"The org field provides namespace isolation — projects within the same org can discover each other via mesh, while cross-org sharing requires explicit linking.
Pluggable Analyzers
The assessment runs a registry of pluggable analyzers. Eight are built in:
| Analyzer | Category | What it checks |
|---|---|---|
| ComplexityAnalyzer | complexity, technical-debt | Files exceeding 500 lines, TODO/FIXME/HACK markers |
| DependencyAnalyzer | dependency | Parses Cargo.toml and package.json, flags missing/wildcard versions |
| SecurityAnalyzer | security | Hardcoded secrets, committed .env files, unsafe blocks in Rust |
| TopologyAnalyzer | topology | docker-compose.yml services, Dockerfiles, Kubernetes manifests, .env files |
| DataSourceAnalyzer | data-source | Database connection strings (postgres://, redis://, etc.), S3 refs, API base URLs |
| NetworkAnalyzer | network | Maps egress URLs, API endpoints, webhook configs from code and config files |
| RabbitMQAnalyzer | rabbitmq | Detects AMQP connection strings, queue/exchange declarations, event-driven patterns |
| TerraformAnalyzer | terraform | Parses HCL files for infrastructure topology, provider configs, resource definitions |
Custom analyzers implement the Analyzer trait and register via AnalyzerRegistry.
Not yet implemented
- An LLM assessor agent. Earlier versions of this page showed a
--with-llm-assessorflag on the run command; the flag does not exist in its--helpand nothing incrates/implements it. - An assessment
diffsubcommand. The kernel has anAssessmentDifftype (crates/clawft-kernel/src/assessment/analyzer.rs) but no CLI command exposes it. To compare runs today, keep timestamped JSON artifacts (see Artifacts) and diff them yourself, or useweft assess reviewfor trend analysis over past assessments.
Assessment Review
weft assess review # analyze the last 5 assessments
weft assess review --history 10 # analyze the last 10Reviews assessment trends and generates SOP improvement recommendations.
Git Hooks
Install automatic assessment on every commit:
weft assess hooks # install post-commit hook
weft assess hooks --hook-type pre-push # install pre-push hook
weft assess hooks --uninstall # remove hookFindings
Each finding has a severity level and category:
| Severity | Meaning |
|---|---|
critical | Security vulnerability or data leak — fix immediately |
high | Architectural issue or significant risk |
medium | Code quality concern — address in next sprint |
low | Informational or minor improvement suggestion |
info | Observation with no action required |
Findings are stored in .weftos/artifacts/assessment-latest.json and logged to the ExoChain when the daemon is running.
CI Integration
GitHub Actions
name: Assessment
on: [push, pull_request]
jobs:
assess:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0 # needed for scope=ci
- name: Install WeftOS
run: |
curl -fsSL https://raw.githubusercontent.com/WeftOS/weftos/master/scripts/install.sh | sh
- name: Run assessment
run: weft assess run --scope ci --format github-annotationsGit Hook
Install a post-commit hook for automatic assessment on every commit:
weft assess hooksThis writes .git/hooks/post-commit, which runs weft assess run --scope commit. Use --hook-type pre-push for a pre-push hook and --uninstall to remove it.
Artifacts
Every assessment writes results to .weftos/artifacts/assessment-latest.json. This file is overwritten on each run. To keep a history, use the JSON format and redirect to timestamped files:
weft assess run --format json > ".weftos/artifacts/assessment-$(date +%Y%m%d-%H%M%S).json"Next Steps
- Deployment SOPs — Full SOP 1-4 reference
- ExoChain — How assessments are logged to the audit trail
- ECC — How the cognitive substrate uses assessment data
Deployment SOPs
Standard operating procedures for adding WeftOS to a project and keeping it assessed: from initial project setup to continuous assessment.
GUI Layer
How the WeftOS GUI is built today - the egui shell, the canon primitive vocabulary, TOML surface descriptions, the substrate RPCs, and the VS Code panel.