Software System Understanding

Software System Understanding is the goal. Workspace Intelligence is the architecture Workspai uses to move toward that goal.

AI does not only need code. It needs a reliable model of the software system.

The seven layers

These seven layers define the understanding problem. They are not a statement that every layer has equal implementation depth today. Workspai currently has its strongest contract-backed coverage in structure, selected relationships, change, evidence, freshness, verification, context, and explain/trace. Intent, long-term evolution, prediction, and broad architectural reasoning remain areas for deeper development.

1. Structure

Structure answers: what exists?

Examples:

• workspaces,
• projects,
• services,
• modules,
• packages,
• runtimes,
• commands,
• policies,
• contracts,
• generated reports.

2. Semantics

Semantics answers: what does each thing mean?

Examples:

• this project is an API service,
• this package is a frontend app,
• this command is a release gate,
• this contract defines agent customization output,
• this report is doctor evidence.

3. Relationships

Relationships answer: what is connected to what?

Examples:

• project depends on package,
• API depends on database,
• service is affected by a diff,
• command produces a report,
• agent surface reads a context pack,
• release gate depends on verification evidence.

4. Intent

Intent answers: why does this exist?

This is where most repository tools stop too early. A file graph can show that two modules are connected. It usually cannot explain why the boundary exists, why a runtime was selected, why a release gate blocks a change, or why an agent should trust one artifact over another.

Workspai treats intent as a product direction: decisions, contracts, policies, history, and evidence should make future explanation possible.

5. Evolution

Evolution answers: how did the system change?

Examples:

• workspace snapshots,
• model diffs,
• dependency edge changes,
• affected projects,
• changed policies,
• freshness drift,
• historical verification outcomes.

6. Trust

Trust answers: what can be used safely right now?

Facts should be treated as:

• verified,
• observed,
• inferred,
• stale,
• unknown.

An AI agent should not treat an old generated summary the same way it treats a fresh verification report.

7. Reasoning

Reasoning answers: what should we do next?

Examples:

• Why is release blocked?
• Which projects are affected by this diff?
• Which evidence is stale?
• What should an agent read before changing this service?
• Which verification gate failed?
• What is the safest remediation plan?

Reasoning is only useful when it is grounded in the model and evidence.

Category boundary

Repository Intelligence helps tools understand a repository.

Workspace Intelligence helps tools understand a software system: projects, runtime, ownership, change, evidence, policies, contracts, and agent-facing surfaces.