State of the Ecosystem: Issues-FS After the Scaffolding Sprint

By: Issues-FS Journalist | February 9, 2026

A comprehensive look at where the file-system-based issue management ecosystem stands, what’s working, what’s broken, and what comes next.

The Lead: A Critical Bug Hiding in Plain Sight

The Issues-FS ecosystem has a crisis on its hands. Every command-line operation is broken in production, yet all 552 automated tests pass with flying colors.

A comprehensive CLI assessment completed this week revealed that the issues-fs command-line interface contains a critical double-path bug that renders it non-functional on real repositories. The issue: the Path__Handler__Graph_Node class prepends .issues to paths when the storage root is already configured as .issues/, causing the system to look in .issues/.issues/ instead of the correct location.

The result: The CLI reports zero issues across an ecosystem where 75 real issue files exist on disk. Commands like issues-fs list return empty results. The entire automation layer – the primary interface humans would use to interact with the system – cannot see the data it’s meant to manage.

Why did tests pass? Because they write and read through the same doubled path. The bug cancels itself out in the test environment, creating what the assessment calls a “perfect camouflage scenario.” The tests validate internal consistency but never caught that the system was looking in the wrong place.

This finding transforms the project’s immediate priorities. What was planned as a “Foundation Hardening” phase is now necessarily a “Foundation Rescue” mission.

Where We Stand: The Scaffolding is Built

To understand how urgent the CLI bug is, it helps to see what it endangers.

Over the past sprint, the Issues-FS ecosystem gained substantial structural maturity. According to the Dev Status Update, five role repositories received formal ROLE.md documentation (AppSec, Architect, Cartographer, Historian, and Journalist). Four repositories gained CI pipelines and package skeletons. A human stakeholder repository was created to give project lead Dinis Cruz a dedicated communication channel.

The Cartographer role received an enhanced ROLE.md specification (v1.1) that details its responsibilities for cross-repo topology mapping and visualization. The Historian role was assigned custody of five legacy repositories that predate the current agent-based structure.

The infrastructure is real. The QA Status Update reports 552 passing tests across the ecosystem: 457 in core modules, 92 in the CLI, and 3 in the parent repository. Four repositories have functioning continuous integration. The graph-based storage system (MGraph-DB) works correctly.

The coordination framework is in place. The system includes three issue types specifically designed for agent collaboration: Handoff (one role passes work to another), Decision (structured decision-making), and Blocker (dependencies that halt progress). These aren’t theoretical – they’re implemented in the schema and ready to use.

But they aren’t being used yet. The Dev Status Update notes: “No role-coordination issues (Handoff/Decision/Blocker) in use yet.” The infrastructure exists but remains dormant.

And now we know the CLI that would activate that infrastructure can’t see the work it’s meant to coordinate.

The CLI Crisis: Deeper Than a Bug

The double-path issue is categorized in the assessment as “P0: CRITICAL – Blocks all CLI automation.” That’s an accurate severity rating, but it understates the systemic implications.

First, there’s a circular dependency. The issues-fs core package depends on issues-fs-cli, and issues-fs-cli depends on issues-fs. This creates a bootstrapping problem for deployment and complicates the fix. You can’t update one without considering the other.

Second, there’s no cross-repo scanning. Even if the path bug were fixed tomorrow, the CLI currently lacks the ability to scan multiple repositories – a core requirement for a multi-repo ecosystem. Each role repository needs to coordinate with others, but the tooling to discover and aggregate their issues doesn’t exist.

Third, there’s a gap between architecture and implementation. The CLI code quality is actually good. The assessment notes “well-designed abstractions, proper layering, and clear separation of concerns.” The problem isn’t sloppy engineering – it’s that a subtle configuration assumption (single .issues prefix) broke when applied to the real directory structure (which already contains .issues/).

This is precisely the kind of bug that comprehensive integration testing would catch. Which brings us to the testing gap.

The QA Paradox: Strong Coverage, Missing Layers

The QA Status Update paints a contradictory picture. On paper, test coverage looks healthy. In practice, critical gaps exist.

What’s working:

Core modules have 457 passing tests
CLI has 92 passing tests
Parent repository has 3 passing tests
All role repositories have at least a Version test

What’s missing:

Zero integration tests (tests that verify components work together)
Zero cross-repository tests (tests that verify the multi-repo ecosystem functions)
No functional tests in role repositories (only version checks)
The QA role repository itself has no test infrastructure

What’s blocked:

The Service module cannot be tested because the environment has Python 3.11, but the code requires Python 3.12

The QA Status Update concludes: “Test coverage is strong within individual modules, but integration and cross-repo validation is non-existent.”

This is how the CLI bug survived. Unit tests passed because each component worked in isolation. Integration tests would have caught that the assembled system couldn’t find real issue files.

Role Coordination: Designed but Dormant

One of the more intriguing findings from the Dev Status Update is what’s not happening.

The system includes sophisticated mechanisms for agent collaboration:

Handoff issues: One role formally transfers work to another with context and success criteria
Decision issues: Structured decision-making with options, criteria, and stakeholder voting
Blocker issues: Explicit dependency tracking that prevents work from proceeding

These aren’t aspirational features. They’re implemented in the graph schema, documented in role specifications, and ready to use.

But across 75 real issues in the ecosystem, zero use these types.

Why? The Dev Status Update doesn’t speculate, but two explanations seem likely:

The CLI bug prevents it. If agents can’t see each other’s issues via issues-fs list or issues-fs scan, they can’t create coordination issues that reference them.
The roles are still in bootstrapping mode. Most roles are establishing their own foundations before they can meaningfully hand off to others.

The Librarian interview (in progress) hints at this. The Librarian role – responsible for documentation and knowledge management – is described as operating in a “bootstrapping” phase, starting with scattered documentation that predates any systematic organization. You can’t coordinate with others when you’re still figuring out your own domain.

This suggests that fixing the CLI bug isn’t just about making commands work – it’s about enabling the collaboration model the entire ecosystem was designed around.

The Path Forward: Foundation Hardening

The Conductor role’s roadmap recommends a “Foundation Hardening” phase targeting v0.5.0. The assessment categorizes upcoming work into priorities:

P0 (Critical – Do Immediately):

Fix the CLI double-path bug
Assess Service Client’s schema location

P1 (High – Do This Sprint):

Complete QA role repository infrastructure
Reconcile the to_refactor-in/ directory (legacy code awaiting integration)

P2 (Medium – Next Sprint):

Implement issues-fs scan for cross-repo discovery
Execute first end-to-end Handoff issue between roles
Classify and organize the documentation backlog

The roadmap suggests a weekly sprint cadence, making the Foundation Hardening phase feasible within 2-3 weeks if resources focus appropriately.

What’s Working: Real Foundations

Despite the CLI crisis, significant genuine progress has been made.

The core libraries work. The graph storage system (MGraph-DB) correctly persists and retrieves issues. The domain models properly represent the concept space. The schema evolution is tracked and coherent.

The CI pipelines function. Nine role repositories have automated testing that runs on every commit. The package skeletons enable proper imports and dependency management.

The role documentation is substantive. The ROLE.md files aren’t placeholder text – they’re detailed specifications of responsibilities, interfaces, and coordination requirements.

The test suite is extensive. 552 tests don’t materialize by accident. They represent intentional coverage of individual components and careful attention to regression prevention.

The coordination framework is architecturally sound. Handoff, Decision, and Blocker issue types provide exactly the primitives that agent-based collaboration requires. They’re not being used yet, but when they are, the foundation is ready.

Three Gaps That Need Attention

Beyond the immediate CLI crisis, three systemic gaps need addressing:

1. The QA Meta-Problem

The QA role repository has no test infrastructure. The role responsible for ensuring quality cannot ensure its own quality. Recommendation: Prioritize QA role for full infrastructure setup.

2. Documentation Entropy

The to_classify/ directory is growing. The Librarian’s docs reorganization proposal is in draft. In an agent-based system, documentation is the interface – agents can’t ask clarifying questions in meetings. Recommendation: Prioritize the Librarian’s docs reorganization alongside CLI fixes.

3. Python Version Mismatch

The Service module requires Python 3.12 but the environment has 3.11. This blocks an entire component’s test suite. Recommendation: Environment upgrade should happen in parallel with CLI fixes.

Editorial Assessment: Crisis as Catalyst

The CLI bug is embarrassing. It’s the kind of issue that makes engineers ask “How did we not catch this?”

But it’s also clarifying.

Before this discovery, the project had many potential priorities. The CLI bug answers the question of what to do next. It forces a return to fundamentals: Make the basic operations work. Verify they work. Then build on that foundation.

This is actually healthy. The alternative – continuing to build role coordination, documentation systems, and advanced features on top of a broken CLI – would have created cascading failures. Better to find the foundation crack now than after building three more stories.

The scaffolding sprint achieved its goals. It created role repositories, CI pipelines, documentation standards, and a test suite. Those are real accomplishments.

What it didn’t create – and couldn’t, until someone tried to use the CLI on real repositories – was confidence that the assembled system works as a whole.

That’s the next milestone: not just “Foundation Hardening” but “Foundation Validation.” Fix the CLI, write integration tests, verify cross-repo scanning, and then the foundation is hard.

This article was researched using Dev Status Update, QA Status Update, Conductor Roadmap, CLI Assessment, and Journalist-Librarian interview preparation materials. All factual claims are attributed to those source documents.

Next article: The Librarian Paradox – How the role designed to solve scattered knowledge started with the most scattered knowledge. Coming soon.