ktogias/gnostoa

Gnostoa is a small Git-native toolkit for project knowledge that must remain
usable by both people and software agents. It validates structured Markdown and
YAML, enforces non-weakening project profiles and policy boundaries, and builds
bounded orientation packs without requiring a hosted knowledge service.
> **Status: pre-stable v0.2.0 source and OCI release.** The immutable source tag
> is v0.2.0. One public
> linux/amd64 image is available as
> ghcr.io/ktogias/gnostoa@sha256:f89bf32c0c4b86bac71fa008579b2385e6ae39bf4822f685479c4f2cc22bfca4.
> No package or site has been released, and artifact availability is not a
> production-readiness or independent-adoption claim.
The earlier pre-publication projection, “No package, image or site has been released yet,”
is superseded by the digest-bound image result above.
Maintaining Gnostoa itself? Start with the compact, derived
current orientation, then follow its source links
and the detailed roadmap. Its timestamp and status bound every
current-state claim; the linked source and provider records remain authoritative.
Why Gnostoa
Project knowledge is often split across prose, configuration, issue history and
tool-specific indexes. That makes authority unclear, permits documentation
drift and forces every new person or agent to rediscover the repository.
Gnostoa keeps the canonical layer deliberately boring:
- Markdown plus YAML frontmatter using OKF v0.2;
- stable concept IDs, owners, lifecycle state and typed relations;
- profiles that specialize by adding constraints rather than weakening them;
- deterministic validation and bounded, replaceable context views; and
- provider-neutral change and CI contracts.
Try Gnostoa from this checkout
The shortest supported evaluation path uses Python 3.11 or newer:
Expected result:
Then build a bounded orientation view from the same validated bundle:
The output contains the selected system, its governing Decision and the project
root, while the Markdown files remain canonical. See the
five-minute quick start for the container route,
interpretation and limits of this result.
The editable install is intentional for evaluating the current source
candidate. A wheel or source-distribution install supplies execution only: set
KNOWLEDGE_KIT_ROOT to the separate pinned public-source checkout that supplies
schemas and profiles. Unbound or wrongly bound native execution fails with an
actionable error instead of treating installed package files as canonical
source. Consumers must pin the artifact, source revision and public-surface
digest together; the released OCI route below is one such exact binding.
What works today
| Capability | Current evidence |
|---|---|
| Validate OKF bundles and profile inheritance | Executable CLI, schemas, anonymous fixtures and unit tests |
| Enforce generic and Gnostoa policy boundaries | Change-control, CI-policy and guardrail checks |
| Build bounded orientation packs | Deterministic graph traversal with explicit depth and token limits |
| Project human documentation | MkDocs build from canonical public and self-knowledge surfaces |
| Run through one command surface | Native CLI plus a pinned, non-root OCI build route |
| Apply the model to Gnostoa itself | Recorded self-dogfood assessment and publication-baseline review |
The raw Issue #12 and PR #2 ledger is retained as one-time B1 self-dogfood
evidence; it is **not the expected contribution workflow**. Normal changes use
the compact route in CONTRIBUTING.md, ordinary Pull Request
review and proportionate evidence. B2/P1 and B2/P2 completed the first bounded
self-hosting measurements and narrowed the claim: the envelope and projection
improve orientation and resumability but are not workflow enforcement. The
bootstrap Decision
keeps the broader platform off the critical path: the full workflow platform
is not a publication prerequisite. The strict