clawft

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-annotations

Commands

weft assess

Run an assessment with default scope (full) and format (table):

weft assess
WeftOS 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 config

weft assess run

Full form with all options:

weft assess run --scope <SCOPE> --format <FORMAT> [--dir <PATH>]
FlagValuesDefaultDescription
--scopefull, commit, ci, dependencyfullWhat to scan
--formattable, json, github-annotationstableOutput format
--dirpath.Project directory
--pr-numbernumber—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 status

weft 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 existing

Scopes

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-annotations

Configuration

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 = true

Cross-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-status

The 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:

AnalyzerCategoryWhat it checks
ComplexityAnalyzercomplexity, technical-debtFiles exceeding 500 lines, TODO/FIXME/HACK markers
DependencyAnalyzerdependencyParses Cargo.toml and package.json, flags missing/wildcard versions
SecurityAnalyzersecurityHardcoded secrets, committed .env files, unsafe blocks in Rust
TopologyAnalyzertopologydocker-compose.yml services, Dockerfiles, Kubernetes manifests, .env files
DataSourceAnalyzerdata-sourceDatabase connection strings (postgres://, redis://, etc.), S3 refs, API base URLs
NetworkAnalyzernetworkMaps egress URLs, API endpoints, webhook configs from code and config files
RabbitMQAnalyzerrabbitmqDetects AMQP connection strings, queue/exchange declarations, event-driven patterns
TerraformAnalyzerterraformParses 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-assessor flag on the run command; the flag does not exist in its --help and nothing in crates/ implements it.
  • An assessment diff subcommand. The kernel has an AssessmentDiff type (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 use weft assess review for trend analysis over past assessments.

Assessment Review

weft assess review                # analyze the last 5 assessments
weft assess review --history 10   # analyze the last 10

Reviews 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 hook

Findings

Each finding has a severity level and category:

SeverityMeaning
criticalSecurity vulnerability or data leak — fix immediately
highArchitectural issue or significant risk
mediumCode quality concern — address in next sprint
lowInformational or minor improvement suggestion
infoObservation 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-annotations

Git Hook

Install a post-commit hook for automatic assessment on every commit:

weft assess hooks

This 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

On this page