luigidemasi opened a new issue, #38: URL: https://github.com/apache/camel-kit/issues/38
> Imported from [luigidemasi/camel-kit#69](https://github.com/luigidemasi/camel-kit/issues/69), opened by [luigidemasi](https://github.com/luigidemasi) on 2026-05-13. > Closed by commit [fbd14d6](https://github.com/luigidemasi/camel-kit/commit/fbd14d6f5ebd60aa5ff787dd228008f9e2e8b681). --- ## Description Replace the current text-marker-based staleness detection (`⚠️ **STALE**` blockquotes scanned by the LLM) with deterministic CLI subcommands that read and write YAML frontmatter. This makes staleness a structured tool-call operation instead of unreliable text parsing. ### Problem The current system requires skills to instruct the LLM to scan the first 10 lines of pipeline artifacts for a `⚠️ **STALE**` marker. This is unreliable because: - LLMs don't always execute the "check for staleness" instruction - Text scanning produces inconsistent results depending on context pressure - The result is an implicit judgment, not a structured machine-readable signal ### Solution Three picocli subcommands under a `doc` parent command: ``` camel kit doc check <file> # Query staleness → JSON camel kit doc stale --reason "..." [--cascade] <file> # Mark stale camel kit doc unstale <file> # Clear staleness ``` ### Frontmatter Schema Each pipeline artifact is created with YAML frontmatter containing two namespaced blocks: ```yaml --- staleness: stale: false since: null reason: null generated: at: "2026-05-13T09:00:00Z" by: camel-plan from: design-spec.md --- ``` - `staleness` — mutable, written by `doc stale` and `doc unstale` - `generated` — immutable after creation, written by the pipeline skill that produces the artifact - `generated.from` enables data-driven cascade without hardcoded pipeline topology ### `doc check` Output Returns JSON to stdout: ```json { "file": "docs/camel-kit/007/implementation-plan.md", "stale": true, "since": "2026-05-13T10:00:00Z", "reason": "design-spec.md was refined", "generated": { "at": "2026-05-13T09:00:00Z", "by": "camel-plan", "from": "design-spec.md" } } ``` Exit code 0 for successful execution regardless of staleness. Non-zero for errors only. Documents without frontmatter return `{"stale": false, ...null fields}`. ### Cascade `--cascade` flag on `doc stale` walks the `generated.from` chain in sibling files to propagate staleness to all downstream artifacts. Single-file marking is the default. ### Skill Contract - Each pipeline skill writes frontmatter when generating artifacts (documents are "born with metadata") - Skills call `doc check` via tool call instead of scanning text - `--reason` is required on `doc stale` for audit trail - `⚠️ **STALE**` text markers are removed entirely — frontmatter is the sole source of truth ### Implementation ``` command/doc/ DocCommand.java # @Command parent (mirrors GraphCommand) DocCheckCommand.java # Reads frontmatter, outputs JSON DocStaleCommand.java # Sets staleness fields DocUnstaleCommand.java # Clears staleness fields ``` ### Tasks - [ ] Implement `DocCommand` parent and three subcommands (`check`, `stale`, `unstale`) - [ ] YAML frontmatter parser (extract/modify/write between `---` delimiters) - [ ] `--cascade` flag with `generated.from` chain walking - [ ] JSON output for `doc check` - [ ] Update pipeline skill files to write frontmatter on artifact creation - [ ] Update pipeline skill files to call `doc check` instead of scanning for `⚠️ **STALE**` - [ ] Update `pipeline-infrastructure.md` to describe the new staleness system - [ ] Update documentation in `docs/` to reflect the new `doc` commands ### Related - Supersedes the staleness marker section of luigidemasi/camel-kit#65 -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
