From d54cf495c6159a7fd0a193b41bc659affd61bc48 Mon Sep 17 00:00:00 2001
From: Nikita Wootten <nikita.wootten@nist.gov>
Date: Thu, 2 Mar 2023 21:09:34 -0500
Subject: [PATCH] Profile resolution how-to readmes (#1666)

* Profile resolution how-to readmes
Fixes #1178

* Delete old `resolver-2018` folder

* Update resolver-pipeline readme.md with more generic instructions on running the pipeline

Co-authored-by: A.J. Stein <alexander.stein@nist.gov>

* Remove notice to only use Saxon 10 in line with previous feedback

* Added instructions for the wrapper script

---------

Co-authored-by: A.J. Stein <alexander.stein@nist.gov>
---
 src/utils/util/resolver-pipeline/README.md    |  66 ++
 src/utils/util/resolver-pipeline/TESTING.md   |   7 +
 .../oscal-profile-resolve.sh                  |  37 +
 src/utils/util/resolver-pipeline/readme.md    |  49 --
 .../resolver-2018/profile-resolver.xsl        | 656 ------------------
 .../resolver-2018/resolution-notes.md         | 146 ----
 6 files changed, 110 insertions(+), 851 deletions(-)
 create mode 100644 src/utils/util/resolver-pipeline/README.md
 create mode 100644 src/utils/util/resolver-pipeline/TESTING.md
 create mode 100755 src/utils/util/resolver-pipeline/oscal-profile-resolve.sh
 delete mode 100644 src/utils/util/resolver-pipeline/readme.md
 delete mode 100644 src/utils/util/resolver-pipeline/resolver-2018/profile-resolver.xsl
 delete mode 100644 src/utils/util/resolver-pipeline/resolver-2018/resolution-notes.md

diff --git a/src/utils/util/resolver-pipeline/README.md b/src/utils/util/resolver-pipeline/README.md
new file mode 100644
index 0000000000..48e7dff106
--- /dev/null
+++ b/src/utils/util/resolver-pipeline/README.md
@@ -0,0 +1,66 @@
+# Profile Resolver Pipeline
+
+Profile resolution is implemented here as a sequence of XSLT transformations. The sequence applies to defined inputs (a **source profile** with imported **catalog** sources) and produces defined outputs (a **profile resolution result** in the form of a catalog). The word **baseline** also refers to a particular profile in application, whether in its unprocessed form or its resolved, serialized form.
+
+The sequence of XSLT transformations reflects and roughly corresponds to the steps in profile resolution described for OSCAL in the [Profile Resolution Specification](https://pages.nist.gov/OSCAL/concepts/processing/profile-resolution/):
+
+- **selection**: importing catalogs or profiles, and selecting controls from them
+
+- **organization (merging)**: organizing the selected controls for the output representation
+
+- **modification**: setting parameters and potentially supplementing, amending or editing control text
+
+## Usage
+
+The entry point for the transformation pipeline is `oscal-profile-RESOLVE.xsl`, which invokes the transformation steps in sequence, taking the source profile document as primary input.
+
+The following additional parameters can be used to modify the transformation pipeline's behavior:
+
+| Name                      | Description                                                                                                                                                                                                                                                                                                                                                                                                                           | Default                                      |
+| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- |
+| `hide-source-profile-uri` | If `true`, the output catalog's metadata does not record the source profile's URI.                                                                                                                                                                                                                                                                                                                                                    | `false`                                      |
+| `path-to-source`          | Path from output catalog to location of source profile.                                                                                                                                                                                                                                                                                                                                                                               | None                                         |
+| `top-uuid`                | UUID value for top-level element in output catalog, if `uuid-method` is `user-provided`.                                                                                                                                                                                                                                                                                                                                              | None                                         |
+| `uuid-method`             | Method for computing UUID of top-level element in output catalog. Valid values are: `random-xslt`, in which case the `random-number-generator` XPath function must be available; `random-java`, in which case the `java.util.UUID.randomUUID()` Java method must be available; `user-provided`, in which case you must specify the `top-uuid` parameter; `web-service`, referring to the `uuid-service` parameter value; and `fixed`. | `fixed`                                      |
+| `uuid-service`            | URI for a web service that produces a UUID, if `uuid-method` is `web-service`.                                                                                                                                                                                                                                                                                                                                                        | `https://www.uuidgenerator.net/api/version4` |
+| `trace`                   | If set to `on`, additional debug information will be printed to the console and `opr:ERROR`, `opr:WARNING` messages will be retained in the output document.                                                                                                                                                                                                                                                                          | None                                         |
+
+Note that URIs (addresses) given in a profile document must link correctly as absolute or relative paths to their imported catalogs, as demonstrated in [examples](../../../specifications/profile-resolution/profile-resolution-examples).
+
+A serialized output of profile resolution takes the form of an OSCAL catalog. Assuming inputs are correctly formed, the output is valid to the catalog schema.
+
+## Invoking the Pipeline
+
+The profile resolver and other utilities in this repo rely on open-source libraries and utilities developed by third parties. To review the software version used by this project, please review [the `build` directory for manifests of software and the specific versions](../../../../build) we recommend for running utilities from this repo, specifically the recommended [version of Saxon XSLT processor defined in the pom.xml manifest](../../../../build/pom.xml).
+
+### Using Saxon Manually From the Command Line
+
+Before you begin:
+
+- Install the Java runtime using your preferred method.
+- Download a compatible version of [Saxon Java Home Edition](https://www.saxonica.com/download/java.xml) and extract the `saxon-he` jar file.
+
+Invoke Saxon with your document and the profile resolution stylesheet as follows:
+
+```
+$ java -jar /path/to/saxon-he-10.x.jar -t -s:YOUR_PROFILE_DOCUMENT.xml -xsl:path/to/oscal-profile-RESOLVE.xsl -o:YOUR_RESULT_BASELINE.xml
+```
+
+Saxon allows users to specify additional parameters (such as the ones specified [above](#usage)) by adding arguments with the format `name=value` to the end of the above command. As an example, see the command:
+
+```bash
+$ java -jar /path/to/saxon-he-10.x.jar -t -s:YOUR_PROFILE_DOCUMENT.xml -xsl:path/to/oscal-profile-RESOLVE.xsl -o:YOUR_RESULT_BASELINE.xml uuid-method=random-xslt hide-source-profile-uri=true
+```
+
+### Using the `oscal-profile-resolve.sh` Wrapper Script
+
+The [`oscal-profile-resolve.sh`](./oscal-profile-resolve.sh) wrapper script only requires [Maven](https://maven.apache.org/) to be installed.
+It manages external dependencies, and can be invoked from other directories.
+
+The syntax for invoking the wrapper script is as follows:
+
+```bash
+$ ./oscal-profile-resolve.sh YOUR_PROFILE_DOCUMENT.xml YOUR_RESULT_BASELINE.xml [additional arguments]
+```
+
+Additional arguments are passed into Saxon verbatim and should be in the same `name=value` format described [above](#using-saxon-manually-from-the-command-line).
diff --git a/src/utils/util/resolver-pipeline/TESTING.md b/src/utils/util/resolver-pipeline/TESTING.md
new file mode 100644
index 0000000000..91b62496d9
--- /dev/null
+++ b/src/utils/util/resolver-pipeline/TESTING.md
@@ -0,0 +1,7 @@
+# Profile Resolver Pipeline Tests
+
+The `testing/*` folders contain XSpec tests that indicate expected interim results of each XSLT transformation in the sequence.
+
+Note that these interim results are _not necessarily valid to any OSCAL schema_, although they are quite close to OSCAL profile and catalog syntax.
+
+The files in `testing/*` are only for this implementation. Implementation-independent tests and sample files for profile resolution are [with the specification](../../../specifications/profile-resolution).
diff --git a/src/utils/util/resolver-pipeline/oscal-profile-resolve.sh b/src/utils/util/resolver-pipeline/oscal-profile-resolve.sh
new file mode 100755
index 0000000000..7ac3e3d3b5
--- /dev/null
+++ b/src/utils/util/resolver-pipeline/oscal-profile-resolve.sh
@@ -0,0 +1,37 @@
+#!/usr/bin/env bash
+# OSCAL Profile Resolution Pipeline Wrapper
+
+set -Eeuo pipefail
+
+usage() {
+    cat <<EOF
+Usage: $(basename "${BASH_SOURCE[0]}") TARGET_PROFILE OUTPUT_BASELINE [ADDITIONAL_ARGS]
+
+Runs the OSCAL Profile Resolution Pipeline on the TARGET_PROFILE.
+
+Additional arguments should be specified in the `key=value` format.
+EOF
+}
+
+if ! [ -x "$(command -v mvn)" ]; then
+  echo 'Error: Maven (mvn) is not in the PATH, is it installed?' >&2
+  exit 1
+fi
+
+[[ -z "${1-}" ]] && { echo "Error: TARGET_PROFILE not specified"; usage; exit 1; }
+TARGET_PROFILE=$1
+[[ -z "${2-}" ]] && { echo "Error: OUTPUT_BASELINE not specified"; usage; exit 1; }
+OUTPUT_BASELINE=$2
+
+ADDITIONAL_ARGS=$(shift 2; echo $@)
+
+SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd)"
+OSCAL_DIR="${SCRIPT_DIR}/../../../.."
+POM_FILE="${OSCAL_DIR}/build/pom.xml"
+ENTRY_STYLESHEET="${SCRIPT_DIR}/oscal-profile-RESOLVE.xsl"
+
+mvn \
+    -f $POM_FILE \
+    exec:java \
+    -Dexec.mainClass="net.sf.saxon.Transform" \
+    -Dexec.args="-t -s:$TARGET_PROFILE -xsl:$ENTRY_STYLESHEET -o:$OUTPUT_BASELINE $ADDITIONAL_ARGS"
diff --git a/src/utils/util/resolver-pipeline/readme.md b/src/utils/util/resolver-pipeline/readme.md
deleted file mode 100644
index 0e8913a01b..0000000000
--- a/src/utils/util/resolver-pipeline/readme.md
+++ /dev/null
@@ -1,49 +0,0 @@
-## Profile Resolver Pipeline
-
-Profile resolution is implemented here as a sequence of XSLT transformations. The sequence applies to defined inputs (a **source profile** with imported **catalog** sources) and produces defined outputs (a **profile resolution result** in the form of a catalog). The word **baseline** also refers to a particular profile in application, whether in its unprocessed form or its resolved, serialized form.
-
-The sequence of XSLT transformations reflects and roughly corresponds to the steps in profile resolution described for OSCAL in the [Profile Resolution Specification](https://pages.nist.gov/OSCAL/concepts/processing/profile-resolution/):
-
-- **selection**: importing catalogs or profiles, and selecting controls from them
-
-- **organization (merging)**: organizing the selected controls for the output representation
-
-- **modification**: setting parameters and potentially supplementing, amending or editing control text
-
-### Tests for this Implementation
-
-The `testing/*` folders contain XSpec tests that indicate expected interim results of each XSLT transformation in the sequence.
-
-Note that these interim results are *not necessarily valid to any OSCAL schema*, although they are quite close to OSCAL profile and catalog syntax.
-
-The files in `testing/*` are only for this implementation. Implementation-independent tests and sample files for profile resolution are [with the specification](../../../specifications/profile-resolution).
-
-### Invoking the XSLT
-
-Use a recent version of Saxon for best results &#8212; although we would also be *very interested* to hear from users of other XSLT engines conformant to the 3.1 family of XML standards (XSLT/XPath/XDM/XQuery).
-
-The entry point for the transformation pipeline is `oscal-profile-RESOLVE.xsl`, which invokes the transformation steps in sequence, taking the source profile document as primary input. Load Saxon with your document and this stylesheet as follows (for example):
-
-```bash
->  java -cp saxon-he-10.0.jar net.sf.saxon.Transform -t -s:YOUR_PROFILE_DOCUMENT.xml -xsl:path/to/oscal-profile-RESOLVE.xsl -o:YOUR_RESULT_BASELINE.xml
-```
-
-You can optionally set one or more of the parameters listed in the following table, using syntax `name=value` at the end of the command above. The sequence of parameters is not significant.
-
-For example,
-```bash
->  java -cp saxon-he-10.0.jar net.sf.saxon.Transform -t -s:YOUR_PROFILE_DOCUMENT.xml -xsl:path/to/oscal-profile-RESOLVE.xsl -o:YOUR_RESULT_BASELINE.xml uuid-method=random-xslt hide-source-profile-uri=true
-```
-| Name  | Description  | Default  |
-|---|---|---|
-| `hide-source-profile-uri` | If `true`, the output catalog's metadata does not record the source profile's URI.  | `false` |
-| `path-to-source`  | Path from output catalog to location of source profile. | None |
-| `top-uuid` | UUID value for top-level element in output catalog, if `uuid-method` is `user-provided`. | None |
-| `uuid-method` | Method for computing UUID of top-level element in output catalog. Valid values are: `random-xslt`, in which case the `random-number-generator` XPath function must be available; `random-java`, in which case the `java.util.UUID.randomUUID()` Java method must be available; `user-provided`, in which case you must specify the `top-uuid` parameter; `web-service`, referring to the `uuid-service` parameter value; and `fixed`. | `fixed`|
-| `uuid-service` | URI for a web service that produces a UUID, if `uuid-method` is `web-service`.| `https://www.uuidgenerator.net/api/version4`|
-
-Alternatively, set up the bindings in an IDE or programming environment that has XSLT 3.1 support.
-
-Note that URIs (addresses) given in a profile document must link correctly as absolute or relative paths to their imported catalogs, as demonstrated in [examples](../../../specifications/profile-resolution/profile-resolution-examples).
-
-A serialized output of profile resolution takes the form of an OSCAL catalog. Assuming inputs are correctly formed, the output is valid to the catalog schema.
diff --git a/src/utils/util/resolver-pipeline/resolver-2018/profile-resolver.xsl b/src/utils/util/resolver-pipeline/resolver-2018/profile-resolver.xsl
deleted file mode 100644
index cdcd2f8ab3..0000000000
--- a/src/utils/util/resolver-pipeline/resolver-2018/profile-resolver.xsl
+++ /dev/null
@@ -1,656 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<xsl:stylesheet version="3.0"
-  xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
-  xmlns:xs="http://www.w3.org/2001/XMLSchema"
-
-  xmlns="http://csrc.nist.gov/ns/oscal/1.0"
-  xmlns:oscal="http://csrc.nist.gov/ns/oscal/1.0"
-  xpath-default-namespace="http://csrc.nist.gov/ns/oscal/1.0"
-  exclude-result-prefixes="#all">
-
-  <!-- Purpose: from OSCAL profile input, produce a representation of all controls called with insertions, alterations, modifications and settings applied. -->
-  <!-- Dependencies: working links to valid control catalogs in OSCAL XML. -->
-
-  <xsl:strip-space elements="group control part section component"/>
-
-  <xsl:output indent="yes"/>
-
-  <xsl:mode name="#default"      on-no-match="shallow-copy"/>
-
-  <xsl:mode name="oscal:resolve" on-no-match="shallow-copy"/>
-
-  <xsl:mode name="copy"          on-no-match="shallow-copy"/>
-
-  <xsl:mode name="import"        on-no-match="shallow-copy"/>
-
-  <!-- 'filter-merge' mode post-processes merged results to remove duplicated data -->
-  <xsl:mode name="filter-merge" on-no-match="shallow-copy"/>
-
-  <!-- Extension point for merge-time enhancement here recording import provenance (otherwise lost in merge) -->
-  <xsl:mode name="merge-enhance" on-no-match="shallow-copy"/>
-
-  <xsl:mode name="patch"         on-no-match="shallow-copy"/>
-
-
-<!-- Presumes new model (import*, merge? modify)
-  1. Test import* across multiple deep imports
-  2. Refine aggregation w/o merge logic
-  3. Install / test merge logic
-  4. Reimplement modify logic
-  -->
-
-  <!-- Frameworks and catalogs are resolved as themselves (for now). -->
-  <xsl:template match="catalog | framework | worksheet" mode="oscal:resolve #default">
-    <xsl:apply-templates select="." mode="copy"/>
-  </xsl:template>
-
-  <!-- Profiles, however, must be executed ... -->
-  <xsl:template match="profile" mode="oscal:resolve #default">
-    <!-- each child of profile indicates a filter:
-      import: adds a new selection of controls
-      merge: merges replicated catalog structures
-      modify: propagates changes and parameter values -->
-
-      <xsl:iterate select="*">
-        <!-- $so-far starts with only a flag -->
-        <xsl:param name="so-far">
-          <resolution profile="{document-uri(/)}"/>
-        </xsl:param>
-        <xsl:on-completion select="$so-far"/>
-        <xsl:next-iteration>
-          <xsl:with-param name="so-far">
-            <!-- now process the import, merge or modify as a proxy -->
-            <xsl:apply-templates select="." mode="process-profile">
-              <xsl:with-param name="so-far" select="$so-far"/>
-            </xsl:apply-templates>
-          </xsl:with-param>
-        </xsl:next-iteration>
-      </xsl:iterate>
-  </xsl:template>
-
-<!-- 'process-profile' mode drives the application of semantics of
-      profile element children 'import', 'merge' and 'modify' -->
-
-<!-- import: adds control set by (recursively) calling profiles/catalogs -->
-
-  <xsl:template match="import" mode="process-profile">
-    <xsl:param name="so-far" as="document-node()"/>
-    <xsl:variable name="imported">
-      <!-- Returns the imported profile or catalog, including only the designated controls. It will be a 'resolution' element or an ERROR.-->
-      <xsl:apply-templates select="." mode="import"/>
-    </xsl:variable>
-    <!-- Returning $so-far, except with the imported / filtered catalog spliced in -->
-    <xsl:for-each select="$so-far/*">
-      <xsl:copy>
-        <xsl:copy-of select="@*"/>
-        <xsl:copy-of select="node()"/>
-        <xsl:sequence select="$imported"/>
-      </xsl:copy>
-    </xsl:for-each>
-    <xsl:apply-templates select="." mode="echo"/>
-  </xsl:template>
-
-  <xsl:template match="*" mode="process-profile">
-    <xsl:param name="so-far"/>
-    <xsl:apply-templates select="." mode="echo"/>
-    <xsl:sequence select="$so-far"/>
-  </xsl:template>
-
-  <!-- Mode 'import' manages importing controls from catalogs or upstream profiles -->
-  <xsl:template match="import" mode="import oscal:resolve">
-    <xsl:param name="authorities-so-far" tunnel="yes" select="document-uri(/)" as="xs:anyURI+"/>
-
-
-    <!--<xsl:param name="invocation" tunnel="yes" select="."/>-->
-    <xsl:variable name="invocation" select="."/>
-
-
-    <!-- $authority will be a catalog, framework or profile. -->
-    <xsl:variable name="authority"    select="document(@href,root(.))"/>
-    <!-- $authorityURI is a full path not whatever relative form was used -->
-    <xsl:variable name="authorityURI" select="document-uri($authority)"/>
-
-    <importing>
-      <xsl:attribute name="href" select="resolve-uri(@href,document-uri(/))"/>
-
-      <xsl:choose>
-        <xsl:when test="$authorityURI = $authorities-so-far" expand-text="true">
-          <ERROR>Can't resolve profile against {$authorityURI}, already imported in this chain:
-            {string-join($authorities-so-far,' / ')}</ERROR>
-        </xsl:when>
-        <xsl:otherwise>
-          <xsl:apply-templates select="." mode="report-invocation"/>
-
-          <!--    first we process ourselves with our own rules, returning a catalog, worksheet or (if a profile), a resolution. -->
-          <!-- then we filter the resolution using the new import -->
-          <xsl:variable name="interim">
-            <xsl:apply-templates select="$authority" mode="oscal:resolve"/>
-          </xsl:variable>
-          <!-- Next we apply templates in mode 'import', passing ourselves in as the invocation -->
-          <xsl:apply-templates select="$interim" mode="import">
-            <xsl:with-param name="invocation" tunnel="yes" select="."/>
-            <xsl:with-param name="authorities-so-far" tunnel="yes" as="xs:anyURI+"
-              select="$authorities-so-far, $authorityURI"/>
-          </xsl:apply-templates>
-          <!--<xsl:copy-of  select="$interim"/>-->
-        </xsl:otherwise>
-      </xsl:choose>
-    </importing>
-  </xsl:template>
-
-  <xsl:template match="import" mode="report-invocation">
-    <xsl:variable name="invocation" select="."/>
-    <!-- $authority will be a catalog, framework or profile. -->
-    <xsl:variable name="authority" select="document(@href,root(.))"/>
-    <xsl:comment expand-text="true"> importing { $authority/*/local-name() }</xsl:comment>
-    <!--<xsl:copy-of select="*"/>-->
-  </xsl:template>
-
-  <xsl:template match="catalog | framework | worksheet | resolution" mode="import">
-    <xsl:variable name="filtered-results">
-      <xsl:apply-templates select="*" mode="#current"/>
-    </xsl:variable>
-    <xsl:if test="exists($filtered-results/*)">
-        <xsl:sequence select="$filtered-results"/>
-    </xsl:if>
-  </xsl:template>
-
-  <xsl:template match="profile" mode="import">
-    <xsl:message terminate="yes">Matched profile unexpectedly</xsl:message>
-  </xsl:template>
-
-  <xsl:template match="section" mode="import"/>
-
-  <xsl:template match="group" mode="import">
-    <xsl:apply-templates select="group | control | component" mode="#current"/>
-    <!--<xsl:variable name="included">
-      <xsl:apply-templates select="group | control | component" mode="#current"/>
-    </xsl:variable>
-    <!-\- If the group contains nothing to be included, it isn't included either -\->
-    <xsl:if test="exists($included/*)">
-      <xsl:copy>
-        <xsl:apply-templates select="@*" mode="#current"/>
-        <xsl:attribute name="process-id" select="generate-id()"/>
-        <xsl:apply-templates select="title" mode="#current"/>
-        <xsl:sequence select="$included"/>
-      </xsl:copy>
-    </xsl:if>-->
-  </xsl:template>
-
-  <!--<xsl:template match="catalog/title | framework/title | worksheet/title | profile/title | group/title" mode="filter-controls">
-    <xsl:param name="invocation" tunnel="yes" as="element(import)" required="yes"/>
-    <xsl:copy>
-      <xsl:copy-of select="@*"/>
-      <xsl:apply-templates/>
-      <xsl:text> [included in </xsl:text>
-      <xsl:apply-templates select="$invocation/ancestor::profile[1]/title"/>
-      <xsl:text>]</xsl:text>
-    </xsl:copy>
-  </xsl:template>-->
-
-  <xsl:function name="oscal:matched" as="xs:boolean">
-    <!-- $comp should be a control or component -->
-    <xsl:param name="comp" as="element()"/>
-    <!-- $imp will be an import element -->
-    <xsl:param name="invocation" as="element()"/>
-    <xsl:variable name="included" as="xs:boolean" select="exists($invocation/include/all) or empty($invocation/include)"/>
-    <xsl:variable name="matched" select="some $re in ($invocation/include/match/@pattern ! ('^' || . || '$') ) satisfies (matches($comp/@id,$re))"/>
-    <xsl:variable name="ancestor-control" select="$comp/(ancestor::control | ancestor::requirement[oscal:classes(.)='control'] )"/>
-    <xsl:variable name="subcontrol-matched" select="some $re in ($invocation/include/match[@with-child-controls='yes']/@pattern ! ('^' || . || '$') ) satisfies (matches($ancestor-control/@id,$re))"/>
-    <!--<xsl:variable name="control-implied" select="some $re in ($invocation/include/match[@with-control='yes']/@pattern ! ('^' || . || '$') ) satisfies (matches($comp/subcontrol/@id,$re))"/>-->
-
-    <xsl:variable name="unmatched" select="some $re in ($invocation/exclude/match/@pattern ! ('^' || . || '$') ) satisfies (matches($comp/@id,$re))"/>
-
-    <xsl:sequence select="($included or $matched or $subcontrol-matched) and not($unmatched)"/>
-  </xsl:function>
-
-  <xsl:template match="control | component[oscal:classes(.)='control']" priority="3" mode="import">
-    <!--A control or subcontrol is always excluded if it appears in import/exclude
-    Otherwise, it is included if empty(import/include), exists(import/all)
-    or exists(import/call[(@control-id | @subcontrol-id)=current()/@id]-->
-    <xsl:param name="invocation" tunnel="yes" as="element(import)" required="yes"/>
-    <!-- A control is included by 'all' or by default when no inclusion rule is given -->
-    <xsl:variable name="included" as="xs:boolean" select="exists($invocation/include/all) or empty($invocation/include)"/>
-    <xsl:variable name="excluded" as="xs:boolean" select="$invocation/exclude/call/@control-id = @id"/>
-    <xsl:variable name="called"   as="xs:boolean" select="$invocation/include/call/@control-id = @id"/>
-    <!--<xsl:copy-of select="$invocation"/>-->
-
-
-    <xsl:choose>
-      <!-- The control is included: go for it -->
-      <xsl:when test="($included or oscal:matched(.,$invocation) or $called) and not($excluded)">
-        <xsl:copy>
-          <xsl:copy-of select="@*"/>
-          <!--<xsl:comment expand-text="true"> invoked by { $invocation/../title } { document-uri($invocation/root()) }</xsl:comment>-->
-          <!--<xsl:apply-templates mode="#current" select="* except (subcontrol | component[oscal:classes(.)='subcontrol'])"/>-->
-          <xsl:apply-templates mode="#current"/>
-        </xsl:copy>
-      </xsl:when>
-      <xsl:otherwise>
-        <!-- The control is not included but it is not impossible than a subcontrol is included anyway -->
-        <xsl:apply-templates select="control" mode="import">
-          <xsl:with-param name="orphan" select="true()"/>
-        </xsl:apply-templates>
-      </xsl:otherwise>
-    </xsl:choose>
-  </xsl:template>
-
-
-  <xsl:template match="processing-instruction()" mode="import"/>
-
-
-
-  <!-- Default merge behavior:
-         collapses duplicates where possible
-         inserts subcontrols into their controls (if warranted by ... what?)
-         flags errors for
-           controls in conflict (or are there collapsing rules)
-           orphan subcontrols remaining -->
-
-
-
-  <xsl:template match="merge" mode="process-profile">
-    <xsl:param name="so-far"/>
-    <!--<xsl:sequence select="$so-far"/>-->
-    <xsl:variable name="merge-spec" select="."/>
-    <xsl:variable name="merged">
-      <merged>
-        <!-- $so-far is giving us a sequence of imported controls and subcontrols, some of which may be nested, so representing all the import trees. -->
-        <xsl:variable name="included" select="$so-far//control"/>
-        <xsl:choose>
-          <xsl:when test="exists($merge-spec/custom)">
-
-            <!-- In this branch, a customized organization will be provided for them, so they are not grouped (by catalog) as below, going in ...  -->
-            <!-- Problem: what to do about clashing IDs (across catalogs) in this case? -->
-
-            <xsl:apply-templates select="$merge-spec/custom" mode="build">
-              <xsl:with-param name="controls" tunnel="yes" select="$included"/>
-            </xsl:apply-templates>
-
-          </xsl:when>
-          <xsl:otherwise>
-
-            <xsl:for-each-group select="$included" group-by="parent::importing/@href">
-              <group source="{current-grouping-key()}">
-
-                <!-- If the merge spec says as-is, we do that -->
-                <xsl:apply-templates select="$merge-spec/as-is" mode="rebuild">
-                  <xsl:with-param name="catalog" select="document(current-grouping-key())/*"/>
-                  <xsl:with-param name="controls" tunnel="yes" select="current-group()"/>
-                </xsl:apply-templates>
-                <!-- nb different mode here -->
-
-                <xsl:if test="empty($merge-spec/(as-is | custom))">
-                  <xsl:for-each-group select="current-group()" group-by="@id">
-                    <xsl:call-template name="emit-component">
-                      <xsl:with-param name="control-set" select="current-group()"/>
-                      <xsl:with-param name="combining" select="$merge-spec/combine"/><!-- XXXX -->
-                    </xsl:call-template>
-                  </xsl:for-each-group>
-                  <!--<xsl:sequence select="current-group()"/>-->
-                </xsl:if>
-
-              </group>
-            </xsl:for-each-group>
-
-          </xsl:otherwise>
-        </xsl:choose>
-      </merged>
-    </xsl:variable>
-    <!--<xsl:sequence select="$merged"/>-->
-
-    <xsl:for-each select="$so-far/*">
-      <xsl:copy>
-        <xsl:copy-of select="@*"/>
-        <xsl:copy-of select="node()"/>
-        <xsl:sequence select="$merged"/>
-      </xsl:copy>
-    </xsl:for-each>
-    <xsl:apply-templates select="." mode="echo"/>
-
-
-  </xsl:template>
-
-
-  <xsl:template match="as-is" mode="rebuild">
-    <xsl:param name="catalog"  select="()" as="element(catalog)?"/>
-    <xsl:apply-templates select="$catalog" mode="rebuild">
-      <xsl:with-param name="merge-spec" tunnel="true" select=".."/>
-    </xsl:apply-templates>
-  </xsl:template>
-
-  <!-- Mode 'rebuild' traverses a home catalog and rebuilds it, containing only the controls and subcontrols
-     included. -->
-  <xsl:mode name="rebuild" on-no-match="shallow-copy"/>
-
-  <xsl:template match="comment() | processing-instruction()" mode="rebuild"/>
-
-  <xsl:template match="catalog | group" mode="rebuild">
-    <xsl:param name="controls" tunnel="yes" select="()"/>
-    <xsl:if test="$controls/@id = .//control/@id">
-      <xsl:copy>
-        <xsl:apply-templates mode="rebuild"/>
-      </xsl:copy>
-    </xsl:if>
-  </xsl:template>
-
-
-  <!-- in 'rebuild' mode, the controls are matched in their original structure,
-       but must then be emitted (now not the originals, but the proxies) according to the merge/combine rules. -->
-  <xsl:template   mode="rebuild" match="control | component">
-    <xsl:param    name="controls"   tunnel="yes" select="()"/>
-    <xsl:param    name="merge-spec" tunnel="yes" as="element(merge)"/>
-    <xsl:variable name="here"  select="."/>
-
-    <xsl:for-each-group select="$controls[@id=$here/@id]" group-by="true()">
-      <xsl:call-template name="emit-component">
-        <xsl:with-param name="combining"   select="$merge-spec/combine"/>
-        <xsl:with-param name="control-set" select="current-group()"/>
-      </xsl:call-template>
-    </xsl:for-each-group>
-      <!--<xsl:for-each-group select="$controls[@id=$here/@id]" group-by="true()">
-        <control id="{$here/@id}">
-          <xsl:if test="exists(current-group()[matches(@class,'\s')])">
-            <xsl:attribute name="class" select="distinct-values(current-group()/tokenize(@class,'\s+'))"/>
-          </xsl:if>
-          <xsl:apply-templates select="current-group()/*" mode="#current"/>
-        </control>
-      </xsl:for-each-group>-->
-  </xsl:template>
-
-
-
-  <xsl:template name="emit-component">
-    <xsl:param name="combining" as="element(combine)?"/>
-    <xsl:param name="control-set"/>
-    <xsl:for-each-group select="$control-set" group-by="true()">
-      <xsl:choose>
-        <xsl:when test="$combining/@method = 'use-first'">
-          <xsl:copy-of select="$control-set[1]"/>
-        </xsl:when>
-        <xsl:when test="$combining/@method = 'merge'">
-          <xsl:element name="{$control-set[1]/name()}">
-            <xsl:copy-of select="$control-set/@*"/>
-
-            <xsl:for-each-group
-              select="$control-set/(* except (component | references))"
-              group-by="local-name() || ':' || @class || ':' || normalize-space(.)">
-              <xsl:copy-of select="."/>
-              <!-- just one -->
-            </xsl:for-each-group>
-
-            <xsl:apply-templates mode="#current" select="$control-set/component"/>
-
-            <xsl:for-each-group select="$control-set/references/*"
-              group-by="local-name() || ':' || @class || ':' || normalize-space(.)">
-              <references>
-                <xsl:copy-of select="."/>
-              </references>
-            </xsl:for-each-group>
-
-          </xsl:element>
-        </xsl:when>
-
-        <!-- catches value 'keep' or anything else -->
-        <xsl:otherwise>
-          <!-- catches value 'keep' or anything else -->
-          <xsl:copy-of select="$control-set"/>
-        </xsl:otherwise>
-      </xsl:choose>
-    </xsl:for-each-group>
-  </xsl:template>
-
-
-
-  <xsl:template match="custom" mode="build">
-    <!-- tunnel parameter $controls holds controls and maybe loose subcontrols -->
-    <xsl:copy>
-      <xsl:apply-templates mode="#current">
-        <xsl:with-param name="merge-spec" tunnel="true" select=".."/>
-      </xsl:apply-templates>
-    </xsl:copy>
-  </xsl:template>
-
-  <xsl:template match="call" mode="build">
-    <xsl:param name="controls" tunnel="yes" select="()"/>
-    <xsl:variable name="calling" select="."/>
-
-    <xsl:call-template name="emit-component">
-      <xsl:with-param name="combining" select="ancestor::merge/combine" />
-      <xsl:with-param name="control-set" select="$controls[@id=$calling/(@control-id|@subcontrol-id)]"/>
-    </xsl:call-template>
-  </xsl:template>
-
-  <xsl:template match="match" mode="build">
-    <xsl:param name="controls" tunnel="yes" select="()"/>
-    <xsl:variable name="calling" select="."/>
-
-    <xsl:call-template name="emit-component">
-      <xsl:with-param name="combining" select="ancestor::merge/combine" />
-      <xsl:with-param name="control-set" select="$controls[matches(@id,$calling/@pattern ! ('^' || . || '$'))]"/>
-    </xsl:call-template>
-  </xsl:template>
-
-  <!-- mode 'build' matches the proxy structure given in the profile, pulling included
-       controls and subcontrols to populate itself. -->
-  <xsl:mode name="build" on-no-match="shallow-copy"/>
-
-  <xsl:template match="comment() | processing-instruction()" mode="build"/>
-
-
-  <xsl:template match="*" mode="echo"/>
-
-  <!-- Next, matching 'modify' - we pass the 'resolution' document into a filter that
-       rewrites parameter values and patches controls, wrt the stipulated modifications. -->
-
-  <xsl:template match="modify" mode="process-profile">
-    <xsl:param name="so-far"/>
-    <xsl:variable name="modifications" select="."/>
-    <xsl:for-each select="$so-far/resolution">
-      <xsl:copy>
-        <xsl:copy-of select="*|node()"/>
-        <xsl:apply-templates select="child::merged" mode="patch">
-          <xsl:with-param name="modifications" tunnel="yes" select="$modifications"/>
-    </xsl:apply-templates>
-
-      </xsl:copy>
-    </xsl:for-each>
-
-    <!--<xsl:apply-templates select="." mode="echo"/>-->
-  </xsl:template>
-
-<!-- 'patch' mode implements modification.  -->
-  <xsl:template match="merged" mode="patch">
-    <modified>
-      <xsl:apply-templates mode="#current"/>
-    </modified>
-  </xsl:template>
-
-  <xsl:template match="control | component[empty(ancestor::component)]" mode="patch">
-    <xsl:param name="modifications" tunnel="yes" as="element(modify)" required="yes"/>
-
-    <xsl:copy-of select="key('alteration-by-target',@id,$modifications)/add[empty(@target)][@position='before']/*"/>
-
-    <xsl:copy>
-      <xsl:copy-of select="@*"/>
-      <xsl:apply-templates select="title" mode="#current"/>
-      <xsl:copy-of select="key('alteration-by-target',@id,$modifications)/add[empty(@target)][@position='starting']/*"/>
-
-      <xsl:apply-templates select="* except title" mode="#current"/>
-      <!--<xsl:message expand-text="true">{ string-join((* except title)/(name() || '#' || @id), ', ') }</xsl:message>-->
-
-      <xsl:copy-of select="key('alteration-by-target',@id,$modifications)/add[empty(@target)][empty(@position) or @position='ending']/*"/>
-
-    </xsl:copy>
-  </xsl:template>
-
-<!--   -->
-  <xsl:function name="oscal:removable" as="xs:boolean">
-    <xsl:param name="who" as="node()"/>
-    <xsl:param name="mods" as="element(modify)"/>
-    <xsl:variable name="home" select="($who/ancestor::control | $who/ancestor::component)[last()]"/>
-    <xsl:variable name="alterations" select="key('alteration-by-target',$home/@id,$mods)"/>
-    <xsl:variable name="removals" select="$alterations/remove"/>
-
-    <xsl:sequence select="some $r in $removals satisfies oscal:remove-match($who,$r)"/>
-  </xsl:function>
-
-  <xsl:function name="oscal:remove-match">
-    <xsl:param name="who" as="node()"/>
-    <xsl:param name="removal" as="element(remove)"/>
-    <xsl:variable name="item-okay"  select="empty($removal/@item-name) or ($removal/@item-name = local-name($who))"/>
-    <xsl:variable name="id-okay"    select="empty($removal/@id-ref)    or ($removal/@id-ref = $who/@id)"/>
-    <xsl:variable name="class-okay" select="empty($removal/@class-ref) or ($removal/@class-ref = oscal:classes($who))"/>
-    <xsl:sequence select="exists($removal/(@item-name|@id-ref|@class-ref)) and ($item-okay and $id-okay and $class-okay)"/>
-  </xsl:function>
-
-
-  <xsl:template match="control//* | component//*" mode="patch">
-    <xsl:param name="modifications" tunnel="yes" as="element(modify)" required="yes"/>
-    <xsl:variable name="here" select="."/>
-    <xsl:variable name="home" select="(ancestor::control | ancestor-or-self::component)[last()]"/>
-    <xsl:variable name="alterations" select="key('alteration-by-target',$home/@id,$modifications)"/>
-    <!-- Key retrievals scoped to alterations...   -->
-    <xsl:variable name="patches-to-id" select="$alterations/key('addition-by-target',$here/@id,.)"/>
-    <xsl:variable name="patches-to-class" select="$alterations/key('addition-by-target',$here/oscal:classes(.),.)"/>
-
-    <!-- $patches-before contains 'add' elements marked as patching before this element, either by its @id
-      or if bound by its @class, iff it is the first of its class in the containing control
-     -->
-    <xsl:variable name="patches-before" select="$patches-to-id[@position='before'] |
-      $patches-to-class[$here is ($home/descendant::*[oscal:classes(.)=oscal:classes($here)])[1] ][@position='before']"/>
-
-    <xsl:copy-of select="$patches-before/*"/>
-    <xsl:if test="not(oscal:removable(.,$modifications))">
-      <xsl:copy>
-        <xsl:apply-templates select="@*" mode="#current"/>
-
-        <xsl:variable name="patches-starting" select="$patches-to-id[@position='starting'] |
-          $patches-to-class[$here is ($home/descendant::*[oscal:classes(.)=oscal:classes($here)])[1] ][@position='starting']"/>
-        <xsl:copy-of select="$patches-starting/*"/>
-
-        <xsl:apply-templates select="node()" mode="#current"/>
-
-        <xsl:variable name="patches-ending" select="$patches-to-id[empty(@position) or @position='ending' or not(@position=('before','after','starting','ending'))] |
-          $patches-to-class[$here is ($home/descendant::*[oscal:classes(.)=oscal:classes($here)])[last()] ][empty(@position) or @position='ending']"/>
-        <xsl:copy-of select="$patches-ending/*"/>
-      </xsl:copy>
-    </xsl:if>
-
-    <!-- Reverse logic for 'after' patches. Note that elements inside descendant subcontrols or components are excluded from consideration.    -->
-    <xsl:variable name="patches-after" select="$patches-to-id[@position='after'] |
-      $patches-to-class[$here is ($home/descendant::*[oscal:classes(.)=oscal:classes($here)])[last()] ]
-      [@position='after']"/>
-    <xsl:copy-of select="$patches-after/*"/>
-
-  </xsl:template>
-
-
-  <!-- When a catalog is filtered through a profile, its parameters are overwritten
-       by parameters passed in from the invocation. -->
-
-<!-- @priority 12 overrides the template above (matching anything inside controls for patching) -->
-  <xsl:template match="param" mode="patch" priority="12">
-    <xsl:param name="modifications" tunnel="yes" as="element(modify)" required="yes"/>
-    <xsl:copy>
-      <xsl:copy-of select="@*"/>
-      <xsl:apply-templates mode="patch" select="desc"/>
-      <xsl:if test="empty(desc)">
-        <xsl:copy-of select="key('param-settings',@id,$modifications)/desc"/>
-      </xsl:if>
-      <xsl:apply-templates mode="patch" select="label"/>
-      <xsl:if test="empty(label)">
-        <xsl:copy-of select="key('param-settings',@id,$modifications)/label"/>
-      </xsl:if>
-      <xsl:apply-templates mode="patch" select="value"/>
-      <xsl:if test="empty(value)">
-        <xsl:copy-of select="key('param-settings',@id,$modifications)/value"/>
-      </xsl:if>
-    </xsl:copy>
-
-  </xsl:template>
-
-  <!-- set-param/desc overrides param/desc -->
-  <xsl:template match="param/desc"  mode="patch" priority="10">
-    <xsl:param name="modifications" tunnel="yes" as="element(modify)" required="yes"/>
-
-    <xsl:copy-of select="(key('param-settings',parent::param/@id,$modifications)/desc,.)[1]"/>
-  </xsl:template>
-
-  <xsl:template match="param/label" mode="patch" priority="10">
-    <xsl:param name="modifications" tunnel="yes" as="element(modify)" required="yes"/>
-    <xsl:copy-of select="(key('param-settings',parent::param/@id,$modifications)/label,.)[1]"/>
-  </xsl:template>
-
-  <!-- same for param/value -->
-  <xsl:template match="param/value" mode="patch" priority="10">
-    <xsl:param name="modifications" tunnel="yes" as="element(modify)" required="yes"/>
-    <xsl:copy-of select="(key('param-settings',parent::param/@id,$modifications)/value,.)[1]"/>
-  </xsl:template>
-
-
-
-  <!--<xsl:template match="control/* | subcontrol/* | component/*" mode="patch">
-    <xsl:param name="modifications" tunnel="yes" as="element(modify)" required="yes"/>
-    <!-\- boolean comes back as true() if a 'remove' element in the invocation matches
-         by id of the parent and class of the matching component -\->
-    <xsl:variable name="remove_me" select="key('alteration-by-target',../@id,$modifications)/remove/@targets/tokenize(.,'\s+') = oscal:classes(.)"/>
-    <xsl:if test="not($remove_me)">
-      <xsl:next-match/>
-    </xsl:if>
-  </xsl:template>-->
-
-
-  <xsl:key name="param-settings" match="oscal:set-param" use="@param-id"/>
-
-  <xsl:key name="alteration-by-target" match="alter" use="@control-id"/>
-
-<!-- additions (modify/alter/add elements) can be applied using either class value or id:
-     however the key must be scoped to within the control (or subcontrol)
-     -->
-  <xsl:key name="addition-by-target" match="add" use="@target"/>
-
-
-  <!-- Service functions: provided for Schematron etc. DON'T MESS WITH THESE OR YOU'LL BREAK IT. -->
-  <!-- Returns a set of controls or components marked as controls for a profile. -->
-  <xsl:function name="oscal:resolved-controls" as="element()*">
-    <!--saxon:memo-function="yes" xmlns:saxon="http://saxon.sf.net/"-->
-    <xsl:param name="who" as="document-node()?"/>
-    <xsl:sequence select="oscal:resolve($who)//(control | component[contains-token(@class,'control')])"/>
-  </xsl:function>
-
-  <!-- Returns a set of subcontrols or components marked as subcontrols for a profile. -->
-  <xsl:function name="oscal:resolved-subcontrols" as="element()*">
-    <xsl:param name="who" as="document-node()?"/>
-    <xsl:sequence select="oscal:resolve($who)//(subcontrol | component[contains-token(@class,'subcontrol')])"/>
-  </xsl:function>
-
-  <!-- Expect a profile to be resolved. If a catalog or framework, this should return a copy of the input. -->
-  <xsl:function name="oscal:resolve" as="document-node()" saxon:memo-function="yes" xmlns:saxon="http://saxon.sf.net/">
-    <xsl:param name="who" as="node()?"/>
-    <xsl:document>
-      <xsl:apply-templates select="$who" mode="oscal:resolve"/>
-    </xsl:document>
-  </xsl:function>
-
-  <!-- returns sequence of tokens including passed value, but non-duplicatively -->
-  <xsl:function name="oscal:classes-including" as="xs:string">
-    <xsl:param name="class" as="attribute(class)?"/>
-    <xsl:param name="value" as="xs:string"/>
-    <xsl:sequence select="string-join((tokenize($class,'\s+')[. ne $value],$value), ' ')"/>
-  </xsl:function>
-
-  <xsl:function name="oscal:classes" as="xs:string*">
-    <xsl:param name="who" as="element()"/>
-    <!-- HTML is not case sensitive so neither are we -->
-    <xsl:sequence select="tokenize($who/@class/lower-case(.), '\s+')"/>
-  </xsl:function>
-
-  <xsl:key name="element-by-id" match="*[@id]" use="@id"/>
-
-
-
-
-
-
-</xsl:stylesheet>
diff --git a/src/utils/util/resolver-pipeline/resolver-2018/resolution-notes.md b/src/utils/util/resolver-pipeline/resolver-2018/resolution-notes.md
deleted file mode 100644
index f382b5d385..0000000000
--- a/src/utils/util/resolver-pipeline/resolver-2018/resolution-notes.md
+++ /dev/null
@@ -1,146 +0,0 @@
-# Profile semantics notes
-
-OSCAL Profile semantics: old profile resolver (2018) notes ...
-
-## Importing catalogs and including controls
-`include/match[@pattern]` and `include/call[@control-id|@subcontrol-id]` *both* provide selection of controls.
-
-### Including controls (or subcontrols) by calling them by ID
-
-The ID of a control is the `@id` in the XML of that control.
-
-```
-<include>
-   <call control-id="pm3"/>
-</include>
-
-```
-
-`call` with `control-id` works to select the control with with given ID (identifier) in its catalog.
-
-Same for `call` with `subcontrol-id`, except subcontrols are included.
-
-Note that subcontrols may be included without their controls. Depending on other considerations (see below) this may not be an error.
-
-It is also possible to use a `with-subcontrols` flag when calling controls by ID, to include all subcontrols along with it.
-
-
-```
-<include>
-   <call control-id="pm3" with-subcontrols="yes"/>
-</include>
-
-```
-
-### Including controls by matching their ID
-
-```
-<include>
-   <match pattern="^pm"/>
-</include>
-
-```
-
-The value of `@pattern` is an (XSD) regular expression. It is matched against the ID. Both/any controls and subcontrols whose IDs match the patterns, are selected - so in this case, any whose ID starts with "pm".
-
-In future we may add the feature to match any associated string e.g. a title or property value, not only the ID.
-
-### Orphan or "loose" subcontrols
-
-It is a requirement that a subcontrol may be included in one import clause, with its control included (only) in another one. (Perhaps the first clause adds a subcontrol to a profile included in the second.) This should be supported as long as the control is indeed included in another import branch (with which it can eventually be merged subject to its logic). "The same control" for these purposes means the control with the same @id from the same catalog - so, to be more precise, a subcontrol can be reunited to any control with the same ID as its parent in (its own) home directory. An orphan subcontrol included without its control included anywhere (in the same profile albeit not the same import), may be an error (TBD).
-
-NB currently this feature (merging loose subcontrols) is still missing, subject to merge rules altogether. 2018/02/27
-
-proposal 20180228 - resolution w/o merge returns import branches w/ orphan subcontrols still orphaned; then merge combines all controls from same catalogs together (w/o regrouping them); merge/build also does the regrouping
-
-test this on simple cases then come back to worse errors (e.g. duplicative/conflicting control imports)
-
-## Merge proposal
-
-`merge` - simply merges import branches together on their source catalogs (reuniting controls and subcontrols)
-
-However this is considered normal indeed to skip it would only be done ordinarily for diagnostic purposes.
-
-`merge/as-is` - rebuilds into hierarchy of home catalog (we have this working)
-
-`merge/custom` - instead, provides a way to "stack" the controls into a new organization (optionally reporting errors for dropped controls):
-
-```
-<group>
-  <title>
-  <match pattern="cm"/>
-</group>
-```
-
-for purposes of error handling, remember that designers should be using exclusions, not letting profiles conflict even apparently. So `merge` might complain *any* time controls appear duplicative (there is always a remedy).
-
-Should running a resolution w/o merge, also make it impossible to patch? (B/c we don't know what we're patching?)
-
-## Modify logic ("patching")
-
-As implemented, modifications permit both removals and additions.
-
-
-```
-<remove id-ref="e95b8652"/>
-<remove class-ref="baseline"/>
-<remove item-name="title"/>
-```
-
- * Remove the element with `@id` (id attribute) `e95b8652`
- * Remove any element with `@class` token `baseline`
- * Remove any `title` element
-
-These can be combined.
-
-`<add>` elements permit two attributes to indicate the position of the addition. `@target` (optional) indicates an element where the patch will be made. `@position` indicates where (in relation to the target) the patch will be placed. Four values are recognized for `@position`: `before`, `after`, `starting` and `ending`.
-
-You can add new components (stuff) to the front (after the title, before everything else) or at the end of any control or subcontrol, by including your addition in an `add` element *without a target*, like so:
-
-```
-<add position="starting">
-  <prop class="cat">Category A</prop>
-</add>
-```
-
-The same for `position="ending"`, which puts the new contents at the end of the control or subcontrol.
-
-If instead of patching your control or subcontrol at its start or end, you wish to locate precisely where you wish an addition. For this, use a `@target`:
-
-```
-<add position="after" target="advice">
-  <part class="more_advice">
-     <title>More advice</title>
-     <p>More advice ...</p>
-</add>
-```
-
-The target works to identify an element by its `@id` or by a class token.
-
-When elements are matched using class tokens, there is the possibility that multiple elements of the given class are present in the control. The element where the insertion is to be made is then determined by the given `@position`:  `position='before'` and `position='starting'` work to select the *first* of the candidates in the control as given, while  `position='after'` and `position='ending'` work to select only the *last* element of the given class, within the control or subcontrol.
-
-The difference between `position='before'` and `position='starting'` is that "before" places the inserted content *before* the targeted element, while "starting" places it *inside* it, at the front. "ending" will place the inserted content at the end, inside the identified element.
-
-When the targeted element is a control or subcontrol, `before` is a synonym for `starting`
-
-If no position is given, `position='ending'` is inferred: the insertion happens inside the targeted element (or the matched control or subcontrol), at the end.
-
-Note that this default works along with the rule that if no target (class or ID) is indicated, the control or subcontrol itself is the point of insertion. So:
-
-```
-<modify control-id="ac.1">
-  <add position="starting">
-    <link href="guidelines/">Local guidelines</link>
-  </add>
-  <add>
-    <part class="supplemental">
-       <title>Supplementary Guidance</title>
-       <p>More advice ...</p>
-    </part>
-  </add>
-</modify>
-```
-
-This adds the new `part` at the end of the `ac.1` control.
-
-Note also that position "before" and "after" work only when @target is also used (to identify some contents inside a control); they are inoperable when the target is a control or subcontrol. They result in no addition being made. (A Schematron check could be made for this.)