Workspace Governance Standard (WGS)

WGS is the constitutional layer for the Aptlantis workspace. It governs root structure, workspace manifests, project registration, standard relationships, workspace services, and agent orientation.

WGS treats the workspace as a governed ecosystem rather than a loose collection of repositories. Its job is to make projects discoverable, keep context recoverable, reduce repeated structural decisions, and give agents a predictable way to orient before making changes.

Status: Candidate v0.2.7

Document Suite

File	Purpose
Workspace Governance Standard.md	Primary WGS specification.
WGS.manifest.toml	Standard manifest.
Workspace-Governance-Implementation-Plan.md	Current implementation plan.
Workspace-Inventory.md	Current-state inventory.
Target-Directory-Map.md	Proposed target state.
Manifest-Conventions.md	Manifest naming and placement policy.
templates/AGENTS.root.md	Root instruction template.
templates/AGENTS.directory.md	Governed-directory instruction template.
templates/AGENTS.project.md	Project and project-group instruction template.
templates/DirectoryName.manifest.toml	Entity-named governed-directory manifest template.
templates/ProjectName.manifest.toml	Entity-named project and project-group manifest template.
templates/Development.manifest.toml	Development-drive identity and root-registry template.
templates/Project-README.md	Internal project orientation and handoff template.
templates/Workspace-Health-Record.md	Repeatable workspace health review template.
examples/City-Hall-Health-Record.md	Filled health record for City Hall.
Agent-Startup-Procedure.md	Required read order for agents.
tools/city_hall_audit.py	Entity-aware standards and workspace validator.
tools/workspace_inventory.py	Read-only physical/registered drift report.
tools/governance_scaffold.py	Dry-run-first entity scaffold and parent registration tool.
tools/snapshot_root_governance.py	SHA-256 checked root-governance recovery snapshot tool.
Documentation-Suite-Roadmap.md	Standards documentation normalization tracker.
Governance-Responsibility-Matrix.md	Ownership and collision rules across standards.
Reference-Index.md	Preserved planning lineage and conversation references.
Cleanup-Log.md	Record of root cleanup and reference relocation.

SFDS Suite Model

WGS.manifest.toml describes WGS as a standard suite (see the schema reference). The manifest templates under Templates describe workspace, directory, project, and standard records governed by WGS.

Core Model

WGS organizes the workspace around four layers:

• Standards layer: WGS, SFDS, PPS, DRS, CTS, SIS, WDS, DDS, and specialized standards.
• Projects layer: artifact-producing projects and technical systems.
• Shared services layer: workspace-level services, caches, automation, and agent support.
• Metadata layer: manifests, registries, relationship maps, inventories, and health records.

The metadata layer is the spine. It makes intent search, lifecycle visibility, and long-term project reactivation possible.

Metadata layer
  --> Standards layer
  --> Projects layer
  --> Shared services layer
Standards layer   --> Recoverable workspace context
Projects layer    --> Recoverable workspace context
Services layer    --> Recoverable workspace context

Metadata layer -. indexes .-> manifests
Metadata layer -. records .-> inventories
Metadata layer -. explains .-> relationship maps
Metadata layer -. checks .-> health records

Agent Rule

Agents must orient from inherited instructions, manifests, and governing documents before making broad changes. The normal read order is root-to-local AGENTS.md, directory manifest, project manifest, Project-README.md, canonical governing standards, and roadmap or handoff notes.

Workspace manifest --> Directory manifest --> Project manifest
  --> Project identity docs --> Governing standard --> Roadmap / handoff notes --> Scoped work

See the full Agent Startup Procedure for the complete read order and missing-document behavior.

Tone

WGS exists to reduce ambiguity, not to create paperwork. Every rule should help a future human or agent recover context, make fewer guesses, and avoid project drift.

---

Full Specification: Workspace Governance Standard

Status

Candidate v0.2.7.

WGS is the architectural constitution of the Aptlantis workspace. It governs the environment itself: where things live, how they are registered, how context survives, how agents orient, and how workspace health is judged.

Scope

WGS governs the Aptlantis workspace as a first-class system: root directories, project registration, manifests, workspace services, standard relationships, agent startup, lifecycle visibility, and workspace health.

Does Not Govern

WGS does not define how desktop apps release, how command tools print output, how services run, how websites deploy, or how datasets are licensed. Those responsibilities belong to DRS, CTS, SIS, WDS, DDS, and related standards.

Core Rule

Projects create artifacts. Standards govern projects. WGS governs the workspace where they live.

Paradigm

The workspace should not depend on memory. It should describe itself clearly enough that a paused project, standard, or service can be understood years later.

WGS is successful when it makes work easier to resume, not harder to start.

WGS shifts the workspace from a collection of repositories into a governed ecosystem. The goal is to prevent architectural entropy: orphaned repositories, forgotten prototypes, ambiguous roots, and project histories that only survive in one person's memory.

Core Principles

Principle	Meaning
The workspace is a system	The workspace is a durable asset. One dormant project must not make the broader environment harder to understand.
Projects must be discoverable	A project can be found and understood through manifests, registries, and read-first documents without source-code archaeology.
Context must survive time	Documentation and manifests preserve intent, boundaries, and state so work can be resumed after long dormancy.
Standards reduce decisions	Common structure keeps humans and agents from reinventing placement, naming, lifecycle, and validation rules.
Agent compatibility is required	Non-human collaborators must be able to orient through standard entry points without project-specific training.

Required Artifacts

• D:\AGENTS.md and D:\Development.manifest.toml.
• [DirectoryName].manifest.toml and AGENTS.md for governed portfolios and containers.
• [ProjectName].manifest.toml, Project-README.md, and AGENTS.md for project and project-group roots.
• [StandardName].manifest.toml for standards.
• Workspace inventory.
• Target directory map.
• Agent startup procedure.
• Standards backlog.

Four-Layer Workspace Architecture

WGS separates rules, working artifacts, services, and metadata so the workspace can evolve without hiding governance inside project-specific implementation details.

Layer	Primary function	Examples
Standards layer	Defines behavior and meta-governance for projects, standards, and artifacts.	WGS, SFDS, PPS, DRS, CTS, SIS, WDS, DDS, AAMHS, AADR, ARHS, SESM, NeonInk, AAS, ATS
Projects layer	Produces functional artifacts, tools, websites, datasets, and technical systems.	FileCabinet, Aegis, Structra, ArchiveHasher, CloneCratesio
Shared services layer	Provides workspace-level infrastructure used across projects.	.agents, .evals, .sonar, .docs, .data, .start, local caches, Docker storage
Metadata layer	Describes the workspace as a self-aware system.	Workspace manifests, directory manifests, project manifests, registries, relationship maps, health records

The metadata layer is the connective tissue of the workspace. It enables intent search: finding projects by purpose, lifecycle state, governing standard, artifact class, or technical suite rather than by filename guesses.

Project Lifecycle

Every governed project must have exactly one lifecycle state in its manifest. The state is not a vibe check; it is the current operational posture of the project.

State	Meaning	Exit criteria
concept	A coherent idea exists with initial scope and boundaries.	Mission and problem statement are recorded.
planning	Formal architecture, proposal, and governance work are underway.	PPS documentation and project manifest are ready.
active	The project is under active implementation.	Core logic or data spine is operational enough for feature completion review.
feature-complete	Core architectural requirements are operational.	Ready for release-side verification and audit.
release-prep	Final checking, hardening, and packaging are underway.	Domain standard compliance and build verification are complete.
released	A stable artifact or service has been released.	Published or distributed artifacts have release notes and verified hashes where applicable.
maintenance	The project is sustained through fixes, updates, or compatibility work.	Update history and stability monitoring continue.
paused	The project is intentionally inactive but expected to remain recoverable.	Context freeze, known state, and reactivation notes are recorded.
archived	The project is historically preserved but inactive.	Metadata and archival integrity records are complete enough for long-term recovery.
superseded	The project has been replaced by a successor.	Manifest links explicitly name the replacement project or standard.

Lifecycle states must be machine-readable. If a project does not fit a state cleanly, record the ambiguity as a governance gap instead of inventing a private state.

Project Classes

The lifecycle state says when the project is in its life. The project class says what kind of thing it is.

Project manifests should classify the project using the closest governed class, such as:

• desktop-app
• command-tool
• website
• dataset
• standard
• service
• document
• infrastructure
• research

The class determines which domain standard is consulted after WGS:

• Desktop applications use DRS for release behavior.
• Command tools use CTS for automation and CLI contracts.
• Services and infrastructure use SIS for lifecycle, health, ports, storage, logs, resources, and recovery.
• Websites use WDS for deployment and site documentation.
• Datasets use DDS for provenance and dataset validation.
• Standards use SFDS for suite structure.

Metadata Spine

Manifests are the machine-readable source of truth for identity, state, relationships, and agent orientation. Human documents provide narrative depth, but manifests are the canonical records for automated discovery.

The current manifest family is Entity Manifest v2.4. Older Project Manifest v2.3 records remain valid historical evidence until migrated.

Every governed entity manifest must answer:

• What is this entity?
• Where does it live?
• What class of thing is it?
• What is its lifecycle state?
• Which standard governs it?
• Which documents are authoritative?
• What relationships or successors matter?
• What should an agent read first?

The release note is the human promise. The manifest is the machine record. WGS owns the existence, placement, identity, and discoverability of that record.

Agent-First Governance

Agent compatibility is mandatory. An agent entering the workspace must be able to recover context through standard read order rather than project-specific memory.

Required Agent Orientation

For workspace or project work, agents read:

1. D:\AGENTS.md and each nearer AGENTS.md toward the target.
2. D:\Development.manifest.toml for drive-wide identity and registration.
3. Nearest entity-named manifest matching its containing directory.
4. Project-README.md, when working in a project or group.
5. Canonical governing standards linked by the manifests.
6. Roadmap, current task note, release note, or handoff record.

Agents must record missing entry-point documents before making broad changes.

Agent Drift Rules

• Do not infer project purpose from code alone when manifests or identity docs are available.
• Do not move, rename, or delete roots as a cleanup reflex.
• Do not silently correct manifest drift.
• Prefer narrow changes until the governing standard and lifecycle state are known.
• Preserve context even when a project is paused, archived, or superseded.

Standards Hierarchy

WGS is the workspace meta-layer. It governs the environment. Other standards govern objects inside that environment.

Layer	Standards	Role
Workspace constitution	WGS	Placement, registration, manifests, services, lifecycle visibility, agent orientation, workspace health.
Meta-standards	SFDS, PPS	Standards formulation, project birth, intent boundaries, proposal readiness.
Domain standards	DRS, CTS, SIS, WDS, DDS	Release, automation, service, deployment, and dataset rules for project classes.
Technical and specialized standards	AAMHS, ARHS, AAS, ATS, AADR, SESM, NeonInk	Integrity, analysis, task handoff, representation, metadata, and design language.

When standards overlap, use the Governance Responsibility Matrix. WGS decides where an entity lives and how it is discoverable; it does not replace the entity's domain standard.

:::note Cross-references PPS, DRS, CTS, SIS, WDS, DDS, ATS, AAS, ARHS, AAMHS, AADR, SESM, and NeonInk are referenced throughout WGS but are owned by other documentation slices (positions 12+ in the sidebar). Links to those standards' docs/<slug>/ pages are left as plain text until those pages exist. :::

Validation

A WGS workspace is valid enough for planning when:

• The workspace root is identifiable.
• Root directories are inventoried.
• Current state and target state are separate.
• Standards have declared scopes.
• Agents have a startup procedure.

A WGS workspace is governed when:

• D:\Development.manifest.toml exists and names governed roots.
• Governed portfolios and containers have entity-named directory manifests and inherited instructions.
• Projects and project groups have entity-named manifests, instructions, and project orientation documents.
• Standards have entity-named standard manifests and SFDS conformance.
• Lifecycle state is explicit for governed projects.
• Shared services are registered or intentionally excluded.
• Drift is recorded before moves, renames, or deletions.
• Workspace health records identify next safe actions.

See the full Validation Checklist.

Workspace Health Model

Workspace health is a planning signal, not a moral score. It tells a future human or agent how safely the workspace can be changed.

State	Meaning	Required response
unknown	The root exists, but current state has not been inspected.	Inventory before making broad changes.
observed	Current state is recorded, but target state or ownership may be incomplete.	Make local changes only; update inventory as facts are discovered.
planned	Current and target state are both documented.	Changes may proceed when they match the target map.
governed	Required manifests and agent read-first docs exist.	Normal project and standard work may proceed.
drifted	Current state conflicts with the target map or manifests.	Record the mismatch before moving, renaming, or deleting anything.
blocked	A conflict, missing owner, or unsafe ambiguity prevents responsible changes.	Stop broad changes and create a review note or backlog item.

Minimum Health Record

A workspace health note should record:

• Date reviewed.
• Root or directory reviewed.
• Observed state.
• Target state, if known.
• Health state.
• Blocking gaps.
• Next safe action.

See the Workspace Health Record template and the filled City Hall Health Record example.

Drift Rules

• Do not silently correct drift by moving or deleting roots.
• Preserve legacy manifest-like files until their role is understood.
• If a current root and target root disagree, record both names and require manual review.
• If a standard owns the domain behavior, WGS owns only placement, registration, and discoverability.

Preservation and Health Metrics

The terminal goal of WGS is recoverability. A workspace is healthy when its projects, standards, services, and metadata can be audited or resumed without depending on memory.

Workspace health reviews should track:

• Manifest coverage.
• Documentation coverage.
• Standards compliance.
• Lifecycle state coverage.
• Drift between current state and target state.
• Missing owner or maintainer records.
• Blocked roots and next safe actions.

Metrics are evidence for stewardship. They should guide cleanup and planning, not become vanity scores.

Tone Requirement

WGS documents should be plain, concrete, and useful. They may carry the civic metaphor of City Hall, zoning, public works, and library roots, but the metaphor should clarify responsibility rather than decorate the system.