diff --git a/.agents/skills/lex-scripta-org-auditor/SKILL.md b/.agents/skills/lex-scripta-org-auditor/SKILL.md new file mode 100644 index 0000000..1b485cd --- /dev/null +++ b/.agents/skills/lex-scripta-org-auditor/SKILL.md @@ -0,0 +1,216 @@ +--- +name: lex-scripta-org-auditor +description: Audit one or more Lex Scripta documents against an org hierarchy defined in Org Map format. Identify statements attributed to the wrong org unit, detect content that should be moved up or down the hierarchy, flag cross-org dependencies that are not coordinated, and report gaps where parent-level policies are missing. Use when you need to verify that structured documents are correctly owned and scoped within a defined organizational structure. +license: MIT +metadata: + author: Lex Scripta Contributors + version: "1.0.0" +--- + +# Lex Scripta Org Auditor + +## Use this skill when + +Activate this skill when: + +- one or more Lex Scripta documents exist and need to be verified against an organizational hierarchy +- an org map exists or can be constructed from context +- the user suspects a document contains statements that belong to a different org unit +- content has accumulated across multiple documents and needs to be redistributed by organizational ownership +- cross-org dependencies or gaps in parent-level policy are suspected + +## Core concepts + +### Org Map + +An Org Map defines the organizational hierarchy using the same indentation model as the Lex Scripta Body. + +- A top-level line names a root org unit. +- One indentation level equals one level of org hierarchy. +- Child org units fall within the scope of their parent. +- A statement owned by a child org unit is also within the scope of all its ancestor units. + +Example: + +```text +Acme Corp + Engineering + Frontend + Backend + Infrastructure + Product + Design + PM + Operations + HR + Finance + Legal +``` + +The Org Map is stored as a separate document using the template in `assets/org-map-template.md`. + +### Org Scope in Lex Scripta documents + +A Lex Scripta document may include an optional `Org Scope` section that declares which org unit owns the document. + +Position: between `Purpose` and `Defined Terms`. + +Format: + +```md +## 0. Org Scope +- Org Unit: Engineering > Backend +- Audience: [Engineering > Backend, Engineering > Infrastructure] +``` + +When `Org Scope` is absent, treat the document as unattributed and include it in the audit with a note. + +### Org path notation + +Write org paths from root to leaf, separated by ` > `. + +Example: `Acme Corp > Engineering > Backend` + +Omit the root when context makes it unambiguous. + +## Audit workflow + +1. Parse the Org Map and build the org hierarchy. +2. For each document, identify its declared `Org Scope` or mark it as `[Unattributed]`. +3. For each statement in the Lex Scripta Body, evaluate whether the subject, action, or scope fits the declared org unit. +4. Classify each issue found. +5. Produce the audit report using the format below. + +## Issue types + +| Code | Name | Meaning | +| --- | --- | --- | +| `MISPLACED` | Org mismatch | A statement belongs to a different org unit than the one declared in `Org Scope` | +| `SHOULD_ELEVATE` | Needs elevation | A statement scoped to a child org unit also applies at a parent level and is missing there | +| `SHOULD_DESCEND` | Needs delegation | A statement written at a parent level is too specific for that level and belongs in a child document | +| `CROSS_DEP` | Cross-org dependency | A statement depends on or affects another org unit but has no corresponding entry in that org's documents | +| `GAP` | Hierarchy gap | A parent org unit is missing a governing policy that its child units assume or depend on | +| `UNATTRIBUTED` | No org scope | A document has no `Org Scope` declaration and its ownership cannot be determined | + +## Evaluation rules + +### Evaluating a statement's org fit + +A statement fits its declared org unit when: + +- the subject of the statement is the org unit or its members +- the action or policy governs only the work within that org unit's domain +- the statement does not reference processes owned by a sibling or parent unit + +A statement does not fit when: + +- the subject is outside the org unit +- the policy governs shared infrastructure, cross-org coordination, or company-wide obligations +- the action requires approval or input from an org unit not represented in the document + +### Determining elevation + +A child-level statement should be elevated when: + +- the same obligation or constraint applies to all sibling org units under the same parent +- the parent org unit has no equivalent governing statement + +### Determining delegation + +A parent-level statement should be delegated when: + +- the statement names a specific team, role, or system that belongs to one child unit only +- the policy cannot affect any sibling unit + +### Detecting cross-org dependencies + +A cross-org dependency exists when: + +- a statement requires output, approval, or data from an org unit not in scope for this document +- no corresponding obligation exists in a document owned by the other org unit + +## Output format + +Produce the audit report in this section order: + +1. `Audit Context` +2. `Summary` +3. `Issues` +4. `Recommendations` + +Use this skeleton: + +````md +# Org Audit Report: + +## 1. Audit Context +- Org Map: <name or path> +- Documents audited: <list> +- Audit date: <date or [Unspecified]> + +## 2. Summary +- Total issues found: N +- MISPLACED: N +- SHOULD_ELEVATE: N +- SHOULD_DESCEND: N +- CROSS_DEP: N +- GAP: N +- UNATTRIBUTED: N + +## 3. Issues + +### [MISPLACED] <short label> +- Document: <document name> +- Org Scope declared: <org path> +- Statement: `<exact statement text>` +- Suggested org: <org path> +- Reason: <one sentence> + +### [SHOULD_ELEVATE] <short label> +- Document: <document name> +- Current location: <org path> +- Statement: `<exact statement text>` +- Suggested parent: <org path> +- Reason: <one sentence> + +### [SHOULD_DESCEND] <short label> +- Document: <document name> +- Current location: <org path> +- Statement: `<exact statement text>` +- Suggested child: <org path> +- Reason: <one sentence> + +### [CROSS_DEP] <short label> +- Document: <document name> +- Org Scope: <org path> +- Statement: `<exact statement text>` +- Affected org: <org path> +- Missing counterpart: <describe the obligation that should exist in the affected org's documents> + +### [GAP] <short label> +- Parent org: <org path> +- Missing policy: <describe the governing statement that is absent> +- Assumed by: <child org path> in `<statement text>` + +### [UNATTRIBUTED] <short label> +- Document: <document name> +- Likely org: <org path or [Cannot determine]> +- Reason: <one sentence> + +## 4. Recommendations +- <Prioritized action, one per bullet> +```` + +## Hard constraints + +- Do not invent org units that are not in the Org Map. +- Do not reassign statements without stating a reason. +- If an org unit is ambiguous, mark it as `[Needs confirmation]` rather than guessing. +- Do not flatten cross-org conflicts by choosing one unit silently. +- If an issue is borderline, note the uncertainty in the reason field. + +## Further reading + +- [Detailed reference](references/REFERENCE.md) +- [Examples](references/EXAMPLES.md) +- [Org Map template](assets/org-map-template.md) diff --git a/.agents/skills/lex-scripta-org-auditor/agents/openai.yaml b/.agents/skills/lex-scripta-org-auditor/agents/openai.yaml new file mode 100644 index 0000000..3a6678d --- /dev/null +++ b/.agents/skills/lex-scripta-org-auditor/agents/openai.yaml @@ -0,0 +1,6 @@ +interface: + display_name: "Lex Scripta Org Auditor" + short_description: "Audit Lex Scripta documents against an org hierarchy" + default_prompt: "Use $lex-scripta-org-auditor to audit these documents against the org map and identify misplaced statements, cross-org dependencies, and hierarchy gaps." +policy: + allow_implicit_invocation: false diff --git a/.agents/skills/lex-scripta-org-auditor/assets/org-map-template.md b/.agents/skills/lex-scripta-org-auditor/assets/org-map-template.md new file mode 100644 index 0000000..7ae54b8 --- /dev/null +++ b/.agents/skills/lex-scripta-org-auditor/assets/org-map-template.md @@ -0,0 +1,35 @@ +# <Organization Name> Org Map + +## 1. Purpose +<One or two sentences describing the organization and the scope of this hierarchy.> + +## 2. Org Hierarchy +```text +<Root Org> + <Division or Department> + <Team or Sub-unit> + <Team or Sub-unit> + <Division or Department> + <Team or Sub-unit> + <Sub-team> +``` + +## 3. Org Definitions +- **<Org Unit>**: <One sentence defining the unit's domain, ownership boundaries, and primary function.> +- **<Org Unit>**: <One sentence.> +- If none, write `- None.` + +## 4. Open Items +- <Unresolved org unit placement, naming conflict, or boundary ambiguity> +- If none, write `- None.` + +--- + +## Usage notes + +- Use the same four-space indentation as the Lex Scripta Body. +- One line = one org unit. +- Use the Org Unit names defined here consistently in all Lex Scripta documents' `Org Scope` sections. +- Org paths are written from root to leaf, separated by ` > `. Example: `<Root Org> > <Division> > <Team>`. +- Do not add policies or rules directly into this document; keep it as a structural reference only. +- If a unit's scope is ambiguous, add it to `Open Items` rather than guessing. diff --git a/.agents/skills/lex-scripta-org-auditor/references/EXAMPLES.md b/.agents/skills/lex-scripta-org-auditor/references/EXAMPLES.md new file mode 100644 index 0000000..dfa1a81 --- /dev/null +++ b/.agents/skills/lex-scripta-org-auditor/references/EXAMPLES.md @@ -0,0 +1,321 @@ +# Examples — Lex Scripta Org Auditor + +## Example 1: Misplaced statement and cross-org dependency + +### Input: Org Map + +```text +Acme Corp + Engineering + Frontend + Backend + Operations + HR + Finance + Legal +``` + +### Input: Document being audited + +````md +# Backend Team Policy + +## 0. Org Scope +- Org Unit: Engineering > Backend + +## 1. Purpose +Define operational rules for the Backend engineering team. + +## 2. Defined Terms +- None. + +## 3. Lex Scripta Body +```text +All employees must complete the annual security awareness training. + Completion must be logged in the HR system by December 31. + +Backend services must have automated test coverage above 80%. + Coverage reports must be submitted to the team lead each sprint. + +New vendor integrations must be reviewed by Legal before activation. + Legal must complete the review within ten business days of request. +``` + +## 4. Open Items +- None. + +## 5. Assumptions +- None. + +## 6. Evidence / Notes +- None. + +## 7. Risks / Conflicts +- None. +```` + +### Output: Audit Report + +````md +# Org Audit Report: Backend Team Policy + +## 1. Audit Context +- Org Map: Acme Corp Org Map +- Documents audited: Backend Team Policy +- Audit date: [Unspecified] + +## 2. Summary +- Total issues found: 3 +- MISPLACED: 1 +- SHOULD_ELEVATE: 0 +- SHOULD_DESCEND: 0 +- CROSS_DEP: 2 +- GAP: 0 +- UNATTRIBUTED: 0 + +## 3. Issues + +### [MISPLACED] Annual security training is a company-wide obligation +- Document: Backend Team Policy +- Org Scope declared: Engineering > Backend +- Statement: `All employees must complete the annual security awareness training.` +- Suggested org: Acme Corp +- Reason: The subject is "all employees," which spans all org units and cannot be governed by a single team's policy document. + +### [CROSS_DEP] HR system logging requires an HR-side obligation +- Document: Backend Team Policy +- Org Scope: Engineering > Backend +- Statement: `Completion must be logged in the HR system by December 31.` +- Affected org: Operations > HR +- Missing counterpart: Operations > HR has no recorded obligation to accept and confirm training completion logs from all teams by the December 31 deadline. + +### [CROSS_DEP] Legal review requires a Legal-side obligation +- Document: Backend Team Policy +- Org Scope: Engineering > Backend +- Statement: `Legal must complete the review within ten business days of request.` +- Affected org: Legal +- Missing counterpart: Legal has no recorded obligation to perform vendor integration reviews or meet the ten business day SLA. This obligation must appear in a Legal-owned document. + +## 4. Recommendations +- Move "All employees must complete the annual security awareness training" and its child statements to an Acme Corp-level policy document. +- Create an obligation in an Operations > HR-owned document requiring HR to accept and confirm training completion logs from all teams by December 31. +- Create an obligation in a Legal-owned document requiring Legal to complete vendor integration reviews within ten business days of request. +```` + +--- + +## Example 2: Elevation and delegation + +### Input: Org Map + +```text +TechCo + Engineering + Frontend + Backend + Infrastructure + Product +``` + +### Input: Two documents being audited + +**Document A** + +````md +# Frontend Development Rules + +## 0. Org Scope +- Org Unit: Engineering > Frontend + +## 1. Purpose +Govern development practices for the Frontend team. + +## 2. Defined Terms +- None. + +## 3. Lex Scripta Body +```text +All code changes must pass peer review before merging. + A minimum of one reviewer is required. + +The Engineering manager must approve all new external library additions. + The library must have an active maintenance record. + Libraries inactive for more than two years are excluded. +``` +```` + +**Document B** + +````md +# Backend Development Rules + +## 0. Org Scope +- Org Unit: Engineering > Backend + +## 1. Purpose +Govern development practices for the Backend team. + +## 2. Defined Terms +- None. + +## 3. Lex Scripta Body +```text +All code changes must pass peer review before merging. + A minimum of one reviewer is required. + +The Backend database schema must be versioned using migration files. + Migration files must be reviewed by the Infrastructure team before deployment. +``` +```` + +### Output: Audit Report + +````md +# Org Audit Report: Frontend and Backend Development Rules + +## 1. Audit Context +- Org Map: TechCo Org Map +- Documents audited: Frontend Development Rules, Backend Development Rules +- Audit date: [Unspecified] + +## 2. Summary +- Total issues found: 3 +- MISPLACED: 0 +- SHOULD_ELEVATE: 1 +- SHOULD_DESCEND: 1 +- CROSS_DEP: 1 +- GAP: 0 +- UNATTRIBUTED: 0 + +## 3. Issues + +### [SHOULD_ELEVATE] Peer review rule is duplicated across Frontend and Backend +- Document: Frontend Development Rules, Backend Development Rules +- Current location: Engineering > Frontend, Engineering > Backend +- Statement: `All code changes must pass peer review before merging.` (identical in both documents) +- Suggested parent: Engineering +- Reason: The rule contains no team-specific system or role and applies equally to all Engineering sub-teams; duplicating it in each child document creates a maintenance risk and suggests a missing Engineering-level policy. + +### [SHOULD_DESCEND] Library approval rule names a role too specific for Frontend scope +- Document: Frontend Development Rules +- Current location: Engineering > Frontend +- Statement: `The Engineering manager must approve all new external library additions.` +- Suggested child: Engineering (elevation, not descent — see note) +- Reason: [Borderline: could also fit Engineering] The subject is "Engineering manager," which governs all Engineering sub-teams, not Frontend alone; this rule may belong at the Engineering level rather than only in the Frontend document, unless Frontend has its own dedicated manager separate from the broader Engineering manager role. Mark as [Needs confirmation]. + +### [CROSS_DEP] Schema migration review requires an Infrastructure-side obligation +- Document: Backend Development Rules +- Org Scope: Engineering > Backend +- Statement: `Migration files must be reviewed by the Infrastructure team before deployment.` +- Affected org: Engineering > Infrastructure +- Missing counterpart: Engineering > Infrastructure has no recorded obligation to review Backend database migration files before deployment. This obligation should appear in an Infrastructure-owned document. + +## 4. Recommendations +- Create an Engineering-level document and move the peer review rule (and its child stating the one-reviewer minimum) there; remove the duplicates from Frontend and Backend documents. +- Confirm whether "Engineering manager" in the library approval rule refers to a role that spans all Engineering sub-teams; if so, elevate the rule to an Engineering-level document. +- Create an obligation in an Engineering > Infrastructure-owned document requiring Infrastructure to review Backend database migration files before deployment. +```` + +--- + +## Example 3: Gap detection and unattributed document + +### Input: Org Map + +```text +GlobalCorp + Sales + Enterprise Sales + SMB Sales + Support + Finance +``` + +### Input: Two documents being audited + +**Document A** — has Org Scope + +````md +# Enterprise Sales Discount Policy + +## 0. Org Scope +- Org Unit: Sales > Enterprise Sales + +## 1. Purpose +Define discount authorization rules for Enterprise Sales. + +## 3. Lex Scripta Body +```text +Discounts up to 15% may be granted by Enterprise Sales representatives. + Discounts above 15% require Sales Director approval as defined in the company discount framework. + Finance must be notified of any discount above 20%. +``` +```` + +**Document B** — no Org Scope + +````md +# Q3 Sales Targets + +## 1. Purpose +Set revenue targets for the upcoming quarter. + +## 3. Lex Scripta Body +```text +The Q3 revenue target is $4.2M. + Enterprise Sales owns 60% of the target. + SMB Sales owns 40% of the target. + +Missed targets must be reported to Finance within five business days of quarter close. +``` +```` + +### Output: Audit Report + +````md +# Org Audit Report: Enterprise Sales Discount Policy and Q3 Sales Targets + +## 1. Audit Context +- Org Map: GlobalCorp Org Map +- Documents audited: Enterprise Sales Discount Policy, Q3 Sales Targets +- Audit date: [Unspecified] + +## 2. Summary +- Total issues found: 4 +- MISPLACED: 0 +- SHOULD_ELEVATE: 0 +- SHOULD_DESCEND: 0 +- CROSS_DEP: 1 +- GAP: 2 +- UNATTRIBUTED: 1 + +## 3. Issues + +### [GAP] Company discount framework is referenced but not found +- Parent org: GlobalCorp or Sales +- Missing policy: A governing "company discount framework" that defines the Sales Director approval threshold and process for discounts above 15%. +- Assumed by: Sales > Enterprise Sales in `Discounts above 15% require Sales Director approval as defined in the company discount framework.` + +### [GAP] Finance notification threshold rule has no parent policy +- Parent org: GlobalCorp or Finance +- Missing policy: A governing rule establishing that Finance must be notified of discounts above 20% and defining who is responsible for sending the notification. +- Assumed by: Sales > Enterprise Sales in `Finance must be notified of any discount above 20%.` + +### [CROSS_DEP] Finance notification requires a Finance-side obligation +- Document: Enterprise Sales Discount Policy +- Org Scope: Sales > Enterprise Sales +- Statement: `Finance must be notified of any discount above 20%.` +- Affected org: Finance +- Missing counterpart: Finance has no recorded obligation to receive, log, or act on discount notifications above 20%. This obligation should appear in a Finance-owned document. + +### [UNATTRIBUTED] Q3 Sales Targets has no Org Scope +- Document: Q3 Sales Targets +- Likely org: Sales [Borderline: could also fit GlobalCorp] +- Reason: The document governs targets for both Enterprise Sales and SMB Sales, suggesting ownership at the Sales level, but the targets may be set at the GlobalCorp level; org attribution requires confirmation. + +## 4. Recommendations +- Create a Sales-level or GlobalCorp-level document defining the company discount framework, including the Sales Director approval process for discounts above 15%. +- Create a Finance-owned document or add an obligation to an existing Finance document requiring Finance to receive, log, and act on discount notifications above 20%. +- Add an Org Scope section to the Q3 Sales Targets document, declaring either Sales or GlobalCorp as the owner after confirming with the document author. +- Confirm whether the revenue target document belongs to the Sales org or to a GlobalCorp-level planning function. +```` diff --git a/.agents/skills/lex-scripta-org-auditor/references/REFERENCE.md b/.agents/skills/lex-scripta-org-auditor/references/REFERENCE.md new file mode 100644 index 0000000..ecf198e --- /dev/null +++ b/.agents/skills/lex-scripta-org-auditor/references/REFERENCE.md @@ -0,0 +1,243 @@ +# Reference Guide — Lex Scripta Org Auditor + +This file expands the operational rules for the `lex-scripta-org-auditor` skill. + +## 1. Org Map semantics + +### 1.1 Hierarchy rules + +The Org Map is the authoritative source of organizational structure. + +- Every indented line is a direct child of the nearest less-indented line above it. +- A child org unit is always within the governance scope of all its ancestors. +- Sibling org units at the same indentation level share a common parent but do not govern each other. + +```text +Company ← root, governs everything + Engineering ← child of Company + Frontend ← child of Engineering, grandchild of Company + Backend ← sibling of Frontend + Operations ← sibling of Engineering + HR ← child of Operations +``` + +### 1.2 Scope inheritance + +A policy written at a parent level applies to all descendants unless a child unit overrides or narrows it. + +A policy written at a child level applies only to that unit and its descendants unless explicitly elevated. + +### 1.3 Org path notation + +Always write the full path from root to leaf when precision is needed: + +```text +Company > Engineering > Backend +``` + +Omit the root only when the context is unambiguous and only one root exists. + +### 1.4 Org Map document structure + +The Org Map is a standalone Lex Scripta document with the following mandatory sections: + +- `Purpose` — describes the organization and the scope of this map +- `Org Hierarchy` — the indented tree in a fenced `text` block +- `Org Definitions` — definitions of each unit's domain and ownership boundaries +- `Open Items` — unresolved placement decisions or missing units + +Optional sections: +- `Constraints by Level` — cross-cutting rules that apply to all units at a given hierarchy depth + +## 2. Org Scope attribution + +### 2.1 What Org Scope declares + +`Org Scope` in a Lex Scripta document declares: + +- **Org Unit** — the org unit that owns and is responsible for the content +- **Audience** — the org units that should act on or be aware of the content (optional) + +Example: + +```md +## 0. Org Scope +- Org Unit: Engineering > Backend +- Audience: [Engineering > Backend, Operations > HR] +``` + +### 2.2 Ownership vs. audience + +Ownership means the org unit is accountable for the document and the policies it contains. + +Audience means the org unit must know and comply with the content, but does not own it. + +An audience org unit that has obligations described in the document may trigger a `CROSS_DEP` issue if the corresponding obligation is absent from that unit's own documents. + +### 2.3 Unattributed documents + +If a document has no `Org Scope` section, the auditor must attempt to infer ownership from: + +1. Document title and purpose +2. Subject of the majority of statements +3. Named roles, systems, and processes in the body + +If inference is not possible with confidence, mark as `[Cannot determine]` and file an `UNATTRIBUTED` issue. + +## 3. Issue classification in detail + +### 3.1 MISPLACED + +A statement is misplaced when its subject, action, or governing scope clearly belongs to a different org unit. + +Signals: +- The statement names a team, role, or system not in the document's declared org unit +- The action governs a process owned by a different unit +- The policy is a company-wide rule and the document is scoped to a single team + +Example: + +```text +Document Org Scope: Engineering > Backend + +Statement: "All employees must complete the annual harassment training." +``` + +This statement belongs at the `Company` level, not `Engineering > Backend`. + +### 3.2 SHOULD_ELEVATE + +A statement should be elevated when it is written in a child document but applies equally to all sibling units under the same parent. + +Signals: +- The rule references no Backend-specific systems or roles +- The same rule would be duplicated if written for Frontend, Infrastructure, and Backend separately +- The parent document has no governing policy in this area + +Example: + +```text +Document Org Scope: Engineering > Backend + +Statement: "All code changes must be reviewed before merging." +``` + +This rule likely applies to all Engineering sub-teams and belongs in an `Engineering`-level document. + +### 3.3 SHOULD_DESCEND + +A statement should be delegated when a parent document contains a rule that is too specific for the parent level. + +Signals: +- The rule names a specific tool, system, or role that belongs to one child unit only +- The rule cannot apply to sibling units without modification +- The level of detail is inconsistent with other rules in the parent document + +Example: + +```text +Document Org Scope: Engineering + +Statement: "The Postgres connection pool must be kept below 80% utilization." +``` + +This is a Backend-specific infrastructure rule, not an Engineering-wide policy. + +### 3.4 CROSS_DEP + +A cross-org dependency exists when a statement requires an action from an org unit that does not own the current document. + +The auditor should flag the dependency and describe what obligation is missing from the other unit's documents. + +Signals: +- A statement says "X team must approve" or "X team will provide" +- The document is owned by a different unit +- No document owned by X team records a corresponding obligation + +Example: + +```text +Document Org Scope: Engineering > Backend + +Statement: "The deployment checklist must be reviewed by Legal before each major release." +``` + +Legal has an obligation here (perform the review) that should be recorded in a Legal-owned document. + +### 3.5 GAP + +A gap exists when child documents assume a parent-level policy that does not exist in any parent-owned document. + +Signals: +- Child documents reference "company policy," "standard process," or "as required by" without a traceable parent document +- Multiple child units have the same rule, suggesting it should exist at the parent level but does not +- A child rule has an exception that references a parent-level rule that cannot be found + +Example: + +```text +Engineering > Frontend document: "Exceptions to the security review rule require VP approval." +Engineering > Backend document: "Exceptions to the security review rule require VP approval." +``` + +If no Engineering-level or Company-level document defines the security review rule, this is a `GAP`. + +### 3.6 UNATTRIBUTED + +A document is unattributed when it has no `Org Scope` section. + +Even if ownership can be inferred, file an `UNATTRIBUTED` issue to ensure the owner adds an explicit declaration. + +## 4. Audit scope decisions + +### 4.1 What to audit + +Audit all statements in the `Lex Scripta Body`. Do not audit: + +- `Open Items` — they are already flagged as unresolved +- `Assumptions` — they are not operational rules +- `Evidence / Notes` — they are context, not obligations + +### 4.2 Prioritizing issues + +Report issues in this order within each document: + +1. `MISPLACED` — highest urgency; content is in the wrong place +2. `CROSS_DEP` — second priority; missing cross-org obligations create gaps in execution +3. `SHOULD_ELEVATE` — third; affects governance completeness +4. `SHOULD_DESCEND` — fourth; affects clarity and correct scoping +5. `GAP` — fifth; affects structural completeness +6. `UNATTRIBUTED` — last; affects attribution only + +### 4.3 Borderline cases + +When a statement could belong to either of two org units, note the ambiguity in the reason field using: `[Borderline: could also fit <org path>]`. + +Do not silently choose one org and suppress the other option. + +## 5. Recommendations format + +Each recommendation must: + +- name the document and statement affected +- state the action required (move, copy, create, elevate, attribute) +- specify the target org unit or document +- be stated in one sentence + +Prioritize recommendations in order of issue type (MISPLACED first, UNATTRIBUTED last). + +Example: + +```text +- Move "All employees must complete the annual harassment training" from the Backend policy document to a Company-level document. +- Create an obligation in a Legal-owned document requiring Legal to review the deployment checklist before each major release. +- Add an Org Scope section to the "Incident Response Runbook" document declaring Engineering > Infrastructure as the owner. +``` + +## 6. Relationship to lex-scripta-structurer + +The `lex-scripta-structurer` skill produces documents. The `lex-scripta-org-auditor` skill audits them. + +Run `lex-scripta-structurer` first to normalize source material into Lex Scripta format. Then run `lex-scripta-org-auditor` to verify organizational placement. + +Both skills use the same indentation-based body format. The Org Map is itself a valid Lex Scripta document. diff --git a/.agents/skills/lex-scripta-structurer/SKILL.md b/.agents/skills/lex-scripta-structurer/SKILL.md index a98ec19..0dc778a 100644 --- a/.agents/skills/lex-scripta-structurer/SKILL.md +++ b/.agents/skills/lex-scripta-structurer/SKILL.md @@ -88,6 +88,8 @@ Produce the document in this exact section order: 6. `Evidence / Notes` 7. `Risks / Conflicts` +Include an optional `Org Scope` section between `Purpose` and `Defined Terms` when the document belongs to a known organizational hierarchy. Omit it when no org hierarchy exists. + Render `Lex Scripta Body` inside a fenced `text` block to preserve indentation. Use this skeleton: @@ -98,6 +100,10 @@ Use this skeleton: ## 1. Purpose <One or two sentences> +## 0. Org Scope *(optional — include when an org hierarchy exists)* +- Org Unit: <path from root to owning unit, e.g. Engineering > Backend> +- Audience: [<other org units that must act on this document>] + ## 2. Defined Terms - <term>: <definition> - If none, write `- None.` @@ -218,3 +224,4 @@ Backend implementation is sequenced before dependent work. - [Examples](references/EXAMPLES.md) - [Output checklist](references/OUTPUT-CHECKLIST.md) - [Reusable output template](assets/output-template.md) +- [Org Auditor skill](../../lex-scripta-org-auditor/SKILL.md) — audit documents against an org hierarchy to detect misplaced content and cross-org gaps diff --git a/.agents/skills/lex-scripta-structurer/assets/output-template.md b/.agents/skills/lex-scripta-structurer/assets/output-template.md index 1092fdb..51474e3 100644 --- a/.agents/skills/lex-scripta-structurer/assets/output-template.md +++ b/.agents/skills/lex-scripta-structurer/assets/output-template.md @@ -3,6 +3,10 @@ ## 1. Purpose <Write one or two sentences that define the scope and intent of the document.> +## 0. Org Scope *(optional — include when an org hierarchy exists)* +- Org Unit: <path from root to owning unit, e.g. Engineering > Backend> +- Audience: [<other org units that must act on this document — omit if none>] + ## 2. Defined Terms - <term>: <definition> - If there are no special terms, write `- None.` @@ -36,3 +40,5 @@ - Keep one claim per line. - Do not guess missing facts. - Use `[Unspecified]` or `[Needs confirmation]` when needed. +- `Org Scope` is optional. Include it when the document belongs to a known org hierarchy. Omit it otherwise. +- Use the `lex-scripta-org-auditor` skill to verify org placement after documents are created. diff --git a/README.md b/README.md index d674401..5860ccb 100644 --- a/README.md +++ b/README.md @@ -1,58 +1,72 @@ -# Lex Scripta Structurer +# Lex Scripta [English](README.md) | [한국어](README.ko.md) | [日本語](README.ja.md) | [简体中文](README.zh-CN.md) -Lex Scripta Structurer is a public Agent Skill for turning conversations, meeting notes, planning drafts, and policy prose into structured Lex Scripta documents. +Lex Scripta is a collection of public Agent Skills for structuring natural language into machine-readable rule trees and auditing that content against organizational hierarchies. Repository: `kuil09/lex-scripta` +## Skills + +| Skill | Purpose | +| --- | --- | +| `lex-scripta-structurer` | Convert conversations, notes, and policy prose into structured Lex Scripta documents | +| `lex-scripta-org-auditor` | Audit Lex Scripta documents against an org hierarchy to detect misplaced content, cross-org dependencies, and policy gaps | + ## Quick Start -### 1. Install it for most agents in one command +### 1. Install a skill for most agents in one command Use the `skills` CLI for the fastest project-local install: ```text npx skills add kuil09/lex-scripta --skill lex-scripta-structurer --copy -y +npx skills add kuil09/lex-scripta --skill lex-scripta-org-auditor --copy -y ``` Add `--global` if you prefer a user-level install instead of a project-local install. -### 2. Install it into a specific agent +### 2. Install into a specific agent Claude Code: ```text npx skills add kuil09/lex-scripta --skill lex-scripta-structurer --agent claude-code --copy -y +npx skills add kuil09/lex-scripta --skill lex-scripta-org-auditor --agent claude-code --copy -y ``` Cursor: ```text npx skills add kuil09/lex-scripta --skill lex-scripta-structurer --agent cursor --copy -y +npx skills add kuil09/lex-scripta --skill lex-scripta-org-auditor --agent cursor --copy -y ``` Gemini CLI: ```text npx skills add kuil09/lex-scripta --skill lex-scripta-structurer --agent gemini-cli --copy -y +npx skills add kuil09/lex-scripta --skill lex-scripta-org-auditor --agent gemini-cli --copy -y ``` ### 3. Manual fallback paths -If you do not want to use the `skills` CLI, copy the canonical skill folder into the target project manually: +If you do not want to use the `skills` CLI, copy the canonical skill folders into the target project manually: -- Universal agents such as Codex, Cursor, and Gemini CLI: `.agents/skills/lex-scripta-structurer` -- Claude Code: `.claude/skills/lex-scripta-structurer` +- Universal agents such as Codex, Cursor, and Gemini CLI: `.agents/skills/lex-scripta-structurer`, `.agents/skills/lex-scripta-org-auditor` +- Claude Code: `.claude/skills/lex-scripta-structurer`, `.claude/skills/lex-scripta-org-auditor` ## What this repository includes -- `.agents/skills/lex-scripta-structurer/` is the canonical installable skill package. +- `.agents/skills/lex-scripta-structurer/` — the structurer skill package +- `.agents/skills/lex-scripta-org-auditor/` — the org auditor skill package - `.github/scripts/validate_skill.py` validates the public packaging contract. - `.github/workflows/release-skill.yml` builds release artifacts for tagged versions. - `docs/catalog-readiness-checklist.md` tracks readiness for review-driven catalogs and public distribution. -## When to use the skill +## When to use each skill + +### lex-scripta-structurer Use Lex Scripta Structurer when you need to convert any of the following into a machine-readable rule tree without losing the original meaning: @@ -63,6 +77,18 @@ Use Lex Scripta Structurer when you need to convert any of the following into a - policy prose - mixed action items and open questions +### lex-scripta-org-auditor + +Use Lex Scripta Org Auditor after documents have been structured when you need to: + +- verify that documents are owned by the correct org unit +- identify statements that belong to a parent, sibling, or child unit +- find cross-org obligations that are missing from the relevant unit's documents +- detect parent-level policy gaps that child documents depend on +- prepare a content audit before merging or redistributing structured documents + +The auditor takes an Org Map (an indentation-based org hierarchy in Lex Scripta format) and one or more Lex Scripta documents with `Org Scope` declarations. It produces a structured report listing each issue and a prioritized set of recommendations. + ## Why the format works Lex Scripta keeps natural language readable while making the execution logic explicit. @@ -128,6 +154,15 @@ lex-scripta/ OUTPUT-CHECKLIST.md assets/ output-template.md + lex-scripta-org-auditor/ + SKILL.md + agents/ + openai.yaml + references/ + REFERENCE.md + EXAMPLES.md + assets/ + org-map-template.md .github/ scripts/ workflows/