From b5e1e48ddb555b001355fba9098b504aca2f6411 Mon Sep 17 00:00:00 2001 From: tegwick Date: Sat, 23 May 2026 04:38:57 +0200 Subject: [PATCH] Add retrieval agent briefs and interface cards --- README.md | 10 + infospace/agent/briefs/kernel-itc-core.md | 29 + .../agent/briefs/kernel-itc-kernel-map.md | 29 + .../agent/briefs/model-access-control.md | 33 + infospace/agent/briefs/model-data.md | 31 + infospace/agent/briefs/model-devsecops.md | 31 + infospace/agent/briefs/model-governance.md | 31 + .../agent/briefs/model-information-space.md | 30 + infospace/agent/briefs/model-landscape.md | 30 + infospace/agent/briefs/model-network.md | 31 + infospace/agent/briefs/model-observability.md | 31 + infospace/agent/briefs/model-organization.md | 31 + infospace/agent/briefs/model-security.md | 31 + infospace/agent/briefs/model-task.md | 30 + infospace/agent/briefs/profile-small-saas.md | 42 + infospace/agent/briefs/standard-caring.md | 56 + infospace/agent/briefs/standard-tagging.md | 31 + .../agent/consumer-briefs/railiance-fabric.md | 24 + .../agent/consumer-briefs/repo-scoping.md | 24 + .../agent/consumer-briefs/user-engine.md | 24 + infospace/agent/global-agent-brief.md | 18 + infospace/agent/retrieval-index.json | 1038 +++++++++++++++++ infospace/agent/retrieval-index.md | 306 +++++ infospace/agent/retrieval-index.yaml | 673 +++++++++++ .../canon-interface-card.template.yaml | 25 + .../templates/consumer-brief.template.md | 28 + infospace/indexes/artifact-tree.yaml | 74 +- infospace/views/repository-tree.md | 26 +- src/info_tech_canon/generation.py | 385 +++++- src/info_tech_canon/validation.py | 123 ++ tests/test_service.py | 8 + ...rieval-agent-briefs-and-interface-cards.md | 19 +- workplans/index.yaml | 2 +- 33 files changed, 3323 insertions(+), 11 deletions(-) create mode 100644 infospace/agent/briefs/kernel-itc-core.md create mode 100644 infospace/agent/briefs/kernel-itc-kernel-map.md create mode 100644 infospace/agent/briefs/model-access-control.md create mode 100644 infospace/agent/briefs/model-data.md create mode 100644 infospace/agent/briefs/model-devsecops.md create mode 100644 infospace/agent/briefs/model-governance.md create mode 100644 infospace/agent/briefs/model-information-space.md create mode 100644 infospace/agent/briefs/model-landscape.md create mode 100644 infospace/agent/briefs/model-network.md create mode 100644 infospace/agent/briefs/model-observability.md create mode 100644 infospace/agent/briefs/model-organization.md create mode 100644 infospace/agent/briefs/model-security.md create mode 100644 infospace/agent/briefs/model-task.md create mode 100644 infospace/agent/briefs/profile-small-saas.md create mode 100644 infospace/agent/briefs/standard-caring.md create mode 100644 infospace/agent/briefs/standard-tagging.md create mode 100644 infospace/agent/consumer-briefs/railiance-fabric.md create mode 100644 infospace/agent/consumer-briefs/repo-scoping.md create mode 100644 infospace/agent/consumer-briefs/user-engine.md create mode 100644 infospace/agent/retrieval-index.json create mode 100644 infospace/agent/retrieval-index.md create mode 100644 infospace/agent/retrieval-index.yaml create mode 100644 infospace/agent/templates/canon-interface-card.template.yaml create mode 100644 infospace/agent/templates/consumer-brief.template.md diff --git a/README.md b/README.md index 3fddf68..97e505e 100644 --- a/README.md +++ b/README.md @@ -64,3 +64,13 @@ The first executable profile proof is `small-saas`. It lives under `infospace/profiles/small-saas/` and includes connected example artifacts for a tenant-aware SaaS service: service, system, tenants, user, team, dataset, deployment, task, policy, control, evidence, and incident. + +## Agent Retrieval + +Agent-facing retrieval assets live under `infospace/agent/`: + +- `global-agent-brief.md` +- `retrieval-index.md`, `retrieval-index.yaml`, and `retrieval-index.json` +- per-artifact briefs in `agent/briefs/` +- consumer brief templates in `agent/consumer-briefs/` +- Canon Interface Card template in `agent/templates/` diff --git a/infospace/agent/briefs/kernel-itc-core.md b/infospace/agent/briefs/kernel-itc-core.md new file mode 100644 index 0000000..3837c9d --- /dev/null +++ b/infospace/agent/briefs/kernel-itc-core.md @@ -0,0 +1,29 @@ +--- +id: agent-brief/kernel-itc-core +artifact_id: kernel/itc-core +source_path: kernel/InfoTechCanonCore.md +source_kind: kernel +generated: true +--- + + + +# Agent Brief: InfoTechCanon Core + +- Artifact ID: `kernel/itc-core` +- Kind: `kernel` +- Canonical path: `kernel/InfoTechCanonCore.md` +- Full source: `kernel/InfoTechCanonCore.md` +- Summary: Kernel artifact that defines canon structure or integration: InfoTechCanon Core. + +## Retrieval Hints + +No imports or anchors recorded. + +## Owned Concepts + +- `InfoTechCanon Core` + +## Related Distinctions + +- **Intent vs Scope vs Purpose**: Intent captures why an actor wants something, scope bounds what is included, and purpose captures consumer demand or use case pressure on the repo. diff --git a/infospace/agent/briefs/kernel-itc-kernel-map.md b/infospace/agent/briefs/kernel-itc-kernel-map.md new file mode 100644 index 0000000..e1313bb --- /dev/null +++ b/infospace/agent/briefs/kernel-itc-kernel-map.md @@ -0,0 +1,29 @@ +--- +id: agent-brief/kernel-itc-kernel-map +artifact_id: kernel/itc-kernel-map +source_path: kernel/InfoTechCanonKernelMap.md +source_kind: kernel +generated: true +--- + + + +# Agent Brief: InfoTechCanon Kernel Map + +- Artifact ID: `kernel/itc-kernel-map` +- Kind: `kernel` +- Canonical path: `kernel/InfoTechCanonKernelMap.md` +- Full source: `kernel/InfoTechCanonKernelMap.md` +- Summary: Kernel artifact that defines canon structure or integration: InfoTechCanon Kernel Map. + +## Retrieval Hints + +No imports or anchors recorded. + +## Owned Concepts + +- `InfoTechCanon Kernel Map` + +## Related Distinctions + +No common distinction is anchored directly on this artifact. diff --git a/infospace/agent/briefs/model-access-control.md b/infospace/agent/briefs/model-access-control.md new file mode 100644 index 0000000..2d1c081 --- /dev/null +++ b/infospace/agent/briefs/model-access-control.md @@ -0,0 +1,33 @@ +--- +id: agent-brief/model-access-control +artifact_id: model/access-control +source_path: models/access-control/InfoTechCanonAccessControlModel.md +source_kind: model +generated: true +--- + + + +# Agent Brief: InfoTechCanon Access Control Model + +- Artifact ID: `model/access-control` +- Kind: `model` +- Canonical path: `models/access-control/InfoTechCanonAccessControlModel.md` +- Full source: `models/access-control/InfoTechCanonAccessControlModel.md` +- Summary: Domain model used by canon profiles and standards: InfoTechCanon Access Control Model. + +## Retrieval Hints + +Imports and anchors: +- `kernel/itc-core` +- `model/governance` +- `model/organization` + +## Owned Concepts + +- `InfoTechCanon Access Control Model` + +## Related Distinctions + +- **Actor vs Subject vs Principal**: Use actor for the acting entity in a context, subject for the entity a policy evaluates, and principal for the authenticated identity bound to access decisions. +- **Organization Role vs AccessRole vs CARING role**: Organization roles describe responsibility or position; access roles describe permissions; CARING roles classify access-governance needs and analysis. diff --git a/infospace/agent/briefs/model-data.md b/infospace/agent/briefs/model-data.md new file mode 100644 index 0000000..5376eb7 --- /dev/null +++ b/infospace/agent/briefs/model-data.md @@ -0,0 +1,31 @@ +--- +id: agent-brief/model-data +artifact_id: model/data +source_path: models/data/InfoTechCanonDataModel.md +source_kind: model +generated: true +--- + + + +# Agent Brief: InfoTechCanon Data Model + +- Artifact ID: `model/data` +- Kind: `model` +- Canonical path: `models/data/InfoTechCanonDataModel.md` +- Full source: `models/data/InfoTechCanonDataModel.md` +- Summary: Domain model used by canon profiles and standards: InfoTechCanon Data Model. + +## Retrieval Hints + +Imports and anchors: +- `kernel/itc-core` +- `model/governance` + +## Owned Concepts + +- `InfoTechCanon Data Model` + +## Related Distinctions + +No common distinction is anchored directly on this artifact. diff --git a/infospace/agent/briefs/model-devsecops.md b/infospace/agent/briefs/model-devsecops.md new file mode 100644 index 0000000..ef79f76 --- /dev/null +++ b/infospace/agent/briefs/model-devsecops.md @@ -0,0 +1,31 @@ +--- +id: agent-brief/model-devsecops +artifact_id: model/devsecops +source_path: models/devsecops/InfoTechCanonDevSecOpsModel.md +source_kind: model +generated: true +--- + + + +# Agent Brief: InfoTechCanon DevSecOps Model + +- Artifact ID: `model/devsecops` +- Kind: `model` +- Canonical path: `models/devsecops/InfoTechCanonDevSecOpsModel.md` +- Full source: `models/devsecops/InfoTechCanonDevSecOpsModel.md` +- Summary: Domain model used by canon profiles and standards: InfoTechCanon DevSecOps Model. + +## Retrieval Hints + +Imports and anchors: +- `kernel/itc-core` +- `model/security` + +## Owned Concepts + +- `InfoTechCanon DevSecOps Model` + +## Related Distinctions + +No common distinction is anchored directly on this artifact. diff --git a/infospace/agent/briefs/model-governance.md b/infospace/agent/briefs/model-governance.md new file mode 100644 index 0000000..4bb097d --- /dev/null +++ b/infospace/agent/briefs/model-governance.md @@ -0,0 +1,31 @@ +--- +id: agent-brief/model-governance +artifact_id: model/governance +source_path: models/governance/InfoTechCanonGovernanceModel.md +source_kind: model +generated: true +--- + + + +# Agent Brief: InfoTechCanon Governance Model + +- Artifact ID: `model/governance` +- Kind: `model` +- Canonical path: `models/governance/InfoTechCanonGovernanceModel.md` +- Full source: `models/governance/InfoTechCanonGovernanceModel.md` +- Summary: Domain model used by canon profiles and standards: InfoTechCanon Governance Model. + +## Retrieval Hints + +Imports and anchors: +- `kernel/itc-core` + +## Owned Concepts + +- `InfoTechCanon Governance Model` + +## Related Distinctions + +- **Policy vs Control vs Evidence**: Policy states intent or rule, control implements or enforces that rule, and evidence records why the claim should be trusted. +- **Intent vs Scope vs Purpose**: Intent captures why an actor wants something, scope bounds what is included, and purpose captures consumer demand or use case pressure on the repo. diff --git a/infospace/agent/briefs/model-information-space.md b/infospace/agent/briefs/model-information-space.md new file mode 100644 index 0000000..eea3ddd --- /dev/null +++ b/infospace/agent/briefs/model-information-space.md @@ -0,0 +1,30 @@ +--- +id: agent-brief/model-information-space +artifact_id: model/information-space +source_path: models/information-space/InfoTechCanonInformationSpaceModel.md +source_kind: model +generated: true +--- + + + +# Agent Brief: InfoTechCanon Information Space Model + +- Artifact ID: `model/information-space` +- Kind: `model` +- Canonical path: `models/information-space/InfoTechCanonInformationSpaceModel.md` +- Full source: `models/information-space/InfoTechCanonInformationSpaceModel.md` +- Summary: Domain model used by canon profiles and standards: InfoTechCanon Information Space Model. + +## Retrieval Hints + +Imports and anchors: +- `kernel/itc-core` + +## Owned Concepts + +- `InfoTechCanon Information Space Model` + +## Related Distinctions + +No common distinction is anchored directly on this artifact. diff --git a/infospace/agent/briefs/model-landscape.md b/infospace/agent/briefs/model-landscape.md new file mode 100644 index 0000000..4911ef3 --- /dev/null +++ b/infospace/agent/briefs/model-landscape.md @@ -0,0 +1,30 @@ +--- +id: agent-brief/model-landscape +artifact_id: model/landscape +source_path: models/landscape/InfoTechCanonLandscapeModel.md +source_kind: model +generated: true +--- + + + +# Agent Brief: InfoTechCanon Landscape Model + +- Artifact ID: `model/landscape` +- Kind: `model` +- Canonical path: `models/landscape/InfoTechCanonLandscapeModel.md` +- Full source: `models/landscape/InfoTechCanonLandscapeModel.md` +- Summary: Domain model used by canon profiles and standards: InfoTechCanon Landscape Model. + +## Retrieval Hints + +Imports and anchors: +- `kernel/itc-core` + +## Owned Concepts + +- `InfoTechCanon Landscape Model` + +## Related Distinctions + +No common distinction is anchored directly on this artifact. diff --git a/infospace/agent/briefs/model-network.md b/infospace/agent/briefs/model-network.md new file mode 100644 index 0000000..d8929d6 --- /dev/null +++ b/infospace/agent/briefs/model-network.md @@ -0,0 +1,31 @@ +--- +id: agent-brief/model-network +artifact_id: model/network +source_path: models/network/InfoTechCanonNetworkModel.md +source_kind: model +generated: true +--- + + + +# Agent Brief: InfoTechCanon Network Model + +- Artifact ID: `model/network` +- Kind: `model` +- Canonical path: `models/network/InfoTechCanonNetworkModel.md` +- Full source: `models/network/InfoTechCanonNetworkModel.md` +- Summary: Domain model used by canon profiles and standards: InfoTechCanon Network Model. + +## Retrieval Hints + +Imports and anchors: +- `kernel/itc-core` +- `model/security` + +## Owned Concepts + +- `InfoTechCanon Network Model` + +## Related Distinctions + +No common distinction is anchored directly on this artifact. diff --git a/infospace/agent/briefs/model-observability.md b/infospace/agent/briefs/model-observability.md new file mode 100644 index 0000000..b32b0d9 --- /dev/null +++ b/infospace/agent/briefs/model-observability.md @@ -0,0 +1,31 @@ +--- +id: agent-brief/model-observability +artifact_id: model/observability +source_path: models/observability/InfoTechCanonObservabilityModel.md +source_kind: model +generated: true +--- + + + +# Agent Brief: InfoTechCanon Observability Model + +- Artifact ID: `model/observability` +- Kind: `model` +- Canonical path: `models/observability/InfoTechCanonObservabilityModel.md` +- Full source: `models/observability/InfoTechCanonObservabilityModel.md` +- Summary: Domain model used by canon profiles and standards: InfoTechCanon Observability Model. + +## Retrieval Hints + +Imports and anchors: +- `kernel/itc-core` +- `model/task` + +## Owned Concepts + +- `InfoTechCanon Observability Model` + +## Related Distinctions + +- **Policy vs Control vs Evidence**: Policy states intent or rule, control implements or enforces that rule, and evidence records why the claim should be trusted. diff --git a/infospace/agent/briefs/model-organization.md b/infospace/agent/briefs/model-organization.md new file mode 100644 index 0000000..eb22190 --- /dev/null +++ b/infospace/agent/briefs/model-organization.md @@ -0,0 +1,31 @@ +--- +id: agent-brief/model-organization +artifact_id: model/organization +source_path: models/organization/InfoTechCanonOrganizationModel.md +source_kind: model +generated: true +--- + + + +# Agent Brief: InfoTechCanon Organization Model + +- Artifact ID: `model/organization` +- Kind: `model` +- Canonical path: `models/organization/InfoTechCanonOrganizationModel.md` +- Full source: `models/organization/InfoTechCanonOrganizationModel.md` +- Summary: Domain model used by canon profiles and standards: InfoTechCanon Organization Model. + +## Retrieval Hints + +Imports and anchors: +- `kernel/itc-core` + +## Owned Concepts + +- `InfoTechCanon Organization Model` + +## Related Distinctions + +- **Actor vs Subject vs Principal**: Use actor for the acting entity in a context, subject for the entity a policy evaluates, and principal for the authenticated identity bound to access decisions. +- **Organization Role vs AccessRole vs CARING role**: Organization roles describe responsibility or position; access roles describe permissions; CARING roles classify access-governance needs and analysis. diff --git a/infospace/agent/briefs/model-security.md b/infospace/agent/briefs/model-security.md new file mode 100644 index 0000000..64c49f1 --- /dev/null +++ b/infospace/agent/briefs/model-security.md @@ -0,0 +1,31 @@ +--- +id: agent-brief/model-security +artifact_id: model/security +source_path: models/security/InfoTechCanonSecurityModel.md +source_kind: model +generated: true +--- + + + +# Agent Brief: InfoTechCanon Security Model + +- Artifact ID: `model/security` +- Kind: `model` +- Canonical path: `models/security/InfoTechCanonSecurityModel.md` +- Full source: `models/security/InfoTechCanonSecurityModel.md` +- Summary: Domain model used by canon profiles and standards: InfoTechCanon Security Model. + +## Retrieval Hints + +Imports and anchors: +- `kernel/itc-core` +- `model/access-control` + +## Owned Concepts + +- `InfoTechCanon Security Model` + +## Related Distinctions + +- **Policy vs Control vs Evidence**: Policy states intent or rule, control implements or enforces that rule, and evidence records why the claim should be trusted. diff --git a/infospace/agent/briefs/model-task.md b/infospace/agent/briefs/model-task.md new file mode 100644 index 0000000..d4673d2 --- /dev/null +++ b/infospace/agent/briefs/model-task.md @@ -0,0 +1,30 @@ +--- +id: agent-brief/model-task +artifact_id: model/task +source_path: models/task/InfoTechCanonTaskModel.md +source_kind: model +generated: true +--- + + + +# Agent Brief: InfoTechCanon Task Model + +- Artifact ID: `model/task` +- Kind: `model` +- Canonical path: `models/task/InfoTechCanonTaskModel.md` +- Full source: `models/task/InfoTechCanonTaskModel.md` +- Summary: Domain model used by canon profiles and standards: InfoTechCanon Task Model. + +## Retrieval Hints + +Imports and anchors: +- `kernel/itc-core` + +## Owned Concepts + +- `InfoTechCanon Task Model` + +## Related Distinctions + +No common distinction is anchored directly on this artifact. diff --git a/infospace/agent/briefs/profile-small-saas.md b/infospace/agent/briefs/profile-small-saas.md new file mode 100644 index 0000000..e57818b --- /dev/null +++ b/infospace/agent/briefs/profile-small-saas.md @@ -0,0 +1,42 @@ +--- +id: agent-brief/profile-small-saas +artifact_id: profile/small-saas +source_path: profiles/small-saas/profile.yaml +source_kind: profile +generated: true +--- + + + +# Agent Brief: Small SaaS System Profile + +- Artifact ID: `profile/small-saas` +- Kind: `profile` +- Canonical path: `profiles/small-saas/profile.yaml` +- Full source: `profiles/small-saas/profile.yaml` +- Summary: Profile that constrains canon artifacts for a practical implementation slice: Small SaaS System Profile. + +## Retrieval Hints + +Imports and anchors: +- `kernel/itc-core` +- `model/access-control` +- `model/data` +- `model/devsecops` +- `model/governance` +- `model/landscape` +- `model/network` +- `model/observability` +- `model/organization` +- `model/security` +- `model/task` +- `standard/caring` +- `standard/tagging` + +## Owned Concepts + +- `Small SaaS System Profile` + +## Related Distinctions + +- **Intent vs Scope vs Purpose**: Intent captures why an actor wants something, scope bounds what is included, and purpose captures consumer demand or use case pressure on the repo. diff --git a/infospace/agent/briefs/standard-caring.md b/infospace/agent/briefs/standard-caring.md new file mode 100644 index 0000000..0a59594 --- /dev/null +++ b/infospace/agent/briefs/standard-caring.md @@ -0,0 +1,56 @@ +--- +id: agent-brief/standard-caring +artifact_id: standard/caring +source_path: standards/caring/InfoTechCanonCaringAccessGovernanceStandard.md +source_kind: standard +generated: true +--- + + + +# Agent Brief: InfoTechCanon CARING Access Governance Standard + +- Artifact ID: `standard/caring` +- Kind: `standard` +- Canonical path: `standards/caring/InfoTechCanonCaringAccessGovernanceStandard.md` +- Full source: `standards/caring/InfoTechCanonCaringAccessGovernanceStandard.md` +- Summary: Cross-cutting canon standard: InfoTechCanon CARING Access Governance Standard. + +## Retrieval Hints + +Imports and anchors: +- `kernel/itc-core` +- `model/access-control` +- `model/data` +- `model/devsecops` +- `model/governance` +- `model/network` +- `model/observability` +- `model/organization` +- `model/security` +- `model/task` +- `standard/tagging` + +## Owned Concepts + +- `CARINGAccessDescriptor` +- `CARINGAnalysisFitnessTest` +- `CARINGAnalysisProcedure` +- `CARINGCanonicalRole` +- `CARINGCapabilityProfile` +- `CARINGDeclaredAccessMap` +- `CARINGDerivedCapability` +- `CARINGEffectiveAccessMap` +- `CARINGExposureEvent` +- `CARINGExposureMode` +- `CARINGInducedAccess` +- `CARINGOrganizationRelation` +- `CARINGPlane` +- `CARINGRedesignProcedure` +- `CARINGRestrictionPrecedence` +- `InfoTechCanon CARING Access Governance Standard` + +## Related Distinctions + +- **Actor vs Subject vs Principal**: Use actor for the acting entity in a context, subject for the entity a policy evaluates, and principal for the authenticated identity bound to access decisions. +- **Organization Role vs AccessRole vs CARING role**: Organization roles describe responsibility or position; access roles describe permissions; CARING roles classify access-governance needs and analysis. diff --git a/infospace/agent/briefs/standard-tagging.md b/infospace/agent/briefs/standard-tagging.md new file mode 100644 index 0000000..a2ae4c1 --- /dev/null +++ b/infospace/agent/briefs/standard-tagging.md @@ -0,0 +1,31 @@ +--- +id: agent-brief/standard-tagging +artifact_id: standard/tagging +source_path: standards/tagging/InfoTechCanonTaggingStandard.md +source_kind: standard +generated: true +--- + + + +# Agent Brief: InfoTechCanon Tagging Standard + +- Artifact ID: `standard/tagging` +- Kind: `standard` +- Canonical path: `standards/tagging/InfoTechCanonTaggingStandard.md` +- Full source: `standards/tagging/InfoTechCanonTaggingStandard.md` +- Summary: Cross-cutting canon standard: InfoTechCanon Tagging Standard. + +## Retrieval Hints + +Imports and anchors: +- `kernel/itc-core` +- `model/task` + +## Owned Concepts + +- `InfoTechCanon Tagging Standard` + +## Related Distinctions + +No common distinction is anchored directly on this artifact. diff --git a/infospace/agent/consumer-briefs/railiance-fabric.md b/infospace/agent/consumer-briefs/railiance-fabric.md new file mode 100644 index 0000000..5df1855 --- /dev/null +++ b/infospace/agent/consumer-briefs/railiance-fabric.md @@ -0,0 +1,24 @@ +--- +id: consumer-brief/railiance-fabric +consumer: railiance-fabric +generated: true +--- + + + +# Railiance Fabric Canon Consumer Brief + +## Purpose + +Use the canon to make captured entities and edges cleaner for conformance and visualization. + +## Starting Points + +- `agent/retrieval-index.md` +- `agent/templates/canon-interface-card.template.yaml` +- `profiles/small-saas/profile.yaml` +- `views/by-concept.md` + +## Workplan Boundary + +Adoption and repo-specific implementation workplans belong in the consumer repository. diff --git a/infospace/agent/consumer-briefs/repo-scoping.md b/infospace/agent/consumer-briefs/repo-scoping.md new file mode 100644 index 0000000..fdb5544 --- /dev/null +++ b/infospace/agent/consumer-briefs/repo-scoping.md @@ -0,0 +1,24 @@ +--- +id: consumer-brief/repo-scoping +consumer: repo-scoping +generated: true +--- + + + +# Repo Scoping Canon Consumer Brief + +## Purpose + +Compare repo-scoping concepts with canon INTENT, SCOPE, PURPOSES, and interface-card expectations. + +## Starting Points + +- `agent/retrieval-index.md` +- `agent/templates/canon-interface-card.template.yaml` +- `profiles/small-saas/profile.yaml` +- `views/by-concept.md` + +## Workplan Boundary + +Adoption and repo-specific implementation workplans belong in the consumer repository. diff --git a/infospace/agent/consumer-briefs/user-engine.md b/infospace/agent/consumer-briefs/user-engine.md new file mode 100644 index 0000000..dd309f6 --- /dev/null +++ b/infospace/agent/consumer-briefs/user-engine.md @@ -0,0 +1,24 @@ +--- +id: consumer-brief/user-engine +consumer: user-engine +generated: true +--- + + + +# User Engine Canon Consumer Brief + +## Purpose + +Evaluate user-management concepts, roles, access traces, profile claims, and governance evidence against the canon before integration. + +## Starting Points + +- `agent/retrieval-index.md` +- `agent/templates/canon-interface-card.template.yaml` +- `profiles/small-saas/profile.yaml` +- `views/by-concept.md` + +## Workplan Boundary + +Adoption and repo-specific implementation workplans belong in the consumer repository. diff --git a/infospace/agent/global-agent-brief.md b/infospace/agent/global-agent-brief.md index 5da9cf0..8e68ada 100644 --- a/infospace/agent/global-agent-brief.md +++ b/infospace/agent/global-agent-brief.md @@ -6,8 +6,10 @@ This brief summarizes the current canon service surface for agents. - Infospace slug: `canon` - Artifact count: 29 +- Retrieval index items: 29 - Primary confidence command: `make validate` - Refresh generated indexes and views with: `make index` +- Refresh agent briefs and interface templates with: `make agent-briefs` ## Useful Commands @@ -15,6 +17,22 @@ This brief summarizes the current canon service surface for agents. - `PYTHONPATH=src python3 -m info_tech_canon validate` - `PYTHONPATH=src python3 -m info_tech_canon graph` - `PYTHONPATH=src python3 -m info_tech_canon index` +- `PYTHONPATH=src python3 -m info_tech_canon profile validate small-saas` + +## Retrieval Entry Points + +- `agent/retrieval-index.md` +- `agent/retrieval-index.yaml` +- `agent/retrieval-index.json` +- `agent/briefs/` for per-artifact briefs +- `agent/templates/canon-interface-card.template.yaml` + +## Common Distinctions + +- **Actor vs Subject vs Principal**: Use actor for the acting entity in a context, subject for the entity a policy evaluates, and principal for the authenticated identity bound to access decisions. +- **Organization Role vs AccessRole vs CARING role**: Organization roles describe responsibility or position; access roles describe permissions; CARING roles classify access-governance needs and analysis. +- **Policy vs Control vs Evidence**: Policy states intent or rule, control implements or enforces that rule, and evidence records why the claim should be trusted. +- **Intent vs Scope vs Purpose**: Intent captures why an actor wants something, scope bounds what is included, and purpose captures consumer demand or use case pressure on the repo. ## Consumption Notes diff --git a/infospace/agent/retrieval-index.json b/infospace/agent/retrieval-index.json new file mode 100644 index 0000000..413711a --- /dev/null +++ b/infospace/agent/retrieval-index.json @@ -0,0 +1,1038 @@ +{ + "common_distinctions": [ + { + "id": "actor-subject-principal", + "source_artifacts": [ + "model/organization", + "model/access-control", + "standard/caring" + ], + "summary": "Use actor for the acting entity in a context, subject for the entity a policy evaluates, and principal for the authenticated identity bound to access decisions.", + "title": "Actor vs Subject vs Principal" + }, + { + "id": "organization-role-access-role-caring-role", + "source_artifacts": [ + "model/organization", + "model/access-control", + "standard/caring" + ], + "summary": "Organization roles describe responsibility or position; access roles describe permissions; CARING roles classify access-governance needs and analysis.", + "title": "Organization Role vs AccessRole vs CARING role" + }, + { + "id": "policy-control-evidence", + "source_artifacts": [ + "model/governance", + "model/security", + "model/observability" + ], + "summary": "Policy states intent or rule, control implements or enforces that rule, and evidence records why the claim should be trusted.", + "title": "Policy vs Control vs Evidence" + }, + { + "id": "intent-scope-purpose", + "source_artifacts": [ + "kernel/itc-core", + "model/governance", + "profile/small-saas" + ], + "summary": "Intent captures why an actor wants something, scope bounds what is included, and purpose captures consumer demand or use case pressure on the repo.", + "title": "Intent vs Scope vs Purpose" + } + ], + "infospace": "canon", + "item_count": 29, + "items": [ + { + "canonical_path": "kernel/InfoTechCanonCore.md", + "id": "kernel/itc-core", + "imports": [], + "kind": "kernel", + "owned_concepts": [ + "InfoTechCanon Core" + ], + "relationships": [], + "source_path": "seeds/InfoTechCanonCore_RC1_seed.md", + "summary": "Kernel artifact that defines canon structure or integration: InfoTechCanon Core.", + "title": "InfoTechCanon Core", + "warnings": [] + }, + { + "canonical_path": "kernel/InfoTechCanonKernelMap.md", + "id": "kernel/itc-kernel-map", + "imports": [], + "kind": "kernel", + "owned_concepts": [ + "InfoTechCanon Kernel Map" + ], + "relationships": [ + { + "target": "kernel/itc-core", + "type": "maps" + }, + { + "target": "model/information-space", + "type": "maps" + }, + { + "target": "model/landscape", + "type": "maps" + }, + { + "target": "model/organization", + "type": "maps" + }, + { + "target": "model/governance", + "type": "maps" + }, + { + "target": "model/task", + "type": "maps" + }, + { + "target": "model/access-control", + "type": "maps" + }, + { + "target": "model/security", + "type": "maps" + }, + { + "target": "model/data", + "type": "maps" + }, + { + "target": "model/devsecops", + "type": "maps" + }, + { + "target": "model/network", + "type": "maps" + }, + { + "target": "model/observability", + "type": "maps" + }, + { + "target": "standard/tagging", + "type": "maps" + }, + { + "target": "standard/caring", + "type": "maps" + } + ], + "source_path": "seeds/InfoTechCanonKernelMap_RC1.md", + "summary": "Kernel artifact that defines canon structure or integration: InfoTechCanon Kernel Map.", + "title": "InfoTechCanon Kernel Map", + "warnings": [] + }, + { + "canonical_path": "models/access-control/InfoTechCanonAccessControlModel.md", + "id": "model/access-control", + "imports": [ + "kernel/itc-core", + "model/governance", + "model/organization" + ], + "kind": "model", + "owned_concepts": [ + "InfoTechCanon Access Control Model" + ], + "relationships": [ + { + "target": "kernel/itc-core", + "type": "conforms_to" + }, + { + "target": "model/organization", + "type": "uses" + }, + { + "target": "model/governance", + "type": "uses" + } + ], + "source_path": "seeds/InfoTechCanonAccessControlModel_RC1_seed.md", + "summary": "Domain model used by canon profiles and standards: InfoTechCanon Access Control Model.", + "title": "InfoTechCanon Access Control Model", + "warnings": [] + }, + { + "canonical_path": "models/data/InfoTechCanonDataModel.md", + "id": "model/data", + "imports": [ + "kernel/itc-core", + "model/governance" + ], + "kind": "model", + "owned_concepts": [ + "InfoTechCanon Data Model" + ], + "relationships": [ + { + "target": "kernel/itc-core", + "type": "conforms_to" + }, + { + "target": "model/governance", + "type": "uses" + } + ], + "source_path": "seeds/InfoTechCanonDataModel_RC1_seed.md", + "summary": "Domain model used by canon profiles and standards: InfoTechCanon Data Model.", + "title": "InfoTechCanon Data Model", + "warnings": [] + }, + { + "canonical_path": "models/devsecops/InfoTechCanonDevSecOpsModel.md", + "id": "model/devsecops", + "imports": [ + "kernel/itc-core", + "model/security" + ], + "kind": "model", + "owned_concepts": [ + "InfoTechCanon DevSecOps Model" + ], + "relationships": [ + { + "target": "kernel/itc-core", + "type": "conforms_to" + }, + { + "target": "model/security", + "type": "uses" + } + ], + "source_path": "seeds/InfoTechCanonDevSecOpsModel_RC1_seed.md", + "summary": "Domain model used by canon profiles and standards: InfoTechCanon DevSecOps Model.", + "title": "InfoTechCanon DevSecOps Model", + "warnings": [] + }, + { + "canonical_path": "models/governance/InfoTechCanonGovernanceModel.md", + "id": "model/governance", + "imports": [ + "kernel/itc-core" + ], + "kind": "model", + "owned_concepts": [ + "InfoTechCanon Governance Model" + ], + "relationships": [ + { + "target": "kernel/itc-core", + "type": "conforms_to" + } + ], + "source_path": "seeds/InfoTechCanonGovernanceModel_RC1_seed.md", + "summary": "Domain model used by canon profiles and standards: InfoTechCanon Governance Model.", + "title": "InfoTechCanon Governance Model", + "warnings": [] + }, + { + "canonical_path": "models/information-space/InfoTechCanonInformationSpaceModel.md", + "id": "model/information-space", + "imports": [ + "kernel/itc-core" + ], + "kind": "model", + "owned_concepts": [ + "InfoTechCanon Information Space Model" + ], + "relationships": [ + { + "target": "kernel/itc-core", + "type": "conforms_to" + } + ], + "source_path": "seeds/InfoTechCanonInformationSpaceModel_RC1_seed.md", + "summary": "Domain model used by canon profiles and standards: InfoTechCanon Information Space Model.", + "title": "InfoTechCanon Information Space Model", + "warnings": [] + }, + { + "canonical_path": "models/landscape/InfoTechCanonLandscapeModel.md", + "id": "model/landscape", + "imports": [ + "kernel/itc-core" + ], + "kind": "model", + "owned_concepts": [ + "InfoTechCanon Landscape Model" + ], + "relationships": [ + { + "target": "kernel/itc-core", + "type": "conforms_to" + } + ], + "source_path": "seeds/InfoTechCanonLandscapeModel_RC1_seed.md", + "summary": "Domain model used by canon profiles and standards: InfoTechCanon Landscape Model.", + "title": "InfoTechCanon Landscape Model", + "warnings": [] + }, + { + "canonical_path": "models/network/InfoTechCanonNetworkModel.md", + "id": "model/network", + "imports": [ + "kernel/itc-core", + "model/security" + ], + "kind": "model", + "owned_concepts": [ + "InfoTechCanon Network Model" + ], + "relationships": [ + { + "target": "kernel/itc-core", + "type": "conforms_to" + }, + { + "target": "model/security", + "type": "uses" + } + ], + "source_path": "seeds/InfoTechCanonNetworkModel_RC1_seed.md", + "summary": "Domain model used by canon profiles and standards: InfoTechCanon Network Model.", + "title": "InfoTechCanon Network Model", + "warnings": [] + }, + { + "canonical_path": "models/observability/InfoTechCanonObservabilityModel.md", + "id": "model/observability", + "imports": [ + "kernel/itc-core", + "model/task" + ], + "kind": "model", + "owned_concepts": [ + "InfoTechCanon Observability Model" + ], + "relationships": [ + { + "target": "kernel/itc-core", + "type": "conforms_to" + }, + { + "target": "model/task", + "type": "uses" + } + ], + "source_path": "seeds/InfoTechCanonObservabilityModel_RC1_seed.md", + "summary": "Domain model used by canon profiles and standards: InfoTechCanon Observability Model.", + "title": "InfoTechCanon Observability Model", + "warnings": [] + }, + { + "canonical_path": "models/organization/InfoTechCanonOrganizationModel.md", + "id": "model/organization", + "imports": [ + "kernel/itc-core" + ], + "kind": "model", + "owned_concepts": [ + "InfoTechCanon Organization Model" + ], + "relationships": [ + { + "target": "kernel/itc-core", + "type": "conforms_to" + } + ], + "source_path": "seeds/InfoTechCanonOrganizationModel_RC1_seed.md", + "summary": "Domain model used by canon profiles and standards: InfoTechCanon Organization Model.", + "title": "InfoTechCanon Organization Model", + "warnings": [] + }, + { + "canonical_path": "models/security/InfoTechCanonSecurityModel.md", + "id": "model/security", + "imports": [ + "kernel/itc-core", + "model/access-control" + ], + "kind": "model", + "owned_concepts": [ + "InfoTechCanon Security Model" + ], + "relationships": [ + { + "target": "kernel/itc-core", + "type": "conforms_to" + }, + { + "target": "model/access-control", + "type": "uses" + } + ], + "source_path": "seeds/InfoTechCanonSecurityModel_RC1_seed.md", + "summary": "Domain model used by canon profiles and standards: InfoTechCanon Security Model.", + "title": "InfoTechCanon Security Model", + "warnings": [] + }, + { + "canonical_path": "models/task/InfoTechCanonTaskModel.md", + "id": "model/task", + "imports": [ + "kernel/itc-core" + ], + "kind": "model", + "owned_concepts": [ + "InfoTechCanon Task Model" + ], + "relationships": [ + { + "target": "kernel/itc-core", + "type": "conforms_to" + } + ], + "source_path": "seeds/InfoTechCanonTaskModel_RC1_seed.md", + "summary": "Domain model used by canon profiles and standards: InfoTechCanon Task Model.", + "title": "InfoTechCanon Task Model", + "warnings": [] + }, + { + "canonical_path": "profiles/small-saas/profile.yaml", + "id": "profile/small-saas", + "imports": [ + "kernel/itc-core", + "model/access-control", + "model/data", + "model/devsecops", + "model/governance", + "model/landscape", + "model/network", + "model/observability", + "model/organization", + "model/security", + "model/task", + "standard/caring", + "standard/tagging" + ], + "kind": "profile", + "owned_concepts": [ + "Small SaaS System Profile" + ], + "relationships": [ + { + "target": "kernel/itc-core", + "type": "conforms_to" + }, + { + "target": "model/landscape", + "type": "requires" + }, + { + "target": "model/organization", + "type": "requires" + }, + { + "target": "model/governance", + "type": "requires" + }, + { + "target": "model/access-control", + "type": "requires" + }, + { + "target": "model/security", + "type": "requires" + }, + { + "target": "model/data", + "type": "requires" + }, + { + "target": "model/devsecops", + "type": "requires" + }, + { + "target": "model/network", + "type": "requires" + }, + { + "target": "model/observability", + "type": "requires" + }, + { + "target": "model/task", + "type": "requires" + }, + { + "target": "standard/tagging", + "type": "requires" + }, + { + "target": "standard/caring", + "type": "requires" + } + ], + "source_path": "infospace/profiles/small-saas/profile.yaml", + "summary": "Profile that constrains canon artifacts for a practical implementation slice: Small SaaS System Profile.", + "title": "Small SaaS System Profile", + "warnings": [] + }, + { + "canonical_path": "profiles/small-saas/artifacts/control.namespace-per-tenant.yaml", + "id": "small-saas/control/namespace-per-tenant", + "imports": [ + "model/security", + "standard/caring" + ], + "kind": "profile-artifact", + "owned_concepts": [ + "Namespace Per Tenant Control" + ], + "relationships": [ + { + "target": "profile/small-saas", + "type": "instantiates" + }, + { + "target": "model/security", + "type": "uses" + }, + { + "target": "standard/caring", + "type": "uses" + }, + { + "target": "small-saas/evidence/access-review-2026-05", + "type": "evidenced_by" + } + ], + "source_path": "profiles/small-saas/artifacts/control.namespace-per-tenant.yaml", + "summary": "Example artifact for the small-saas profile: Namespace Per Tenant Control.", + "title": "Namespace Per Tenant Control", + "warnings": [] + }, + { + "canonical_path": "profiles/small-saas/artifacts/dataset.subscription-ledger.yaml", + "id": "small-saas/dataset/subscription-ledger", + "imports": [ + "model/data" + ], + "kind": "profile-artifact", + "owned_concepts": [ + "Subscription Ledger Dataset" + ], + "relationships": [ + { + "target": "profile/small-saas", + "type": "instantiates" + }, + { + "target": "model/data", + "type": "uses" + }, + { + "target": "small-saas/service/billing-portal", + "type": "owned_by" + }, + { + "target": "small-saas/tenant/acme", + "type": "partitioned_for" + }, + { + "target": "small-saas/tenant/globex", + "type": "partitioned_for" + }, + { + "target": "small-saas/policy/tenant-isolation", + "type": "governed_by" + } + ], + "source_path": "profiles/small-saas/artifacts/dataset.subscription-ledger.yaml", + "summary": "Example artifact for the small-saas profile: Subscription Ledger Dataset.", + "title": "Subscription Ledger Dataset", + "warnings": [] + }, + { + "canonical_path": "profiles/small-saas/artifacts/deployment.production.yaml", + "id": "small-saas/deployment/production", + "imports": [ + "model/devsecops", + "model/network" + ], + "kind": "profile-artifact", + "owned_concepts": [ + "Production Deployment" + ], + "relationships": [ + { + "target": "profile/small-saas", + "type": "instantiates" + }, + { + "target": "model/devsecops", + "type": "uses" + }, + { + "target": "model/network", + "type": "uses" + }, + { + "target": "small-saas/service/billing-portal", + "type": "deploys" + }, + { + "target": "small-saas/tenant/acme", + "type": "separates" + }, + { + "target": "small-saas/tenant/globex", + "type": "separates" + }, + { + "target": "small-saas/control/namespace-per-tenant", + "type": "implements" + } + ], + "source_path": "profiles/small-saas/artifacts/deployment.production.yaml", + "summary": "Example artifact for the small-saas profile: Production Deployment.", + "title": "Production Deployment", + "warnings": [] + }, + { + "canonical_path": "profiles/small-saas/artifacts/evidence.access-review-2026-05.yaml", + "id": "small-saas/evidence/access-review-2026-05", + "imports": [ + "model/observability" + ], + "kind": "profile-artifact", + "owned_concepts": [ + "Access Review 2026-05" + ], + "relationships": [ + { + "target": "profile/small-saas", + "type": "instantiates" + }, + { + "target": "model/observability", + "type": "uses" + } + ], + "source_path": "profiles/small-saas/artifacts/evidence.access-review-2026-05.yaml", + "summary": "Example artifact for the small-saas profile: Access Review 2026-05.", + "title": "Access Review 2026-05", + "warnings": [] + }, + { + "canonical_path": "profiles/small-saas/artifacts/incident.cross-tenant-access-attempt.yaml", + "id": "small-saas/incident/cross-tenant-access-attempt", + "imports": [ + "model/security" + ], + "kind": "profile-artifact", + "owned_concepts": [ + "Cross-Tenant Access Attempt" + ], + "relationships": [ + { + "target": "profile/small-saas", + "type": "instantiates" + }, + { + "target": "model/security", + "type": "uses" + }, + { + "target": "small-saas/control/namespace-per-tenant", + "type": "constrained_by" + }, + { + "target": "small-saas/evidence/access-review-2026-05", + "type": "evidenced_by" + } + ], + "source_path": "profiles/small-saas/artifacts/incident.cross-tenant-access-attempt.yaml", + "summary": "Example artifact for the small-saas profile: Cross-Tenant Access Attempt.", + "title": "Cross-Tenant Access Attempt", + "warnings": [] + }, + { + "canonical_path": "profiles/small-saas/artifacts/policy.tenant-isolation.yaml", + "id": "small-saas/policy/tenant-isolation", + "imports": [ + "model/governance", + "small-saas/control/namespace-per-tenant" + ], + "kind": "profile-artifact", + "owned_concepts": [ + "Tenant Isolation Policy" + ], + "relationships": [ + { + "target": "profile/small-saas", + "type": "instantiates" + }, + { + "target": "model/governance", + "type": "uses" + }, + { + "target": "small-saas/control/namespace-per-tenant", + "type": "requires" + }, + { + "target": "small-saas/evidence/access-review-2026-05", + "type": "evidenced_by" + } + ], + "source_path": "profiles/small-saas/artifacts/policy.tenant-isolation.yaml", + "summary": "Example artifact for the small-saas profile: Tenant Isolation Policy.", + "title": "Tenant Isolation Policy", + "warnings": [] + }, + { + "canonical_path": "profiles/small-saas/artifacts/service.billing-portal.yaml", + "id": "small-saas/service/billing-portal", + "imports": [ + "model/landscape" + ], + "kind": "profile-artifact", + "owned_concepts": [ + "Billing Portal Service" + ], + "relationships": [ + { + "target": "profile/small-saas", + "type": "instantiates" + }, + { + "target": "model/landscape", + "type": "uses" + }, + { + "target": "small-saas/system/billing-system", + "type": "part_of" + }, + { + "target": "small-saas/team/platform", + "type": "owned_by" + } + ], + "source_path": "profiles/small-saas/artifacts/service.billing-portal.yaml", + "summary": "Example artifact for the small-saas profile: Billing Portal Service.", + "title": "Billing Portal Service", + "warnings": [] + }, + { + "canonical_path": "profiles/small-saas/artifacts/system.billing-system.yaml", + "id": "small-saas/system/billing-system", + "imports": [ + "model/landscape" + ], + "kind": "profile-artifact", + "owned_concepts": [ + "Small SaaS Billing System" + ], + "relationships": [ + { + "target": "profile/small-saas", + "type": "instantiates" + }, + { + "target": "model/landscape", + "type": "uses" + }, + { + "target": "small-saas/tenant/acme", + "type": "serves" + }, + { + "target": "small-saas/tenant/globex", + "type": "serves" + } + ], + "source_path": "profiles/small-saas/artifacts/system.billing-system.yaml", + "summary": "Example artifact for the small-saas profile: Small SaaS Billing System.", + "title": "Small SaaS Billing System", + "warnings": [] + }, + { + "canonical_path": "profiles/small-saas/artifacts/task.onboard-tenant.yaml", + "id": "small-saas/task/onboard-tenant", + "imports": [ + "model/task" + ], + "kind": "profile-artifact", + "owned_concepts": [ + "Onboard Tenant" + ], + "relationships": [ + { + "target": "profile/small-saas", + "type": "instantiates" + }, + { + "target": "model/task", + "type": "uses" + }, + { + "target": "small-saas/team/platform", + "type": "owned_by" + }, + { + "target": "small-saas/tenant/acme", + "type": "changes" + }, + { + "target": "small-saas/policy/tenant-isolation", + "type": "governed_by" + } + ], + "source_path": "profiles/small-saas/artifacts/task.onboard-tenant.yaml", + "summary": "Example artifact for the small-saas profile: Onboard Tenant.", + "title": "Onboard Tenant", + "warnings": [] + }, + { + "canonical_path": "profiles/small-saas/artifacts/team.platform.yaml", + "id": "small-saas/team/platform", + "imports": [ + "model/organization" + ], + "kind": "profile-artifact", + "owned_concepts": [ + "Platform Team" + ], + "relationships": [ + { + "target": "profile/small-saas", + "type": "instantiates" + }, + { + "target": "model/organization", + "type": "uses" + } + ], + "source_path": "profiles/small-saas/artifacts/team.platform.yaml", + "summary": "Example artifact for the small-saas profile: Platform Team.", + "title": "Platform Team", + "warnings": [] + }, + { + "canonical_path": "profiles/small-saas/artifacts/tenant.acme.yaml", + "id": "small-saas/tenant/acme", + "imports": [ + "model/organization" + ], + "kind": "profile-artifact", + "owned_concepts": [ + "Acme Tenant" + ], + "relationships": [ + { + "target": "profile/small-saas", + "type": "instantiates" + }, + { + "target": "model/organization", + "type": "uses" + }, + { + "target": "small-saas/user/ada-admin", + "type": "represented_by" + }, + { + "target": "small-saas/control/namespace-per-tenant", + "type": "isolated_by" + } + ], + "source_path": "profiles/small-saas/artifacts/tenant.acme.yaml", + "summary": "Example artifact for the small-saas profile: Acme Tenant.", + "title": "Acme Tenant", + "warnings": [] + }, + { + "canonical_path": "profiles/small-saas/artifacts/tenant.globex.yaml", + "id": "small-saas/tenant/globex", + "imports": [ + "model/organization" + ], + "kind": "profile-artifact", + "owned_concepts": [ + "Globex Tenant" + ], + "relationships": [ + { + "target": "profile/small-saas", + "type": "instantiates" + }, + { + "target": "model/organization", + "type": "uses" + }, + { + "target": "small-saas/control/namespace-per-tenant", + "type": "isolated_by" + } + ], + "source_path": "profiles/small-saas/artifacts/tenant.globex.yaml", + "summary": "Example artifact for the small-saas profile: Globex Tenant.", + "title": "Globex Tenant", + "warnings": [] + }, + { + "canonical_path": "profiles/small-saas/artifacts/user.ada-admin.yaml", + "id": "small-saas/user/ada-admin", + "imports": [ + "model/access-control", + "model/organization" + ], + "kind": "profile-artifact", + "owned_concepts": [ + "Ada Admin" + ], + "relationships": [ + { + "target": "profile/small-saas", + "type": "instantiates" + }, + { + "target": "model/organization", + "type": "uses" + }, + { + "target": "model/access-control", + "type": "uses" + }, + { + "target": "small-saas/team/platform", + "type": "member_of" + }, + { + "target": "small-saas/policy/tenant-isolation", + "type": "has_access_under" + }, + { + "target": "small-saas/evidence/access-review-2026-05", + "type": "access_evidenced_by" + } + ], + "source_path": "profiles/small-saas/artifacts/user.ada-admin.yaml", + "summary": "Example artifact for the small-saas profile: Ada Admin.", + "title": "Ada Admin", + "warnings": [] + }, + { + "canonical_path": "standards/caring/InfoTechCanonCaringAccessGovernanceStandard.md", + "id": "standard/caring", + "imports": [ + "kernel/itc-core", + "model/access-control", + "model/data", + "model/devsecops", + "model/governance", + "model/network", + "model/observability", + "model/organization", + "model/security", + "model/task", + "standard/tagging" + ], + "kind": "standard", + "owned_concepts": [ + "CARINGAccessDescriptor", + "CARINGAnalysisFitnessTest", + "CARINGAnalysisProcedure", + "CARINGCanonicalRole", + "CARINGCapabilityProfile", + "CARINGDeclaredAccessMap", + "CARINGDerivedCapability", + "CARINGEffectiveAccessMap", + "CARINGExposureEvent", + "CARINGExposureMode", + "CARINGInducedAccess", + "CARINGOrganizationRelation", + "CARINGPlane", + "CARINGRedesignProcedure", + "CARINGRestrictionPrecedence", + "InfoTechCanon CARING Access Governance Standard" + ], + "relationships": [ + { + "target": "kernel/itc-core", + "type": "conforms_to" + }, + { + "target": "model/organization", + "type": "imports" + }, + { + "target": "model/governance", + "type": "imports" + }, + { + "target": "model/access-control", + "type": "imports" + }, + { + "target": "model/security", + "type": "imports" + }, + { + "target": "model/data", + "type": "imports" + }, + { + "target": "model/devsecops", + "type": "imports" + }, + { + "target": "model/network", + "type": "imports" + }, + { + "target": "model/observability", + "type": "imports" + }, + { + "target": "model/task", + "type": "imports" + }, + { + "target": "standard/tagging", + "type": "imports" + } + ], + "source_path": "seeds/InfoTechCanonCaringAccessGovernanceStandard.md", + "summary": "Cross-cutting canon standard: InfoTechCanon CARING Access Governance Standard.", + "title": "InfoTechCanon CARING Access Governance Standard", + "warnings": [] + }, + { + "canonical_path": "standards/tagging/InfoTechCanonTaggingStandard.md", + "id": "standard/tagging", + "imports": [ + "kernel/itc-core", + "model/task" + ], + "kind": "standard", + "owned_concepts": [ + "InfoTechCanon Tagging Standard" + ], + "relationships": [ + { + "target": "kernel/itc-core", + "type": "conforms_to" + }, + { + "target": "model/task", + "type": "imports" + } + ], + "source_path": "seeds/InfoTechCanonTaggingStandard_RC1_seed.md", + "summary": "Cross-cutting canon standard: InfoTechCanon Tagging Standard.", + "title": "InfoTechCanon Tagging Standard", + "warnings": [] + } + ], + "schema": "info-tech-canon.retrieval-index.v1" +} diff --git a/infospace/agent/retrieval-index.md b/infospace/agent/retrieval-index.md new file mode 100644 index 0000000..9a27f96 --- /dev/null +++ b/infospace/agent/retrieval-index.md @@ -0,0 +1,306 @@ + + +# Retrieval Index + +Schema: `info-tech-canon.retrieval-index.v1` +Infospace: `canon` +Items: **29** + +## Common Distinctions + +- **Actor vs Subject vs Principal**: Use actor for the acting entity in a context, subject for the entity a policy evaluates, and principal for the authenticated identity bound to access decisions. Sources: `model/organization`, `model/access-control`, `standard/caring` +- **Organization Role vs AccessRole vs CARING role**: Organization roles describe responsibility or position; access roles describe permissions; CARING roles classify access-governance needs and analysis. Sources: `model/organization`, `model/access-control`, `standard/caring` +- **Policy vs Control vs Evidence**: Policy states intent or rule, control implements or enforces that rule, and evidence records why the claim should be trusted. Sources: `model/governance`, `model/security`, `model/observability` +- **Intent vs Scope vs Purpose**: Intent captures why an actor wants something, scope bounds what is included, and purpose captures consumer demand or use case pressure on the repo. Sources: `kernel/itc-core`, `model/governance`, `profile/small-saas` + +## Items + +### InfoTechCanon Core + +- ID: `kernel/itc-core` +- Kind: `kernel` +- Canonical path: `kernel/InfoTechCanonCore.md` +- Source path: `seeds/InfoTechCanonCore_RC1_seed.md` +- Summary: Kernel artifact that defines canon structure or integration: InfoTechCanon Core. +- Imports and anchors: none +- Owned concepts: `InfoTechCanon Core` + +### InfoTechCanon Kernel Map + +- ID: `kernel/itc-kernel-map` +- Kind: `kernel` +- Canonical path: `kernel/InfoTechCanonKernelMap.md` +- Source path: `seeds/InfoTechCanonKernelMap_RC1.md` +- Summary: Kernel artifact that defines canon structure or integration: InfoTechCanon Kernel Map. +- Imports and anchors: none +- Owned concepts: `InfoTechCanon Kernel Map` + +### InfoTechCanon Access Control Model + +- ID: `model/access-control` +- Kind: `model` +- Canonical path: `models/access-control/InfoTechCanonAccessControlModel.md` +- Source path: `seeds/InfoTechCanonAccessControlModel_RC1_seed.md` +- Summary: Domain model used by canon profiles and standards: InfoTechCanon Access Control Model. +- Imports and anchors: `kernel/itc-core`, `model/governance`, `model/organization` +- Owned concepts: `InfoTechCanon Access Control Model` + +### InfoTechCanon Data Model + +- ID: `model/data` +- Kind: `model` +- Canonical path: `models/data/InfoTechCanonDataModel.md` +- Source path: `seeds/InfoTechCanonDataModel_RC1_seed.md` +- Summary: Domain model used by canon profiles and standards: InfoTechCanon Data Model. +- Imports and anchors: `kernel/itc-core`, `model/governance` +- Owned concepts: `InfoTechCanon Data Model` + +### InfoTechCanon DevSecOps Model + +- ID: `model/devsecops` +- Kind: `model` +- Canonical path: `models/devsecops/InfoTechCanonDevSecOpsModel.md` +- Source path: `seeds/InfoTechCanonDevSecOpsModel_RC1_seed.md` +- Summary: Domain model used by canon profiles and standards: InfoTechCanon DevSecOps Model. +- Imports and anchors: `kernel/itc-core`, `model/security` +- Owned concepts: `InfoTechCanon DevSecOps Model` + +### InfoTechCanon Governance Model + +- ID: `model/governance` +- Kind: `model` +- Canonical path: `models/governance/InfoTechCanonGovernanceModel.md` +- Source path: `seeds/InfoTechCanonGovernanceModel_RC1_seed.md` +- Summary: Domain model used by canon profiles and standards: InfoTechCanon Governance Model. +- Imports and anchors: `kernel/itc-core` +- Owned concepts: `InfoTechCanon Governance Model` + +### InfoTechCanon Information Space Model + +- ID: `model/information-space` +- Kind: `model` +- Canonical path: `models/information-space/InfoTechCanonInformationSpaceModel.md` +- Source path: `seeds/InfoTechCanonInformationSpaceModel_RC1_seed.md` +- Summary: Domain model used by canon profiles and standards: InfoTechCanon Information Space Model. +- Imports and anchors: `kernel/itc-core` +- Owned concepts: `InfoTechCanon Information Space Model` + +### InfoTechCanon Landscape Model + +- ID: `model/landscape` +- Kind: `model` +- Canonical path: `models/landscape/InfoTechCanonLandscapeModel.md` +- Source path: `seeds/InfoTechCanonLandscapeModel_RC1_seed.md` +- Summary: Domain model used by canon profiles and standards: InfoTechCanon Landscape Model. +- Imports and anchors: `kernel/itc-core` +- Owned concepts: `InfoTechCanon Landscape Model` + +### InfoTechCanon Network Model + +- ID: `model/network` +- Kind: `model` +- Canonical path: `models/network/InfoTechCanonNetworkModel.md` +- Source path: `seeds/InfoTechCanonNetworkModel_RC1_seed.md` +- Summary: Domain model used by canon profiles and standards: InfoTechCanon Network Model. +- Imports and anchors: `kernel/itc-core`, `model/security` +- Owned concepts: `InfoTechCanon Network Model` + +### InfoTechCanon Observability Model + +- ID: `model/observability` +- Kind: `model` +- Canonical path: `models/observability/InfoTechCanonObservabilityModel.md` +- Source path: `seeds/InfoTechCanonObservabilityModel_RC1_seed.md` +- Summary: Domain model used by canon profiles and standards: InfoTechCanon Observability Model. +- Imports and anchors: `kernel/itc-core`, `model/task` +- Owned concepts: `InfoTechCanon Observability Model` + +### InfoTechCanon Organization Model + +- ID: `model/organization` +- Kind: `model` +- Canonical path: `models/organization/InfoTechCanonOrganizationModel.md` +- Source path: `seeds/InfoTechCanonOrganizationModel_RC1_seed.md` +- Summary: Domain model used by canon profiles and standards: InfoTechCanon Organization Model. +- Imports and anchors: `kernel/itc-core` +- Owned concepts: `InfoTechCanon Organization Model` + +### InfoTechCanon Security Model + +- ID: `model/security` +- Kind: `model` +- Canonical path: `models/security/InfoTechCanonSecurityModel.md` +- Source path: `seeds/InfoTechCanonSecurityModel_RC1_seed.md` +- Summary: Domain model used by canon profiles and standards: InfoTechCanon Security Model. +- Imports and anchors: `kernel/itc-core`, `model/access-control` +- Owned concepts: `InfoTechCanon Security Model` + +### InfoTechCanon Task Model + +- ID: `model/task` +- Kind: `model` +- Canonical path: `models/task/InfoTechCanonTaskModel.md` +- Source path: `seeds/InfoTechCanonTaskModel_RC1_seed.md` +- Summary: Domain model used by canon profiles and standards: InfoTechCanon Task Model. +- Imports and anchors: `kernel/itc-core` +- Owned concepts: `InfoTechCanon Task Model` + +### Small SaaS System Profile + +- ID: `profile/small-saas` +- Kind: `profile` +- Canonical path: `profiles/small-saas/profile.yaml` +- Source path: `infospace/profiles/small-saas/profile.yaml` +- Summary: Profile that constrains canon artifacts for a practical implementation slice: Small SaaS System Profile. +- Imports and anchors: `kernel/itc-core`, `model/access-control`, `model/data`, `model/devsecops`, `model/governance`, `model/landscape`, `model/network`, `model/observability`, `model/organization`, `model/security`, `model/task`, `standard/caring`, `standard/tagging` +- Owned concepts: `Small SaaS System Profile` + +### Namespace Per Tenant Control + +- ID: `small-saas/control/namespace-per-tenant` +- Kind: `profile-artifact` +- Canonical path: `profiles/small-saas/artifacts/control.namespace-per-tenant.yaml` +- Source path: `profiles/small-saas/artifacts/control.namespace-per-tenant.yaml` +- Summary: Example artifact for the small-saas profile: Namespace Per Tenant Control. +- Imports and anchors: `model/security`, `standard/caring` +- Owned concepts: `Namespace Per Tenant Control` + +### Subscription Ledger Dataset + +- ID: `small-saas/dataset/subscription-ledger` +- Kind: `profile-artifact` +- Canonical path: `profiles/small-saas/artifacts/dataset.subscription-ledger.yaml` +- Source path: `profiles/small-saas/artifacts/dataset.subscription-ledger.yaml` +- Summary: Example artifact for the small-saas profile: Subscription Ledger Dataset. +- Imports and anchors: `model/data` +- Owned concepts: `Subscription Ledger Dataset` + +### Production Deployment + +- ID: `small-saas/deployment/production` +- Kind: `profile-artifact` +- Canonical path: `profiles/small-saas/artifacts/deployment.production.yaml` +- Source path: `profiles/small-saas/artifacts/deployment.production.yaml` +- Summary: Example artifact for the small-saas profile: Production Deployment. +- Imports and anchors: `model/devsecops`, `model/network` +- Owned concepts: `Production Deployment` + +### Access Review 2026-05 + +- ID: `small-saas/evidence/access-review-2026-05` +- Kind: `profile-artifact` +- Canonical path: `profiles/small-saas/artifacts/evidence.access-review-2026-05.yaml` +- Source path: `profiles/small-saas/artifacts/evidence.access-review-2026-05.yaml` +- Summary: Example artifact for the small-saas profile: Access Review 2026-05. +- Imports and anchors: `model/observability` +- Owned concepts: `Access Review 2026-05` + +### Cross-Tenant Access Attempt + +- ID: `small-saas/incident/cross-tenant-access-attempt` +- Kind: `profile-artifact` +- Canonical path: `profiles/small-saas/artifacts/incident.cross-tenant-access-attempt.yaml` +- Source path: `profiles/small-saas/artifacts/incident.cross-tenant-access-attempt.yaml` +- Summary: Example artifact for the small-saas profile: Cross-Tenant Access Attempt. +- Imports and anchors: `model/security` +- Owned concepts: `Cross-Tenant Access Attempt` + +### Tenant Isolation Policy + +- ID: `small-saas/policy/tenant-isolation` +- Kind: `profile-artifact` +- Canonical path: `profiles/small-saas/artifacts/policy.tenant-isolation.yaml` +- Source path: `profiles/small-saas/artifacts/policy.tenant-isolation.yaml` +- Summary: Example artifact for the small-saas profile: Tenant Isolation Policy. +- Imports and anchors: `model/governance`, `small-saas/control/namespace-per-tenant` +- Owned concepts: `Tenant Isolation Policy` + +### Billing Portal Service + +- ID: `small-saas/service/billing-portal` +- Kind: `profile-artifact` +- Canonical path: `profiles/small-saas/artifacts/service.billing-portal.yaml` +- Source path: `profiles/small-saas/artifacts/service.billing-portal.yaml` +- Summary: Example artifact for the small-saas profile: Billing Portal Service. +- Imports and anchors: `model/landscape` +- Owned concepts: `Billing Portal Service` + +### Small SaaS Billing System + +- ID: `small-saas/system/billing-system` +- Kind: `profile-artifact` +- Canonical path: `profiles/small-saas/artifacts/system.billing-system.yaml` +- Source path: `profiles/small-saas/artifacts/system.billing-system.yaml` +- Summary: Example artifact for the small-saas profile: Small SaaS Billing System. +- Imports and anchors: `model/landscape` +- Owned concepts: `Small SaaS Billing System` + +### Onboard Tenant + +- ID: `small-saas/task/onboard-tenant` +- Kind: `profile-artifact` +- Canonical path: `profiles/small-saas/artifacts/task.onboard-tenant.yaml` +- Source path: `profiles/small-saas/artifacts/task.onboard-tenant.yaml` +- Summary: Example artifact for the small-saas profile: Onboard Tenant. +- Imports and anchors: `model/task` +- Owned concepts: `Onboard Tenant` + +### Platform Team + +- ID: `small-saas/team/platform` +- Kind: `profile-artifact` +- Canonical path: `profiles/small-saas/artifacts/team.platform.yaml` +- Source path: `profiles/small-saas/artifacts/team.platform.yaml` +- Summary: Example artifact for the small-saas profile: Platform Team. +- Imports and anchors: `model/organization` +- Owned concepts: `Platform Team` + +### Acme Tenant + +- ID: `small-saas/tenant/acme` +- Kind: `profile-artifact` +- Canonical path: `profiles/small-saas/artifacts/tenant.acme.yaml` +- Source path: `profiles/small-saas/artifacts/tenant.acme.yaml` +- Summary: Example artifact for the small-saas profile: Acme Tenant. +- Imports and anchors: `model/organization` +- Owned concepts: `Acme Tenant` + +### Globex Tenant + +- ID: `small-saas/tenant/globex` +- Kind: `profile-artifact` +- Canonical path: `profiles/small-saas/artifacts/tenant.globex.yaml` +- Source path: `profiles/small-saas/artifacts/tenant.globex.yaml` +- Summary: Example artifact for the small-saas profile: Globex Tenant. +- Imports and anchors: `model/organization` +- Owned concepts: `Globex Tenant` + +### Ada Admin + +- ID: `small-saas/user/ada-admin` +- Kind: `profile-artifact` +- Canonical path: `profiles/small-saas/artifacts/user.ada-admin.yaml` +- Source path: `profiles/small-saas/artifacts/user.ada-admin.yaml` +- Summary: Example artifact for the small-saas profile: Ada Admin. +- Imports and anchors: `model/access-control`, `model/organization` +- Owned concepts: `Ada Admin` + +### InfoTechCanon CARING Access Governance Standard + +- ID: `standard/caring` +- Kind: `standard` +- Canonical path: `standards/caring/InfoTechCanonCaringAccessGovernanceStandard.md` +- Source path: `seeds/InfoTechCanonCaringAccessGovernanceStandard.md` +- Summary: Cross-cutting canon standard: InfoTechCanon CARING Access Governance Standard. +- Imports and anchors: `kernel/itc-core`, `model/access-control`, `model/data`, `model/devsecops`, `model/governance`, `model/network`, `model/observability`, `model/organization`, `model/security`, `model/task`, `standard/tagging` +- Owned concepts: `CARINGAccessDescriptor`, `CARINGAnalysisFitnessTest`, `CARINGAnalysisProcedure`, `CARINGCanonicalRole`, `CARINGCapabilityProfile`, `CARINGDeclaredAccessMap`, `CARINGDerivedCapability`, `CARINGEffectiveAccessMap`, `CARINGExposureEvent`, `CARINGExposureMode`, `CARINGInducedAccess`, `CARINGOrganizationRelation`, `CARINGPlane`, `CARINGRedesignProcedure`, `CARINGRestrictionPrecedence`, `InfoTechCanon CARING Access Governance Standard` + +### InfoTechCanon Tagging Standard + +- ID: `standard/tagging` +- Kind: `standard` +- Canonical path: `standards/tagging/InfoTechCanonTaggingStandard.md` +- Source path: `seeds/InfoTechCanonTaggingStandard_RC1_seed.md` +- Summary: Cross-cutting canon standard: InfoTechCanon Tagging Standard. +- Imports and anchors: `kernel/itc-core`, `model/task` +- Owned concepts: `InfoTechCanon Tagging Standard` diff --git a/infospace/agent/retrieval-index.yaml b/infospace/agent/retrieval-index.yaml new file mode 100644 index 0000000..75e57f3 --- /dev/null +++ b/infospace/agent/retrieval-index.yaml @@ -0,0 +1,673 @@ +schema: info-tech-canon.retrieval-index.v1 +infospace: canon +item_count: 29 +items: +- id: kernel/itc-core + kind: kernel + title: InfoTechCanon Core + canonical_path: kernel/InfoTechCanonCore.md + source_path: seeds/InfoTechCanonCore_RC1_seed.md + summary: 'Kernel artifact that defines canon structure or integration: InfoTechCanon + Core.' + owned_concepts: + - InfoTechCanon Core + imports: [] + relationships: [] + warnings: [] +- id: kernel/itc-kernel-map + kind: kernel + title: InfoTechCanon Kernel Map + canonical_path: kernel/InfoTechCanonKernelMap.md + source_path: seeds/InfoTechCanonKernelMap_RC1.md + summary: 'Kernel artifact that defines canon structure or integration: InfoTechCanon + Kernel Map.' + owned_concepts: + - InfoTechCanon Kernel Map + imports: [] + relationships: + - type: maps + target: kernel/itc-core + - type: maps + target: model/information-space + - type: maps + target: model/landscape + - type: maps + target: model/organization + - type: maps + target: model/governance + - type: maps + target: model/task + - type: maps + target: model/access-control + - type: maps + target: model/security + - type: maps + target: model/data + - type: maps + target: model/devsecops + - type: maps + target: model/network + - type: maps + target: model/observability + - type: maps + target: standard/tagging + - type: maps + target: standard/caring + warnings: [] +- id: model/access-control + kind: model + title: InfoTechCanon Access Control Model + canonical_path: models/access-control/InfoTechCanonAccessControlModel.md + source_path: seeds/InfoTechCanonAccessControlModel_RC1_seed.md + summary: 'Domain model used by canon profiles and standards: InfoTechCanon Access + Control Model.' + owned_concepts: + - InfoTechCanon Access Control Model + imports: + - kernel/itc-core + - model/governance + - model/organization + relationships: + - type: conforms_to + target: kernel/itc-core + - type: uses + target: model/organization + - type: uses + target: model/governance + warnings: [] +- id: model/data + kind: model + title: InfoTechCanon Data Model + canonical_path: models/data/InfoTechCanonDataModel.md + source_path: seeds/InfoTechCanonDataModel_RC1_seed.md + summary: 'Domain model used by canon profiles and standards: InfoTechCanon Data + Model.' + owned_concepts: + - InfoTechCanon Data Model + imports: + - kernel/itc-core + - model/governance + relationships: + - type: conforms_to + target: kernel/itc-core + - type: uses + target: model/governance + warnings: [] +- id: model/devsecops + kind: model + title: InfoTechCanon DevSecOps Model + canonical_path: models/devsecops/InfoTechCanonDevSecOpsModel.md + source_path: seeds/InfoTechCanonDevSecOpsModel_RC1_seed.md + summary: 'Domain model used by canon profiles and standards: InfoTechCanon DevSecOps + Model.' + owned_concepts: + - InfoTechCanon DevSecOps Model + imports: + - kernel/itc-core + - model/security + relationships: + - type: conforms_to + target: kernel/itc-core + - type: uses + target: model/security + warnings: [] +- id: model/governance + kind: model + title: InfoTechCanon Governance Model + canonical_path: models/governance/InfoTechCanonGovernanceModel.md + source_path: seeds/InfoTechCanonGovernanceModel_RC1_seed.md + summary: 'Domain model used by canon profiles and standards: InfoTechCanon Governance + Model.' + owned_concepts: + - InfoTechCanon Governance Model + imports: + - kernel/itc-core + relationships: + - type: conforms_to + target: kernel/itc-core + warnings: [] +- id: model/information-space + kind: model + title: InfoTechCanon Information Space Model + canonical_path: models/information-space/InfoTechCanonInformationSpaceModel.md + source_path: seeds/InfoTechCanonInformationSpaceModel_RC1_seed.md + summary: 'Domain model used by canon profiles and standards: InfoTechCanon Information + Space Model.' + owned_concepts: + - InfoTechCanon Information Space Model + imports: + - kernel/itc-core + relationships: + - type: conforms_to + target: kernel/itc-core + warnings: [] +- id: model/landscape + kind: model + title: InfoTechCanon Landscape Model + canonical_path: models/landscape/InfoTechCanonLandscapeModel.md + source_path: seeds/InfoTechCanonLandscapeModel_RC1_seed.md + summary: 'Domain model used by canon profiles and standards: InfoTechCanon Landscape + Model.' + owned_concepts: + - InfoTechCanon Landscape Model + imports: + - kernel/itc-core + relationships: + - type: conforms_to + target: kernel/itc-core + warnings: [] +- id: model/network + kind: model + title: InfoTechCanon Network Model + canonical_path: models/network/InfoTechCanonNetworkModel.md + source_path: seeds/InfoTechCanonNetworkModel_RC1_seed.md + summary: 'Domain model used by canon profiles and standards: InfoTechCanon Network + Model.' + owned_concepts: + - InfoTechCanon Network Model + imports: + - kernel/itc-core + - model/security + relationships: + - type: conforms_to + target: kernel/itc-core + - type: uses + target: model/security + warnings: [] +- id: model/observability + kind: model + title: InfoTechCanon Observability Model + canonical_path: models/observability/InfoTechCanonObservabilityModel.md + source_path: seeds/InfoTechCanonObservabilityModel_RC1_seed.md + summary: 'Domain model used by canon profiles and standards: InfoTechCanon Observability + Model.' + owned_concepts: + - InfoTechCanon Observability Model + imports: + - kernel/itc-core + - model/task + relationships: + - type: conforms_to + target: kernel/itc-core + - type: uses + target: model/task + warnings: [] +- id: model/organization + kind: model + title: InfoTechCanon Organization Model + canonical_path: models/organization/InfoTechCanonOrganizationModel.md + source_path: seeds/InfoTechCanonOrganizationModel_RC1_seed.md + summary: 'Domain model used by canon profiles and standards: InfoTechCanon Organization + Model.' + owned_concepts: + - InfoTechCanon Organization Model + imports: + - kernel/itc-core + relationships: + - type: conforms_to + target: kernel/itc-core + warnings: [] +- id: model/security + kind: model + title: InfoTechCanon Security Model + canonical_path: models/security/InfoTechCanonSecurityModel.md + source_path: seeds/InfoTechCanonSecurityModel_RC1_seed.md + summary: 'Domain model used by canon profiles and standards: InfoTechCanon Security + Model.' + owned_concepts: + - InfoTechCanon Security Model + imports: + - kernel/itc-core + - model/access-control + relationships: + - type: conforms_to + target: kernel/itc-core + - type: uses + target: model/access-control + warnings: [] +- id: model/task + kind: model + title: InfoTechCanon Task Model + canonical_path: models/task/InfoTechCanonTaskModel.md + source_path: seeds/InfoTechCanonTaskModel_RC1_seed.md + summary: 'Domain model used by canon profiles and standards: InfoTechCanon Task + Model.' + owned_concepts: + - InfoTechCanon Task Model + imports: + - kernel/itc-core + relationships: + - type: conforms_to + target: kernel/itc-core + warnings: [] +- id: profile/small-saas + kind: profile + title: Small SaaS System Profile + canonical_path: profiles/small-saas/profile.yaml + source_path: infospace/profiles/small-saas/profile.yaml + summary: 'Profile that constrains canon artifacts for a practical implementation + slice: Small SaaS System Profile.' + owned_concepts: + - Small SaaS System Profile + imports: + - kernel/itc-core + - model/access-control + - model/data + - model/devsecops + - model/governance + - model/landscape + - model/network + - model/observability + - model/organization + - model/security + - model/task + - standard/caring + - standard/tagging + relationships: + - type: conforms_to + target: kernel/itc-core + - type: requires + target: model/landscape + - type: requires + target: model/organization + - type: requires + target: model/governance + - type: requires + target: model/access-control + - type: requires + target: model/security + - type: requires + target: model/data + - type: requires + target: model/devsecops + - type: requires + target: model/network + - type: requires + target: model/observability + - type: requires + target: model/task + - type: requires + target: standard/tagging + - type: requires + target: standard/caring + warnings: [] +- id: small-saas/control/namespace-per-tenant + kind: profile-artifact + title: Namespace Per Tenant Control + canonical_path: profiles/small-saas/artifacts/control.namespace-per-tenant.yaml + source_path: profiles/small-saas/artifacts/control.namespace-per-tenant.yaml + summary: 'Example artifact for the small-saas profile: Namespace Per Tenant Control.' + owned_concepts: + - Namespace Per Tenant Control + imports: + - model/security + - standard/caring + relationships: + - type: instantiates + target: profile/small-saas + - type: uses + target: model/security + - type: uses + target: standard/caring + - type: evidenced_by + target: small-saas/evidence/access-review-2026-05 + warnings: [] +- id: small-saas/dataset/subscription-ledger + kind: profile-artifact + title: Subscription Ledger Dataset + canonical_path: profiles/small-saas/artifacts/dataset.subscription-ledger.yaml + source_path: profiles/small-saas/artifacts/dataset.subscription-ledger.yaml + summary: 'Example artifact for the small-saas profile: Subscription Ledger Dataset.' + owned_concepts: + - Subscription Ledger Dataset + imports: + - model/data + relationships: + - type: instantiates + target: profile/small-saas + - type: uses + target: model/data + - type: owned_by + target: small-saas/service/billing-portal + - type: partitioned_for + target: small-saas/tenant/acme + - type: partitioned_for + target: small-saas/tenant/globex + - type: governed_by + target: small-saas/policy/tenant-isolation + warnings: [] +- id: small-saas/deployment/production + kind: profile-artifact + title: Production Deployment + canonical_path: profiles/small-saas/artifacts/deployment.production.yaml + source_path: profiles/small-saas/artifacts/deployment.production.yaml + summary: 'Example artifact for the small-saas profile: Production Deployment.' + owned_concepts: + - Production Deployment + imports: + - model/devsecops + - model/network + relationships: + - type: instantiates + target: profile/small-saas + - type: uses + target: model/devsecops + - type: uses + target: model/network + - type: deploys + target: small-saas/service/billing-portal + - type: separates + target: small-saas/tenant/acme + - type: separates + target: small-saas/tenant/globex + - type: implements + target: small-saas/control/namespace-per-tenant + warnings: [] +- id: small-saas/evidence/access-review-2026-05 + kind: profile-artifact + title: Access Review 2026-05 + canonical_path: profiles/small-saas/artifacts/evidence.access-review-2026-05.yaml + source_path: profiles/small-saas/artifacts/evidence.access-review-2026-05.yaml + summary: 'Example artifact for the small-saas profile: Access Review 2026-05.' + owned_concepts: + - Access Review 2026-05 + imports: + - model/observability + relationships: + - type: instantiates + target: profile/small-saas + - type: uses + target: model/observability + warnings: [] +- id: small-saas/incident/cross-tenant-access-attempt + kind: profile-artifact + title: Cross-Tenant Access Attempt + canonical_path: profiles/small-saas/artifacts/incident.cross-tenant-access-attempt.yaml + source_path: profiles/small-saas/artifacts/incident.cross-tenant-access-attempt.yaml + summary: 'Example artifact for the small-saas profile: Cross-Tenant Access Attempt.' + owned_concepts: + - Cross-Tenant Access Attempt + imports: + - model/security + relationships: + - type: instantiates + target: profile/small-saas + - type: uses + target: model/security + - type: constrained_by + target: small-saas/control/namespace-per-tenant + - type: evidenced_by + target: small-saas/evidence/access-review-2026-05 + warnings: [] +- id: small-saas/policy/tenant-isolation + kind: profile-artifact + title: Tenant Isolation Policy + canonical_path: profiles/small-saas/artifacts/policy.tenant-isolation.yaml + source_path: profiles/small-saas/artifacts/policy.tenant-isolation.yaml + summary: 'Example artifact for the small-saas profile: Tenant Isolation Policy.' + owned_concepts: + - Tenant Isolation Policy + imports: + - model/governance + - small-saas/control/namespace-per-tenant + relationships: + - type: instantiates + target: profile/small-saas + - type: uses + target: model/governance + - type: requires + target: small-saas/control/namespace-per-tenant + - type: evidenced_by + target: small-saas/evidence/access-review-2026-05 + warnings: [] +- id: small-saas/service/billing-portal + kind: profile-artifact + title: Billing Portal Service + canonical_path: profiles/small-saas/artifacts/service.billing-portal.yaml + source_path: profiles/small-saas/artifacts/service.billing-portal.yaml + summary: 'Example artifact for the small-saas profile: Billing Portal Service.' + owned_concepts: + - Billing Portal Service + imports: + - model/landscape + relationships: + - type: instantiates + target: profile/small-saas + - type: uses + target: model/landscape + - type: part_of + target: small-saas/system/billing-system + - type: owned_by + target: small-saas/team/platform + warnings: [] +- id: small-saas/system/billing-system + kind: profile-artifact + title: Small SaaS Billing System + canonical_path: profiles/small-saas/artifacts/system.billing-system.yaml + source_path: profiles/small-saas/artifacts/system.billing-system.yaml + summary: 'Example artifact for the small-saas profile: Small SaaS Billing System.' + owned_concepts: + - Small SaaS Billing System + imports: + - model/landscape + relationships: + - type: instantiates + target: profile/small-saas + - type: uses + target: model/landscape + - type: serves + target: small-saas/tenant/acme + - type: serves + target: small-saas/tenant/globex + warnings: [] +- id: small-saas/task/onboard-tenant + kind: profile-artifact + title: Onboard Tenant + canonical_path: profiles/small-saas/artifacts/task.onboard-tenant.yaml + source_path: profiles/small-saas/artifacts/task.onboard-tenant.yaml + summary: 'Example artifact for the small-saas profile: Onboard Tenant.' + owned_concepts: + - Onboard Tenant + imports: + - model/task + relationships: + - type: instantiates + target: profile/small-saas + - type: uses + target: model/task + - type: owned_by + target: small-saas/team/platform + - type: changes + target: small-saas/tenant/acme + - type: governed_by + target: small-saas/policy/tenant-isolation + warnings: [] +- id: small-saas/team/platform + kind: profile-artifact + title: Platform Team + canonical_path: profiles/small-saas/artifacts/team.platform.yaml + source_path: profiles/small-saas/artifacts/team.platform.yaml + summary: 'Example artifact for the small-saas profile: Platform Team.' + owned_concepts: + - Platform Team + imports: + - model/organization + relationships: + - type: instantiates + target: profile/small-saas + - type: uses + target: model/organization + warnings: [] +- id: small-saas/tenant/acme + kind: profile-artifact + title: Acme Tenant + canonical_path: profiles/small-saas/artifacts/tenant.acme.yaml + source_path: profiles/small-saas/artifacts/tenant.acme.yaml + summary: 'Example artifact for the small-saas profile: Acme Tenant.' + owned_concepts: + - Acme Tenant + imports: + - model/organization + relationships: + - type: instantiates + target: profile/small-saas + - type: uses + target: model/organization + - type: represented_by + target: small-saas/user/ada-admin + - type: isolated_by + target: small-saas/control/namespace-per-tenant + warnings: [] +- id: small-saas/tenant/globex + kind: profile-artifact + title: Globex Tenant + canonical_path: profiles/small-saas/artifacts/tenant.globex.yaml + source_path: profiles/small-saas/artifacts/tenant.globex.yaml + summary: 'Example artifact for the small-saas profile: Globex Tenant.' + owned_concepts: + - Globex Tenant + imports: + - model/organization + relationships: + - type: instantiates + target: profile/small-saas + - type: uses + target: model/organization + - type: isolated_by + target: small-saas/control/namespace-per-tenant + warnings: [] +- id: small-saas/user/ada-admin + kind: profile-artifact + title: Ada Admin + canonical_path: profiles/small-saas/artifacts/user.ada-admin.yaml + source_path: profiles/small-saas/artifacts/user.ada-admin.yaml + summary: 'Example artifact for the small-saas profile: Ada Admin.' + owned_concepts: + - Ada Admin + imports: + - model/access-control + - model/organization + relationships: + - type: instantiates + target: profile/small-saas + - type: uses + target: model/organization + - type: uses + target: model/access-control + - type: member_of + target: small-saas/team/platform + - type: has_access_under + target: small-saas/policy/tenant-isolation + - type: access_evidenced_by + target: small-saas/evidence/access-review-2026-05 + warnings: [] +- id: standard/caring + kind: standard + title: InfoTechCanon CARING Access Governance Standard + canonical_path: standards/caring/InfoTechCanonCaringAccessGovernanceStandard.md + source_path: seeds/InfoTechCanonCaringAccessGovernanceStandard.md + summary: 'Cross-cutting canon standard: InfoTechCanon CARING Access Governance Standard.' + owned_concepts: + - CARINGAccessDescriptor + - CARINGAnalysisFitnessTest + - CARINGAnalysisProcedure + - CARINGCanonicalRole + - CARINGCapabilityProfile + - CARINGDeclaredAccessMap + - CARINGDerivedCapability + - CARINGEffectiveAccessMap + - CARINGExposureEvent + - CARINGExposureMode + - CARINGInducedAccess + - CARINGOrganizationRelation + - CARINGPlane + - CARINGRedesignProcedure + - CARINGRestrictionPrecedence + - InfoTechCanon CARING Access Governance Standard + imports: + - kernel/itc-core + - model/access-control + - model/data + - model/devsecops + - model/governance + - model/network + - model/observability + - model/organization + - model/security + - model/task + - standard/tagging + relationships: + - type: conforms_to + target: kernel/itc-core + - type: imports + target: model/organization + - type: imports + target: model/governance + - type: imports + target: model/access-control + - type: imports + target: model/security + - type: imports + target: model/data + - type: imports + target: model/devsecops + - type: imports + target: model/network + - type: imports + target: model/observability + - type: imports + target: model/task + - type: imports + target: standard/tagging + warnings: [] +- id: standard/tagging + kind: standard + title: InfoTechCanon Tagging Standard + canonical_path: standards/tagging/InfoTechCanonTaggingStandard.md + source_path: seeds/InfoTechCanonTaggingStandard_RC1_seed.md + summary: 'Cross-cutting canon standard: InfoTechCanon Tagging Standard.' + owned_concepts: + - InfoTechCanon Tagging Standard + imports: + - kernel/itc-core + - model/task + relationships: + - type: conforms_to + target: kernel/itc-core + - type: imports + target: model/task + warnings: [] +common_distinctions: +- id: actor-subject-principal + title: Actor vs Subject vs Principal + summary: Use actor for the acting entity in a context, subject for the entity a + policy evaluates, and principal for the authenticated identity bound to access + decisions. + source_artifacts: + - model/organization + - model/access-control + - standard/caring +- id: organization-role-access-role-caring-role + title: Organization Role vs AccessRole vs CARING role + summary: Organization roles describe responsibility or position; access roles describe + permissions; CARING roles classify access-governance needs and analysis. + source_artifacts: + - model/organization + - model/access-control + - standard/caring +- id: policy-control-evidence + title: Policy vs Control vs Evidence + summary: Policy states intent or rule, control implements or enforces that rule, + and evidence records why the claim should be trusted. + source_artifacts: + - model/governance + - model/security + - model/observability +- id: intent-scope-purpose + title: Intent vs Scope vs Purpose + summary: Intent captures why an actor wants something, scope bounds what is included, + and purpose captures consumer demand or use case pressure on the repo. + source_artifacts: + - kernel/itc-core + - model/governance + - profile/small-saas diff --git a/infospace/agent/templates/canon-interface-card.template.yaml b/infospace/agent/templates/canon-interface-card.template.yaml new file mode 100644 index 0000000..e227e10 --- /dev/null +++ b/infospace/agent/templates/canon-interface-card.template.yaml @@ -0,0 +1,25 @@ +schema: info-tech-canon.interface-card.v1 +id: consumer-repo/interface-card +title: Consumer Repo Canon Interface Card +consumer: + repo: '' + domain: '' + owner: '' + intent: '' + scope: '' + purposes: [] +canon_surfaces: + implemented_profiles: [] + consumed_artifacts: [] + owned_concepts: [] + produced_concepts: [] + consumed_concepts: [] + mappings: [] +validation_expectations: + commands: [] + evidence_required: [] + known_gaps: [] +consumer_needs: + current: [] + requested_extensions: [] + feedback: [] diff --git a/infospace/agent/templates/consumer-brief.template.md b/infospace/agent/templates/consumer-brief.template.md new file mode 100644 index 0000000..d9df033 --- /dev/null +++ b/infospace/agent/templates/consumer-brief.template.md @@ -0,0 +1,28 @@ +--- +id: consumer-brief/template +consumer: TBD +generated: true +--- + + + +# Consumer Brief Template + +## Consumer Intent + +- Intent: +- Scope: +- Purposes: + +## Canon Surfaces + +- Implemented profiles: +- Consumed standards: +- Produced concepts: +- Consumed concepts: + +## Validation Expectations + +- Commands: +- Evidence: +- Known gaps: diff --git a/infospace/indexes/artifact-tree.yaml b/infospace/indexes/artifact-tree.yaml index 3b0c534..96c54e8 100644 --- a/infospace/indexes/artifact-tree.yaml +++ b/infospace/indexes/artifact-tree.yaml @@ -1,5 +1,5 @@ root: infospace -file_count: 67 +file_count: 91 files: - path: README.md directory: . @@ -7,9 +7,81 @@ files: - path: agent/README.md directory: agent name: README.md +- path: agent/briefs/kernel-itc-core.md + directory: agent/briefs + name: kernel-itc-core.md +- path: agent/briefs/kernel-itc-kernel-map.md + directory: agent/briefs + name: kernel-itc-kernel-map.md +- path: agent/briefs/model-access-control.md + directory: agent/briefs + name: model-access-control.md +- path: agent/briefs/model-data.md + directory: agent/briefs + name: model-data.md +- path: agent/briefs/model-devsecops.md + directory: agent/briefs + name: model-devsecops.md +- path: agent/briefs/model-governance.md + directory: agent/briefs + name: model-governance.md +- path: agent/briefs/model-information-space.md + directory: agent/briefs + name: model-information-space.md +- path: agent/briefs/model-landscape.md + directory: agent/briefs + name: model-landscape.md +- path: agent/briefs/model-network.md + directory: agent/briefs + name: model-network.md +- path: agent/briefs/model-observability.md + directory: agent/briefs + name: model-observability.md +- path: agent/briefs/model-organization.md + directory: agent/briefs + name: model-organization.md +- path: agent/briefs/model-security.md + directory: agent/briefs + name: model-security.md +- path: agent/briefs/model-task.md + directory: agent/briefs + name: model-task.md +- path: agent/briefs/profile-small-saas.md + directory: agent/briefs + name: profile-small-saas.md +- path: agent/briefs/standard-caring.md + directory: agent/briefs + name: standard-caring.md +- path: agent/briefs/standard-tagging.md + directory: agent/briefs + name: standard-tagging.md +- path: agent/consumer-briefs/railiance-fabric.md + directory: agent/consumer-briefs + name: railiance-fabric.md +- path: agent/consumer-briefs/repo-scoping.md + directory: agent/consumer-briefs + name: repo-scoping.md +- path: agent/consumer-briefs/user-engine.md + directory: agent/consumer-briefs + name: user-engine.md - path: agent/global-agent-brief.md directory: agent name: global-agent-brief.md +- path: agent/retrieval-index.json + directory: agent + name: retrieval-index.json +- path: agent/retrieval-index.md + directory: agent + name: retrieval-index.md +- path: agent/retrieval-index.yaml + directory: agent + name: retrieval-index.yaml +- path: agent/templates/canon-interface-card.template.yaml + directory: agent/templates + name: canon-interface-card.template.yaml +- path: agent/templates/consumer-brief.template.md + directory: agent/templates + name: consumer-brief.template.md - path: artifacts/index.yaml directory: artifacts name: index.yaml diff --git a/infospace/views/repository-tree.md b/infospace/views/repository-tree.md index d22eb0a..bfcad9b 100644 --- a/infospace/views/repository-tree.md +++ b/infospace/views/repository-tree.md @@ -2,11 +2,35 @@ # Repository Tree -File count: **67** +File count: **91** - `README.md` - `agent/README.md` +- `agent/briefs/kernel-itc-core.md` +- `agent/briefs/kernel-itc-kernel-map.md` +- `agent/briefs/model-access-control.md` +- `agent/briefs/model-data.md` +- `agent/briefs/model-devsecops.md` +- `agent/briefs/model-governance.md` +- `agent/briefs/model-information-space.md` +- `agent/briefs/model-landscape.md` +- `agent/briefs/model-network.md` +- `agent/briefs/model-observability.md` +- `agent/briefs/model-organization.md` +- `agent/briefs/model-security.md` +- `agent/briefs/model-task.md` +- `agent/briefs/profile-small-saas.md` +- `agent/briefs/standard-caring.md` +- `agent/briefs/standard-tagging.md` +- `agent/consumer-briefs/railiance-fabric.md` +- `agent/consumer-briefs/repo-scoping.md` +- `agent/consumer-briefs/user-engine.md` - `agent/global-agent-brief.md` +- `agent/retrieval-index.json` +- `agent/retrieval-index.md` +- `agent/retrieval-index.yaml` +- `agent/templates/canon-interface-card.template.yaml` +- `agent/templates/consumer-brief.template.md` - `artifacts/index.yaml` - `assimilation/README.md` - `examples/README.md` diff --git a/src/info_tech_canon/generation.py b/src/info_tech_canon/generation.py index 22c1335..4047bfb 100644 --- a/src/info_tech_canon/generation.py +++ b/src/info_tech_canon/generation.py @@ -1,6 +1,7 @@ from __future__ import annotations from collections import defaultdict +import json from pathlib import Path from typing import Any @@ -8,6 +9,50 @@ import yaml GENERATED_NOTICE = "" +RETRIEVAL_ARTIFACT_KINDS = {"kernel", "model", "standard", "profile"} +CONSUMER_BRIEF_IDS = ("user-engine", "railiance-fabric", "repo-scoping") +COMMON_DISTINCTIONS = [ + { + "id": "actor-subject-principal", + "title": "Actor vs Subject vs Principal", + "summary": "Use actor for the acting entity in a context, subject for the entity a policy evaluates, and principal for the authenticated identity bound to access decisions.", + "source_artifacts": [ + "model/organization", + "model/access-control", + "standard/caring", + ], + }, + { + "id": "organization-role-access-role-caring-role", + "title": "Organization Role vs AccessRole vs CARING role", + "summary": "Organization roles describe responsibility or position; access roles describe permissions; CARING roles classify access-governance needs and analysis.", + "source_artifacts": [ + "model/organization", + "model/access-control", + "standard/caring", + ], + }, + { + "id": "policy-control-evidence", + "title": "Policy vs Control vs Evidence", + "summary": "Policy states intent or rule, control implements or enforces that rule, and evidence records why the claim should be trusted.", + "source_artifacts": [ + "model/governance", + "model/security", + "model/observability", + ], + }, + { + "id": "intent-scope-purpose", + "title": "Intent vs Scope vs Purpose", + "summary": "Intent captures why an actor wants something, scope bounds what is included, and purpose captures consumer demand or use case pressure on the repo.", + "source_artifacts": [ + "kernel/itc-core", + "model/governance", + "profile/small-saas", + ], + }, +] def generate_indexes(context: Any) -> dict[str, Any]: @@ -86,12 +131,48 @@ def generate_tree(context: Any) -> dict[str, Any]: def generate_agent_briefs(context: Any) -> dict[str, Any]: + retrieval = retrieval_index(context) files = [ _write_text( context.infospace_root / "agent" / "global-agent-brief.md", - _render_global_agent_brief(context), - ) + _render_global_agent_brief(context, retrieval), + ), + _write_text( + context.infospace_root / "agent" / "retrieval-index.md", + _render_retrieval_index_markdown(retrieval), + ), + _write_yaml( + context.infospace_root / "agent" / "retrieval-index.yaml", + retrieval, + ), + _write_json( + context.infospace_root / "agent" / "retrieval-index.json", + retrieval, + ), + _write_yaml( + context.infospace_root / "agent" / "templates" / "canon-interface-card.template.yaml", + interface_card_template(), + ), + _write_text( + context.infospace_root / "agent" / "templates" / "consumer-brief.template.md", + _render_consumer_brief_template(), + ), ] + for artifact in sorted(context.infospace.artifacts, key=lambda item: item.id): + if artifact.kind in RETRIEVAL_ARTIFACT_KINDS: + files.append( + _write_text( + context.infospace_root / "agent" / "briefs" / f"{_safe_id(artifact.id)}.md", + _render_artifact_agent_brief(context, artifact, retrieval), + ) + ) + for consumer_id in CONSUMER_BRIEF_IDS: + files.append( + _write_text( + context.infospace_root / "agent" / "consumer-briefs" / f"{consumer_id}.md", + _render_consumer_brief(consumer_id), + ) + ) return _result("agent-briefs", files) @@ -211,6 +292,61 @@ def artifact_tree(context: Any) -> dict[str, Any]: return {"root": "infospace", "file_count": len(files), "files": files} +def retrieval_index(context: Any) -> dict[str, Any]: + ownership = concept_ownership(context) + concepts_by_owner: dict[str, list[str]] = defaultdict(list) + for concept in ownership["concepts"]: + concepts_by_owner[str(concept["owner"])].append(str(concept["concept"])) + + items = [] + for artifact in sorted(context.infospace.artifacts, key=lambda item: item.id): + relationships = [ + { + "type": str(relationship.get("type") or "related"), + "target": str(relationship.get("target") or ""), + } + for relationship in artifact.relationships + ] + imports = [ + item["target"] + for item in relationships + if item["type"] in {"imports", "requires", "uses", "conforms_to"} + ] + warnings = [] + source_path = str(artifact.provenance.get("source_path") or artifact.path) + if not (context.repo_root / source_path).is_file() and not ( + context.infospace_root / source_path + ).is_file(): + warnings.append( + { + "code": "source_path_not_file", + "source_path": source_path, + } + ) + items.append( + { + "id": artifact.id, + "kind": artifact.kind, + "title": artifact.title, + "canonical_path": artifact.path, + "source_path": source_path, + "summary": _summary_for_artifact(artifact), + "owned_concepts": sorted(set(concepts_by_owner.get(artifact.id, []))), + "imports": sorted(set(imports)), + "relationships": relationships, + "warnings": warnings, + } + ) + + return { + "schema": "info-tech-canon.retrieval-index.v1", + "infospace": context.infospace.config.slug, + "item_count": len(items), + "items": items, + "common_distinctions": COMMON_DISTINCTIONS, + } + + def _render_by_standard(context: Any) -> str: lines = _heading("By Standard") standards = [ @@ -348,7 +484,7 @@ def _render_repository_tree(tree: dict[str, Any]) -> str: return "\n".join(lines).rstrip() + "\n" -def _render_global_agent_brief(context: Any) -> str: +def _render_global_agent_brief(context: Any, retrieval: dict[str, Any]) -> str: lines = _heading("Global Agent Brief") lines.extend( [ @@ -356,8 +492,10 @@ def _render_global_agent_brief(context: Any) -> str: "", f"- Infospace slug: `{context.infospace.config.slug}`", f"- Artifact count: {len(context.infospace.artifacts)}", + f"- Retrieval index items: {retrieval['item_count']}", "- Primary confidence command: `make validate`", "- Refresh generated indexes and views with: `make index`", + "- Refresh agent briefs and interface templates with: `make agent-briefs`", "", "## Useful Commands", "", @@ -365,6 +503,24 @@ def _render_global_agent_brief(context: Any) -> str: "- `PYTHONPATH=src python3 -m info_tech_canon validate`", "- `PYTHONPATH=src python3 -m info_tech_canon graph`", "- `PYTHONPATH=src python3 -m info_tech_canon index`", + "- `PYTHONPATH=src python3 -m info_tech_canon profile validate small-saas`", + "", + "## Retrieval Entry Points", + "", + "- `agent/retrieval-index.md`", + "- `agent/retrieval-index.yaml`", + "- `agent/retrieval-index.json`", + "- `agent/briefs/` for per-artifact briefs", + "- `agent/templates/canon-interface-card.template.yaml`", + "", + "## Common Distinctions", + "", + ] + ) + for distinction in retrieval["common_distinctions"]: + lines.append(f"- **{distinction['title']}**: {distinction['summary']}") + lines.extend( + [ "", "## Consumption Notes", "", @@ -376,6 +532,205 @@ def _render_global_agent_brief(context: Any) -> str: return "\n".join(lines).rstrip() + "\n" +def _render_retrieval_index_markdown(retrieval: dict[str, Any]) -> str: + lines = _heading("Retrieval Index") + lines.extend( + [ + f"Schema: `{retrieval['schema']}`", + f"Infospace: `{retrieval['infospace']}`", + f"Items: **{retrieval['item_count']}**", + "", + "## Common Distinctions", + "", + ] + ) + for distinction in retrieval["common_distinctions"]: + sources = ", ".join(f"`{item}`" for item in distinction["source_artifacts"]) + lines.append(f"- **{distinction['title']}**: {distinction['summary']} Sources: {sources}") + lines.extend(["", "## Items", ""]) + for item in retrieval["items"]: + imports = ", ".join(f"`{target}`" for target in item["imports"]) or "none" + concepts = ", ".join(f"`{concept}`" for concept in item["owned_concepts"]) or "none" + lines.extend( + [ + f"### {item['title']}", + "", + f"- ID: `{item['id']}`", + f"- Kind: `{item['kind']}`", + f"- Canonical path: `{item['canonical_path']}`", + f"- Source path: `{item['source_path']}`", + f"- Summary: {item['summary']}", + f"- Imports and anchors: {imports}", + f"- Owned concepts: {concepts}", + "", + ] + ) + return "\n".join(lines).rstrip() + "\n" + + +def _render_artifact_agent_brief( + context: Any, + artifact: Any, + retrieval: dict[str, Any], +) -> str: + item = next(entry for entry in retrieval["items"] if entry["id"] == artifact.id) + frontmatter = { + "id": f"agent-brief/{_safe_id(artifact.id)}", + "artifact_id": artifact.id, + "source_path": artifact.path, + "source_kind": artifact.kind, + "generated": True, + } + lines = [ + "---", + yaml.safe_dump(frontmatter, sort_keys=False).strip(), + "---", + "", + GENERATED_NOTICE, + "", + f"# Agent Brief: {artifact.title}", + "", + f"- Artifact ID: `{artifact.id}`", + f"- Kind: `{artifact.kind}`", + f"- Canonical path: `{artifact.path}`", + f"- Full source: `{artifact.path}`", + f"- Summary: {item['summary']}", + "", + "## Retrieval Hints", + "", + ] + if item["imports"]: + lines.append("Imports and anchors:") + lines.extend(f"- `{target}`" for target in item["imports"]) + else: + lines.append("No imports or anchors recorded.") + lines.extend(["", "## Owned Concepts", ""]) + if item["owned_concepts"]: + lines.extend(f"- `{concept}`" for concept in item["owned_concepts"]) + else: + lines.append("No owned concepts recorded yet.") + lines.extend(["", "## Related Distinctions", ""]) + related = [ + distinction + for distinction in retrieval["common_distinctions"] + if artifact.id in distinction["source_artifacts"] + ] + if related: + for distinction in related: + lines.append(f"- **{distinction['title']}**: {distinction['summary']}") + else: + lines.append("No common distinction is anchored directly on this artifact.") + return "\n".join(lines).rstrip() + "\n" + + +def interface_card_template() -> dict[str, Any]: + return { + "schema": "info-tech-canon.interface-card.v1", + "id": "consumer-repo/interface-card", + "title": "Consumer Repo Canon Interface Card", + "consumer": { + "repo": "", + "domain": "", + "owner": "", + "intent": "", + "scope": "", + "purposes": [], + }, + "canon_surfaces": { + "implemented_profiles": [], + "consumed_artifacts": [], + "owned_concepts": [], + "produced_concepts": [], + "consumed_concepts": [], + "mappings": [], + }, + "validation_expectations": { + "commands": [], + "evidence_required": [], + "known_gaps": [], + }, + "consumer_needs": { + "current": [], + "requested_extensions": [], + "feedback": [], + }, + } + + +def _render_consumer_brief_template() -> str: + lines = [ + "---", + "id: consumer-brief/template", + "consumer: TBD", + "generated: true", + "---", + "", + GENERATED_NOTICE, + "", + "# Consumer Brief Template", + "", + "## Consumer Intent", + "", + "- Intent:", + "- Scope:", + "- Purposes:", + "", + "## Canon Surfaces", + "", + "- Implemented profiles:", + "- Consumed standards:", + "- Produced concepts:", + "- Consumed concepts:", + "", + "## Validation Expectations", + "", + "- Commands:", + "- Evidence:", + "- Known gaps:", + ] + return "\n".join(lines).rstrip() + "\n" + + +def _render_consumer_brief(consumer_id: str) -> str: + titles = { + "user-engine": "User Engine Canon Consumer Brief", + "railiance-fabric": "Railiance Fabric Canon Consumer Brief", + "repo-scoping": "Repo Scoping Canon Consumer Brief", + } + purposes = { + "user-engine": "Evaluate user-management concepts, roles, access traces, profile claims, and governance evidence against the canon before integration.", + "railiance-fabric": "Use the canon to make captured entities and edges cleaner for conformance and visualization.", + "repo-scoping": "Compare repo-scoping concepts with canon INTENT, SCOPE, PURPOSES, and interface-card expectations.", + } + lines = [ + "---", + f"id: consumer-brief/{consumer_id}", + f"consumer: {consumer_id}", + "generated: true", + "---", + "", + GENERATED_NOTICE, + "", + f"# {titles[consumer_id]}", + "", + "## Purpose", + "", + purposes[consumer_id], + "", + "## Starting Points", + "", + "- `agent/retrieval-index.md`", + "- `agent/templates/canon-interface-card.template.yaml`", + "- `profiles/small-saas/profile.yaml`", + "- `views/by-concept.md`", + "", + "## Workplan Boundary", + "", + "Adoption and repo-specific implementation workplans belong in the consumer repository.", + ] + return "\n".join(lines).rstrip() + "\n" + + def _heading(title: str) -> list[str]: return [GENERATED_NOTICE, "", f"# {title}", ""] @@ -395,6 +750,12 @@ def _write_yaml(path: Path, data: dict[str, Any]) -> dict[str, Any]: return _write_text(path, content) +def _write_json(path: Path, data: dict[str, Any]) -> dict[str, Any]: + path.parent.mkdir(parents=True, exist_ok=True) + content = json.dumps(data, indent=2, sort_keys=True) + "\n" + return _write_text(path, content) + + def _result(kind: str, files: list[dict[str, Any]]) -> dict[str, Any]: return { "ok": True, @@ -420,6 +781,24 @@ def _normalize_concept(value: str) -> str: return "-".join(value.lower().replace("_", "-").split()) +def _safe_id(value: str) -> str: + return value.replace("/", "-").replace("_", "-") + + +def _summary_for_artifact(artifact: Any) -> str: + if artifact.kind == "profile-artifact": + return f"Example artifact for the {artifact.provenance.get('profile', 'unknown')} profile: {artifact.title}." + if artifact.kind == "profile": + return f"Profile that constrains canon artifacts for a practical implementation slice: {artifact.title}." + if artifact.kind == "kernel": + return f"Kernel artifact that defines canon structure or integration: {artifact.title}." + if artifact.kind == "model": + return f"Domain model used by canon profiles and standards: {artifact.title}." + if artifact.kind == "standard": + return f"Cross-cutting canon standard: {artifact.title}." + return f"Canon artifact: {artifact.title}." + + def _is_generated(path: Path) -> bool: try: return path.read_text(encoding="utf-8").startswith(GENERATED_NOTICE) diff --git a/src/info_tech_canon/validation.py b/src/info_tech_canon/validation.py index c0f5d1c..8e946e4 100644 --- a/src/info_tech_canon/validation.py +++ b/src/info_tech_canon/validation.py @@ -62,6 +62,7 @@ def structural_checks(context: Any) -> dict[str, list[dict[str, Any]]]: _check_required_schemas(context.infospace_root, errors) _check_canon_paths(context.repo_root, context.infospace_root, errors) _check_artifact_index(context.repo_root, context.infospace_root, errors) + _check_agent_assets(context.infospace_root, context.infospace.artifacts, errors) _check_optional_assets(context.infospace_root, warnings) return {"errors": errors, "warnings": warnings} @@ -314,6 +315,97 @@ def _check_optional_assets( ) +def _check_agent_assets( + infospace_root: Path, + artifacts: list[Any], + errors: list[dict[str, Any]], +) -> None: + required_files = ( + "agent/global-agent-brief.md", + "agent/retrieval-index.md", + "agent/retrieval-index.yaml", + "agent/retrieval-index.json", + "agent/templates/canon-interface-card.template.yaml", + "agent/templates/consumer-brief.template.md", + "agent/consumer-briefs/user-engine.md", + "agent/consumer-briefs/railiance-fabric.md", + "agent/consumer-briefs/repo-scoping.md", + ) + for relative in required_files: + if not (infospace_root / relative).is_file(): + errors.append( + { + "code": "missing_agent_asset", + "path": str(Path("infospace") / relative), + } + ) + + retrieval_index = _read_yaml(infospace_root / "agent" / "retrieval-index.yaml", errors) + artifact_ids = {artifact.id for artifact in artifacts} + if isinstance(retrieval_index, dict): + items = retrieval_index.get("items") or [] + if not isinstance(items, list): + errors.append( + { + "code": "invalid_retrieval_index", + "path": "infospace/agent/retrieval-index.yaml", + "message": "Expected items list.", + } + ) + else: + indexed_ids = { + str(item.get("id")) + for item in items + if isinstance(item, dict) and item.get("id") + } + missing = sorted(artifact_ids - indexed_ids) + for artifact_id in missing: + errors.append( + { + "code": "artifact_missing_from_retrieval_index", + "artifact_id": artifact_id, + } + ) + + required_brief_artifacts = [ + artifact + for artifact in artifacts + if artifact.kind in {"kernel", "model", "standard", "profile"} + ] + for artifact in required_brief_artifacts: + relative = Path("agent") / "briefs" / f"{_safe_id(artifact.id)}.md" + brief_path = infospace_root / relative + if not brief_path.is_file(): + errors.append( + { + "code": "missing_agent_brief", + "artifact_id": artifact.id, + "path": str(Path("infospace") / relative), + } + ) + continue + frontmatter = _read_markdown_frontmatter(brief_path, errors) + if frontmatter.get("artifact_id") != artifact.id: + errors.append( + { + "code": "agent_brief_artifact_mismatch", + "artifact_id": artifact.id, + "path": str(Path("infospace") / relative), + "value": frontmatter.get("artifact_id"), + } + ) + if frontmatter.get("source_path") != artifact.path: + errors.append( + { + "code": "agent_brief_source_path_mismatch", + "artifact_id": artifact.id, + "path": str(Path("infospace") / relative), + "value": frontmatter.get("source_path"), + "expected": artifact.path, + } + ) + + def _artifact_paths_by_path( infospace_root: Path, errors: list[dict[str, Any]], @@ -348,6 +440,33 @@ def _read_yaml(path: Path, errors: list[dict[str, Any]]) -> Any: return None +def _read_markdown_frontmatter(path: Path, errors: list[dict[str, Any]]) -> dict[str, Any]: + try: + text = path.read_text(encoding="utf-8") + except FileNotFoundError: + errors.append({"code": "missing_markdown", "path": str(path)}) + return {} + if not text.startswith("---\n"): + errors.append({"code": "missing_markdown_frontmatter", "path": str(path)}) + return {} + end = text.find("\n---\n", 4) + if end == -1: + errors.append({"code": "invalid_markdown_frontmatter", "path": str(path)}) + return {} + try: + data = yaml.safe_load(text[4:end]) or {} + except yaml.YAMLError as exc: + errors.append( + { + "code": "invalid_markdown_frontmatter_yaml", + "path": str(path), + "message": str(exc), + } + ) + return {} + return data if isinstance(data, dict) else {} + + def _strip_infospace_prefix(path: str) -> str: prefix = "infospace/" return path[len(prefix) :] if path.startswith(prefix) else path @@ -358,3 +477,7 @@ def _has_substantive_files(directory: Path) -> bool: if path.is_file() and path.name != "README.md": return True return False + + +def _safe_id(value: str) -> str: + return value.replace("/", "-").replace("_", "-") diff --git a/tests/test_service.py b/tests/test_service.py index e84b8e6..0fd4968 100644 --- a/tests/test_service.py +++ b/tests/test_service.py @@ -83,3 +83,11 @@ def test_generators_write_expected_assets(tmp_path) -> None: encoding="utf-8" ).startswith("