tracker: AGS-39
Two independent doc audits found systematic doc↔code drift. The pattern is not typos — whole chapters document APIs that were refactored away, and the primary run commands fail.
- Most documented
mvn exec:java commands cannot run. exec-maven-plugin is not declared in the root pom at all, and Flink is provided scope while exec:java defaults to the runtime classpath — so every Flink-job example dies with NoClassDefFoundError. The repo already knows: TEST_REPORT.md records using -Dexec.classpathScope=test, and one example documents the workaround in its own javadoc.
- The doc presenting "the banking agent as Java" runs a generic Ollama chat bot with no tools whose own javadoc says "No Flink".
flink run "$JAR" <class> in the market scripts passes the class as a program arg, so it launches the manifest Main-Class instead.docs/reference/external-state-storage.md is entirely fictional — every class and method it documents is absent repo-wide, and its DDL matches neither the implementation nor sql/schema.sql. Recommend deleting it.docs/reference/storage-architecture.md has the status table inverted: Postgres/Qdrant/pgvector are marked "Planned" while all three ship and are ServiceLoader-registered, and it documents a RedisShortTermStore that does not exist while never mentioning the real Flink-state-first memory.- The storage-backends guide teaches an obsolete registration flow ("add a case to the factory switch") and never mentions the actual
ServiceLoader + META-INF/services mechanism.
- Wrong env var names (
POSTGRES_URL vs the real AGENTIC_FLINK_POSTGRES_URL), wrong Qdrant config keys and default port, and a ContextItem(String, String) constructor used 8 times that does not exist.
TEST_REPORT.md is stale: claims 487/487 on Java 17; actual is 770 tests, 0 failures on JDK 21.
Clean and should not be rewritten: docs/examples/incident.md (zero findings) and docs/guides/creating-tools.md (~95% accurate).
Roadmap epic. Detailed findings, file:line citations and sub-tasks live in the AI-grind tracker (project AGS), which is the source of truth for this work. Local dev — build, test, tracking, profiling — is managed with AI-grind.
Tracked as AGS-39 in the devtools-mcp tracker.
tracker: AGS-39Two independent doc audits found systematic doc↔code drift. The pattern is not typos — whole chapters document APIs that were refactored away, and the primary run commands fail.
mvn exec:javacommands cannot run.exec-maven-pluginis not declared in the root pom at all, and Flink isprovidedscope whileexec:javadefaults to the runtime classpath — so every Flink-job example dies withNoClassDefFoundError. The repo already knows:TEST_REPORT.mdrecords using-Dexec.classpathScope=test, and one example documents the workaround in its own javadoc.flink run "$JAR" <class>in the market scripts passes the class as a program arg, so it launches the manifestMain-Classinstead.docs/reference/external-state-storage.mdis entirely fictional — every class and method it documents is absent repo-wide, and its DDL matches neither the implementation norsql/schema.sql. Recommend deleting it.docs/reference/storage-architecture.mdhas the status table inverted: Postgres/Qdrant/pgvector are marked "Planned" while all three ship and are ServiceLoader-registered, and it documents aRedisShortTermStorethat does not exist while never mentioning the real Flink-state-first memory.ServiceLoader+META-INF/servicesmechanism.POSTGRES_URLvs the realAGENTIC_FLINK_POSTGRES_URL), wrong Qdrant config keys and default port, and aContextItem(String, String)constructor used 8 times that does not exist.TEST_REPORT.mdis stale: claims 487/487 on Java 17; actual is 770 tests, 0 failures on JDK 21.Clean and should not be rewritten:
docs/examples/incident.md(zero findings) anddocs/guides/creating-tools.md(~95% accurate).Roadmap epic. Detailed findings, file:line citations and sub-tasks live in the AI-grind tracker (project
AGS), which is the source of truth for this work. Local dev — build, test, tracking, profiling — is managed with AI-grind.Tracked as
AGS-39in the devtools-mcp tracker.