Assessment Workflow

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:      /home/user/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>]

weft assess status

Show the results of the last assessment:

weft assess status

weft assess init

Create .weftos/ directory structure and weave.toml config:

weft assess init
weft assess init --force    # overwrite existing

Scopes

full

Scans all files matching configured patterns (default: *.rs, *.ts, *.tsx, *.json). Excludes node_modules/, target/, .weftos/, .git/.

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

[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
weft assess link /path/to/other-project

# Link a remote project via HTTP
weft assess link https://other-host:8080

# List linked peers
weft assess peers

# Compare assessments across projects
weft assess compare

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

Custom analyzers implement the Analyzer trait and register via AnalyzerRegistry.

LLM Assessor Agent

The assessment framework can optionally spawn an LLM-powered assessor agent that analyzes findings for higher-order insights:

weft assess run --with-llm-assessor

The assessor reads the structured findings from all analyzers and produces narrative analysis: architectural risks, dependency patterns, security posture assessment, and recommended remediation priorities. It runs via the kernel's AgentSupervisor with standard governance and chain logging.

Assessment Diff

Compare the current assessment against a previous run to surface regressions and improvements:

weft assess diff
weft assess diff --baseline .weftos/artifacts/assessment-2026-04-01.json

Output highlights:

• New findings introduced since the baseline
• Resolved findings that no longer appear
• Changed severity — findings that got better or worse
• Metric deltas — LOC changes, file count changes, coherence score trend

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:

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://github.com/weave-logic-ai/weftos/releases/latest/download/clawft-cli-installer.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 hooks install --type post-commit

This creates .git/hooks/post-commit that runs weft assess --scope commit.

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