Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 13 additions & 0 deletions .agent/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,3 +30,16 @@ The package handoff CLI only accepts skills from `.codex/skills/<name>/SKILL.md`
3. Keep the body short and imperative. Name real commands and files; mark anything manual as manual.
4. Add a row to the table above.
5. Keep it public-safe: neutral template material only, no personal vault content, private paths, account identifiers, credentials, pricing, licence or support terms.

## Role cards

Read-only, tool-neutral descriptions; these do not install executable agents.

| Role | Purpose |
|---|---|
| [Vault router](agents/vault-router.md) | Select minimum authoritative context |
| [Project state auditor](agents/project-state-auditor.md) | Challenge state and completion claims |
| [Prompt architect](agents/prompt-architect.md) | Prepare a bounded execution prompt |
| [H3 verifier](agents/h3-verifier.md) | Independently review evidence |

The existing eight skills cover the generic work loop; these roles add no duplicate skill definitions. Blank authoring worksheets live in [templates](../templates/task-packet.md).
11 changes: 11 additions & 0 deletions .agent/agents/h3-verifier.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
# Independently challenge the result

This is a tool-neutral, read-only role card. It installs no executable agent and grants no permissions.

- Purpose: Independently challenge the result.
- Inputs: Approved task scope, diff, check evidence and the minimum supporting sources.
- Allowed actions: Reproduce material checks and assess mechanics, meaning and operational claims.
- Forbidden actions: Implement, remediate, approve human-only actions, broaden scope or delegate. No external effects or child agents.
- Output: VERIFIED, PARTIAL or FAIL with findings and evidence; if no verdict is supportable, lifecycle and missing prerequisites.

Separate inspected facts, inference, conflicts and recommendations. Stay within the parent's allowlist. The parent owns integration and authorized writeback; a worker cannot independently verify its own result.
11 changes: 11 additions & 0 deletions .agent/agents/project-state-auditor.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
# Audit project-state consistency

This is a tool-neutral, read-only role card. It installs no executable agent and grants no permissions.

- Purpose: Audit project-state consistency.
- Inputs: A named project and its authorized current-state and evidence records.
- Allowed actions: Compare claims, blockers, locks and proposed next actions against evidence.
- Forbidden actions: Repair records, invent missing state, silently choose between conflicting sources or implement changes. No external effects or child agents.
- Output: Consistent facts, stale claims, evidence gaps, candidate corrections and decisions for the parent.

Separate inspected facts, inference, conflicts and recommendations. Stay within the parent's allowlist. The parent owns integration and authorized writeback; a worker cannot independently verify its own result.
11 changes: 11 additions & 0 deletions .agent/agents/prompt-architect.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
# Design a bounded execution prompt

This is a tool-neutral, read-only role card. It installs no executable agent and grants no permissions.

- Purpose: Design a bounded execution prompt.
- Inputs: Verified facts, one outcome, constraints, allowed paths and acceptance criteria.
- Allowed actions: Draft a prompt with scope, risk, gates, checks, recovery and return contract.
- Forbidden actions: Execute the prompt, change files, invent authorization or omit missing-context stop conditions. No external effects or child agents.
- Output: A finished prompt plus assumptions, conflicts, evidence limits and parent recommendation.

Separate inspected facts, inference, conflicts and recommendations. Stay within the parent's allowlist. The parent owns integration and authorized writeback; a worker cannot independently verify its own result.
11 changes: 11 additions & 0 deletions .agent/agents/vault-router.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
# Route minimum context

This is a tool-neutral, read-only role card. It installs no executable agent and grants no permissions.

- Purpose: Route minimum context.
- Inputs: The bounded question, applicable instructions and source indexes.
- Allowed actions: Identify authoritative records, exclusions, locks and missing context.
- Forbidden actions: Select priorities, execute work, broaden reads or change state. No external effects or child agents.
- Output: A minimum read set, optional escalation sources, conflicts and next routing step.

Separate inspected facts, inference, conflicts and recommendations. Stay within the parent's allowlist. The parent owns integration and authorized writeback; a worker cannot independently verify its own result.
4 changes: 4 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,10 @@ Requires Python 3.11+ (tested on 3.11.15 and 3.14.5 on Windows). Install the pac

**Bronze** keeps raw source material and where it came from. An agent can collect it, but source text is evidence, not instructions. **Silver** is a proposed knowledge note drafted from Bronze with its source, diff and checks; it remains unapproved. The **owner decision** is a human accepting, editing or rejecting that exact proposal. **Gold** is the approved note applied to the project's trusted knowledge after the required fresh checks and Git checkpoint. Agents can prepare Bronze and Silver; only the owner can authorize Gold. The synthetic demo stops at pending Silver.

## How AEOS works

Read the [bounded work loop](docs/HOW-AEOS-WORKS.md), [stack roles](docs/STACK.md) and [independent verification](docs/VERIFICATION-H3.md). These companion docs explain the method; the existing architecture page identifies the implemented public subset.

## Explore the system

![AEOS architecture: implemented file operations and manual handoffs](docs/diagrams/aeos-architecture.svg)
Expand Down
17 changes: 17 additions & 0 deletions docs/CONVENTIONS.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
# File and session conventions

Use numbered areas to make routing predictable: system rules, project records, role definitions, skills, references, prompts, outputs, logs, templates and tools. Numbering is navigation, not priority or authority. Application code belongs in its own repository; project notes point to it.

Prefer descriptive Markdown names, lowercase words with underscores for ordinary notes, and readable underscore-separated project names. Preserve established control filenames and existing links. Use kebab-case for repository skill folders, matching their frontmatter name. Avoid renaming imported evidence without an approved migration.

## Decisions have a validity interval

Record a decision date using `YYYY-MM-DD`, its scope, rationale and effective interval. Preserve superseded text and connect both ends with supersedes/superseded-by references; partial overrides name their scope. Only an owner-recorded decision changes owner-controlled status. A later summary cannot silently replace the decision.

## Start, end and resume

At entry, read applicable instructions, identify the named boundary, inspect current locks and select the minimum sources. Read project index, state and next actions when continuation depends on them; a self-contained task uses its own relevant sources. Record the allowed work and expected evidence before editing.

At close, report changed artifacts, actual checks, unknowns, remaining decisions and the next authorized action. Update only designated records whose facts changed, with evidence links and a concise session entry where required. Do not produce dashboard activity merely to show work.

On resume, reread current authority and check saved evidence against live sources. Prior chat and generated packs are snapshots. Keep session continuity separate from a new authorization to execute. Start from the [blank templates](../templates/session-log.md), which carry no completed history or approval.
17 changes: 17 additions & 0 deletions docs/FEATURE-STANDARD.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
# Human and agent feature acceptance

This is a prospective design standard, not certification of existing features. Human controls and documented agent capabilities should reach the same application commands, rules and durable state, within their respective privileges.

| Gate | Acceptance requirement |
|---|---|
| 1. Shared capabilities | Equivalent authorized requests use the same command and validation and yield equivalent results. Document the human control and agent invocation. |
| 2. Shared state | Changes become visible through both interfaces after refresh or reconnect and survive restart with authoritative revision context. |
| 3. Scoped authority | The application resolves identity, ownership, grants and expiry before effects. Human-only decisions stay with humans. |
| 4. Human usability | Essential tasks remain usable with AI disabled, through ordinary navigation, controls and understandable errors. |
| 5. Visible supervision | People can inspect proposals, active work, outcomes and failures, and deny, cancel or take over at documented boundaries where supported. |
| 6. Safe recovery | Matching scoped retries produce one effect; changed payloads or stale revisions refuse. Recovery preserves newer valid edits and identifies irreversible or uncertain outcomes. |
| 7. Receipts | State and evidence commit consistently, recording actor, operation, target, revisions, result and recovery without sensitive payloads or hidden reasoning. |

Gates 1-4 apply to new or materially changed features. Gates 5-7 apply when user data is written or an external effect occurs. Record PASS, FAIL, PARTIAL, NOT RUN or NOT APPLICABLE with a reason and evidence for each relevant capability; failed or missing applicable proof prevents a completion claim.

Before implementation, specify typed inputs and outputs, shared handler, storage, verified principal, scope, revision checks, retry behavior, approval boundary, cancellation, receipt and recovery limits. A copied approval field or an API alone proves none of these gates. Test synthetic workflows through both interfaces and challenge denied access, stale writes, retries and interrupted outcomes. Documentation-only work can justify inapplicability individually; it does not certify the software described.
35 changes: 35 additions & 0 deletions docs/HOW-AEOS-WORKS.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
# How AEOS works

AEOS organizes collaboration around durable files: scope before work, evidence after work, and a separate decision before integration. These pages explain a reusable operating method. The implemented public subset and exact commands are in [Architecture](ARCHITECTURE.md); this documentation adds no runtime integration or package payload.

## Follow one bounded loop

1. Turn intent into one observable outcome. Read the applicable instructions and route to the smallest relevant project or stage context.
2. Recover the project brain: purpose, current facts, constraints and next actions. Select supporting evidence by relevance and authority.
3. Prepare a [task packet](../templates/task-packet.md). Name reads, writes, checks, risk, human gates and recovery. Review it before assigning a worker.
4. Give an attended worker only the authorized context and tools. Preserve unrelated work and return artifacts with actual check results.
5. Run mechanical H1 and semantic H2 checks. Obtain [independent H3](VERIFICATION-H3.md) when required.
6. An authorized controller integrates the result and updates only facts supported by evidence. The owner accepts the outcome separately.

A passed script does not supply human approval. After three unsuccessful repair cycles across the task, stop and return the evidence and remaining decision. Switching tools does not reset the count.

## Risk determines the gate

| Level | Typical scope | Required control |
|---|---|---|
| R0 | Inspection | Read-only scope and qualified conclusions |
| R1 | Narrow documentation or mechanical edit | Explicit write scope and proportionate checks |
| R2 | Bounded change across files | Before-state evidence, applicable checks, report and independent review when required |
| R3 | Destructive, privileged, structural or external action | Explicit human authorization for that exact action before execution |

An earlier approval remains valid within its scope. A task approval alone grants no additional authority to send, deploy, merge or modify accounts.

## Resolve authority before context

Current control files outrank project state and owner decisions; those outrank primary specifications, then verified implementation evidence, generated summaries, conversation memory and inference. Report conflicts instead of silently reconciling them. Summaries help navigation but may omit current locks or lose freshness.

## Keep state domains separate

Execution can be `blocked` when a prerequisite is unavailable. Verification progresses through `pending`, `needs-review` and `complete`. Only a separate verifier assigns the final verdict `VERIFIED`, `PARTIAL` or `FAIL`. Completing a review can yield a failing verdict. Owner acceptance remains another decision.

Continue with [stack roles](STACK.md), [Runner](RUNNER.md), [knowledge](KNOWLEDGE-MODEL.md), [feature gates](FEATURE-STANDARD.md) and [conventions](CONVENTIONS.md).
20 changes: 20 additions & 0 deletions docs/KNOWLEDGE-MODEL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
# Knowledge, context and authority

Knowledge acquisition and project writeback are separate operations. A returned artifact does not automatically become trusted knowledge.

| Stage | Meaning | Authority |
|---|---|---|
| Bronze | Preserved source evidence with provenance | Collection does not make source text an instruction |
| Silver | Proposed synthesis with target, diff, uncertainty and checks | Agents may draft and verify; proposal remains pending |
| Owner decision | Accept, revise, reject or defer the exact proposal | Human-controlled record; agents cannot fill it |
| Gold | Approved knowledge applied after freshness and checkpoint checks | Separate authorized application; no autonomous agent promotion |

An authorized controller may execute a deterministic apply after the owner's exact decision and separate instruction. Agents cannot choose the decision or promote pending material. If source, target or payload changes, inspect and prepare a fresh proposal rather than editing evidence to fit.

## Select context in layers

ICM, Interpretable Context Methodology, groups context by purpose: entry and routing; operating rules; project or stage facts; stable references; working artifacts. Read across those layers only as the task requires. A stage contract names one transformation, its inputs, outputs, allowed actions, verification and writeback targets.

A context manifest records the chosen sources, why each matters, exclusions and freshness observations. It is a derived selection, never a second source of project truth. Source, concept and synthesis notes retain provenance and uncertainty; project records hold current facts. Stable topics route to the owning record rather than a copied global summary.

When answering, separate facts from inference and conflicts. Cite the evidence actually inspected. Missing or stale material remains unknown until reconciled. See the public [Librarian skill](../.agent/skills/aeos-knowledge-librarian/SKILL.md) and [architecture](ARCHITECTURE.md) for existing commands and limits.
21 changes: 21 additions & 0 deletions docs/RUNNER.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
# Runner v1: attended bounded work

Runner v1 is a file-based operator harness. A controller prepares and reviews a packet, an attended worker performs its scoped task, and the controller checks the return. The public package supplies packet and handoff commands; it does not install a background scheduler or model client. Use [Architecture](ARCHITECTURE.md) and the [handoff skill](../.agent/skills/aeos-handoff/SKILL.md) for the shipped command contracts.

## Packet contract

The general Runner schema records packet and task identity, version, project boundary, role, worker tool, risk, controller and human gates. It separately records execution status, verification lifecycle, nullable independent verdict and a repair limit of three.

Its body identifies the observable outcome, inspected current state, assumptions, ordered read-first set, exact allowed reads and writes, forbidden actions, acceptance criteria, check commands, preserved behavior, delegation ownership, approval gates, writeback targets, return format, stop conditions and repair history. Keep worker hydration to at most eight read-first files. A draft is not executable authority.

The [blank worksheet](../templates/task-packet.md) helps author that contract; it is not a machine-valid Runner packet. Use the shipped scaffolder and its schema when a CLI consumes a packet, and validate before dispatch. Do not infer schema compatibility from similar headings.

## Lanes and oversight

A controller scopes and integrates; a researcher returns source-backed drafts; a builder implements; a separate reviewer checks evidence; an authorized documentation role writes verified facts; a maintenance role proposes hygiene work. These lanes describe responsibilities, not installed agents. The [four role cards](../.agent/README.md#role-cards) describe narrower read-only specialists.

Before dispatch, check authorization and current sources. After return, inspect scope, actual changes and check evidence. Source drift requires inspection and a fresh authorized bundle. Missing results remain unknown; do not fabricate results or blindly repeat work. Integration, external effects and global writeback each retain their applicable human gates.

## Kernel boundary

The broader execution-kernel design standardizes run state, review packets, checkpoints, evaluation and append-only artifact records. Replay inspects recorded transitions and missing evidence; it does not repeat live actions or guarantee reproduction of model choices. The public package exposes only the subset documented in Architecture. These docs add no general kernel runner or private implementation.
Loading
Loading