← Back to Journal

Abbey Research Status Implementation

Tags: abbey-root • research • cli • deterministic-workflows • voice-analysis

Abbey Research Status Implementation

Today I implemented the first working version of abbey research status.

This grew out of the earlier architecture work around formal research artifacts and the Voice Analysis project. The goal was not to build every validation rule from the architecture in one pass. The goal was to prove that Abbey could deterministically discover real research artifacts, understand their relationships, and report the current state without depending on an AI model.

That part now works.

The new command is registered through the existing Abbey CLI structure:

abbey research status

It is also included in the main research help and in config/cli/cli.yml.

The implementation lives in:

scripts/abbey_research_status.py

The Bash wrapper in tools/bin/abbey-research handles the subcommand and delegates to the Python script.

The script scans formal research projects beneath:

docs/research

It currently recognizes these artifact directories:

corpus
experiments
observations
evidence
hypotheses
validation

A Markdown file is treated as a formal research artifact only when it contains YAML frontmatter with the required fields:

artifact_id
artifact_type
title
version
status

This is important because the Voice Analysis workspace also contains supporting Markdown documents that are not individual formal artifacts. Those files are ignored rather than being incorrectly added to the artifact graph.

The command discovered the Voice Analysis project and indexed 14 formal artifacts:

Corpus:       1
Experiments:  1
Observations: 3
Evidence:     3
Hypotheses:   3
Validations:  3

It then resolved the three complete research chains:

OBS-001 -> EVID-001 -> HYP-001 -> VAL-001
OBS-002 -> EVID-002 -> HYP-002 -> VAL-002
OBS-003 -> EVID-003 -> HYP-003 -> VAL-003

That gives the current project:

Complete chains:      3
Incomplete chains:    0
Formal artifacts:     14

The artifacts also contain references to older research identifiers such as:

OBSERVATION004-deadpan-delivery
EVIDENCE004-deadpan-delivery

These identifiers do not match the newer formal artifact IDs, but they are still useful provenance. The implementation reports them as informational references instead of assuming they are broken relationships.

The current report includes six legacy provenance references:

EVID-001 -> EVIDENCE004-deadpan-delivery
EVID-002 -> EVIDENCE003-preference-for-concise-writing
EVID-003 -> EVIDENCE005-recurring-narrative-elements
OBS-001 -> OBSERVATION004-deadpan-delivery
OBS-002 -> OBSERVATION003-preference-for-concise-writing
OBS-003 -> OBSERVATION005-recurring-narrative-elements

That conservative behavior feels right for the first implementation. Abbey should not declare old references broken just because they do not yet follow the latest ID convention.

The command is deterministic and read-only. It does not modify research documents, generate replacement indexes, change planning files, or call an AI model.

I also expanded the existing research regression suite.

Before this work, the suite had 17 tests. It now has 26 tests, covering:

research status help
successful repository status execution
Voice Analysis project discovery
formal artifact count
all three complete chains
complete-chain summary
legacy provenance reporting

The final test result was:

Passed: 26
Failed: 0

Additional validation included:

bash -n tools/bin/abbey tools/bin/abbey-review tools/bin/abbey-research
python3 -m py_compile scripts/abbey_research_status.py
tests/test-abbey-research.sh
abbey help
abbey research status
git diff --check

All checks passed.

One small side quest happened during the implementation when I pasted a descriptive layout directly into the shell. Bash did what Bash does and objected to status) appearing in the middle of nowhere. No files were changed, and the repository was clean apart from the intended planning update. After that, the remaining edits were applied through heredocs so the shell could stop interpreting the documentation as performance art.

The first version intentionally stops at the real repository happy path.

The next refinement session should focus on synthetic fixtures and explicit reporting for:

duplicate artifact IDs
malformed YAML frontmatter
missing required metadata
directory and artifact type mismatches
broken corpus references
broken experiment references
broken formal parent references
missing chain stages
multiple competing chain children
warning and failure exit codes

The important milestone from this session is that the Abbey research workspace is no longer just a collection of related Markdown documents. Abbey can now inspect the formal artifacts, connect them into research chains, and describe the state of the project deterministically.